@otto-code/protocol 0.6.7 → 0.7.0

package/dist/agent-labels.d.ts

@@ -9,4 +9,25 @@ export declare const ORCHESTRATION_POLICIES: readonly ["deterministic", "autonom
 export type OrchestrationPolicy = (typeof ORCHESTRATION_POLICIES)[number];
 export declare function getOrchestrationPolicyFromLabels(labels: Record<string, unknown> | null | undefined): OrchestrationPolicy | null;
 export declare const ORCHESTRATION_RUN_ID_LABEL = "otto.orchestration-run-id";
+export declare const ORCHESTRATION_OUTPUT_FIELDS_LABEL = "otto.orchestration-output-fields";
+export interface OrchestrationOutputField {
+    key: string;
+    type: string;
+    description?: string;
+    required?: boolean;
+}
+export declare function getOutputFieldsFromLabels(labels: Record<string, unknown> | null | undefined): OrchestrationOutputField[] | null;
+export declare const ORCHESTRATION_TOOL_GROUPS_LABEL = "otto.orchestration-tool-groups";
+export declare function getToolGroupsFromLabels(labels: Record<string, unknown> | null | undefined): string[] | null;
+export declare const ORCHESTRATION_QUERY_TOOLS_LABEL = "otto.orchestration-query-tools";
+export interface OrchestrationQueryToolLabel {
+    name: string;
+    description: string;
+    kind: string;
+    parameters?: OrchestrationOutputField[];
+    command?: string[];
+    url?: string;
+    path?: string;
+}
+export declare function getQueryToolsFromLabels(labels: Record<string, unknown> | null | undefined): OrchestrationQueryToolLabel[] | null;
 //# sourceMappingURL=agent-labels.d.ts.map

package/dist/agent-labels.js

@@ -24,4 +24,70 @@ export function getOrchestrationPolicyFromLabels(labels) {
 // First-class run attribution for orchestration children (parentage rides
 // PARENT_AGENT_ID_LABEL; this ties the child to the run record itself).
 export const ORCHESTRATION_RUN_ID_LABEL = "otto.orchestration-run-id";
+// The node's declared output fields, JSON-encoded, stamped on the spawned
+// agent. The otto-tool catalog reads it to register that agent's submit_output
+// tool — which is why this rides a label rather than a spawn option: the
+// catalog is built per agent from the agent's own record, so every provider
+// (MCP-served and native-loop alike) inherits the tool with no per-provider
+// plumbing. Malformed JSON reads as "no declared fields" — a node that can't
+// parse its own contract falls back to prose rather than failing to spawn.
+export const ORCHESTRATION_OUTPUT_FIELDS_LABEL = "otto.orchestration-output-fields";
+export function getOutputFieldsFromLabels(labels) {
+    return parseJsonArrayLabel(labels, ORCHESTRATION_OUTPUT_FIELDS_LABEL, (candidate) => {
+        return typeof candidate.key === "string" && typeof candidate.type === "string";
+    });
+}
+// The node's per-node Otto tool-group allowlist, JSON-encoded. Read by the tool
+// catalog to narrow (never widen) what this one agent may reach.
+export const ORCHESTRATION_TOOL_GROUPS_LABEL = "otto.orchestration-tool-groups";
+export function getToolGroupsFromLabels(labels) {
+    const raw = labels?.[ORCHESTRATION_TOOL_GROUPS_LABEL];
+    if (typeof raw !== "string" || raw.trim().length === 0) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed)) {
+            return null;
+        }
+        const groups = parsed.filter((entry) => typeof entry === "string");
+        // An empty allowlist is meaningful ("no Otto tools at all"), so it is
+        // returned as an empty array rather than collapsing to null.
+        return groups;
+    }
+    catch {
+        return null;
+    }
+}
+// The node's query tools, JSON-encoded. Read by the tool catalog, which
+// registers each one for this agent alone.
+export const ORCHESTRATION_QUERY_TOOLS_LABEL = "otto.orchestration-query-tools";
+export function getQueryToolsFromLabels(labels) {
+    return parseJsonArrayLabel(labels, ORCHESTRATION_QUERY_TOOLS_LABEL, (candidate) => {
+        return typeof candidate.name === "string" && typeof candidate.kind === "string";
+    });
+}
+// Labels are strings, so structured node config rides as JSON. Malformed JSON
+// reads as "nothing declared" everywhere: a node that cannot parse its own
+// configuration should lose the capability, never fail to spawn.
+function parseJsonArrayLabel(labels, key, isValid) {
+    const raw = labels?.[key];
+    if (typeof raw !== "string" || raw.trim().length === 0) {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(parsed)) {
+        return null;
+    }
+    const entries = parsed.filter((entry) => {
+        return typeof entry === "object" && entry !== null && isValid(entry);
+    });
+    return entries.length > 0 ? entries : null;
+}
 //# sourceMappingURL=agent-labels.js.map

package/dist/agent-types.d.ts

@@ -196,6 +196,24 @@ export interface ContextComposition {
     /** Content returned by child / observed sub-agents. */
     subagentResults?: number;
 }
+/**
+ * One provider-reported context-window category. `name` is a provider-supplied
+ * *display label* ("Messages", "System prompt", "MCP tools") — deliberately an
+ * OPEN-ENDED string and not an enum, so each provider reports the split it
+ * actually has instead of being squeezed into categories it can't populate.
+ *
+ * Structurally identical to `AgentContextUsageCategory` on the pull path
+ * (`agent.context.get_usage`, see messages.ts) *by design*: the two carry the
+ * same accounting, one pushed on the agent snapshot and one pulled on demand.
+ * Keep them in sync — a divergence here is how the context meter and the
+ * visualizer would start disagreeing about the same agent.
+ */
+export interface AgentContextCategory {
+    name: string;
+    tokens: number;
+    /** Deferred content (e.g. on-demand tool schemas) is not counted in the total. */
+    isDeferred?: boolean;
+}
 export interface AgentUsage {
     inputTokens?: number;
     cachedInputTokens?: number;
@@ -216,6 +234,18 @@ export interface AgentUsage {
      * shows occupancy only. Added for the visualizer context ring/bar.
      */
     contextComposition?: ContextComposition;
+    /**
+     * The provider's OWN context-window split, with its own labels — the same
+     * accounting the `agent.context.get_usage` RPC returns, pushed here on the
+     * agent snapshot so stream/backfill consumers (the visualizer) read the very
+     * numbers the context meter shows rather than a parallel estimate.
+     *
+     * Preferred over {@link ContextComposition} wherever present. The estimate
+     * remains the coarse tier for providers that can't report a real split;
+     * absence of both ⇒ occupancy only. Optional/additive: absence is the
+     * graceful-degrade signal, so no capability flag is needed.
+     */
+    contextCategories?: AgentContextCategory[];
 }
 export declare const TOOL_CALL_ICON_NAMES: readonly ["wrench", "square_terminal", "eye", "pencil", "search", "bot", "sparkles", "brain", "mic_vocal"];
 export type ToolCallIconName = (typeof TOOL_CALL_ICON_NAMES)[number];
@@ -459,6 +489,21 @@ export interface ObservedSubagentUpdate {
     status: "initializing" | "running" | "idle" | "error" | "closed";
     requiresAttention?: boolean;
     usage?: AgentUsage;
+    /**
+     * Tool invocations this subagent has made so far (cumulative). Neutral field
+     * any provider can set; kept monotonic by the daemon so a status-only final
+     * update can't drop the readout. Claude reads it from the SDK's per-task
+     * `usage.tool_uses`. Absent ⇒ the row shows no count.
+     */
+    toolUseCount?: number;
+    /**
+     * The tool this subagent is running (or ran last) — the "spinning _on a 90s
+     * Bash_" signal. Neutral field any provider can set; unlike the counters it is
+     * NOT monotonic (latest wins) and the daemon drops it once the row goes
+     * terminal. Claude reads it from `task_progress.last_tool_name`. Absent ⇒ the
+     * row omits it; never guess a value.
+     */
+    currentTool?: string;
 }
 /**
  * A background shell task reported by a provider's own Bash tool (Claude:
@@ -517,6 +562,9 @@ export interface AgentRunResult {
     timeline: AgentTimelineItem[];
     canceled?: boolean;
 }
+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 interface AgentSessionConfig {
     provider: AgentProvider;
     cwd: string;
@@ -532,6 +580,13 @@ export interface AgentSessionConfig {
     title?: string | null;
     approvalPolicy?: string;
     sandboxMode?: string;
+    /**
+     * Ceiling on what this session may do to its workspace (see
+     * WORKSPACE_ACCESS_LEVELS). Absent ⇒ "write", today's behaviour. Set by graph
+     * nodes that declare an access level; each provider adapter narrows its own
+     * tool surface to match.
+     */
+    workspaceAccess?: string;
     networkAccess?: boolean;
     webSearch?: boolean;
     extra?: {

package/dist/agent-types.js

@@ -19,4 +19,18 @@ export const TOOL_CALL_ICON_NAMES = [
 export function getAgentStreamEventTurnId(event) {
     return "turnId" in event ? event.turnId : undefined;
 }
+// ── Workspace access ────────────────────────────────────────────────────────
+// How much of its workspace one agent session may touch. Provider-neutral by
+// intent: each adapter maps it onto whatever its own runtime enforces, and a
+// provider that cannot enforce it must say so (AgentCapabilities) rather than
+// accept the setting and ignore it.
+//
+// This is a *boundary*, not an instruction. "read" means the write tools are
+// not offered, so there is no write to make — never a line of prompt asking the
+// model to behave. A control a user relies on when deciding to run something
+// unattended has to be true in exactly the cases where the model is confused.
+export const WORKSPACE_ACCESS_LEVELS = ["none", "read", "write"];
+export function isWorkspaceAccess(value) {
+    return value === "none" || value === "read" || value === "write";
+}
 //# sourceMappingURL=agent-types.js.map