@otto-code/protocol 0.5.2 → 0.5.4

package/dist/agent-personalities.d.ts

@@ -8,6 +8,41 @@ export declare function isPersonalityRole(value: string): value is PersonalityRo
  */
 export declare function normalizePersonalityRoles(roles: readonly string[] | undefined): PersonalityRole[];
 export declare function personalityHasRole(personality: Pick<AgentPersonality, "roles">, role: PersonalityRole): boolean;
+export type PersonalityRoleTier = "coordinator" | "focused";
+interface PersonalityRoleInfo {
+    tier: PersonalityRoleTier;
+    guidance: string;
+}
+export declare const PERSONALITY_ROLE_INFO: Readonly<Record<PersonalityRole, PersonalityRoleInfo>>;
+/**
+ * A personality may launch/coordinate when it carries at least one coordinator
+ * role. A personality whose roles are entirely focused (researcher, planner,
+ * judger, advisor, coder, designer, writer), or that has no roles at all, is a
+ * "lifter": it should finish its task, not fan out.
+ */
+export declare function personalityCanLaunch(personality: Pick<AgentPersonality, "roles">): boolean;
+export interface PersonalitySelectionSummary {
+    tier: PersonalityRoleTier;
+    canLaunch: boolean;
+    /** The "why you'd choose me" blurb — each of the personality's roles, joined. */
+    guidance: string;
+}
+/**
+ * Build the selection decision-aid for a personality from its roles: the tier
+ * (coordinator if any role coordinates), whether it may launch, and a short
+ * multi-role "why choose me" blurb. Surfaced by list_personalities so a
+ * deciding agent can pick the right teammate from the list alone.
+ */
+export declare function summarizePersonalityForSelection(personality: Pick<AgentPersonality, "roles">): PersonalitySelectionSummary;
+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
+ * 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.
+ */
+export declare function composeRoleFocusDirective(roles: readonly string[] | undefined): string | undefined;
 export type PersonalityUnavailableCode = "provider-missing" | "provider-disabled" | "provider-not-ready" | "model-missing" | "mode-missing";
 export interface PersonalityAvailabilityInput {
     /** Provider snapshot status, or undefined when the provider is absent entirely. */
@@ -30,4 +65,5 @@ export type PersonalityAvailability = {
  * The caller grays it out in pickers and hard-fails it in automation.
  */
 export declare function checkPersonalityAvailability(personality: Pick<AgentPersonality, "provider" | "model" | "modeId">, input: PersonalityAvailabilityInput): PersonalityAvailability;
+export {};
 //# sourceMappingURL=agent-personalities.d.ts.map

package/dist/agent-personalities.js

@@ -37,6 +37,110 @@ export function normalizePersonalityRoles(roles) {
 export function personalityHasRole(personality, role) {
     return normalizePersonalityRoles(personality.roles).includes(role);
 }
+export const PERSONALITY_ROLE_INFO = {
+    // ── Surfaces ──────────────────────────────────────────────────────────────
+    chatter: {
+        tier: "coordinator",
+        guidance: "Interactive driver — converse, plan, and delegate. Pick to run a chat or coordinate work.",
+    },
+    artificer: {
+        tier: "coordinator",
+        guidance: "Builds and manages artifacts; may run multi-step work to produce them. Pick for artifact creation.",
+    },
+    scheduler: {
+        tier: "coordinator",
+        guidance: "Creates and manages schedules; may orchestrate recurring or multi-step jobs. Pick for scheduling.",
+    },
+    // ── Thinking workers (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.",
+    },
+    planner: {
+        tier: "focused",
+        guidance: "Planning specialist — turns a goal into a typed, sequenced phase plan for others to execute. Pick to draft an actionable plan; stays on the plan and doesn't dispatch.",
+    },
+    judger: {
+        tier: "focused",
+        guidance: "Review specialist — evaluates work or a plan against criteria and returns a structured verdict. Pick for a focused review; stays on task.",
+    },
+    advisor: {
+        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) ────────────────────────
+    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.",
+    },
+    designer: {
+        tier: "focused",
+        guidance: "Design maker — styling and layout plus the human-skill text (copy, naming). Pick for the look-and-feel or the words; stays on task.",
+    },
+    writer: {
+        tier: "focused",
+        guidance: "Fast small-text specialist — commit messages, summaries, names. Pick for quick text; stays on the one task.",
+    },
+    // ── 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.",
+    },
+};
+/**
+ * A personality may launch/coordinate when it carries at least one coordinator
+ * role. A personality whose roles are entirely focused (researcher, planner,
+ * judger, advisor, coder, designer, writer), or that has no roles at all, is a
+ * "lifter": it should finish its task, not fan out.
+ */
+export function personalityCanLaunch(personality) {
+    return normalizePersonalityRoles(personality.roles).some((role) => PERSONALITY_ROLE_INFO[role].tier === "coordinator");
+}
+/**
+ * Build the selection decision-aid for a personality from its roles: the tier
+ * (coordinator if any role coordinates), whether it may launch, and a short
+ * multi-role "why choose me" blurb. Surfaced by list_personalities so a
+ * deciding agent can pick the right teammate from the list alone.
+ */
+export function summarizePersonalityForSelection(personality) {
+    const roles = normalizePersonalityRoles(personality.roles);
+    const canLaunch = roles.some((role) => PERSONALITY_ROLE_INFO[role].tier === "coordinator");
+    return {
+        tier: canLaunch ? "coordinator" : "focused",
+        canLaunch,
+        guidance: roles.map((role) => PERSONALITY_ROLE_INFO[role].guidance).join(" "),
+    };
+}
+// The conductor's standing directive — the distilled `/epic` method taught to
+// the sole orchestrator role at spawn, so orchestration is emergent (the agent
+// recognizes team-shaped work and runs it) rather than something a user must
+// invoke. Kept here as one exported constant so the wording is testable and
+// shared. See projects/agent-orchestration/agent-orchestration.md.
+export const ORCHESTRATOR_METHOD_DIRECTIVE = "You are the orchestrator — the team's sole conductor. Team-shaped work is yours to run, and you should reach for it naturally, not only when asked. " +
+    "First apply the complexity gate: if a task is small and not splittable, just do it — no ceremony. Only orchestrate when the work is large, parallelizable, or benefits from independent perspectives. " +
+    "When you do orchestrate: (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. " +
+    "Prefer start_run over hand-spawning and tracking agents yourself — the runtime fans out, gathers typed verdicts, and enforces the loop for you. 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
+ * 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.
+ */
+export function composeRoleFocusDirective(roles) {
+    const normalized = normalizePersonalityRoles(roles);
+    if (normalized.length === 0) {
+        return undefined;
+    }
+    const roleList = normalized.join(", ");
+    if (normalized.includes("orchestrator")) {
+        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: use list_personalities to see who else is available, and spawn other agents or hand off to the team's orchestrator whenever delegating gets the work done faster or better.`;
+    }
+    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.`;
+}
 /**
  * Decide whether a personality is usable against a provider's current snapshot.
  * A personality is out of commission the moment any bound setting can't resolve:

package/dist/agent-types.d.ts

@@ -399,6 +399,10 @@ export type AgentStreamEvent = {
     item: AgentTimelineItem;
     turnId?: string;
     timestamp?: string;
+} | {
+    type: "background_shell_task_updated";
+    provider: AgentProvider;
+    update: BackgroundShellTaskUpdate;
 };
 export declare function getAgentStreamEventTurnId(event: AgentStreamEvent): string | undefined;
 /**
@@ -419,6 +423,23 @@ export interface ObservedSubagentUpdate {
     requiresAttention?: boolean;
     usage?: AgentUsage;
 }
+/**
+ * A background shell task reported by a provider's own Bash tool (Claude:
+ * `run_in_background`). `key` is a provider-local stable identifier (Claude:
+ * the Bash tool_use id); the daemon namespaces it under the owning agent.
+ * Unlike {@link ObservedSubagentUpdate} this has no transcript/pane — it's a
+ * plain status row (command, status, elapsed) in the Background Tasks track.
+ */
+export interface BackgroundShellTaskUpdate {
+    key: string;
+    /** Provider task id, used to stop the task (Claude: `task_id`). */
+    taskId?: string;
+    command?: string;
+    description?: string;
+    status: "running" | "idle" | "error" | "closed";
+    requiresAttention?: boolean;
+    usage?: AgentUsage;
+}
 export type AgentPermissionRequestKind = "tool" | "plan" | "question" | "mode" | "other";
 export type AgentPermissionUpdate = AgentMetadata;
 export interface AgentPermissionAction {

package/dist/artifacts/rpc-schemas.d.ts

@@ -73,8 +73,8 @@ export declare const ArtifactListResponseSchema: z.ZodObject<{
             starred: z.ZodBoolean;
             status: z.ZodEnum<{
                 error: "error";
-                generating: "generating";
                 ready: "ready";
+                generating: "generating";
             }>;
             createdAt: z.ZodString;
             updatedAt: z.ZodString;
@@ -109,8 +109,8 @@ export declare const ArtifactCreateResponseSchema: z.ZodObject<{
             starred: z.ZodBoolean;
             status: z.ZodEnum<{
                 error: "error";
-                generating: "generating";
                 ready: "ready";
+                generating: "generating";
             }>;
             createdAt: z.ZodString;
             updatedAt: z.ZodString;
@@ -153,8 +153,8 @@ export declare const ArtifactStarResponseSchema: z.ZodObject<{
             starred: z.ZodBoolean;
             status: z.ZodEnum<{
                 error: "error";
-                generating: "generating";
                 ready: "ready";
+                generating: "generating";
             }>;
             createdAt: z.ZodString;
             updatedAt: z.ZodString;
@@ -189,8 +189,8 @@ export declare const ArtifactUpdateResponseSchema: z.ZodObject<{
             starred: z.ZodBoolean;
             status: z.ZodEnum<{
                 error: "error";
-                generating: "generating";
                 ready: "ready";
+                generating: "generating";
             }>;
             createdAt: z.ZodString;
             updatedAt: z.ZodString;
@@ -225,8 +225,8 @@ export declare const ArtifactRegenerateResponseSchema: z.ZodObject<{
             starred: z.ZodBoolean;
             status: z.ZodEnum<{
                 error: "error";
-                generating: "generating";
                 ready: "ready";
+                generating: "generating";
             }>;
             createdAt: z.ZodString;
             updatedAt: z.ZodString;
@@ -261,8 +261,8 @@ export declare const ArtifactCancelResponseSchema: z.ZodObject<{
             starred: z.ZodBoolean;
             status: z.ZodEnum<{
                 error: "error";
-                generating: "generating";
                 ready: "ready";
+                generating: "generating";
             }>;
             createdAt: z.ZodString;
             updatedAt: z.ZodString;
@@ -306,8 +306,8 @@ export declare const ArtifactCreatedNotificationSchema: z.ZodObject<{
             starred: z.ZodBoolean;
             status: z.ZodEnum<{
                 error: "error";
-                generating: "generating";
                 ready: "ready";
+                generating: "generating";
             }>;
             createdAt: z.ZodString;
             updatedAt: z.ZodString;
@@ -339,8 +339,8 @@ export declare const ArtifactUpdatedNotificationSchema: z.ZodObject<{
             starred: z.ZodBoolean;
             status: z.ZodEnum<{
                 error: "error";
-                generating: "generating";
                 ready: "ready";
+                generating: "generating";
             }>;
             createdAt: z.ZodString;
             updatedAt: z.ZodString;

package/dist/artifacts/types.d.ts

@@ -5,8 +5,8 @@ export declare const ArtifactKindSchema: z.ZodEnum<{
 export type ArtifactKind = z.infer<typeof ArtifactKindSchema>;
 export declare const ArtifactStatusSchema: z.ZodEnum<{
     error: "error";
-    generating: "generating";
     ready: "ready";
+    generating: "generating";
 }>;
 export type ArtifactStatus = z.infer<typeof ArtifactStatusSchema>;
 export declare const ArtifactSpinnerSchema: z.ZodObject<{
@@ -26,8 +26,8 @@ export declare const ArtifactMetadataSchema: z.ZodObject<{
     starred: z.ZodBoolean;
     status: z.ZodEnum<{
         error: "error";
-        generating: "generating";
         ready: "ready";
+        generating: "generating";
     }>;
     createdAt: z.ZodString;
     updatedAt: z.ZodString;
@@ -55,8 +55,8 @@ export declare const ArtifactSummarySchema: z.ZodObject<{
     starred: z.ZodBoolean;
     status: z.ZodEnum<{
         error: "error";
-        generating: "generating";
         ready: "ready";
+        generating: "generating";
     }>;
     createdAt: z.ZodString;
     updatedAt: z.ZodString;
@@ -79,8 +79,8 @@ export declare const ArtifactRunTriggerSchema: z.ZodEnum<{
 export type ArtifactRunTrigger = z.infer<typeof ArtifactRunTriggerSchema>;
 export declare const ArtifactRunStatusSchema: z.ZodEnum<{
     running: "running";
-    succeeded: "succeeded";
     failed: "failed";
+    succeeded: "succeeded";
 }>;
 export type ArtifactRunStatus = z.infer<typeof ArtifactRunStatusSchema>;
 export declare const ArtifactRunSchema: z.ZodObject<{
@@ -91,8 +91,8 @@ export declare const ArtifactRunSchema: z.ZodObject<{
     }>;
     status: z.ZodEnum<{
         running: "running";
-        succeeded: "succeeded";
         failed: "failed";
+        succeeded: "succeeded";
     }>;
     startedAt: z.ZodString;
     endedAt: z.ZodNullable<z.ZodString>;
@@ -114,8 +114,8 @@ export declare const StoredArtifactSchema: z.ZodObject<{
     starred: z.ZodBoolean;
     status: z.ZodEnum<{
         error: "error";
-        generating: "generating";
         ready: "ready";
+        generating: "generating";
     }>;
     createdAt: z.ZodString;
     updatedAt: z.ZodString;
@@ -137,8 +137,8 @@ export declare const StoredArtifactSchema: z.ZodObject<{
         }>;
         status: z.ZodEnum<{
             running: "running";
-            succeeded: "succeeded";
             failed: "failed";
+            succeeded: "succeeded";
         }>;
         startedAt: z.ZodString;
         endedAt: z.ZodNullable<z.ZodString>;

package/dist/default-personalities.js

@@ -9,11 +9,13 @@
 //  - Ids are STABLE and prefixed `personality_builtin_*`. Restore re-adds only
 //    the builtins whose id is missing, so a user who kept/renamed some never
 //    gets duplicates. Renaming a builtin keeps its id, so it is still "present".
-//  - Every one of the 8 roles is covered; some personalities are multi-role to
-//    show that a single template can serve several surfaces. Dash is the Writer
-//    (fast, cheap small-text generation — commit messages, summaries, branch
-//    names) and Sprocket is the Coder (methodical sub-agent building work); the
-//    two together are the heirs of the retired "worker" role.
+//  - Every one of the 11 roles is covered; some personalities are multi-role to
+//    show that a single template can serve several lanes. Sage is the team's
+//    read-only thinker (advisor + researcher + planner); Pixel both an artificer
+//    and a designer. Dash is the Writer (fast, cheap small-text generation —
+//    commit messages, summaries, branch names) and Sprocket is the Coder
+//    (methodical sub-agent building work); the two together are the heirs of the
+//    retired "worker" role. Atlas is the sole conductor (orchestrator).
 //  - Models are Anthropic (Claude Code) — the assumption for launch. On a host
 //    without Claude these simply show as "out of commission" until a matching
 //    provider exists; nothing breaks.
@@ -54,11 +56,13 @@ export const DEFAULT_AGENT_PERSONALITIES = [
         effortLevel: "xhigh",
         modeId: "plan",
         respectGlobalAppendPrompt: true,
-        roles: ["advisor"],
-        personalityPrompt: "You are Sage, a trusted advisor. You are read-only: you counsel, you never change " +
-            "code. Step back before answering, weigh the real trade-offs, surface the risk others " +
-            "miss, and give the one option you would take and why — a clear recommendation, not a " +
-            "menu of possibilities.",
+        roles: ["advisor", "researcher", "planner"],
+        personalityPrompt: "You are Sage, the team's read-only thinker: you research, you plan, and you advise, but " +
+            "you never change code. Asked to survey, map what actually exists — the files, types, " +
+            "patterns, and gotchas — and report facts, not solutions. Asked to plan, turn the goal " +
+            "into a clear, sequenced set of steps a team could execute. Asked to advise, weigh the " +
+            "real trade-offs, surface the risk others miss, and give the one option you would take and " +
+            "why — a recommendation, not a menu.",
         spinner: { glowA: "#14B8A6", glowB: "#8B5CF6" },
         voice: kokoroVoice("af_heart"),
     },
@@ -86,7 +90,7 @@ export const DEFAULT_AGENT_PERSONALITIES = [
         effortLevel: "medium",
         modeId: "acceptEdits",
         respectGlobalAppendPrompt: true,
-        roles: ["artificer"],
+        roles: ["artificer", "designer"],
         personalityPrompt: "You are Pixel, a maker of polished things. You build artifacts and interfaces that " +
             "feel intentional — real hierarchy, deliberate spacing, no templated defaults. Sweat " +
             "the small stuff, prefer a clean version that ships over a clever one that doesn't, and " +