@otto-code/protocol 0.8.10 → 0.8.13

package/dist/agent-labels.d.ts

@@ -1,4 +1,6 @@
 export declare const PARENT_AGENT_ID_LABEL = "otto.parent-agent-id";
+export declare function getOpenAgentTabLabel(clientId: string): string;
+export declare function isOpenAgentTabLabel(label: string): boolean;
 export interface AgentLabelSource {
     labels?: Record<string, unknown> | null;
 }
@@ -30,4 +32,5 @@ export interface OrchestrationQueryToolLabel {
     path?: string;
 }
 export declare function getQueryToolsFromLabels(labels: Record<string, unknown> | null | undefined): OrchestrationQueryToolLabel[] | null;
+export declare function hasOpenAgentTab(labels: Record<string, unknown> | null | undefined): boolean;
 //# sourceMappingURL=agent-labels.d.ts.map

package/dist/agent-labels.js

@@ -1,4 +1,11 @@
 export const PARENT_AGENT_ID_LABEL = "otto.parent-agent-id";
+const OPEN_AGENT_TAB_LABEL_PREFIX = "otto.open-agent-tab.";
+export function getOpenAgentTabLabel(clientId) {
+    return `${OPEN_AGENT_TAB_LABEL_PREFIX}${clientId}`;
+}
+export function isOpenAgentTabLabel(label) {
+    return label.startsWith(OPEN_AGENT_TAB_LABEL_PREFIX);
+}
 export function getParentAgentIdFromLabels(labels) {
     const parentAgentId = labels?.[PARENT_AGENT_ID_LABEL];
     return typeof parentAgentId === "string" && parentAgentId.trim().length > 0
@@ -90,4 +97,7 @@ function parseJsonArrayLabel(labels, key, isValid) {
     });
     return entries.length > 0 ? entries : null;
 }
+export function hasOpenAgentTab(labels) {
+    return Object.entries(labels ?? {}).some(([label, value]) => isOpenAgentTabLabel(label) && value === "true");
+}
 //# sourceMappingURL=agent-labels.js.map

package/dist/agent-personalities.d.ts

@@ -3,8 +3,8 @@ export declare function isPersonalityRole(value: string): value is PersonalityRo
 /**
  * Filter an arbitrary role array (roles ride the wire as plain strings) down to
  * the known set, deduped and returned in canonical `PERSONALITY_ROLES` order.
- * Retired role names are mapped through `LEGACY_ROLE_ALIASES`; anything else
- * unknown (e.g. a role from a newer peer) is dropped rather than trusted.
+ * Unknown roles (for example, a role from a newer peer) are dropped rather
+ * than trusted.
  */
 export declare function normalizePersonalityRoles(roles: readonly string[] | undefined): PersonalityRole[];
 export declare function personalityHasRole(personality: Pick<AgentPersonality, "roles">, role: PersonalityRole): boolean;
@@ -34,11 +34,12 @@ export interface PersonalitySelectionSummary {
  * deciding agent can pick the right teammate from the list alone.
  */
 export declare function summarizePersonalityForSelection(personality: Pick<AgentPersonality, "roles">): PersonalitySelectionSummary;
+export declare const OTTO_WORK_VOCABULARY_DIRECTIVE = "Otto work vocabulary: a suggested task is deferred work for the user and does not start work; a chat is an active Otto chat session; a child chat is created by another chat; a personality profile is a reusable provider, model, mode, effort, and behavior template; an orchestration coordinates multiple chats; a schedule starts a background chat when due; a heartbeat sends a reminder or prompt and does not start a chat. Use suggest_task for concrete work to preserve for later, create_chat to start one chat now, and start_orchestration only for managed multi-chat coordination. Use list_personalities, optionally filtered by roles, before choosing a personality profile. Never substitute a harness-native agent-spawn tool for suggest_task, and when a user names an Otto tool exactly, use that exact Otto tool.";
 export declare const ORCHESTRATOR_METHOD_DIRECTIVE: string;
 /**
  * The in-context "role directive" injected into a personality's system prompt at
  * spawn. The orchestrator gets the full conductor method; other coordinators
- * (chatter/artificer/scheduler) get a lighter delegate nudge; focused workers
+ * (chatter/artificer/scheduler) get a lighter delegate nudge; focused personalities
  * are told to stay on the task someone is waiting on. Roleless spawns get
  * nothing. This is guidance, not a gate - the tools stay available either way.
  */

package/dist/agent-personalities.js

@@ -4,22 +4,14 @@ import { PERSONALITY_ROLES } from "./messages.js";
 // resolution is NOT here - it needs the model's advertised thinking options and
 // lives with the daemon's effort resolver; availability does not depend on it.
 const ROLE_SET = new Set(PERSONALITY_ROLES);
-// Retired role names, mapped to their canonical replacement. "worker" was split
-// into "writer" (fast small-text generation) and "coder" (sub-agent coding); a
-// personality that still carries the old tag resolves to "coder", the closer
-// heir of what a worker did. Normalization applies these before filtering so
-// personalities persisted before the split keep a real role.
-const LEGACY_ROLE_ALIASES = {
-    worker: "coder",
-};
 export function isPersonalityRole(value) {
     return ROLE_SET.has(value);
 }
 /**
  * Filter an arbitrary role array (roles ride the wire as plain strings) down to
  * the known set, deduped and returned in canonical `PERSONALITY_ROLES` order.
- * Retired role names are mapped through `LEGACY_ROLE_ALIASES`; anything else
- * unknown (e.g. a role from a newer peer) is dropped rather than trusted.
+ * Unknown roles (for example, a role from a newer peer) are dropped rather
+ * than trusted.
  */
 export function normalizePersonalityRoles(roles) {
     if (!roles || roles.length === 0) {
@@ -27,7 +19,7 @@ export function normalizePersonalityRoles(roles) {
     }
     const present = new Set();
     for (const raw of roles) {
-        const canonical = LEGACY_ROLE_ALIASES[raw] ?? (isPersonalityRole(raw) ? raw : null);
+        const canonical = isPersonalityRole(raw) ? raw : null;
         if (canonical) {
             present.add(canonical);
         }
@@ -51,7 +43,7 @@ export const PERSONALITY_ROLE_INFO = {
         tier: "coordinator",
         guidance: "Creates and manages schedules; may orchestrate recurring or multi-step jobs. Pick for scheduling.",
     },
-    // ── Thinking workers (read-only, structured findings) ─────────────────────
+    // ── Thinking specialists (read-only, structured findings) ────────────────
     researcher: {
         tier: "focused",
         guidance: "Read-only surveyor - maps the code or domain and reports files, types, patterns, and gotchas. Pick to gather facts; proposes no solutions and edits nothing.",
@@ -68,7 +60,7 @@ export const PERSONALITY_ROLE_INFO = {
         tier: "focused",
         guidance: "Read-only second opinion - weighs the trade-offs and returns one recommendation. Pick for advice; never edits and does not fan out.",
     },
-    // ── Making workers (produce code, design, or text) ────────────────────────
+    // ── Making specialists (produce code, design, or text) ───────────────────
     coder: {
         tier: "focused",
         guidance: "Focused implementer - writes code for one sub-task others are waiting on. Pick to get a coding job done; stays on task.",
@@ -84,7 +76,7 @@ export const PERSONALITY_ROLE_INFO = {
     // ── Conductor ─────────────────────────────────────────────────────────────
     orchestrator: {
         tier: "coordinator",
-        guidance: "The sole conductor - plans team-shaped work, dispatches typed tasks to the right teammates, gathers, and synthesizes. Pick to run a multi-agent workflow.",
+        guidance: "The sole conductor - plans team-shaped work, dispatches typed tasks to the right teammates, gathers, and synthesizes. Pick to coordinate a multi-chat workflow.",
     },
 };
 /**
@@ -113,17 +105,18 @@ export function summarizePersonalityForSelection(personality) {
 }
 // The conductor's standing directive - the distilled `/epic` method taught to
 // the sole orchestrator role at spawn. It chooses direct work, a dedicated
-// worker, a follow-up task, or a Run by the task's actual needs rather than
+// chat, a suggested task, or an orchestration by the task's actual needs rather than
 // treating orchestration as the default. Kept here as one exported constant so
 // the wording is testable and shared. See projects/agent-orchestration/agent-orchestration.md.
+export const OTTO_WORK_VOCABULARY_DIRECTIVE = "Otto work vocabulary: a suggested task is deferred work for the user and does not start work; a chat is an active Otto chat session; a child chat is created by another chat; a personality profile is a reusable provider, model, mode, effort, and behavior template; an orchestration coordinates multiple chats; a schedule starts a background chat when due; a heartbeat sends a reminder or prompt and does not start a chat. Use suggest_task for concrete work to preserve for later, create_chat to start one chat now, and start_orchestration only for managed multi-chat coordination. Use list_personalities, optionally filtered by roles, before choosing a personality profile. Never substitute a harness-native agent-spawn tool for suggest_task, and when a user names an Otto tool exactly, use that exact Otto tool.";
 export const ORCHESTRATOR_METHOD_DIRECTIVE = "You are the orchestrator - the team's sole conductor. Choose tools because the task needs their specific capability, never because a tool is available or named. " +
-    "Do a small, self-contained task directly. Use create_agent only for an independently executable piece of active work that benefits from a dedicated worker. Use spawn_task only to preserve a concrete, out-of-scope follow-up for later. Use start_run only when the active work needs a declared multi-agent plan with daemon-managed fan-out, gathering, judging, loops, or approval gates. " +
-    "For work that genuinely needs orchestration: (1) if the shape is unclear, dispatch a researcher to survey and a planner to draft a typed plan; (2) declare that plan as a Run with start_run - phases typed research/plan/implement/design/verify/gate/deliver, fanning out candidates where several angles help and attaching a judger to grade them, looping until enough pass; (3) put a gate before irreversible or costly steps so the user approves; (4) synthesize the passing results into the deliverable. " +
+    "Do a small, self-contained task directly. Use create_chat only for an independently executable piece of active work that benefits from its own chat. Use suggest_task only to preserve a concrete, out-of-scope follow-up for later. Use start_orchestration only when the active work needs a declared multi-chat plan with daemon-managed fan-out, gathering, judging, loops, or approval gates. " +
+    "For work that genuinely needs orchestration: (1) if the shape is unclear, dispatch research and planning chats; (2) declare the plan with start_orchestration - phases typed research/plan/implement/design/verify/gate/deliver, fanning out where several angles help and attaching a judger to grade them, looping until enough pass; (3) put a gate before irreversible or costly steps so the user approves; (4) synthesize the passing results into the deliverable. " +
     "Every phase maps to a teammate's role; if the active team lacks a role a phase needs, say so plainly and stop rather than papering over the gap.";
 /**
  * The in-context "role directive" injected into a personality's system prompt at
  * spawn. The orchestrator gets the full conductor method; other coordinators
- * (chatter/artificer/scheduler) get a lighter delegate nudge; focused workers
+ * (chatter/artificer/scheduler) get a lighter delegate nudge; focused personalities
  * are told to stay on the task someone is waiting on. Roleless spawns get
  * nothing. This is guidance, not a gate - the tools stay available either way.
  */
@@ -137,9 +130,9 @@ export function composeRoleFocusDirective(roles) {
         return `${ORCHESTRATOR_METHOD_DIRECTIVE} (Your roles: ${roleList}.)`;
     }
     if (normalized.some((role) => PERSONALITY_ROLE_INFO[role].tier === "coordinator")) {
-        return `You are a coordinator personality (roles: ${roleList}). You front interactive work and may delegate when the task benefits from it: use list_personalities to see who else is available, then either do the work directly, spawn a dedicated worker for an independent active piece, or hand off genuinely multi-agent work to the team's orchestrator.`;
+        return `You are a coordinator personality (roles: ${roleList}). You front interactive work and may delegate when the task benefits from it: use list_personalities to see who else is available, then either do the work directly, create a child chat for an independent active piece, or hand off genuinely multi-chat work to the team's orchestrator.`;
     }
-    return `You are a focused worker personality (roles: ${roleList}). Someone is waiting on this specific task - stay on it and finish it. You can still call list_personalities to see the roster, but don't spawn sub-agents or start side workflows unless it is genuinely essential to completing this job.`;
+    return `You are a focused personality (roles: ${roleList}). Someone is waiting on this specific task - stay on it and finish it. You can still call list_personalities to see the roster, but don't create child chats or start side workflows unless it is genuinely essential to completing this job.`;
 }
 /**
  * Decide whether a personality is usable against a provider's current snapshot.

package/dist/agent-queue.d.ts

@@ -0,0 +1,87 @@
+import { z } from "zod";
+/**
+ * Otto steer-queue wire schemas: the agent.queue.* remove, reorder and clear RPCs and the queued-message payload. Fork-only capability, so it owns its schemas; messages.ts re-exports them.
+ */
+/**
+ * One message parked for delivery as an agent's NEXT turn (`delivery: "queue"`).
+ * The daemon owns the queue; this is the read-only projection the Queue track
+ * renders. Declared above AgentSnapshotPayloadSchema - zod-aot emits schemas in
+ * source order, so a forward reference is a build-time ReferenceError.
+ */
+export declare const QueuedAgentMessagePayloadSchema: z.ZodObject<{
+    id: z.ZodString;
+    preview: z.ZodString;
+    enqueuedAt: z.ZodString;
+    attachmentCount: z.ZodOptional<z.ZodNumber>;
+    source: z.ZodOptional<z.ZodEnum<{
+        user: "user";
+        system: "system";
+    }>>;
+}, z.core.$strip>;
+/** Pull one message back out of an agent's queue (Queue-track edit / send now). */
+export declare const AgentQueueRemoveRequestMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"agent.queue.remove.request">;
+    requestId: z.ZodString;
+    agentId: z.ZodString;
+    messageId: z.ZodString;
+}, z.core.$strip>;
+/**
+ * Move one queued message to a different position in an agent's queue.
+ *
+ * Order is what the queue means, so this is the edit that changes the next
+ * turn's content without changing the queue's membership. The daemon resolves
+ * `messageId` fresh and clamps `toIndex`, so a client acting on a snapshot that
+ * is one drain stale reorders what is actually there or reports `moved: false`.
+ * COMPAT(steerQueueReorder): added in v0.6.9, drop the gate when floor >= v0.6.9.
+ */
+export declare const AgentQueueReorderRequestMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"agent.queue.reorder.request">;
+    requestId: z.ZodString;
+    agentId: z.ZodString;
+    messageId: z.ZodString;
+    toIndex: z.ZodNumber;
+}, z.core.$strip>;
+/** Drop every message queued behind an agent's current turn. */
+export declare const AgentQueueClearRequestMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"agent.queue.clear.request">;
+    requestId: z.ZodString;
+    agentId: z.ZodString;
+}, z.core.$strip>;
+export declare const AgentQueueRemoveResponseMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"agent.queue.remove.response">;
+    payload: z.ZodObject<{
+        requestId: z.ZodString;
+        agentId: z.ZodString;
+        removed: z.ZodNullable<z.ZodObject<{
+            id: z.ZodString;
+            text: z.ZodString;
+        }, z.core.$strip>>;
+        error: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const AgentQueueReorderResponseMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"agent.queue.reorder.response">;
+    payload: z.ZodObject<{
+        requestId: z.ZodString;
+        agentId: z.ZodString;
+        moved: z.ZodBoolean;
+        error: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const AgentQueueClearResponseMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"agent.queue.clear.response">;
+    payload: z.ZodObject<{
+        requestId: z.ZodString;
+        agentId: z.ZodString;
+        clearedCount: z.ZodNumber;
+        error: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type QueuedAgentMessagePayload = z.infer<typeof QueuedAgentMessagePayloadSchema>;
+export type AgentQueueRemoveRequestMessage = z.infer<typeof AgentQueueRemoveRequestMessageSchema>;
+export type AgentQueueRemoveResponseMessage = z.infer<typeof AgentQueueRemoveResponseMessageSchema>;
+export type AgentQueueReorderRequestMessage = z.infer<typeof AgentQueueReorderRequestMessageSchema>;
+export type AgentQueueReorderResponseMessage = z.infer<typeof AgentQueueReorderResponseMessageSchema>;
+export type AgentQueueClearRequestMessage = z.infer<typeof AgentQueueClearRequestMessageSchema>;
+export type AgentQueueClearResponseMessage = z.infer<typeof AgentQueueClearResponseMessageSchema>;
+//# sourceMappingURL=agent-queue.d.ts.map

package/dist/agent-queue.js

@@ -0,0 +1,106 @@
+import { z } from "zod";
+/**
+ * Otto steer-queue wire schemas: the agent.queue.* remove, reorder and clear RPCs and the queued-message payload. Fork-only capability, so it owns its schemas; messages.ts re-exports them.
+ */
+/**
+ * One message parked for delivery as an agent's NEXT turn (`delivery: "queue"`).
+ * The daemon owns the queue; this is the read-only projection the Queue track
+ * renders. Declared above AgentSnapshotPayloadSchema - zod-aot emits schemas in
+ * source order, so a forward reference is a build-time ReferenceError.
+ */
+export const QueuedAgentMessagePayloadSchema = z.object({
+    id: z.string(),
+    /** Leading text of the message, truncated for display. */
+    preview: z.string(),
+    enqueuedAt: z.string(),
+    attachmentCount: z.number().int().nonnegative().optional(),
+    /**
+     * Who parked the message. Absent (from an older daemon) or "user" is a normal
+     * user turn; "system" marks a system-injected entry (a chat mention, a
+     * scheduled fire) that the daemon's drain never merges into a user turn - the
+     * client must likewise exclude it from "Send all".
+     */
+    source: z.enum(["user", "system"]).optional(),
+});
+/** Pull one message back out of an agent's queue (Queue-track edit / send now). */
+export const AgentQueueRemoveRequestMessageSchema = z.object({
+    type: z.literal("agent.queue.remove.request"),
+    requestId: z.string(),
+    /** Accepts full ID, unique prefix, or exact full title (server resolves). */
+    agentId: z.string(),
+    /** The queued message's `id` from `AgentSnapshotPayload.queuedMessages`. */
+    messageId: z.string(),
+});
+/**
+ * Move one queued message to a different position in an agent's queue.
+ *
+ * Order is what the queue means, so this is the edit that changes the next
+ * turn's content without changing the queue's membership. The daemon resolves
+ * `messageId` fresh and clamps `toIndex`, so a client acting on a snapshot that
+ * is one drain stale reorders what is actually there or reports `moved: false`.
+ * COMPAT(steerQueueReorder): added in v0.6.9, drop the gate when floor >= v0.6.9.
+ */
+export const AgentQueueReorderRequestMessageSchema = z.object({
+    type: z.literal("agent.queue.reorder.request"),
+    requestId: z.string(),
+    /** Accepts full ID, unique prefix, or exact full title (server resolves). */
+    agentId: z.string(),
+    /** The queued message's `id` from `AgentSnapshotPayload.queuedMessages`. */
+    messageId: z.string(),
+    /** Zero-based destination, clamped to the queue's current length. */
+    toIndex: z.number().int().nonnegative(),
+});
+/** Drop every message queued behind an agent's current turn. */
+export const AgentQueueClearRequestMessageSchema = z.object({
+    type: z.literal("agent.queue.clear.request"),
+    requestId: z.string(),
+    /** Accepts full ID, unique prefix, or exact full title (server resolves). */
+    agentId: z.string(),
+});
+export const AgentQueueRemoveResponseMessageSchema = z.object({
+    type: z.literal("agent.queue.remove.response"),
+    payload: z.object({
+        requestId: z.string(),
+        agentId: z.string(),
+        /**
+         * The removed message's text, handed back so the composer can put it back
+         * in the box for editing or re-send it right away. Null when the id was
+         * already gone - the turn drained it while the tap was in flight.
+         * Attachments are not echoed: the client that queued the message keeps its
+         * own local copy keyed by `id` (see the composer's queued-attachment
+         * sidecar), and a client that never queued it has nothing to restore.
+         */
+        removed: z
+            .object({
+            id: z.string(),
+            text: z.string(),
+        })
+            .nullable(),
+        error: z.string().nullable(),
+    }),
+});
+export const AgentQueueReorderResponseMessageSchema = z.object({
+    type: z.literal("agent.queue.reorder.response"),
+    payload: z.object({
+        requestId: z.string(),
+        agentId: z.string(),
+        /**
+         * False when the id was already gone (the turn drained it while the tap was
+         * in flight) or the entry was already at that position. The authoritative
+         * order arrives on the agent snapshot either way, so a client only needs
+         * this to decide whether to surface an error.
+         */
+        moved: z.boolean(),
+        error: z.string().nullable(),
+    }),
+});
+export const AgentQueueClearResponseMessageSchema = z.object({
+    type: z.literal("agent.queue.clear.response"),
+    payload: z.object({
+        requestId: z.string(),
+        agentId: z.string(),
+        clearedCount: z.number().int().nonnegative(),
+        error: z.string().nullable(),
+    }),
+});
+//# sourceMappingURL=agent-queue.js.map

package/dist/agent-types.d.ts

@@ -77,6 +77,8 @@ export type ModelTier = "deep" | "standard" | "fast";
 export interface AgentModelDefinition {
     provider: AgentProvider;
     id: string;
+    aliases?: string[];
+    isSelectable?: boolean;
     label: string;
     description?: string;
     /** Catalog-owned model-family identity, currently emitted by Otto Brain only. */
@@ -372,6 +374,13 @@ export interface CompactionTimelineItem {
     preTokens?: number;
     postTokens?: number;
 }
+export interface AgentTaskItem {
+    text: string;
+    completed: boolean;
+    id?: string;
+    status?: "pending" | "in_progress" | "completed";
+    activeForm?: string;
+}
 export type AgentTimelineItem = {
     type: "user_message";
     text: string;
@@ -386,10 +395,7 @@ export type AgentTimelineItem = {
     text: string;
 } | ToolCallTimelineItem | {
     type: "todo";
-    items: {
-        text: string;
-        completed: boolean;
-    }[];
+    items: AgentTaskItem[];
 } | {
     type: "error";
     message: string;
@@ -581,6 +587,18 @@ export interface AgentRunResult {
 export declare const WORKSPACE_ACCESS_LEVELS: readonly ["none", "read", "write"];
 export type WorkspaceAccess = (typeof WORKSPACE_ACCESS_LEVELS)[number];
 export declare function isWorkspaceAccess(value: unknown): value is WorkspaceAccess;
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type ProviderOptions = Record<string, JsonValue>;
+export interface McpToolRef {
+    kind: "mcp";
+    server: string;
+    tool: string;
+}
+export interface ToolPolicy {
+    preapproved: McpToolRef[];
+}
 export interface AgentSessionConfig {
     provider: AgentProvider;
     cwd: string;
@@ -609,6 +627,8 @@ export interface AgentSessionConfig {
         codex?: AgentMetadata;
         claude?: AgentMetadata;
     };
+    providerOptions?: ProviderOptions;
+    toolPolicy?: ToolPolicy;
     mcpServers?: Record<string, McpServerConfig>;
     /**
      * Internal agents are hidden from listings and don't trigger notifications.

package/dist/binary-frames/terminal.d.ts

@@ -3,6 +3,10 @@ import { TerminalStateSchema } from "../messages.js";
 export declare const TerminalStreamResizeSchema: z.ZodObject<{
     rows: z.ZodNumber;
     cols: z.ZodNumber;
+    intent: z.ZodOptional<z.ZodEnum<{
+        claim: "claim";
+        update: "update";
+    }>>;
 }, z.core.$strip>;
 export declare const TerminalStreamOpcode: {
     readonly Output: 1;

package/dist/binary-frames/terminal.js

@@ -3,6 +3,7 @@ import { TerminalStateSchema } from "../messages.js";
 export const TerminalStreamResizeSchema = z.object({
     rows: z.number().int().positive(),
     cols: z.number().int().positive(),
+    intent: z.enum(["claim", "update"]).optional(),
 });
 export const TerminalStreamOpcode = {
     Output: 0x01,