@otto-code/protocol 0.5.2 → 0.5.4

package/dist/messages.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { TerminalActivitySchema } from "./terminal-activity.js";
+import { RunSchema } from "./orchestration.js";
 import { ArtifactMetadataSchema } from "./artifacts/types.js";
 import { ArtifactListRequestSchema, ArtifactCreateRequestSchema, ArtifactUpdateRequestSchema, ArtifactRegenerateRequestSchema, ArtifactCancelRequestSchema, ArtifactDeleteRequestSchema, ArtifactStarRequestSchema, ArtifactGetContentRequestSchema, ArtifactListResponseSchema, ArtifactCreateResponseSchema, ArtifactUpdateResponseSchema, ArtifactRegenerateResponseSchema, ArtifactCancelResponseSchema, ArtifactDeleteResponseSchema, ArtifactStarResponseSchema, ArtifactGetContentResponseSchema, ArtifactCreatedNotificationSchema, ArtifactUpdatedNotificationSchema, ArtifactDeletedNotificationSchema, } from "./artifacts/rpc-schemas.js";
 import { CLIENT_CAPS } from "./client-capabilities.js";
@@ -139,13 +140,20 @@ export const MutableGitHostingConfigSchema = z
 // agent-personalities.ts) so personalities persisted before the split keep their
 // role rather than silently losing it.
 export const PERSONALITY_ROLES = [
+    // Surfaces — the interactive / host-facing entry points.
     "chatter",
     "artificer",
     "scheduler",
-    "writer",
-    "coder",
+    // Thinking workers — read-only, return structured findings, never edit.
+    "researcher",
+    "planner",
     "judger",
     "advisor",
+    // Making workers — produce code, design, or short text.
+    "coder",
+    "designer",
+    "writer",
+    // Conductor — the sole role whose whole job is planning and driving a team.
     "orchestrator",
 ];
 // Two glow colors for the personality's thinking spinner (BlobLoader glowA/glowB).
@@ -1321,6 +1329,38 @@ export const ProviderUsageListRequestMessageSchema = z.object({
     type: z.literal("provider.usage.list.request"),
     requestId: z.string(),
 });
+// Daemon-wide "fun stats" counters — see docs/data-model.md ActivityStatsStore.
+// Every field defaults to 0 so old and new daemons/clients stay compatible as
+// counters are added later.
+export const ActivityCountersSchema = z.object({
+    messagesSent: z.number().default(0),
+    messagesReceived: z.number().default(0),
+    tokensSent: z.number().default(0),
+    tokensReceived: z.number().default(0),
+    agentsCreated: z.number().default(0),
+    runsOrchestrated: z.number().default(0),
+    subagentsInvoked: z.number().default(0),
+    backgroundTasksInvoked: z.number().default(0),
+    thoughts: z.number().default(0),
+    toolsCalled: z.number().default(0),
+    artifactsCreated: z.number().default(0),
+    schedulesExecuted: z.number().default(0),
+});
+export const StatsActivityGetRequestMessageSchema = z.object({
+    type: z.literal("stats.activity.get.request"),
+    requestId: z.string(),
+});
+export const StatsActivityGetResponseMessageSchema = z.object({
+    type: z.literal("stats.activity.get.response"),
+    payload: z.object({
+        requestId: z.string(),
+        today: ActivityCountersSchema,
+        yesterday: ActivityCountersSchema,
+        last7Days: ActivityCountersSchema,
+        last30Days: ActivityCountersSchema,
+        allTime: ActivityCountersSchema,
+    }),
+});
 export const AgentContextGetUsageRequestMessageSchema = z.object({
     type: z.literal("agent.context.get_usage.request"),
     agentId: z.string(),
@@ -1456,6 +1496,56 @@ export const AgentSubagentStopResponseMessageSchema = z.object({
     type: z.literal("agent.subagent.stop.response"),
     payload: AgentActionResponsePayloadSchema,
 });
+// A background shell task launched by a provider's own Bash tool (Claude:
+// run_in_background). Not an agent, not a subagent — a plain shell process
+// the daemon tracks for the parent agent's Background Tasks track.
+// COMPAT(backgroundShellTasks): added in v0.5.3, drop the gate when daemon floor >= v0.5.3.
+export const BackgroundShellTaskInfoSchema = z.object({
+    id: z.string(),
+    parentAgentId: z.string(),
+    provider: z.string(),
+    command: z.string().optional(),
+    description: z.string().optional(),
+    status: z.enum(["running", "idle", "error", "closed"]),
+    requiresAttention: z.boolean().optional(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+    archivedAt: z.string().optional(),
+});
+// Pushed with the full current set of background shell tasks for a parent
+// agent whenever any of them changes (start/progress/settle/clear) — same
+// full-list reconciliation shape as TerminalsChangedSchema.
+export const BackgroundShellTasksChangedSchema = z.object({
+    type: z.literal("background_shell_tasks_changed"),
+    payload: z.object({
+        parentAgentId: z.string(),
+        tasks: z.array(BackgroundShellTaskInfoSchema),
+    }),
+});
+// Stop a running background shell task. The daemon resolves it to the owning
+// provider session's task and calls stopTask, same as agent.subagent.stop.
+export const AgentBackgroundTaskStopRequestMessageSchema = z.object({
+    type: z.literal("agent.background_task.stop.request"),
+    parentAgentId: z.string(),
+    taskId: z.string(),
+    requestId: z.string(),
+});
+export const AgentBackgroundTaskStopResponseMessageSchema = z.object({
+    type: z.literal("agent.background_task.stop.response"),
+    payload: AgentActionResponsePayloadSchema,
+});
+// Clear one or more terminal background shell tasks from the track. Still-live
+// tasks are stopped best-effort first.
+export const AgentBackgroundTaskClearRequestMessageSchema = z.object({
+    type: z.literal("agent.background_task.clear.request"),
+    parentAgentId: z.string(),
+    taskIds: z.array(z.string()),
+    requestId: z.string(),
+});
+export const AgentBackgroundTaskClearResponseMessageSchema = z.object({
+    type: z.literal("agent.background_task.clear.response"),
+    payload: AgentActionResponsePayloadSchema,
+});
 // Switch a running agent to an Agent Personality (or clear with null). The
 // daemon re-resolves the id against the roster + the agent's cwd provider
 // snapshot and applies the full personality live — system prompt, identity
@@ -1622,6 +1712,80 @@ export const CheckoutGitLogAppendedNotificationSchema = z.object({
         entries: z.array(GitOperationLogEntrySchema),
     }),
 });
+// ── Orchestration runs (agent-orchestration) ────────────────────────────────
+// Daemon-owned multi-agent Run projection + control. Gated by
+// server_info.features.agentOrchestration. See projects/agent-orchestration.
+export const RunsGetSnapshotRequestSchema = z.object({
+    type: z.literal("runs.get_snapshot.request"),
+    requestId: z.string(),
+});
+export const RunsGetSnapshotResponseSchema = z.object({
+    type: z.literal("runs.get_snapshot.response"),
+    payload: z.object({
+        runs: z.array(RunSchema),
+        requestId: z.string(),
+    }),
+});
+// Single-run push, broadcast on every phase/status change. Clients merge by id.
+export const RunsUpdatedNotificationSchema = z.object({
+    type: z.literal("runs.updated.notification"),
+    payload: z.object({
+        run: RunSchema,
+    }),
+});
+// Answer an attended run's `gate` phase (approve or reject, with an optional
+// note). `accepted` is false when the run wasn't awaiting a gate.
+export const RunsGateRespondRequestSchema = z.object({
+    type: z.literal("runs.gate_respond.request"),
+    runId: z.string(),
+    phaseId: z.string(),
+    approved: z.boolean(),
+    note: z.string().optional(),
+    requestId: z.string(),
+});
+export const RunsGateRespondResponseSchema = z.object({
+    type: z.literal("runs.gate_respond.response"),
+    payload: z.object({
+        runId: z.string(),
+        accepted: z.boolean(),
+        requestId: z.string(),
+    }),
+});
+export const RunsCancelRequestSchema = z.object({
+    type: z.literal("runs.cancel.request"),
+    runId: z.string(),
+    requestId: z.string(),
+});
+export const RunsCancelResponseSchema = z.object({
+    type: z.literal("runs.cancel.response"),
+    payload: z.object({
+        runId: z.string(),
+        canceled: z.boolean(),
+        requestId: z.string(),
+    }),
+});
+// Delete every finished (done/failed/canceled) run from disk and memory.
+// Active/paused runs are left untouched. Gated by
+// server_info.features.runsClear.
+export const RunsClearRequestSchema = z.object({
+    type: z.literal("runs.clear.request"),
+    requestId: z.string(),
+});
+export const RunsClearResponseSchema = z.object({
+    type: z.literal("runs.clear.response"),
+    payload: z.object({
+        runIds: z.array(z.string()),
+        requestId: z.string(),
+    }),
+});
+// Broadcast to every connected client (including the requester) so all
+// caches drop the same runs, mirroring runs.updated.notification's upsert.
+export const RunsClearedNotificationSchema = z.object({
+    type: z.literal("runs.cleared.notification"),
+    payload: z.object({
+        runIds: z.array(z.string()),
+    }),
+});
 // Namespaced successor to checkout_commit_request: per-file selection and
 // structured errors. Gated by server_info.features.checkoutGitCommit; the flat
 // RPC stays accepted for old clients.
@@ -2320,6 +2484,7 @@ export const SessionInboundMessageSchema = z.discriminatedUnion("type", [
     RefreshProvidersSnapshotRequestMessageSchema,
     ProviderDiagnosticRequestMessageSchema,
     ProviderUsageListRequestMessageSchema,
+    StatsActivityGetRequestMessageSchema,
     AgentContextGetUsageRequestMessageSchema,
     ResumeAgentRequestMessageSchema,
     ImportAgentRequestMessageSchema,
@@ -2336,6 +2501,8 @@ export const SessionInboundMessageSchema = z.discriminatedUnion("type", [
     SetAgentFeatureRequestMessageSchema,
     AgentDetachRequestMessageSchema,
     AgentSubagentStopRequestMessageSchema,
+    AgentBackgroundTaskStopRequestMessageSchema,
+    AgentBackgroundTaskClearRequestMessageSchema,
     AgentPersonalitySetRequestMessageSchema,
     AgentRewindRequestMessageSchema,
     AgentPermissionResponseMessageSchema,
@@ -2347,6 +2514,10 @@ export const SessionInboundMessageSchema = z.discriminatedUnion("type", [
     CheckoutGitCommitAgentRequestSchema,
     CheckoutGitRollbackRequestSchema,
     CheckoutGitGetOperationLogRequestSchema,
+    RunsGetSnapshotRequestSchema,
+    RunsGateRespondRequestSchema,
+    RunsCancelRequestSchema,
+    RunsClearRequestSchema,
     CheckoutMergeRequestSchema,
     CheckoutMergeFromBaseRequestSchema,
     CheckoutPullRequestSchema,
@@ -2623,6 +2794,8 @@ export const ServerInfoStatusPayloadSchema = z
         artifacts: z.boolean().optional(),
         // COMPAT(observedSubagents): added in v0.4.3, drop the gate when daemon floor >= v0.4.3.
         observedSubagents: z.boolean().optional(),
+        // COMPAT(backgroundShellTasks): added in v0.5.3, drop the gate when daemon floor >= v0.5.3.
+        backgroundShellTasks: z.boolean().optional(),
         // COMPAT(textEditor): added in v0.4.4, drop the gate when daemon floor >= v0.4.4.
         textEditor: z.boolean().optional(),
         // COMPAT(projectSearch): added in v0.4.4, drop the gate when daemon floor >= v0.4.4.
@@ -2653,6 +2826,12 @@ export const ServerInfoStatusPayloadSchema = z
         agentTeams: z.boolean().optional(),
         // COMPAT(modelTierOverrides): added in v0.5.2, drop the gate when daemon floor >= v0.5.2.
         modelTierOverrides: z.boolean().optional(),
+        // COMPAT(agentOrchestration): added in v0.5.3, drop the gate when daemon floor >= v0.5.3.
+        agentOrchestration: z.boolean().optional(),
+        // COMPAT(activityStats): added in v0.5.3, drop the gate when daemon floor >= v0.5.3.
+        activityStats: z.boolean().optional(),
+        // COMPAT(runsClear): added in v0.5.3, drop the gate when daemon floor >= v0.5.3.
+        runsClear: z.boolean().optional(),
     })
         .optional(),
 })
@@ -4807,6 +4986,9 @@ export const SessionOutboundMessageSchema = z.discriminatedUnion("type", [
     SetAgentFeatureResponseMessageSchema,
     AgentDetachResponseMessageSchema,
     AgentSubagentStopResponseMessageSchema,
+    AgentBackgroundTaskStopResponseMessageSchema,
+    AgentBackgroundTaskClearResponseMessageSchema,
+    BackgroundShellTasksChangedSchema,
     AgentPersonalitySetResponseMessageSchema,
     AgentRewindResponseMessageSchema,
     UpdateAgentResponseMessageSchema,
@@ -4829,6 +5011,12 @@ export const SessionOutboundMessageSchema = z.discriminatedUnion("type", [
     CheckoutGitRollbackResponseSchema,
     CheckoutGitGetOperationLogResponseSchema,
     CheckoutGitLogAppendedNotificationSchema,
+    RunsGetSnapshotResponseSchema,
+    RunsUpdatedNotificationSchema,
+    RunsGateRespondResponseSchema,
+    RunsCancelResponseSchema,
+    RunsClearResponseSchema,
+    RunsClearedNotificationSchema,
     CheckoutMergeResponseSchema,
     CheckoutMergeFromBaseResponseSchema,
     CheckoutPullResponseSchema,
@@ -4881,6 +5069,7 @@ export const SessionOutboundMessageSchema = z.discriminatedUnion("type", [
     RefreshProvidersSnapshotResponseMessageSchema,
     ProviderDiagnosticResponseMessageSchema,
     ProviderUsageListResponseMessageSchema,
+    StatsActivityGetResponseMessageSchema,
     AgentContextGetUsageResponseMessageSchema,
     ListCommandsResponseSchema,
     ListTerminalsResponseSchema,

package/dist/orchestration.d.ts

@@ -0,0 +1,152 @@
+import { z } from "zod";
+export declare const RUN_PHASE_TYPES: readonly ["research", "plan", "refactor", "implement", "design", "verify", "gate", "deliver"];
+export type RunPhaseType = (typeof RUN_PHASE_TYPES)[number];
+export declare function isRunPhaseType(value: string): value is RunPhaseType;
+/** The role a phase type dispatches to by default (null for human `gate`). */
+export declare function defaultRoleForPhaseType(type: RunPhaseType): string | null;
+export declare const RUN_PHASE_STATUSES: readonly ["pending", "running", "blocked", "done", "failed", "skipped"];
+export type RunPhaseStatus = (typeof RUN_PHASE_STATUSES)[number];
+export declare const RUN_STATUSES: readonly ["pending", "running", "paused", "done", "failed", "canceled"];
+export type RunStatus = (typeof RUN_STATUSES)[number];
+export declare function isRunPhaseStatus(value: string): value is RunPhaseStatus;
+export declare function isRunStatus(value: string): value is RunStatus;
+/** Terminal run statuses — no further phases will run. */
+export declare function isTerminalRunStatus(value: string): boolean;
+/** Terminal phase statuses — the phase will not change again on its own. */
+export declare function isTerminalPhaseStatus(value: string): boolean;
+export declare const RunPhaseJudgeSpecSchema: z.ZodObject<{
+    role: z.ZodOptional<z.ZodString>;
+    criteria: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$loose>;
+export declare const RunPhaseDeclarationSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodString;
+    title: z.ZodString;
+    task: z.ZodString;
+    role: z.ZodOptional<z.ZodString>;
+    dependsOn: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    fanOut: z.ZodOptional<z.ZodNumber>;
+    keepBest: z.ZodOptional<z.ZodNumber>;
+    judge: z.ZodOptional<z.ZodObject<{
+        role: z.ZodOptional<z.ZodString>;
+        criteria: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export type RunPhaseDeclaration = z.infer<typeof RunPhaseDeclarationSchema>;
+export declare const RunPlanSchema: z.ZodObject<{
+    title: z.ZodString;
+    requirements: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    autopilot: z.ZodOptional<z.ZodBoolean>;
+    phases: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodString;
+        title: z.ZodString;
+        task: z.ZodString;
+        role: z.ZodOptional<z.ZodString>;
+        dependsOn: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        fanOut: z.ZodOptional<z.ZodNumber>;
+        keepBest: z.ZodOptional<z.ZodNumber>;
+        judge: z.ZodOptional<z.ZodObject<{
+            role: z.ZodOptional<z.ZodString>;
+            criteria: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$loose>>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export type RunPlan = z.infer<typeof RunPlanSchema>;
+export declare const RunPhaseCandidateSchema: z.ZodObject<{
+    agentId: z.ZodString;
+    personalityId: z.ZodOptional<z.ZodString>;
+    verdict: z.ZodOptional<z.ZodObject<{
+        verdict: z.ZodString;
+        score: z.ZodOptional<z.ZodNumber>;
+        criteria: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            met: z.ZodBoolean;
+            evidence: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>>;
+        summary: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    summary: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type RunPhaseCandidate = z.infer<typeof RunPhaseCandidateSchema>;
+export declare const RunPhaseSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodString;
+    title: z.ZodString;
+    task: z.ZodString;
+    status: z.ZodString;
+    assigneeRole: z.ZodOptional<z.ZodString>;
+    dependsOn: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    fanOut: z.ZodOptional<z.ZodNumber>;
+    keepBest: z.ZodOptional<z.ZodNumber>;
+    candidates: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        agentId: z.ZodString;
+        personalityId: z.ZodOptional<z.ZodString>;
+        verdict: z.ZodOptional<z.ZodObject<{
+            verdict: z.ZodString;
+            score: z.ZodOptional<z.ZodNumber>;
+            criteria: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                name: z.ZodString;
+                met: z.ZodBoolean;
+                evidence: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>>>;
+            summary: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>;
+        summary: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    notes: z.ZodOptional<z.ZodString>;
+    startedAt: z.ZodOptional<z.ZodString>;
+    completedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type RunPhase = z.infer<typeof RunPhaseSchema>;
+export declare const RunSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    status: z.ZodString;
+    requirements: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    autopilot: z.ZodOptional<z.ZodBoolean>;
+    phases: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodString;
+        title: z.ZodString;
+        task: z.ZodString;
+        status: z.ZodString;
+        assigneeRole: z.ZodOptional<z.ZodString>;
+        dependsOn: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        fanOut: z.ZodOptional<z.ZodNumber>;
+        keepBest: z.ZodOptional<z.ZodNumber>;
+        candidates: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            agentId: z.ZodString;
+            personalityId: z.ZodOptional<z.ZodString>;
+            verdict: z.ZodOptional<z.ZodObject<{
+                verdict: z.ZodString;
+                score: z.ZodOptional<z.ZodNumber>;
+                criteria: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    name: z.ZodString;
+                    met: z.ZodBoolean;
+                    evidence: z.ZodOptional<z.ZodString>;
+                }, z.core.$loose>>>;
+                summary: z.ZodOptional<z.ZodString>;
+            }, z.core.$loose>>;
+            summary: z.ZodOptional<z.ZodString>;
+        }, z.core.$loose>>>;
+        notes: z.ZodOptional<z.ZodString>;
+        startedAt: z.ZodOptional<z.ZodString>;
+        completedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>>;
+    conductorAgentId: z.ZodOptional<z.ZodString>;
+    cwd: z.ZodOptional<z.ZodString>;
+    workspaceId: z.ZodOptional<z.ZodString>;
+    teamId: z.ZodOptional<z.ZodString>;
+    teamName: z.ZodOptional<z.ZodString>;
+    error: z.ZodOptional<z.ZodString>;
+    summary: z.ZodOptional<z.ZodString>;
+    summaryStatus: z.ZodOptional<z.ZodString>;
+    agentCount: z.ZodOptional<z.ZodNumber>;
+    createdAt: z.ZodOptional<z.ZodString>;
+    updatedAt: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type Run = z.infer<typeof RunSchema>;
+export declare const RUN_SUMMARY_STATUSES: readonly ["pending", "ready", "failed"];
+export type RunSummaryStatus = (typeof RUN_SUMMARY_STATUSES)[number];
+//# sourceMappingURL=orchestration.d.ts.map

package/dist/orchestration.js

@@ -0,0 +1,199 @@
+import { z } from "zod";
+import { JudgeVerdictSchema } from "./judge-verdict.js";
+// The orchestration data model — a daemon-owned "Run": one execution of a
+// declared multi-agent plan, and its observable/resumable projection to clients.
+// See projects/agent-orchestration/agent-orchestration.md. This is Otto's
+// provider-agnostic answer to a harness "Workflow": the conductor (an
+// orchestrator-role agent) DECLARES the shape (typed phases, assignments, the
+// loop target) via `start_run`, and the daemon runtime drives control flow —
+// fan-out, gather-barrier, gate, loop — in code, so orchestrating is cheaper
+// than hand-tracking N agent ids across async notifications.
+//
+// Wire-forward-compat, per the protocol contract: every open vocabulary (phase
+// type, phase/run status) rides as a plain string leaf validated by a
+// normalizer, never a z.enum, so the daemon can grow the vocabulary without
+// breaking an older client's parse. Objects `.passthrough()`; no transforms.
+// ── The deterministic plan vocabulary ──────────────────────────────────────
+// Fixed phase types used by the runtime (NOT roles). The dispatcher maps a phase
+// type to the role that fills it: research→researcher, plan→planner,
+// refactor/implement→coder, design→designer, verify→judger, gate→human (no
+// agent), deliver→coder/writer.
+export const RUN_PHASE_TYPES = [
+    "research",
+    "plan",
+    "refactor",
+    "implement",
+    "design",
+    "verify",
+    "gate",
+    "deliver",
+];
+const PHASE_TYPE_SET = new Set(RUN_PHASE_TYPES);
+export function isRunPhaseType(value) {
+    return PHASE_TYPE_SET.has(value);
+}
+// The default role that fills each phase type. `gate` has no role — it's a human
+// approval point. `deliver` defaults to coder (a writer may cover small text
+// deliverables; the conductor can override per phase).
+const PHASE_TYPE_DEFAULT_ROLE = {
+    research: "researcher",
+    plan: "planner",
+    refactor: "coder",
+    implement: "coder",
+    design: "designer",
+    verify: "judger",
+    gate: null,
+    deliver: "coder",
+};
+/** The role a phase type dispatches to by default (null for human `gate`). */
+export function defaultRoleForPhaseType(type) {
+    return PHASE_TYPE_DEFAULT_ROLE[type];
+}
+// ── Phase + run status (open vocabularies, plain-string on the wire) ─────────
+export const RUN_PHASE_STATUSES = [
+    "pending",
+    "running",
+    "blocked", // a gate phase awaiting human approval
+    "done",
+    "failed",
+    "skipped",
+];
+export const RUN_STATUSES = [
+    "pending",
+    "running",
+    "paused", // stopped at an attended gate, awaiting the user
+    "done",
+    "failed",
+    "canceled",
+];
+const PHASE_STATUS_SET = new Set(RUN_PHASE_STATUSES);
+const RUN_STATUS_SET = new Set(RUN_STATUSES);
+export function isRunPhaseStatus(value) {
+    return PHASE_STATUS_SET.has(value);
+}
+export function isRunStatus(value) {
+    return RUN_STATUS_SET.has(value);
+}
+/** Terminal run statuses — no further phases will run. */
+export function isTerminalRunStatus(value) {
+    return value === "done" || value === "failed" || value === "canceled";
+}
+/** Terminal phase statuses — the phase will not change again on its own. */
+export function isTerminalPhaseStatus(value) {
+    return value === "done" || value === "failed" || value === "skipped";
+}
+// ── Declaration schema (the `start_run` input) ──────────────────────────────
+// What the conductor DECLARES. Kept minimal and schema-validated so a bad plan
+// is rejected at the tool boundary. `role` overrides the phase-type default;
+// `fanOut` spawns N parallel candidates; `judge` attaches a verify sub-step so a
+// making/research phase's output is graded and (with `keepBest`) looped until
+// enough candidates pass.
+export const RunPhaseJudgeSpecSchema = z
+    .object({
+    role: z.string().min(1).optional(),
+    criteria: z.array(z.string().min(1)).optional(),
+})
+    .passthrough();
+export const RunPhaseDeclarationSchema = z
+    .object({
+    // Caller-assigned id, referenced by other phases' `dependsOn`.
+    id: z.string().min(1),
+    type: z.string().min(1),
+    title: z.string().min(1),
+    // The instruction handed to the assigned agent(s) as their prompt.
+    task: z.string().min(1),
+    // Override the phase-type's default role (e.g. deliver→writer).
+    role: z.string().min(1).optional(),
+    // Phase ids that must reach a terminal state before this phase starts.
+    // Absent/empty ⇒ runs after the previous declared phase (linear default).
+    dependsOn: z.array(z.string().min(1)).optional(),
+    // Spawn N parallel candidates from the same task (different angles). 1 ⇒ solo.
+    fanOut: z.number().int().min(1).max(16).optional(),
+    // With a judge: keep the best N passers; if fewer pass, the runtime
+    // re-dispatches replacements until the target is met or a cap trips.
+    keepBest: z.number().int().min(1).max(16).optional(),
+    // Attach a structured-judge sub-step to a non-verify phase.
+    judge: RunPhaseJudgeSpecSchema.optional(),
+})
+    .passthrough();
+export const RunPlanSchema = z
+    .object({
+    title: z.string().min(1),
+    // Immutable acceptance criteria — the run is "not done until every one is
+    // met." Carried onto the Run and shown at gates.
+    requirements: z.array(z.string().min(1)).optional(),
+    // Attended by default: the run pauses at `gate` phases for the user.
+    // Autopilot runs straight through (eligibility enforced daemon-side).
+    autopilot: z.boolean().optional(),
+    phases: z.array(RunPhaseDeclarationSchema).min(1).max(64),
+})
+    .passthrough();
+// ── Projection schema (the Run the daemon persists + pushes to clients) ─────
+// One spawned candidate for a phase: the observable child agent plus, when the
+// phase judged it, that candidate's verdict.
+export const RunPhaseCandidateSchema = z
+    .object({
+    agentId: z.string().min(1),
+    // The personality that filled the role for this candidate, if resolved.
+    personalityId: z.string().min(1).optional(),
+    verdict: JudgeVerdictSchema.optional(),
+    // The candidate's final message (synthesis input); may be large — clients
+    // truncate for display.
+    summary: z.string().optional(),
+})
+    .passthrough();
+export const RunPhaseSchema = z
+    .object({
+    id: z.string().min(1),
+    type: z.string().min(1),
+    title: z.string().min(1),
+    task: z.string().min(1),
+    status: z.string().min(1),
+    // Resolved dispatch target. `assigneeRole` is what the type/override asked
+    // for; `candidates` are the spawned agents (>1 when fanned out).
+    assigneeRole: z.string().min(1).optional(),
+    dependsOn: z.array(z.string().min(1)).optional(),
+    fanOut: z.number().int().min(1).optional(),
+    keepBest: z.number().int().min(1).optional(),
+    candidates: z.array(RunPhaseCandidateSchema).optional(),
+    // Free-text runtime notes (why it blocked, which cap tripped, gap named).
+    notes: z.string().optional(),
+    startedAt: z.string().optional(),
+    completedAt: z.string().optional(),
+})
+    .passthrough();
+export const RunSchema = z
+    .object({
+    id: z.string().min(1),
+    title: z.string().min(1),
+    status: z.string().min(1),
+    // Immutable requirements block (see RunPlan.requirements).
+    requirements: z.array(z.string().min(1)).optional(),
+    autopilot: z.boolean().optional(),
+    phases: z.array(RunPhaseSchema).default([]),
+    // The conductor agent that owns this run, and the workspace it runs in.
+    conductorAgentId: z.string().min(1).optional(),
+    cwd: z.string().optional(),
+    workspaceId: z.string().optional(),
+    // The team that was active when this run started (id for a stable filter key,
+    // name for display). Absent on runs started without an active team.
+    teamId: z.string().min(1).optional(),
+    teamName: z.string().min(1).optional(),
+    // Set when the run ends in failure or a cap trips.
+    error: z.string().optional(),
+    // AI-generated, human-readable summary of the whole run (from a Writer
+    // personality). `summaryStatus` is a plain-string, forward-compat leaf:
+    // "pending" (being generated), "ready", or "failed". Both absent on daemons
+    // or runs without the run-summary feature.
+    summary: z.string().optional(),
+    summaryStatus: z.string().optional(),
+    // Total child agents this run spawned (makers + judgers) — a complexity
+    // signal surfaced in the Runs display. Grows as the run executes.
+    agentCount: z.number().int().min(0).optional(),
+    createdAt: z.string().optional(),
+    updatedAt: z.string().optional(),
+})
+    .passthrough();
+// Summary generation lifecycle (plain-string on the wire; see RunSchema.summaryStatus).
+export const RUN_SUMMARY_STATUSES = ["pending", "ready", "failed"];
+//# sourceMappingURL=orchestration.js.map

package/dist/provider-manifest.d.ts

@@ -8,6 +8,7 @@ export interface AgentModeVisuals {
 }
 export type AgentProviderModeDefinition = Omit<AgentMode, "icon" | "colorTier"> & AgentModeVisuals & {
     isUnattended?: boolean;
+    userSelectable?: boolean;
 };
 export interface AgentProviderDefinition {
     id: string;
@@ -30,5 +31,14 @@ export declare const AGENT_PROVIDER_IDS: string[];
 export declare const AgentProviderSchema: z.ZodString;
 export declare function isValidAgentProvider(value: string, validIds?: Iterable<string>): boolean;
 export declare function getUnattendedModeId(provider: string, definitions?: AgentProviderDefinition[]): string | undefined;
+/**
+ * Whether a user may pick this mode themselves. False only for modes explicitly
+ * flagged `userSelectable: false` in the static manifest (Claude "dontAsk") — a
+ * system-assigned mode that agents can run in but no one selects by hand. Unknown
+ * modes (dynamic/ACP, custom providers) default to selectable. The flag is a
+ * static property of the mode, so this always consults the built-in manifest
+ * rather than snapshot-derived definitions (which don't carry it).
+ */
+export declare function isUserSelectableMode(provider: string, modeId: string): boolean;
 export declare function getModeVisuals(provider: string, modeId: string, definitions: AgentProviderDefinition[]): AgentModeVisuals | undefined;
 //# sourceMappingURL=provider-manifest.d.ts.map