Skip to main content

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:

bash
octavus validate ./path/to/agent

v7 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.

ModeLive and stored alike
hiddenNothing reaches the client
titleA labeled card with its status and error. No arguments, no result, no input, no output, no nested work
streamEverything: 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:

yaml
agent:
  references:
    names: [design, fraud-prevention] # the array alone is still the shorthand
    display: stream

The 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:

yaml
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:

yaml
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:

tsx
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"):

typescript
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:

yaml
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: SUMMARY
typescript
useOctavusChat({
  onResourceUpdate: (name, value) => {
    if (name === 'CONVERSATION_SUMMARY') persist(value);
  },
});

After:

yaml
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: SUMMARY
typescript
const 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:

yaml
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:16

4. 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:

typescript
// 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:

typescript
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.

BeforeAfter
error instanceof ApiErrorOctavusError.isInstance(error)
error.status, error.codeSame 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 appYour 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:

typescript
// 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 it

Switch 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:

typescript
// 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.

v6v7
POST /api/agent-sessions -> { sessionId }POST /api/v1/sessions -> the session
POST /api/agent-sessions/startPOST /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=uiGET /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=slugGET /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/revokePOST /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/modelsGET /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:

typescript
// 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).

typescript
// 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.

PackageRemovedUse instead
coreChatMessage, MessagePart, ToolCallInfo, WorkerPartInfo, OperationInfo, and the other internal message typesUIMessage and its parts
coreResourceUpdateEvent, ResourceUpdateHandlerA tool (section 2)
coreAppError, NotFoundError, ValidationError, ConflictError, ForbiddenErrorOctavusError
corecreateErrorEvent, createInternalErrorEvent, createApiErrorEvent, errorToStreamEventOctavusError.internal(), .fromApiResponse(), .toEvent()
corechatMessageSchema, todoInfoSchemauiMessageSchema
coreGeneratedFileFileReference (the same fields)
server-sdkApiError, Resource, SessionStateOctavusError, a tool, Session
server-sdkWorkerErrorDetailsThe fields on WorkerError itself
server-sdkAgentSessionsApi, SessionInfo, UISessionState, ExpiredSessionState, RestoreSessionResult, ClearSessionResult, ExecutionLogsResultSessionsApi, Session, UIMessage[], ExecutionLogs
client-sdkonResourceUpdate, the AppError family and error-event constructorsOctavusError
reactonResourceUpdate, the AppError family and error-event constructorsOctavusError

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

  1. Validate every agent and resolve each DISPLAY_MODE_REMOVED and REMOVED_FIELD issue.
  2. Replace display: name / display: description with display: title (plus a title) or display: stream; move block labels from description to title. If your UI showed the content of reference reads, set references: { names, display: stream } on the scope.
  3. Replace resources:, set-resource, and onResourceUpdate with a tool your application implements.
  4. Replace a generate-image size with aspectRatio.
  5. In client code, label cards with getPartLabel(part) and treat createdAt as a string; move a stored tool call's displayName to title where it was one (a title-mode call, a built-in octavus_* call) if those cards should keep their titles.
  6. Replace ApiError and the AppError family with OctavusError; read status, code, and requestId from it. Read a WorkerError's classification from the error itself instead of details.
  7. If you drive the tool loop yourself, submit only your own results, each as { toolCallId, result }.
  8. Add a default branch that ignores the value wherever you switch on an event or part type; never make such a switch exhaustive.
  9. Rename client.agentSessions to client.sessions and read the session from create(), restoreFromMessages(), and clear(), the messages from getMessages(), and the status from get(); read onStart's ids from its { executionId, sessionId } argument. If you call the API directly, move to the /api/v1 paths and drop the X-Octavus-Sdk-Version header.
  10. Upgrade every @octavus/* package to 7.x together.