@claxedo/agent-runtime-contract 0.8.0 → 0.10.0

package/dist/events.d.ts

@@ -1,5 +1,16 @@
 import type { AgentConfigOption, AgentContentPart, AgentMessageInfo, AgentPermission, AgentQuestion, AgentSnapshotFileDiff, AgentTodo } from "./content";
 import type { AgentRuntimeStatus } from "./availability";
+import type { BackgroundWork } from "./background-work";
+import type { AgentRuntimeHealth, ConnectionRuntimeStatus } from "./connections";
+import type { AgentSubagentUpdate, RuntimeGoalSnapshot } from "./subagents";
+import type { TurnAccount } from "./turn-account";
+/**
+ * Provider-reported token categories for one turn observation.
+ *
+ * `null` means the provider did not report the category. This is deliberately
+ * different from a reported zero: metering consumers must never manufacture a
+ * measured zero for an unknown category.
+ */
 export type RuntimeTokenUsage = {
     input: number | null;
     output: number | null;
@@ -7,13 +18,36 @@ export type RuntimeTokenUsage = {
     cache: {
         read: number | null;
         write: number | null;
+        /**
+         * The part of `write` held in the one-hour cache, which Anthropic bills at
+         * 2x input instead of the five-minute 1.25x. Absent where the provider
+         * reports no split; a write with no split is a five-minute write.
+         */
+        write1h?: number | null;
     };
 };
 export type RuntimeUsageObservation = {
+    /** Whether this observation replaces prior usage in its scope or adds to it. */
     kind: "cumulative" | "delta";
+    /**
+     * One independent stream of usage within the turn — a provider thread's own
+     * turn, a subagent's requests. A cumulative observation replaces only its
+     * scope's running total, and the turn's usage is the sum over every scope,
+     * so two streams that land on one turn never overwrite each other. Absent is
+     * the turn's own stream.
+     */
+    scope?: string;
     tokens: RuntimeTokenUsage;
+    /**
+     * The model id the provider reports having served these requests with, where
+     * it names one. A session's configured model can be an alias (`opus[1m]`)
+     * that no price list carries.
+     */
+    model?: string;
+    /** Provider-native ordering data when the source exposes it. */
     sequence?: number;
     providerObservationId?: string;
+    /** Provider-native session/thread identity used only for local overlap classification. */
     nativeSessionId?: string;
     observedAt?: number;
 };
@@ -59,11 +93,27 @@ export type AgentPresentationEvent = {
         field: string;
         delta: string;
     };
-} | {
+}
+/** These text and reasoning parts belong to a response the harness withdrew; they keep their content and gain `retracted`. */
+ | {
+    id: string;
+    type: "message.part.retracted";
+    properties: {
+        sessionID: string;
+        reason: string;
+        parts: Array<{
+            messageID: string;
+            partID: string;
+        }>;
+    };
+}
+/** `cancelled` marks the message a stopped turn ended on; the runtime records that turn as cancelled from it. */
+ | {
     type: "message.completed";
     properties: {
         sessionID: string;
         messageID: string;
+        cancelled?: true;
     };
 } | {
     id: string;
@@ -75,7 +125,19 @@ export type AgentPresentationEvent = {
     properties: {
         sessionID: string;
         requestID: string;
+    } & ({
         reply: "once" | "always" | "reject";
+        optionId?: never;
+    } | {
+        optionId: string;
+        reply?: never;
+    });
+} | {
+    id: string;
+    type: "permission.expired";
+    properties: {
+        sessionID: string;
+        requestID: string;
     };
 } | {
     id: string;
@@ -96,6 +158,13 @@ export type AgentPresentationEvent = {
         sessionID: string;
         requestID: string;
     };
+} | {
+    id: string;
+    type: "question.expired";
+    properties: {
+        sessionID: string;
+        requestID: string;
+    };
 } | {
     id: string;
     type: "todo.updated";
@@ -110,11 +179,19 @@ export type AgentPresentationEvent = {
         sessionID: string;
         status: AgentRuntimeStatus;
     };
-} | {
+}
+/**
+ * `lastTurn` is on the one frame that ends a turn, the `session.idle` (completed or cancelled) or
+ * `session.error` (failed) that `RuntimeStore.finishTurn` returns beside the `turn.finish` it journals:
+ * that outcome's status and `completedAt`, which the session's read and its list row then carry.
+ * A `session.error` raised outside a turn's end, such as a refused prompt admission, carries none.
+ */
+ | {
     id: string;
     type: "session.idle";
     properties: {
         sessionID: string;
+        lastTurn?: import("./sessions").SessionLastTurn;
     };
 } | {
     id: string;
@@ -127,6 +204,7 @@ export type AgentPresentationEvent = {
                 message?: string;
             };
         };
+        lastTurn?: import("./sessions").SessionLastTurn;
     };
 } | {
     id: string;
@@ -160,6 +238,12 @@ export type AgentPresentationEvent = {
         sessionID: string;
         options: AgentConfigOption[];
     };
+} | {
+    type: "session.commands";
+    properties: {
+        sessionID: string;
+        commands: import("./sessions").AgentSessionCommand[];
+    };
 } | {
     type: "session.usage";
     properties: {
@@ -172,6 +256,27 @@ export type AgentPresentationEvent = {
             amount: number;
             currency: string;
         };
+        account?: TurnAccount;
+    };
+} | {
+    id?: string;
+    type: "subagent.updated";
+    properties: {
+        sessionID: string;
+        update: AgentSubagentUpdate;
+    };
+} | {
+    id?: string;
+    type: "goal.updated";
+    properties: {
+        sessionID: string;
+        goal: RuntimeGoalSnapshot;
+    };
+} | {
+    id?: string;
+    type: "goal.cleared";
+    properties: {
+        sessionID: string;
     };
 } | {
     id?: string;
@@ -201,6 +306,35 @@ export type AgentPresentationEvent = {
 } | {
     type: "server.heartbeat";
     properties: Record<string, unknown>;
+}
+/** `parentID` names a subsession, whose deletion leaves the visible session count alone. */
+ | {
+    type: "session.deleted";
+    properties: {
+        info: {
+            id: string;
+            directory: string;
+            parentID?: string;
+        };
+    };
+}
+/** Whether the session's harness runs work outside any turn; live state pushed when it changes and never journaled. */
+ | {
+    type: "session.background-work";
+    properties: {
+        sessionID: string;
+    } & BackgroundWork;
+}
+/** A session's harness health and its connection's state, pushed when either changes. */
+ | {
+    type: "harness.health";
+    properties: {
+        sessionID: string;
+        harnessHealth: AgentRuntimeHealth;
+        connectionState?: ConnectionRuntimeStatus & {
+            connectionId: string;
+        };
+    };
 };
 export type AgentPresentationEventType = AgentPresentationEvent["type"];
 export declare const AGENT_PRESENTATION_EVENT_TYPE_REGISTRY: {
@@ -209,12 +343,15 @@ export declare const AGENT_PRESENTATION_EVENT_TYPE_REGISTRY: {
     "message.part.updated": true;
     "message.part.removed": true;
     "message.part.delta": true;
+    "message.part.retracted": true;
     "message.completed": true;
     "permission.asked": true;
     "permission.replied": true;
+    "permission.expired": true;
     "question.asked": true;
     "question.replied": true;
     "question.rejected": true;
+    "question.expired": true;
     "todo.updated": true;
     "session.status": true;
     "session.idle": true;
@@ -224,10 +361,17 @@ export declare const AGENT_PRESENTATION_EVENT_TYPE_REGISTRY: {
     "session.compacted": true;
     "session.agent": true;
     "session.config": true;
+    "session.commands": true;
     "session.usage": true;
+    "subagent.updated": true;
+    "goal.updated": true;
+    "goal.cleared": true;
     "runtime.diagnostic": true;
     "server.connected": true;
     "server.heartbeat": true;
+    "session.deleted": true;
+    "harness.health": true;
+    "session.background-work": true;
 };
 /** Sound because the registry is `satisfies Record<AgentPresentationEventType, true>`: its keys are exactly the union. */
 export declare function isAgentPresentationEventType(value: string): value is AgentPresentationEventType;
@@ -236,12 +380,6 @@ export type AgentEventEnvelope<Event extends AgentPresentationEvent = AgentPrese
     directory: string;
     payload: Event;
 };
-export type RawHarnessEvent = {
-    source: string;
-    method?: string;
-    payload: unknown;
-    receivedAt?: number;
-};
 export type RuntimeQuestion = {
     text: string;
     options?: string[];
@@ -250,211 +388,3 @@ export type RuntimeQuestion = {
     multiple?: boolean;
     custom?: boolean;
 };
-export type AgentRuntimeEvent = ({
-    harness?: string;
-    threadId?: string;
-    raw?: RawHarnessEvent;
-    diagnostics?: Array<{
-        code: string;
-        message: string;
-        severity: "debug" | "info" | "warn" | "error";
-        details?: Record<string, unknown>;
-    }>;
-}) & ({
-    type: "text-delta";
-    delta: string;
-} | {
-    type: "thinking-delta";
-    delta: string;
-} | {
-    type: "user-message-delta";
-    messageId?: string;
-    content: Record<string, unknown> & {
-        type: string;
-    };
-} | {
-    type: "tool-start";
-    toolCallId: string;
-    toolName: string;
-    kind?: string;
-    display?: Record<string, unknown>;
-    metadata?: Record<string, unknown>;
-} | {
-    type: "tool-input";
-    toolCallId: string;
-    input: unknown;
-    display?: Record<string, unknown>;
-    metadata?: Record<string, unknown>;
-} | {
-    type: "tool-status";
-    toolCallId: string;
-    status: "pending" | "running" | "completed" | "failed";
-    display?: Record<string, unknown>;
-    metadata?: Record<string, unknown>;
-} | {
-    type: "tool-content";
-    toolCallId: string;
-    content: Record<string, unknown> & {
-        type: string;
-    };
-    display?: Record<string, unknown>;
-    metadata?: Record<string, unknown>;
-} | {
-    type: "tool-output";
-    toolCallId: string;
-    output: unknown;
-    display?: Record<string, unknown>;
-    metadata?: Record<string, unknown>;
-} | {
-    type: "tool-error";
-    toolCallId: string;
-    error: string;
-    display?: Record<string, unknown>;
-    metadata?: Record<string, unknown>;
-} | {
-    type: "file-diff";
-    toolCallId?: string;
-    path: string;
-    oldText?: string;
-    newText: string;
-} | {
-    type: "step-start";
-    newMessageId: string;
-} | {
-    type: "permission-request";
-    requestId: string;
-    tool: string;
-    paths: string[];
-} | {
-    type: "question";
-    requestId: string;
-    questions: RuntimeQuestion[];
-} | {
-    type: "question-answered";
-    requestId: string;
-    answers: Record<string, string | string[]>;
-} | {
-    type: "proposed-plan-delta";
-    delta: string;
-} | {
-    type: "proposed-plan-complete";
-    planMarkdown: string;
-} | {
-    type: "todo-update";
-    todos: Array<{
-        id: string;
-        description: string;
-        status: string;
-        priority?: string;
-    }>;
-} | {
-    type: "session-status";
-    status: "busy" | "idle" | "error" | "recovering";
-} | {
-    type: "session-compaction";
-    phase: "started" | "completed";
-    reason?: string;
-    summary?: string;
-    metadata?: Record<string, unknown>;
-} | {
-    type: "harness-notice";
-    code: string;
-    message: string;
-    severity?: "debug" | "info" | "warn" | "error";
-    details?: unknown;
-} | {
-    type: "auth-status";
-    status: "authenticated" | "unauthenticated" | "unknown";
-    authMode?: string | null;
-    planType?: string | null;
-    metadata?: Record<string, unknown>;
-} | {
-    type: "rate-limit";
-    status: "ok" | "limited";
-    usedPercent?: number;
-    resetsAt?: number | null;
-    windowDurationMins?: number | null;
-    limitId?: string | null;
-    limitName?: string | null;
-    reason?: string | null;
-    metadata?: Record<string, unknown>;
-} | {
-    type: "mcp-server-status";
-    serverName: string;
-    status: "starting" | "ready" | "failed" | "cancelled";
-    error?: string | null;
-} | {
-    type: "subagent-updated";
-    subagentKey: string;
-    revision: number;
-    [key: string]: unknown;
-} | {
-    type: "finish";
-    sessionId: string;
-} | {
-    type: "error";
-    error: string;
-} | {
-    type: "image-delta" | "audio-delta" | "thinking-audio-delta";
-    mimeType: string;
-    data: string;
-} | {
-    type: "resource-link-delta" | "thinking-resource-link-delta";
-    uri: string;
-    name: string;
-    mimeType?: string;
-    title?: string;
-} | {
-    type: "resource-delta";
-    resource: unknown;
-    channel: "assistant" | "thinking";
-} | {
-    type: "tool-location";
-    toolCallId: string;
-    locations: Array<{
-        path: string;
-        line?: number;
-    }>;
-} | {
-    type: "tool-terminal";
-    toolCallId: string;
-    terminalId: string;
-} | {
-    type: "available-commands-update";
-    commands: Array<{
-        name: string;
-        description?: string;
-        input?: unknown;
-    }>;
-} | {
-    type: "session-agent";
-    agentId: string;
-} | {
-    type: "config-update";
-    options: AgentConfigOption[];
-} | {
-    type: "session-info";
-    title?: string | null;
-    updatedAt?: string | null;
-    parentID?: string;
-} | {
-    type: "session-title";
-    title: string;
-} | {
-    type: "usage";
-    contextSize: number;
-    contextUsed: number;
-    observation?: RuntimeUsageObservation;
-    cost?: {
-        amount: number;
-        currency: string;
-    };
-} | {
-    type: "diagnostic";
-    diagnostic: {
-        code: string;
-        message: string;
-        severity: "debug" | "info" | "warn" | "error";
-        details?: unknown;
-    };
-});

package/dist/files.d.ts

@@ -50,3 +50,5 @@ export type AgentPresentationProvider = {
 export declare function isAgentReviewFileDiff(value: unknown): value is AgentReviewFileDiff;
 /** Coerce an unknown payload (array, single diff, or keyed object) into a diff list. */
 export declare function agentReviewFileDiffList(value: unknown): AgentReviewFileDiff[];
+/** The file content `value` holds, or `undefined` when it is not one; a malformed patch is dropped, not fatal. */
+export declare function parseAgentFileContent(value: unknown): AgentFileContent | undefined;

package/dist/first-turn-error.d.ts

@@ -0,0 +1,12 @@
+import type { FirstTurnErrorClass } from "./turn-error-classes";
+import type { TurnAccount } from "./turn-account";
+export declare function classifyFirstTurnError(error: unknown): FirstTurnErrorClass;
+/** `errorClass` is the transport's structured class; the message is read only without one. */
+export declare function firstTurnErrorData(message: string, facts?: {
+    errorClass?: FirstTurnErrorClass;
+    account?: TurnAccount;
+}): {
+    message: string;
+    firstTurnErrorClass: "credential" | "egress" | "harness" | "model" | "rate_limit" | "session" | "unknown" | "usage_limit" | "workspace";
+    account?: TurnAccount | undefined;
+};

package/dist/goals.d.ts

@@ -0,0 +1,28 @@
+import type { RuntimeGoalSnapshot } from "./subagents";
+export type AgentGoalStartInput = {
+    objective: string;
+};
+export type AgentGoalMutationFailure = {
+    ok: false;
+    status: "unsupported" | "unavailable" | "not_found" | "conflict" | "failed";
+    message: string;
+};
+export type AgentGoalMutationResult<Goal extends RuntimeGoalSnapshot | null = RuntimeGoalSnapshot | null> = {
+    ok: true;
+    goal: Goal;
+} | AgentGoalMutationFailure;
+export type GoalAction = "pause" | "resume" | "delete";
+export type GoalRecovery = "reconcile" | "blocked";
+export type GoalOptionalField = "tokenBudget" | "tokensUsed" | "timeUsedSeconds" | "iteration" | "lastReason";
+export type GoalCapabilities = {
+    /** Whether this adapter contains a real Goal implementation. */
+    implemented: boolean;
+    /** Whether that implementation can be used in the current session/runtime. */
+    available: boolean;
+    unavailableReason?: string;
+    actions: readonly GoalAction[];
+    /** Whether authoritative state can be reconciled after reconnect/reload. */
+    recovery: GoalRecovery;
+    /** Optional snapshot fields this implementation may report without fabrication. */
+    optionalFields: readonly GoalOptionalField[];
+};

package/dist/harness-permission-modes.d.ts

@@ -0,0 +1,76 @@
+import type { AgentPermissionMode } from "./permissions";
+/**
+ * When a change lands. `next-session` is a harness whose options are read only
+ * when its agent is created, and that cannot recreate the agent in front of
+ * the user. `immediate` uses a live session control.
+ */
+export type PermissionModesApplyFrom = "immediate" | "next-turn" | "next-session";
+export type HarnessPermissionModes = {
+    modes: readonly AgentPermissionMode[];
+    appliesFrom: PermissionModesApplyFrom;
+    /**
+     * The mode a session runs under before anyone has chosen, as the transport
+     * launches it. Absent where the harness's own configuration decides instead,
+     * so a session that chose nothing names no mode.
+     */
+    defaultModeId?: string;
+};
+/**
+ * Claude's `PermissionMode` union, with the SDK's OWN descriptions copied from
+ * its doc comment (`sdk.d.ts`) so the picker never paraphrases.
+ *
+ * `plan` and `dontAsk` carry no rung. `plan` executes nothing and `dontAsk`
+ * DENIES rather than allows, so neither sits on an allow-more ladder at all.
+ * `acceptEdits` carries none either: it still prompts for every command.
+ *
+ * `immediate`: streaming queries acknowledge `setPermissionMode()` without
+ * restarting the active turn.
+ */
+export declare const CLAUDE_PERMISSION_MODES: {
+    modes: AgentPermissionMode[];
+    appliesFrom: "immediate";
+    defaultModeId: string;
+};
+/**
+ * Cursor's two `LocalAgentOptions` booleans, presented as the combinations that
+ * mean something.
+ *
+ * `next-turn`: both fields are read by `Agent.create` and `Agent.resume`, and
+ * the per-send `LocalSendOptions` carries only `force` and `customTools`, so a
+ * change closes the session's agent and the next turn resumes it with the new
+ * options.
+ *
+ * No default: with nothing chosen the transport passes no sandbox options and
+ * Cursor's own configured defaults decide. A sandboxed mode needs Cursor's
+ * `cursorsandbox` binary, which the SDK refuses to run without.
+ *
+ * `force` is deliberately NOT mapped to a rung. It expires a wedged run after a
+ * crashed CLI — a recovery flag, not a permission control — and treating it as
+ * "full access" would hand a destructive-sounding label to something that does
+ * not grant anything.
+ */
+export declare const CURSOR_PERMISSION_MODES: {
+    modes: AgentPermissionMode[];
+    appliesFrom: "next-turn";
+};
+/**
+ * Codex approval policy + sandbox pairs. `auto` here is the strongest `auto` of
+ * any harness: `on-request` with a workspace-write sandbox means in-workspace
+ * commands run unprompted and the boundary is enforced by the OS
+ * (seatbelt/landlock), not by an allowlist.
+ */
+export declare const CODEX_PERMISSION_MODES: {
+    modes: AgentPermissionMode[];
+    appliesFrom: "next-turn";
+    defaultModeId: string;
+};
+/**
+ * Pi asks before nothing on its own. `ask` routes each write, edit, bash and
+ * MCP call through Claxedo's broker from a `beforeTool` hook; `full` runs them
+ * unasked, as Pi itself does.
+ */
+export declare const PI_PERMISSION_MODES: {
+    modes: AgentPermissionMode[];
+    appliesFrom: "next-turn";
+    defaultModeId: string;
+};

package/dist/harness-table.d.ts

@@ -9,6 +9,8 @@
  * not another — and a provider id missing from a list loses its login without
  * anything failing.
  */
+import { type HarnessPermissionModes } from "./harness-permission-modes";
+import { type SessionHarness } from "./harnesses";
 export declare const HARNESS_IDS: readonly ["claude", "codex", "cursor"];
 export type HarnessId = (typeof HARNESS_IDS)[number];
 type HarnessRecord = {
@@ -21,10 +23,11 @@ type HarnessRecord = {
      * fallback.
      *
      * The order is load-bearing at both ends. A connect card stores under
-     * `connectProvider`, and `harnessProjection` takes the first of these ids a
-     * projection map holds — so a Claude turn binds through `claude-sdk` when one
-     * is selected and through a plain `anthropic` key when it is not, and a list
-     * that stopped at the aliases would drop that key.
+     * `connectProvider`, and the harness's `selectedProviderProjection` takes
+     * the first of these ids whose projection is available, else the first held
+     * — so a Claude turn binds through `claude-sdk` when its account can be used
+     * and through a plain `anthropic` key when it cannot, and a list that
+     * stopped at the aliases would drop that key.
      */
     providerIds: readonly string[];
     /** The provider id a sign-in for this harness is stored against. */
@@ -42,9 +45,41 @@ type HarnessRecord = {
      * an `Agent.create` argument and refuses a turn however signed in the CLI is.
      */
     machineLoginServes: readonly string[];
+    permissionModes: HarnessPermissionModes;
+    /**
+     * The model row a session that stored no model runs on, where the harness
+     * declares one without asking its live catalog. Absent on codex: an unnamed
+     * model is the app-server's own configured default, which only `model/list`
+     * reports.
+     */
+    defaultModelId?: string;
 };
 export declare const HARNESS_TABLE: Readonly<Record<HarnessId, HarnessRecord>>;
 export declare function isHarnessId(value: string): value is HarnessId;
+/** The name every surface writes for a native harness: the product's own for the table's, the catalog's for the engines. */
+export declare function harnessProductLabel(id: string): string | undefined;
+/**
+ * The permission modes a session's harness declares: a table harness's, and
+ * Pi's, which Claxedo's own hook enforces. Undefined for an ACP connection,
+ * whose agent reports its own list, and for a native harness with no mode
+ * surface.
+ */
+export declare function declaredPermissionModes(harness: SessionHarness): HarnessPermissionModes | undefined;
+/**
+ * The mode a session runs under: the stored one while its harness still offers
+ * it, else the harness's declared default, or none where the harness's own
+ * configuration decides. A harness the table does not describe runs what was
+ * stored, or nothing that anyone chose.
+ */
+export declare function effectivePermissionModeId(harness: SessionHarness, stored: string | null | undefined): string | null;
+/** The model a session runs on: the stored one, else the row its harness declares as default. */
+export declare function effectiveSessionModel(harness: SessionHarness, stored: {
+    providerID: string;
+    modelID: string;
+} | undefined): {
+    providerID: string;
+    modelID: string;
+} | undefined;
 /**
  * The harness a provider id belongs to, where one does. Every other provider id
  * names a vendor an engine can run rather than a harness's own login, and has
@@ -53,4 +88,31 @@ export declare function isHarnessId(value: string): value is HarnessId;
 export declare function harnessForProviderId(id: string): HarnessId | undefined;
 /** The bindings a harness resolves its own auth through: everything but the vendor id. */
 export declare function harnessBindingIds(harness: HarnessId): string[];
+/**
+ * Every stored provider id whose row can stand in for one vendor, the vendor's
+ * own id first and the harness logins behind it.
+ *
+ * A subscription connected for Claude Code is an Anthropic login and nothing
+ * about it is Claude Code's alone — the broker sends it to the same origin and
+ * the same paths an Anthropic key goes to, differing only in the header it
+ * rides in. So Pi, which runs Anthropic models and sends a subscription's own
+ * headers, resolves it here instead of asking for the account a second time.
+ * OpenCode's engine does not: it is handed rows under their stored ids and its
+ * Anthropic provider speaks only an API key.
+ *
+ * The vendor leads, which is the opposite of the order a harness's
+ * `selectedProviderProjection` reads. Both are right about their own question: Claude Code asked which
+ * login to run ITSELF on and its own binding is the answer, while an engine
+ * borrowing the vendor spends the key that was pasted for the vendor before it
+ * reaches for a subscription that belongs to another product. The engine's
+ * overlay precedence already resolved a tie this way, and two orders for one
+ * question is how they would come to disagree.
+ *
+ * Structure only. Whether a candidate can be bound at all is the broker's
+ * answer (a provider with no destination row has no binding), and whether this
+ * vendor's binding can spend a given form is the caller's: a ChatGPT plan and
+ * an OpenAI key reach different origins, so an engine provider that means the
+ * key must not take the plan.
+ */
+export declare function vendorCredentialProviderIds(vendorProvider: string): string[];
 export {};