Migrating from v6 to v7
v7 is a wire-contract release: the versioned /api/v1 resource model and the SDK on it, one display model with three modes, one error for the SDK, tool results that follow the executor, a tolerant @octavus/core, and the removal of resources and of the size alias. The published 6.x packages keep working against the platform while you migrate, so you can move at your own pace - validate your agents, update your application, then upgrade the packages.
Before you upgrade: validate your agents
Run the validator on every agent, in the dashboard editor (the Problems panel) or with the CLI:
octavus validate ./path/to/agentv7 reports display: name and display: description as errors (DISPLAY_MODE_REMOVED), and resources:, the set-resource block, and a generate-image size as removed fields (REMOVED_FIELD). An agent that validates clean on v7 is ready. The dashboard editor and the 6.x CLI keep saving an agent that still carries the two retired display values (they run as title), so a deployed agent does not break while you edit it.
1. Display: three modes, one label rule
The display modes are hidden, title, and stream. title is the default for tools, skills, MCP servers, and the indicator blocks (tool-call, generate-image, ...); workers and next-message default to stream.
| Mode | Live and stored alike |
|---|---|
hidden | Nothing reaches the client |
title | A labeled card with its status and error. No arguments, no result, no input, no output, no nested work |
stream | Everything: arguments as they stream, the result, a worker's input, output, and nested activity |
The label of a visible card is its authored title; without one, the client derives a label from the tool name, the worker slug, or the block name. A description is written for the model and is never shown (the protocol overview states the rule for the three fields; the validator hints, at info level, when a visible step or a streaming tool has a description and no title). What a mode reveals is the same on the live stream and in the stored conversation, so a reload shows what the run showed.
The built-in octavus_* tools (web search, image, video, and speech generation, transcription, image viewing, and the sandbox code and file tools) have no display in the protocol and render in stream, each with a title the platform supplies. On the wire that is what v6's description mode gave you for these tools: the arguments as they stream and the result when it lands. What is new is that the UI transcript now keeps their results too, so getMessages() returns them and a conversation you persist contains them. If your UI should not show a built-in tool's arguments or result, leave them out when rendering the part.
The reference tools are the exception: a read's result is a whole document written for the agent, so octavus_reference_list and octavus_reference_read render as labels (title) by default - the card names the reference (its frontmatter title, else "Reading reference: {name}") and carries no content. In v6 their cards streamed the document; to keep that, set the display on the scope's references:
agent:
references:
names: [design, fraud-prevention] # the array alone is still the shorthand
display: streamThe same object form works on start-thread.references, and a reference file may carry a title in its frontmatter beside its description, the label of its read card.
Protocol
Replace display: name and display: description with display: title (adding a title when you want a specific label) or display: stream:
tools:
get-user-account:
display: title
title: Looking up your account # the label
description: Retrieves the user's account by id. # written for the model
parameters:
userId: { type: string }
save-draft:
display: stream # show the arguments and result
description: Persist the current draft
parameters:
body: { type: string }On blocks, the UI label moves from description to title:
Generate image:
block: generate-image
prompt: OPTIMIZED_PROMPT
imageModel: openai/gpt-image-2.5-flare
title: Generating your image # was `description: Generating your image...`Skills carry a title in their SKILL.md frontmatter, which the protocol's skills.<slug>.title overrides. MCP servers take a namespace title, and a title a server advertises for a tool takes precedence for that tool.
Client code
UIToolCallPart.displayName is gone, and so is UIWorkerPart.description; both are title, set only when a title was authored. Label every tool, worker, and operation card with getPartLabel(part), which applies the title-or-identity rule and accepts a resolver for your own labels:
import { getPartLabel } from '@octavus/react';
// Before
<span>{part.displayName || part.toolName}</span>;
// After
<span>{getPartLabel(part)}</span>;UIOperationPart.name is now the block's name as authored in the protocol; in v6 it carried the card's label. Label operation cards with getPartLabel(part) too, which reads the authored title first.
Every tool-call, worker, and operation part carries its display; displayReveals(part.display) tells a renderer what the part will carry (visible, label, input, output, nested), so it can skip the sections it will never get.
Stored messages
Messages you stored under v6 render and restore as they are: the parser keeps every part and field it does not know. The one thing v7 does not read is the v6 label field, displayName: v7 labels a card with title, else from its tool name. Where displayName held a title, move it once - a title-mode tool call stored under v6 carries its authored title there, and a built-in octavus_* tool call carries the platform's label there in every mode ("Searching the web", "Running code"):
import { isOctavusInternalTool } from '@octavus/core';
for (const part of message.parts) {
if (part.type !== 'tool-call' || part.title) continue;
if (part.display !== 'title' && !isOctavusInternalTool(part.toolName)) continue;
// `displayName` is a v6 field the v7 types no longer declare; the parser kept it.
const { displayName } = part as { displayName?: string };
if (displayName) part.title = displayName;
}The other v6 label fields (your own stream-mode tool call's displayName, a worker's description) held the model-facing description, which is not a title; leave them.
2. Resources are removed
resources:, the set-resource block, the resource-update event, onResourceUpdate, the Resource class, and attach({ resources }) are gone. Persist state with a tool your application implements: a deterministic handler passes the value into a tool-call block, and your handler writes it wherever you store state.
Before:
resources:
CONVERSATION_SUMMARY:
type: string
default: ''
handlers:
wrap-up:
Generate summary:
block: next-message
output: SUMMARY
Save summary:
block: set-resource
resource: CONVERSATION_SUMMARY
value: SUMMARYuseOctavusChat({
onResourceUpdate: (name, value) => {
if (name === 'CONVERSATION_SUMMARY') persist(value);
},
});After:
tools:
save-conversation-summary:
description: Persist the running summary of this conversation.
display: hidden
parameters:
summary:
type: string
handlers:
wrap-up:
Generate summary:
block: next-message
output: SUMMARY
Save summary:
block: tool-call
tool: save-conversation-summary
input:
summary: SUMMARYconst session = client.sessions.attach(sessionId, {
tools: {
'save-conversation-summary': async (args) => {
await db.conversations.update(id, { summary: args.summary as string });
return { saved: true };
},
},
});The tool's parameters are the shape of the state, and your handler owns where it goes. An inline MCP server (createInlineMcpServer) groups such tools with the rest of your integration when you prefer.
3. The size alias on generate-image is removed
Use aspectRatio:
Generate image:
block: generate-image
prompt: PROMPT
imageModel: openai/gpt-image-2.5-flare
aspectRatio: 16:9 # was `size: 1792x1024`; 1024x1024 -> 1:1, 1024x1792 -> 9:164. Tool results follow the executor
Each executor submits only the results of the tools it ran. In a step that mixes server and client tools, the Server SDK submits its own results first; the platform records them and asks again for the calls still open, and those reach the client as the client-tool-request event. serverToolResults is gone from that event, and a client never echoes another executor's results.
A submitted result is the toolCallId with its result (or error, and files). The platform routes it by the call it recorded when it issued it, so the routing fields a v6 continue carried (toolName, outputVariable, blockIndex, thread, workerId) are no longer part of a result. A result for a call the execution did not request is refused with 400 UNKNOWN_TOOL_CALL; a second result for the same call is ignored, and so is a result re-sent for a call the execution already applied (a continue retried after a dropped connection).
If you drive the loop yourself, drop the echo:
// Before
session.execute({
type: 'continue',
executionId,
toolResults: [...event.serverToolResults, { toolCallId, toolName, result }],
});
// After
session.execute({
type: 'continue',
executionId,
toolResults: [{ toolCallId, result }],
});The Server SDK, the client SDK, and the React hook do all of this for you.
Because a result no longer says what it is for, the Server SDK treats every result it ran the same way, whether the model called the tool or a tool-call block did: an oversized result is reduced to a head-and-tail preview with a note and marked truncated: true, and inline media is uploaded and replaced by file references. ToolResultTruncation.variableCapture is gone with the distinction. The platform knows which calls a block captures into a variable, and refuses a truncated result for one: the capture fails with an error the agent can act on, as in v6, instead of storing the preview as the value.
5. One error: OctavusError
ApiError (server SDK), the AppError family (NotFoundError, ValidationError, ConflictError, ForbiddenError), and the error-event constructors (createErrorEvent, createInternalErrorEvent, createApiErrorEvent, errorToStreamEvent) are gone from the public packages. A failed request and a stream error event both surface as OctavusError, with the same classification:
import { OctavusError } from '@octavus/server-sdk';
try {
await client.sessions.getMessages(sessionId);
} catch (error) {
if (OctavusError.isInstance(error)) {
error.status; // the HTTP status of a failed request
error.code; // the platform's stable code ('NOT_FOUND', 'AGENT_BUSY', ...)
error.errorType; // the classification ('not_found_error', 'conflict_error', ...)
error.retryable; // whether the same request can succeed if retried
error.requestId; // quote it to support
error.issues; // the structured issues of a 400 or 422
}
}For a definition the platform refused (agents.create(), agents.update()), validationIssuesOf(error) returns the issues it carried typed as ValidationIssue[], each at its severity.
| Before | After |
|---|---|
error instanceof ApiError | OctavusError.isInstance(error) |
error.status, error.code | Same names, on OctavusError |
errorToStreamEvent(error) | error.toEvent() |
createInternalErrorEvent(message) | OctavusError.internal(message).toEvent() |
createApiErrorEvent(status, message) | OctavusError.fromApiResponse(status, body, message) |
new ValidationError(...) in an app | Your own error class |
WorkerError.details.errorType, ... | WorkerError.errorType, ... (WorkerErrorDetails is gone) |
WorkerError, which workers.generate() throws, is an OctavusError: the guards (isRateLimitError, isValidationError, ...) recognize it, it carries the requestId, and the classification that details held in v6 is on the error itself. instanceof WorkerError works as before, and its sessionId still names the run.
Every endpoint answers errors with one body - error, code, type, retryable, requestId, plus issues and retryAfter when they apply - and every response carries a Request-Id header. An invalid agent definition is 422 INVALID_PROTOCOL with its issues (it was a 400), a plan limit is 402, and an agent you cannot access is 404.
A failed response that carries no such body is never shown as it came. The v6 client transport used the response's text as the error message, so an error page from your own server or a proxy reached onError as markup; both SDKs now classify such a response by its status and describe it (Request failed: 502 Bad Gateway (text/html)), as the client error handling page states.
6. @octavus/core is schema-first and tolerant
Every object schema keeps the fields it does not know, an event or part of an unknown type is kept rather than dropped, and an unknown enum value falls back to a documented default (reported once per value through setUnknownWireValueReporter). safeParseStreamEvent returns { kind: 'event' | 'unknown' | 'invalid' } instead of a Zod result:
// Before
const result = safeParseStreamEvent(data);
if (result.success) handle(result.data);
// After
const result = safeParseStreamEvent(data);
if (result.kind === 'event') handle(result.event);
else if (result.kind === 'unknown') forward(result.event); // or ignore itSwitch on type with a default branch wherever you render parts or handle events. See Versioning for the rules the platform follows.
@octavus/core no longer declares zod as a peer dependency (it was ^4.0.0): the packages bring their own copy, which your project shares when it uses zod 4.3.5 or newer, and the public types are plain TypeScript types that do not depend on your zod version. safeParseUIMessage and safeParseUIMessages still return success and data; on a failure, error is a WireParseError (message and issues) instead of a ZodError.
7. Timestamps are strings
UIMessage.createdAt is an ISO 8601 string, on the wire and in the types. Wrap it where you need a Date:
// Before
message.createdAt.toLocaleTimeString();
// After
new Date(message.createdAt).toLocaleTimeString();8. The session read is metadata
client.sessions.get(sessionId) returns the session (id, agentId, status, createdAt) instead of the raw internal state. Read the conversation with getMessages() and the full execution record with getLogs(). The internal ChatMessage type and its MessagePart types are gone from the public packages; UIMessage is the one message shape.
9. The API is /api/v1, and the SDK speaks it
Every endpoint lives under /api/v1 as a resource: sessions, their messages, logs, and executions; agents and their executions; skills, tokens, and models. The path is the version (see Versioning); the X-Octavus-Sdk-Version header is gone, and so is everything it negotiated - a v1 caller always receives execution legs (finish: continue, resumed with an empty continuation). The unversioned paths the 6.x packages call keep working until v6 support ends.
| v6 | v7 |
|---|---|
POST /api/agent-sessions -> { sessionId } | POST /api/v1/sessions -> the session |
POST /api/agent-sessions/start | POST /api/v1/sessions/start |
GET /api/agent-sessions/:id (raw state) | GET /api/v1/sessions/:id -> the session, status: active | expired |
GET /api/agent-sessions/:id?format=ui | GET /api/v1/sessions/:id/messages -> { messages }, empty when expired |
POST .../trigger (a trigger body) | POST /api/v1/sessions/:id/executions, no type |
POST .../trigger (a continue body) | POST /api/v1/sessions/:id/executions/:executionId/continue, { toolResults? } |
POST .../restore -> { sessionId, restored } | POST /api/v1/sessions/:id/restore { messages, input } -> the session |
DELETE /api/agent-sessions/:id -> { sessionId, cleared } | POST /api/v1/sessions/:id/clear -> the session, now expired |
GET .../logs (three bodies) | GET /api/v1/sessions/:id/logs -> { entries, total, truncated }, empty when expired |
POST /api/files/upload-urls { sessionId, files } | POST /api/v1/sessions/:id/uploads { files } |
POST /api/files/view-url { sessionId, fileUrl } | POST /api/v1/sessions/:id/files/view-url { fileUrl } |
GET /api/agents/:id?by=slug | GET /api/v1/agents?slug= -> { agents }; paths carry ids only |
POST /api/agents { settings, protocol, ... } -> { agentId, message } | POST /api/v1/agents { slug, name, format, protocol, ... } -> the agent, one flat object |
PATCH / DELETE /api/agents/:id -> { agentId, message } | PATCH / DELETE /api/v1/agents/:id -> the agent; every PATCH field optional on its own |
POST /api/agents/validate -> { valid, errors, warnings, issues } | POST /api/v1/agents/validate -> { valid, issues } |
POST /api/agents/:id/execute { type: 'start', input } | POST /api/v1/agents/:id/executions { input } |
POST /api/agents/:id/execute { type: 'continue', ... } | POST /api/v1/agents/:id/executions/:executionId/continue |
POST /api/tokens, /api/tokens/revoke | POST /api/v1/tokens, /api/v1/tokens/revoke (same shapes) |
POST /api/skills -> { skillId, slug, created } | POST /api/v1/skills -> the skill (201 created, 200 updated) |
PUT /api/skills/:id/secrets -> { updated } | PATCH /api/v1/skills/:id/secrets -> { secrets: [{ name, updatedAt }] }, the set after the merge |
GET /api/models | GET /api/v1/models (same shape) |
PATCH /api/v1/agents/:id validates the definition it produces as fully as a create, so an update that leaves the agent invalid is refused with 422 where v6 saved it.
The agent is one flat object everywhere (id, slug, name, description, format, projectId, createdAt, updatedAt, plus protocol, prompts, and references outside the list); v6 nested slug, name, description, and format under settings on the definition reads and writes, which was the CLI's settings.json, not a resource. POST /api/v1/sessions/start takes its idempotency key as the Idempotency-Key header (v6: idempotencyKey in the body) and answers the created session's id in the Octavus-Session-Id header (v6: X-Octavus-Session-Id). An operation that needs a session's live state on an expired session - a new execution, upload URLs - is 409 SESSION_EXPIRED (v6: 404), and a view URL for an expired session's file is minted rather than refused. Execution ids, a session's and a worker's alike, are UUIDs.
The Server SDK
client.sessions replaces client.agentSessions, and every method returns the resource:
// Before
const sessionId = await client.agentSessions.create(agentId, input);
const state = await client.agentSessions.getMessages(sessionId);
if (state.status === 'expired') {
const { restored } = await client.agentSessions.restore(sessionId, stored, input);
}
const logs = await client.agentSessions.getLogs(sessionId);
if (logs.status !== 'expired') console.log(logs.entries);
// After
const { id: sessionId } = await client.sessions.create(agentId, input);
const session = await client.sessions.get(sessionId); // { id, agentId, status, createdAt }
if (session.status === 'expired') {
await client.sessions.restoreFromMessages(sessionId, stored, input); // the session, active again
}
const messages = await client.sessions.getMessages(sessionId); // UIMessage[], [] once expired
const { entries, total, truncated } = await client.sessions.getLogs(sessionId);getMessages() returns the UIMessage[] itself (v6 returned a state object with the messages and a status; the status is now on get()), clear() and restoreFromMessages() (v6's restore()) return the session; UISessionState, ExpiredSessionState, RestoreSessionResult, ClearSessionResult, ExecutionLogsResult, and SessionInfo are gone (Session and ExecutionLogs replace them). attach() and start() are unchanged, except that start()'s idempotencyKey is sent as the Idempotency-Key header and so is 1-255 printable ASCII characters with no spaces.
baseUrl is optional and defaults to https://octavus.ai. client.agents.list({ slug }) finds an agent by slug, and client.agents gains create, update, archive, and validate (the Agents permission); AgentDefinition is flat (agent.slug, not agent.settings.slug), AgentDefinitionInput takes the same flat fields, and AgentUpdateInput takes each field on its own (AgentSettings is gone). client.skills (an organization key) uploads a bundle with sync() and sets secrets with setSecrets(), which returns the skill's secrets (SkillSecret[], names and updatedAt) after the merge; client.files.getViewUrl() mints a view URL for a session file. An operation on an expired session that needs its live state fails with the code SESSION_EXPIRED (SESSION_EXPIRED_CODE).
The client SDK and React
onStart receives { executionId, sessionId? } instead of a bare id that was the execution's. useOctavusChat returns executionId (the id sessionId held in v6) and a sessionId that is the session's: the id to keep, where the execution's only continues a paused turn (see Sessions and Executions).
// Before
useOctavusChat({ transport, onStart: (id) => setExecutionId(id) });
// After
useOctavusChat({ transport, onStart: ({ executionId }) => setExecutionId(executionId) });The CLI
@octavus/cli is built on the Server SDK's client. octavus sync resolves the agent by slug and creates or updates it by id, with the same full validation the editor runs, so a definition with errors fails the command and deploys nothing where the 6.x CLI updated it. octavus validate --json prints { slug, valid, issues }; the errors and warnings arrays are gone (filter issues by severity).
10. Removed exports
Everything below is gone from the public packages. Each row names the replacement.
| Package | Removed | Use instead |
|---|---|---|
core | ChatMessage, MessagePart, ToolCallInfo, WorkerPartInfo, OperationInfo, and the other internal message types | UIMessage and its parts |
core | ResourceUpdateEvent, ResourceUpdateHandler | A tool (section 2) |
core | AppError, NotFoundError, ValidationError, ConflictError, ForbiddenError | OctavusError |
core | createErrorEvent, createInternalErrorEvent, createApiErrorEvent, errorToStreamEvent | OctavusError.internal(), .fromApiResponse(), .toEvent() |
core | chatMessageSchema, todoInfoSchema | uiMessageSchema |
core | GeneratedFile | FileReference (the same fields) |
server-sdk | ApiError, Resource, SessionState | OctavusError, a tool, Session |
server-sdk | WorkerErrorDetails | The fields on WorkerError itself |
server-sdk | AgentSessionsApi, SessionInfo, UISessionState, ExpiredSessionState, RestoreSessionResult, ClearSessionResult, ExecutionLogsResult | SessionsApi, Session, UIMessage[], ExecutionLogs |
client-sdk | onResourceUpdate, the AppError family and error-event constructors | OctavusError |
react | onResourceUpdate, the AppError family and error-event constructors | OctavusError |
Protocol fields: display: name, display: description, resources:, the set-resource block, generate-image.size.
Wire: resource-update, client-tool-request.serverToolResults, UIToolCallPart.displayName, UIWorkerPart.description, the description label on worker-start, worker-input-start, and block-start (all title), the routing fields on a submitted tool result, and source, outputVariable, and blockIndex on a tool-request's pending calls. UIOperationPart.name keeps its name but is now the block's name, not its label. In the execution log (getLogs()), a tool-call entry's toolDescription is toolTitle: the call's authored title, where it used to carry the label of the time. The X-Octavus-Sdk-Version header is gone with the unversioned paths (section 9).
Checklist
- Validate every agent and resolve each
DISPLAY_MODE_REMOVEDandREMOVED_FIELDissue. - Replace
display: name/display: descriptionwithdisplay: title(plus atitle) ordisplay: stream; move block labels fromdescriptiontotitle. If your UI showed the content of reference reads, setreferences: { names, display: stream }on the scope. - Replace
resources:,set-resource, andonResourceUpdatewith a tool your application implements. - Replace a
generate-imagesizewithaspectRatio. - In client code, label cards with
getPartLabel(part)and treatcreatedAtas a string; move a stored tool call'sdisplayNametotitlewhere it was one (atitle-mode call, a built-inoctavus_*call) if those cards should keep their titles. - Replace
ApiErrorand theAppErrorfamily withOctavusError; readstatus,code, andrequestIdfrom it. Read aWorkerError's classification from the error itself instead ofdetails. - If you drive the tool loop yourself, submit only your own results, each as
{ toolCallId, result }. - Add a
defaultbranch that ignores the value wherever you switch on an event or parttype; never make such a switch exhaustive. - Rename
client.agentSessionstoclient.sessionsand read the session fromcreate(),restoreFromMessages(), andclear(), the messages fromgetMessages(), and the status fromget(); readonStart's ids from its{ executionId, sessionId }argument. If you call the API directly, move to the/api/v1paths and drop theX-Octavus-Sdk-Versionheader. - Upgrade every
@octavus/*package to 7.x together.