@otto-code/protocol 0.6.6 → 0.7.0

package/dist/orchestration.js

@@ -59,6 +59,7 @@ export const RUN_PHASE_STATUSES = [
     "skipped",
 ];
 export const RUN_STATUSES = [
+    "draft", // a user orchestration created by the dialog, graph not yet executed
     "pending",
     "running",
     "paused", // stopped at an attended gate, awaiting the user
@@ -140,6 +141,9 @@ export const RunPhaseCandidateSchema = z
     // The candidate's final message (synthesis input); may be large — clients
     // truncate for display.
     summary: z.string().optional(),
+    // Validated output fields, when the node declared them (GraphNode.output).
+    // Values only — anything large belongs in a file the next node reads.
+    outputFields: z.record(z.string(), z.unknown()).optional(),
 })
     .passthrough();
 export const RunPhaseSchema = z
@@ -158,15 +162,46 @@ export const RunPhaseSchema = z
     candidates: z.array(RunPhaseCandidateSchema).optional(),
     // Free-text runtime notes (why it blocked, which cap tripped, gap named).
     notes: z.string().optional(),
+    // Machine-readable reason a phase is "skipped" — the human sentence stays in
+    // `notes`. Absent on a skipped phase means an older daemon wrote it (read it
+    // as "upstream-failed", the only skip that existed then). Open vocabulary,
+    // plain string on the wire; known values in GRAPH_SKIP_REASONS.
+    skipReason: z.string().optional(),
+    // How many extra attempts a node's retry policy spent (0/absent = none).
+    retryAttempts: z.number().int().min(0).optional(),
+    // True when the phase's last attempt ended at its time limit rather than
+    // by failing on its own — a different diagnosis, so a different flag.
+    timedOut: z.boolean().optional(),
     startedAt: z.string().optional(),
     completedAt: z.string().optional(),
 })
     .passthrough();
+// Why a phase is "skipped" (see RunPhase.skipReason). A skip is never an error:
+// "condition" means an edge's condition routed around this node, the other two
+// mean an upstream node was itself skipped or failed. Plain string on the wire.
+export const GRAPH_SKIP_REASONS = [
+    "condition",
+    "upstream-skipped",
+    "upstream-failed",
+    "canceled",
+];
 export const RunSchema = z
     .object({
     id: z.string().min(1),
     title: z.string().min(1),
+    // User-authored description from the New Orchestration dialog (what this
+    // orchestration is for). Distinct from `summary`, which is AI-generated
+    // after the run settles. Absent on conductor-declared (start_run) runs.
+    description: z.string().optional(),
     status: z.string().min(1),
+    // Which engine drives this orchestration: absent/"phases" = the conductor
+    // -declared phase plan; "graph" = a user-authored deterministic graph
+    // (projects/orchestration-graphs). Open vocabulary, plain string on the wire.
+    kind: z.string().optional(),
+    // Graph runs only: the executed graph template and the fill-in values the
+    // user supplied for its declared inputs.
+    graphId: z.string().optional(),
+    graphInputs: z.record(z.string(), z.string()).optional(),
     // Immutable requirements block (see RunPlan.requirements).
     requirements: z.array(z.string().min(1)).optional(),
     autopilot: z.boolean().optional(),
@@ -196,4 +231,403 @@ export const RunSchema = z
     .passthrough();
 // Summary generation lifecycle (plain-string on the wire; see RunSchema.summaryStatus).
 export const RUN_SUMMARY_STATUSES = ["pending", "ready", "failed"];
+// ── Orchestration graphs (user orchestrations) ──────────────────────────────
+// The reusable template a User orchestration executes — authored in the graph
+// designer, stored host-level, parameterized by declared inputs. Executing a
+// graph starts an orchestration (a Run with kind "graph"). See
+// projects/orchestration-graphs. Same wire-forward-compat posture as the Run
+// schemas: open string vocabularies, `.passthrough()` objects, no transforms.
+// A declared fill-in parameter. The New Orchestration dialog renders these as
+// a form when the graph is picked; values substitute into node prompts via
+// {{inputs.<key>}} and via GraphNode.promptFromInput.
+export const GraphInputSchema = z
+    .object({
+    key: z.string().min(1),
+    label: z.string().min(1),
+    description: z.string().optional(),
+    multiline: z.boolean().optional(),
+    required: z.boolean().optional(),
+    defaultValue: z.string().optional(),
+})
+    .passthrough();
+// ── Prompt templates ────────────────────────────────────────────────────────
+// Host-level reusable prompts, stored like Graphs. A template with
+// `snippet: true` is meant to be included by other templates rather than bound
+// to a node directly — the shared "how to submit your output" block is the
+// motivating case, since repeating it in every node is both duplication and
+// tokens on every dispatch.
+export const PromptTemplateSchema = z
+    .object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    description: z.string().optional(),
+    // EJS source. Rendered with HTML escaping disabled — these are prompts,
+    // not markup, and characters like & must survive verbatim.
+    content: z.string(),
+    // Variables the template expects, so the designer can render a binding
+    // form instead of asking the author to remember them.
+    variables: z.array(GraphInputSchema).optional(),
+    snippet: z.boolean().optional(),
+    builtIn: z.boolean().optional(),
+    createdAt: z.string().optional(),
+    updatedAt: z.string().optional(),
+})
+    .passthrough();
+// A node's binding to a stored template. A value is a literal, `$inputs.<key>`
+// (a declared graph input), or `$output.<nodeId>.<field>` (an upstream node's
+// output field).
+export const NodePromptTemplateRefSchema = z
+    .object({
+    templateId: z.string().min(1),
+    variables: z.record(z.string(), z.string()).optional(),
+})
+    .passthrough();
+// Node kinds (open vocabulary): "orchestrator" — the single root that hosts
+// the orchestration chat and anchors the Visualizer; "agent" — a worker node.
+export const GRAPH_NODE_KINDS = ["orchestrator", "agent"];
+// Loop annotation — exactly one of `times` (fixed repeat) or `until` (bounded
+// retry graded by a structured judge between iterations; self-grading is not
+// an exit test). `max` is a hard cap in both readings.
+export const GraphNodeLoopSchema = z
+    .object({
+    times: z.number().int().min(1).max(64).optional(),
+    until: z
+        .object({
+        // What the judge grades each iteration's output against.
+        criteria: z.array(z.string().min(1)).min(1),
+        // Role that fills the judge seat; defaults to "judger".
+        judgeRole: z.string().min(1).optional(),
+        max: z.number().int().min(1).max(16),
+    })
+        .passthrough()
+        .optional(),
+})
+    .passthrough();
+// ── Output fields (the value plane) ─────────────────────────────────────────
+// What a node declares it will produce. Plain JSON descriptors, never a
+// serialized Zod schema: they have to be three things at once — wire-safe, a
+// form the designer can render, and compilable to both Zod (validation) and
+// JSON Schema (the submit_output tool's input). `type` is an open string
+// vocabulary so a new type can never break an old parser.
+export const GRAPH_OUTPUT_FIELD_TYPES = ["string", "number", "boolean", "array"];
+export const GraphOutputFieldSchema = z
+    .object({
+    key: z.string().min(1),
+    type: z.string().min(1),
+    // Shown to the node's agent as the field's description — this is the whole
+    // instruction it gets about what to put here, so it earns its place.
+    description: z.string().optional(),
+    // Absent ⇒ required. You declared the field; producing it is the contract.
+    required: z.boolean().optional(),
+})
+    .passthrough();
+export const GraphNodeOutputSchema = z
+    .object({
+    fields: z.array(GraphOutputFieldSchema),
+})
+    .passthrough();
+// ── Query tools (per-node read-only lookups) ────────────────────────────────
+// Author-defined tools that exist only inside one node's session, so a node can
+// be given exactly the lookup it needs instead of the whole workspace.
+//
+// Three kinds, all read-only by construction:
+//   command    argv array only — no shell, so no operators and no injection
+//              surface. A pipeline belongs in a script the tool points at.
+//   http-get   GET only, no author-supplied headers (credentials can't leak
+//              into a graph template).
+//   file-read  path must resolve inside the run's cwd.
+export const GRAPH_QUERY_TOOL_KINDS = ["command", "http-get", "file-read"];
+export const GraphQueryToolSchema = z
+    .object({
+    // Tool name the agent calls. Namespaced at registration so it can never
+    // shadow a built-in Otto tool.
+    name: z.string().min(1),
+    description: z.string().min(1),
+    kind: z.string().min(1),
+    // Declared parameters, reusing the output-field descriptor shape.
+    parameters: z.array(GraphOutputFieldSchema).optional(),
+    // kind "command": the executable plus its arguments, each argument a
+    // separate entry. `{{param}}` substitutes a declared parameter's value as
+    // one argument — never as a fragment the shell could re-split.
+    command: z.array(z.string()).optional(),
+    // kind "http-get": the URL, with `{{param}}` substitution (encoded).
+    url: z.string().optional(),
+    // kind "file-read": workspace-relative path, with `{{param}}` substitution.
+    path: z.string().optional(),
+})
+    .passthrough();
+// Bounded re-dispatch with exponential backoff. `maxAttempts` counts the first
+// try, so 1 means "no retry" and is allowed (a designer default that hasn't
+// been changed yet shouldn't be a validation error).
+export const GraphNodeRetrySchema = z
+    .object({
+    maxAttempts: z.number().int().min(1).max(10),
+    backoffMs: z.number().int().min(0).max(600000),
+    multiplier: z.number().min(1).max(4).optional(),
+})
+    .passthrough();
+export const GraphNodeSchema = z
+    .object({
+    id: z.string().min(1),
+    kind: z.string().min(1),
+    title: z.string().min(1),
+    // Team role the node dispatches to (agent nodes). Resolution at execute
+    // time: active team fills the role → dialog personality → bare model.
+    role: z.string().min(1).optional(),
+    // Fixed prompt text; may reference {{inputs.<key>}}.
+    prompt: z.string().optional(),
+    // Key of a declared input whose value joins (or forms) the prompt.
+    promptFromInput: z.string().optional(),
+    // Load this node's prompt from a stored template instead of `prompt`.
+    // Resolution failure falls back to `prompt`, so a deleted template
+    // degrades a node rather than breaking a graph.
+    promptTemplate: NodePromptTemplateRefSchema.optional(),
+    // Leaf-only: the node may orchestrate its own agents (full otto toolset
+    // minus start_run). Non-autonomous nodes get no orchestration tools at all.
+    autonomous: z.boolean().optional(),
+    loop: GraphNodeLoopSchema.optional(),
+    // Declared output fields. Present ⇒ the node's agent gets a submit_output
+    // tool it must call, its result is validated, and downstream nodes receive
+    // the fields as data instead of re-reading prose. Absent ⇒ today exactly.
+    output: GraphNodeOutputSchema.optional(),
+    // How much of the workspace this node's agent may touch: "none" (no
+    // filesystem), "read", or "write". Absent ⇒ "write", today's behaviour.
+    //
+    // Enforced by withholding tools at spawn, never by asking the model — and a
+    // provider that can't enforce it refuses the node at compile time rather
+    // than running it with full access. Open string vocabulary; known values in
+    // WORKSPACE_ACCESS_LEVELS (protocol/agent-types).
+    access: z.string().optional(),
+    // Per-node Otto tool allowlist, by group (see OTTO_TOOL_GROUPS). Absent ⇒
+    // whatever the node's tool policy already allows. Present ⇒ only these
+    // groups, intersected with that policy and the daemon-wide allowlist — a
+    // node can narrow its own authority, never widen it.
+    //
+    // Narrowing is a cost lever as much as a safety one: the tool catalog is
+    // paid for in input tokens on every request the node's agent makes, and a
+    // smaller catalog measurably helps smaller models stay on task.
+    tools: z.array(z.string().min(1)).optional(),
+    // Read-only lookups available only inside this node's session.
+    queryTools: z.array(GraphQueryToolSchema).optional(),
+    // Resilience against transient failure. Distinct from `loop`, which is
+    // quality iteration: a loop re-runs work that succeeded but wasn't good
+    // enough; a retry re-runs work that never completed. Retry wraps the whole
+    // node including its loop, and every attempt is charged to the run's agent
+    // cap — a retry is never a private allowance.
+    retry: GraphNodeRetrySchema.optional(),
+    // Wall-clock ceiling for one attempt of this node. On expiry the agent is
+    // really cancelled (not merely stopped being awaited) and the node fails,
+    // which its retry policy may then catch.
+    timeoutMs: z.number().int().min(1000).max(21600000).optional(),
+    // Explicit model override (otherwise the resolved personality/team decides).
+    model: z.string().optional(),
+    // Designer canvas layout.
+    position: z.object({ x: z.number(), y: z.number() }).passthrough().optional(),
+})
+    .passthrough();
+// An edge condition. Kept as a wrapper object rather than a bare string so a
+// future evaluation dialect can be named without a second field.
+export const GraphEdgeConditionSchema = z
+    .object({
+    expression: z.string().min(1),
+})
+    .passthrough();
+// A directed edge: `from`'s final output becomes labeled input material for
+// `to`. Fan-in is an all-inputs barrier held by the daemon — agents never know
+// about waiting.
+export const GraphEdgeSchema = z
+    .object({
+    id: z.string().min(1).optional(),
+    from: z.string().min(1),
+    to: z.string().min(1),
+    // Named ports. Absent ⇒ "output" → "input", which is every edge today, so
+    // existing graphs parse and execute identically. Reserved ahead of the
+    // control nodes that need more than one outcome (a gate's approved/rejected,
+    // a check's pass/fail): adding two optional fields now is free, and adding a
+    // second port later would mean changing the canvas, the schema and the
+    // engine's value routing at once.
+    fromPort: z.string().min(1).optional(),
+    toPort: z.string().min(1).optional(),
+    // Condition: a JSONata expression evaluated against the upstream node's
+    // output fields once it settles (falling back to its prose as `output`
+    // when it declared none). Truthy ⇒ this edge delivers; falsy ⇒ the edge is
+    // inactive and its target is skipped with reason "condition". Absent ⇒
+    // always delivers, which is every edge today.
+    //
+    // The condition lives on the edge rather than inside a node so the branch
+    // is visible as a labelled wire — the graph shows its own control flow.
+    when: GraphEdgeConditionSchema.optional(),
+    // Which of the upstream node's output fields this edge carries. Absent ⇒
+    // all of them. Selection only, never renaming: downstream is a prompt, not
+    // a typed function signature, so remapping keys would buy nothing and
+    // cost the reader the ability to trace a value by name.
+    fields: z.array(z.string().min(1)).optional(),
+    // Display-only label for the wire.
+    label: z.string().optional(),
+})
+    .passthrough();
+export const OrchestrationGraphSchema = z
+    .object({
+    id: z.string().min(1),
+    name: z.string().min(1),
+    description: z.string().optional(),
+    inputs: z.array(GraphInputSchema).optional(),
+    nodes: z.array(GraphNodeSchema),
+    edges: z.array(GraphEdgeSchema).optional(),
+    // Bundled starter graphs; copy-on-edit, never deleted in place.
+    builtIn: z.boolean().optional(),
+    createdAt: z.string().optional(),
+    updatedAt: z.string().optional(),
+})
+    .passthrough();
+// ── Graph structural validation ──────────────────────────────────────────────
+// Shared by the daemon (hard gate before execute) and the designer (live
+// feedback). Returns human-readable problems; empty ⇒ executable. Split into
+// per-concern helpers to stay under the complexity ceiling.
+export function validateOrchestrationGraph(graph) {
+    const nodeIds = new Set();
+    const problems = [];
+    for (const node of graph.nodes) {
+        if (nodeIds.has(node.id))
+            problems.push(`Duplicate node id "${node.id}".`);
+        nodeIds.add(node.id);
+    }
+    const roots = graph.nodes.filter((n) => n.kind === "orchestrator");
+    if (roots.length === 0) {
+        problems.push("The graph needs exactly one Orchestrator node (the root).");
+    }
+    else if (roots.length > 1) {
+        problems.push("The graph has more than one Orchestrator node.");
+    }
+    problems.push(...validateGraphEdges(graph, nodeIds));
+    const declaredInputs = new Set((graph.inputs ?? []).map((i) => i.key));
+    for (const node of graph.nodes) {
+        problems.push(...validateGraphNode(node, declaredInputs));
+    }
+    return problems;
+}
+function validateGraphEdges(graph, nodeIds) {
+    const problems = [];
+    const edges = graph.edges ?? [];
+    const rootId = graph.nodes.find((node) => node.kind === "orchestrator")?.id ?? null;
+    const outgoing = new Map();
+    const incoming = new Map();
+    for (const edge of edges) {
+        if (!nodeIds.has(edge.from))
+            problems.push(`Edge from unknown node "${edge.from}".`);
+        if (!nodeIds.has(edge.to))
+            problems.push(`Edge to unknown node "${edge.to}".`);
+        if (edge.from === edge.to)
+            problems.push(`Node "${edge.from}" connects to itself.`);
+        // Edges INTO the orchestrator are passive answer-delivery, not execution
+        // dependencies — excluding them here keeps "root kicks off A, A delivers
+        // back to root" from reading as a cycle.
+        if (edge.to === rootId)
+            continue;
+        outgoing.set(edge.from, [...(outgoing.get(edge.from) ?? []), edge.to]);
+        incoming.set(edge.to, [...(incoming.get(edge.to) ?? []), edge.from]);
+    }
+    if (hasGraphCycle(graph, outgoing, incoming)) {
+        problems.push("The graph contains a cycle.");
+    }
+    return problems;
+}
+/**
+ * Advisory findings: things that are almost certainly authoring mistakes but
+ * leave the graph executable. Separate from `validateOrchestrationGraph`
+ * because that one is the daemon's hard gate — anything it returns stops a run,
+ * and none of these should.
+ *
+ * Expression *syntax* is not checked here: the JSONata parser is daemon-side,
+ * so this stays dependency-free for the client bundle.
+ */
+export function reviewOrchestrationGraph(graph) {
+    const warnings = [];
+    for (const edge of graph.edges ?? []) {
+        if (!edge.when?.expression?.trim()) {
+            continue;
+        }
+        const source = graph.nodes.find((node) => node.id === edge.from);
+        if (source && !source.output?.fields?.length) {
+            warnings.push(`The edge from "${source.title}" has a condition, but "${source.title}" declares no output fields — the condition can only test its prose as \`output\`.`);
+        }
+    }
+    return warnings;
+}
+// Cycle check (loops are node-level annotations, never cyclic edges): Kahn.
+function hasGraphCycle(graph, outgoing, incoming) {
+    const indegree = new Map();
+    for (const node of graph.nodes)
+        indegree.set(node.id, incoming.get(node.id)?.length ?? 0);
+    const queue = graph.nodes.filter((n) => (indegree.get(n.id) ?? 0) === 0).map((n) => n.id);
+    let visited = 0;
+    while (queue.length > 0) {
+        const id = queue.shift();
+        visited += 1;
+        for (const next of outgoing.get(id) ?? []) {
+            const d = (indegree.get(next) ?? 0) - 1;
+            indegree.set(next, d);
+            if (d === 0)
+                queue.push(next);
+        }
+    }
+    return visited !== graph.nodes.length;
+}
+const GRAPH_INPUT_REF = /\{\{\s*inputs\.([A-Za-z0-9_-]+)\s*\}\}/g;
+function validateGraphNode(node, declaredInputs) {
+    const isRoot = node.kind === "orchestrator";
+    if (!isRoot && node.kind !== "agent")
+        return []; // unknown kinds pass through
+    const problems = [];
+    // Autonomous nodes may feed results onward via edges; what they must not
+    // do is orchestrate deterministic children — which edges don't express, so
+    // autonomy is allowed on any node except the root.
+    if (node.autonomous && isRoot) {
+        problems.push("The Orchestrator node can't be autonomous.");
+    }
+    if (!isRoot && !node.prompt?.trim() && !node.promptFromInput) {
+        problems.push(`Node "${node.title}" has no prompt and no prompt input.`);
+    }
+    if (node.promptFromInput && !declaredInputs.has(node.promptFromInput)) {
+        problems.push(`Node "${node.title}" reads input "${node.promptFromInput}", which isn't declared.`);
+    }
+    for (const match of (node.prompt ?? "").matchAll(GRAPH_INPUT_REF)) {
+        if (!declaredInputs.has(match[1])) {
+            problems.push(`Node "${node.title}" references {{inputs.${match[1]}}}, which isn't declared.`);
+        }
+    }
+    problems.push(...validateGraphNodeLoop(node));
+    problems.push(...validateGraphNodeOutput(node));
+    return problems;
+}
+function validateGraphNodeOutput(node) {
+    if (!node.output) {
+        return [];
+    }
+    const fields = node.output.fields ?? [];
+    if (fields.length === 0) {
+        return [`Node "${node.title}" declares output fields but lists none.`];
+    }
+    const problems = [];
+    const seen = new Set();
+    for (const field of fields) {
+        if (seen.has(field.key)) {
+            problems.push(`Node "${node.title}" declares the output field "${field.key}" twice.`);
+        }
+        seen.add(field.key);
+    }
+    return problems;
+}
+function validateGraphNodeLoop(node) {
+    if (!node.loop) {
+        return [];
+    }
+    if (node.loop.times === undefined && node.loop.until === undefined) {
+        return [`Node "${node.title}" has a loop with neither "times" nor "until".`];
+    }
+    if (node.loop.times !== undefined && node.loop.until !== undefined) {
+        return [`Node "${node.title}" has both loop forms — pick "times" or "until".`];
+    }
+    return [];
+}
 //# sourceMappingURL=orchestration.js.map

package/dist/provider-config.d.ts

@@ -40,7 +40,7 @@ export declare const ProviderProfileModelSchema: z.ZodObject<{
  * of these groups; omitting the selection means all groups. Kept deliberately
  * coarse — users pick groups, not individual tools.
  */
-export declare const OTTO_TOOL_GROUPS: readonly ["preview", "browser", "web", "agents", "terminals", "schedules", "artifacts", "workspace"];
+export declare const OTTO_TOOL_GROUPS: readonly ["preview", "browser", "web", "agents", "terminals", "schedules", "artifacts", "widgets", "workspace"];
 export type OttoToolGroup = (typeof OTTO_TOOL_GROUPS)[number];
 /**
  * Map a tool name to its group. Covers both Otto's catalog tools and the
@@ -148,6 +148,7 @@ export declare const ProviderOverrideSchema: z.ZodObject<{
         agents: "agents";
         terminals: "terminals";
         schedules: "schedules";
+        widgets: "widgets";
         workspace: "workspace";
     }>>>;
     mcpServers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -221,6 +222,7 @@ export declare const ProviderOverridesSchema: z.ZodRecord<z.ZodString, z.ZodObje
         agents: "agents";
         terminals: "terminals";
         schedules: "schedules";
+        widgets: "widgets";
         workspace: "workspace";
     }>>>;
     mcpServers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodDiscriminatedUnion<[z.ZodObject<{

package/dist/provider-config.js

@@ -48,6 +48,7 @@ export const OTTO_TOOL_GROUPS = [
     "terminals",
     "schedules",
     "artifacts",
+    "widgets",
     "workspace",
 ];
 /**
@@ -68,6 +69,8 @@ export function ottoToolGroupForName(name) {
         return "schedules";
     if (name.includes("artifact"))
         return "artifacts";
+    if (name === "show_widget" || name === "widget_contract")
+        return "widgets";
     if (name.includes("worktree") || name.includes("workspace"))
         return "workspace";
     return "agents";