@claxedo/agent-runtime-contract 0.8.0

package/dist/errors.d.ts

@@ -0,0 +1,43 @@
+import type { AgentExecutionBinding, AgentExecutionBindingExpectation, AgentExecutionBindingField } from "./sessions";
+export declare const AGENT_RUNTIME_ERROR_CODES: readonly ["selection_required", "harness_unavailable", "workspace_offline", "unsupported_operation", "replay_gap", "upstream_error", "invalid_execution_binding"];
+export type AgentRuntimeError = {
+    code: "selection_required";
+    message: string;
+    selection: "harness" | "model";
+} | {
+    code: "harness_unavailable";
+    message: string;
+    connectionId: string;
+} | {
+    code: "workspace_offline";
+    message: string;
+    workspaceId: string;
+} | {
+    code: "unsupported_operation";
+    message: string;
+    operation: string;
+} | {
+    code: "replay_gap";
+    message: string;
+    cursor: string;
+} | {
+    code: "upstream_error";
+    message: string;
+    connectionId?: string;
+} | {
+    code: "invalid_execution_binding";
+    message: string;
+    field: AgentExecutionBindingField;
+};
+export type ClientResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: AgentRuntimeError;
+};
+export declare class AgentRuntimeContractError extends Error {
+    readonly detail: AgentRuntimeError;
+    constructor(detail: AgentRuntimeError);
+}
+export declare function assertAgentExecutionBinding(binding: Readonly<AgentExecutionBinding>, expected?: AgentExecutionBindingExpectation): AgentExecutionBinding;

package/dist/events.d.ts

@@ -0,0 +1,460 @@
+import type { AgentConfigOption, AgentContentPart, AgentMessageInfo, AgentPermission, AgentQuestion, AgentSnapshotFileDiff, AgentTodo } from "./content";
+import type { AgentRuntimeStatus } from "./availability";
+export type RuntimeTokenUsage = {
+    input: number | null;
+    output: number | null;
+    reasoning: number | null;
+    cache: {
+        read: number | null;
+        write: number | null;
+    };
+};
+export type RuntimeUsageObservation = {
+    kind: "cumulative" | "delta";
+    tokens: RuntimeTokenUsage;
+    sequence?: number;
+    providerObservationId?: string;
+    nativeSessionId?: string;
+    observedAt?: number;
+};
+export type AgentPresentationEvent = {
+    id: string;
+    type: "message.updated";
+    properties: {
+        sessionID: string;
+        info: AgentMessageInfo & {
+            sessionID: string;
+        };
+    };
+} | {
+    id: string;
+    type: "message.removed";
+    properties: {
+        sessionID: string;
+        messageID: string;
+    };
+} | {
+    id: string;
+    type: "message.part.updated";
+    properties: {
+        sessionID: string;
+        part: AgentContentPart;
+        time: number;
+    };
+} | {
+    id: string;
+    type: "message.part.removed";
+    properties: {
+        sessionID: string;
+        messageID: string;
+        partID: string;
+    };
+} | {
+    id: string;
+    type: "message.part.delta";
+    properties: {
+        sessionID: string;
+        messageID: string;
+        partID: string;
+        field: string;
+        delta: string;
+    };
+} | {
+    type: "message.completed";
+    properties: {
+        sessionID: string;
+        messageID: string;
+    };
+} | {
+    id: string;
+    type: "permission.asked";
+    properties: AgentPermission;
+} | {
+    id: string;
+    type: "permission.replied";
+    properties: {
+        sessionID: string;
+        requestID: string;
+        reply: "once" | "always" | "reject";
+    };
+} | {
+    id: string;
+    type: "question.asked";
+    properties: AgentQuestion;
+} | {
+    id: string;
+    type: "question.replied";
+    properties: {
+        sessionID: string;
+        requestID: string;
+        answers: string[][];
+    };
+} | {
+    id: string;
+    type: "question.rejected";
+    properties: {
+        sessionID: string;
+        requestID: string;
+    };
+} | {
+    id: string;
+    type: "todo.updated";
+    properties: {
+        sessionID: string;
+        todos: AgentTodo[];
+    };
+} | {
+    id: string;
+    type: "session.status";
+    properties: {
+        sessionID: string;
+        status: AgentRuntimeStatus;
+    };
+} | {
+    id: string;
+    type: "session.idle";
+    properties: {
+        sessionID: string;
+    };
+} | {
+    id: string;
+    type: "session.error";
+    properties: {
+        sessionID?: string;
+        error?: {
+            name: string;
+            data: Record<string, unknown> & {
+                message?: string;
+            };
+        };
+    };
+} | {
+    id: string;
+    type: "session.updated";
+    properties: {
+        sessionID: string;
+        info: import("./sessions").AgentSession;
+    };
+} | {
+    id: string;
+    type: "session.diff";
+    properties: {
+        sessionID: string;
+        diff: AgentSnapshotFileDiff[];
+    };
+} | {
+    id: string;
+    type: "session.compacted";
+    properties: {
+        sessionID: string;
+    };
+} | {
+    type: "session.agent";
+    properties: {
+        sessionID: string;
+        agentId: string;
+    };
+} | {
+    type: "session.config";
+    properties: {
+        sessionID: string;
+        options: AgentConfigOption[];
+    };
+} | {
+    type: "session.usage";
+    properties: {
+        sessionID: string;
+        messageID?: string;
+        contextSize: number;
+        contextUsed: number;
+        observation?: RuntimeUsageObservation;
+        cost?: {
+            amount: number;
+            currency: string;
+        };
+    };
+} | {
+    id?: string;
+    type: "runtime.diagnostic";
+    properties: {
+        sessionID: string;
+        harness?: string;
+        threadId?: string;
+        projection?: string;
+        phase?: "ingest" | "terminalize";
+        code: string;
+        message: string;
+        severity: "debug" | "info" | "warn" | "error";
+        eventType?: string;
+        issues?: string[];
+        details?: unknown;
+        auth?: unknown;
+        rateLimit?: unknown;
+        mcp?: unknown;
+        diagnostic?: unknown;
+        raw?: unknown;
+    };
+} | {
+    id: string;
+    type: "server.connected";
+    properties: Record<string, unknown>;
+} | {
+    type: "server.heartbeat";
+    properties: Record<string, unknown>;
+};
+export type AgentPresentationEventType = AgentPresentationEvent["type"];
+export declare const AGENT_PRESENTATION_EVENT_TYPE_REGISTRY: {
+    "message.updated": true;
+    "message.removed": true;
+    "message.part.updated": true;
+    "message.part.removed": true;
+    "message.part.delta": true;
+    "message.completed": true;
+    "permission.asked": true;
+    "permission.replied": true;
+    "question.asked": true;
+    "question.replied": true;
+    "question.rejected": true;
+    "todo.updated": true;
+    "session.status": true;
+    "session.idle": true;
+    "session.error": true;
+    "session.updated": true;
+    "session.diff": true;
+    "session.compacted": true;
+    "session.agent": true;
+    "session.config": true;
+    "session.usage": true;
+    "runtime.diagnostic": true;
+    "server.connected": true;
+    "server.heartbeat": 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;
+export declare const AGENT_PRESENTATION_EVENT_TYPES: AgentPresentationEventType[];
+export type AgentEventEnvelope<Event extends AgentPresentationEvent = AgentPresentationEvent> = {
+    directory: string;
+    payload: Event;
+};
+export type RawHarnessEvent = {
+    source: string;
+    method?: string;
+    payload: unknown;
+    receivedAt?: number;
+};
+export type RuntimeQuestion = {
+    text: string;
+    options?: string[];
+    optionDescriptions?: Record<string, string>;
+    header?: string;
+    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

@@ -0,0 +1,52 @@
+export type AgentFileContent = {
+    type: "text" | "binary";
+    content: string;
+    diff?: string;
+    patch?: {
+        oldFileName: string;
+        newFileName: string;
+        oldHeader?: string;
+        newHeader?: string;
+        hunks: Array<{
+            oldStart: number;
+            oldLines: number;
+            newStart: number;
+            newLines: number;
+            lines: string[];
+        }>;
+        index?: string;
+    };
+    encoding?: "base64";
+    mimeType?: string;
+};
+export type AgentVcsFileDiff = {
+    file: string;
+    patch?: string;
+    additions: number;
+    deletions: number;
+    status?: "added" | "deleted" | "modified";
+};
+/** A fully identified diff ready for review presentation. */
+export type AgentReviewFileDiff = {
+    file: string;
+    patch?: string;
+    before?: string;
+    after?: string;
+    additions: number;
+    deletions: number;
+    status?: "added" | "deleted" | "modified";
+};
+export type AgentPresentationModel = {
+    id: string;
+    name: string;
+};
+/** Provider fields consumed by transcript presentation. */
+export type AgentPresentationProvider = {
+    id: string;
+    name: string;
+    models: Record<string, AgentPresentationModel>;
+};
+/** Structural guard: is `value` a well-formed review diff record? */
+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[];

package/dist/harness-effort.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The closed set of effort words a harness may be asked for, mirroring the
+ * Claude Agent SDK's `EffortLevel` union. This is the VOCABULARY; which of
+ * these words a given model accepts is `HarnessEffortLevels` below.
+ */
+export declare const HARNESS_EFFORT_LEVELS: readonly ["low", "medium", "high", "xhigh", "max"];
+export type HarnessEffortLevel = (typeof HARNESS_EFFORT_LEVELS)[number];
+/** Sound because `HARNESS_EFFORT_LEVELS` is the tuple `HarnessEffortLevel` is derived from. */
+export declare function isHarnessEffortLevel(value: string): value is HarnessEffortLevel;
+/** One model's accepted effort levels, exactly as the harness reported them. */
+export type HarnessModelEffort = {
+    modelID: string;
+    levels: readonly string[];
+    /** The level the harness runs when a turn names none. */
+    default?: string;
+};
+/**
+ * Which effort words a harness accepts, per model, and how sure it is.
+ *
+ * `unsupported` — the harness has no effort control, so every level is refused.
+ * `unresolved` — it has one, but no model catalog has answered yet, so neither
+ * accepting nor refusing a level is grounded in what the harness said.
+ * `resolved` — `models` is complete: a model absent from it takes no effort.
+ */
+export type HarnessEffortLevels = {
+    status: "unsupported" | "unresolved" | "resolved";
+    models: readonly HarnessModelEffort[];
+};
+export declare const NO_HARNESS_EFFORT: HarnessEffortLevels;
+export type HarnessEffortVerdict = "accepted" | "refused" | "unknown";
+/**
+ * Whether a harness accepts an effort for a model, read off the same catalog
+ * the capability response carries so no caller keeps a second list.
+ *
+ * `unknown` is distinct from `refused`: an unresolved catalog is an unanswered
+ * question, and refusing a turn on it would ground the refusal in nothing.
+ */
+export declare function harnessEffortVerdict(catalog: HarnessEffortLevels | undefined, modelID: string | undefined, effort: string | undefined): HarnessEffortVerdict;
+/** The catalog a capability response carries, or `undefined` when it carries none. */
+export declare function parseHarnessEffortLevels(value: unknown): HarnessEffortLevels | undefined;
+/**
+ * The sentence a caller refuses a configuration's effort with, or `undefined`
+ * when the effort must be admitted.
+ *
+ * Only a `resolved` catalog refuses. `unresolved` has not answered yet, and
+ * `unsupported` is what every harness whose model rows carry no per-model
+ * levels reports even when it honours a level anyway — Pi runs the
+ * `set_thinking_level` it never publishes a catalog for — so refusing on
+ * either would refuse on silence rather than on what the harness said.
+ */
+export declare function harnessEffortRefusal(input: {
+    harness: string;
+    catalog: HarnessEffortLevels | undefined;
+    modelID: string | undefined;
+    effort: string | undefined;
+}): string | undefined;

package/dist/harness-table.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The harnesses Claxedo runs turns on, and the provider ids each resolves its
+ * auth through.
+ *
+ * Data only, and in the contract package rather than beside any one consumer:
+ * the server decides which binding a sign-in is stored against, the machine
+ * scan decides which bindings a CLI login drives, and the app draws one row per
+ * harness. Held separately those lists drifted — `cursor-sdk` was in one and
+ * not another — and a provider id missing from a list loses its login without
+ * anything failing.
+ */
+export declare const HARNESS_IDS: readonly ["claude", "codex", "cursor"];
+export type HarnessId = (typeof HARNESS_IDS)[number];
+type HarnessRecord = {
+    /** The product's own name, as every surface writes it. */
+    label: string;
+    vendor: string;
+    /**
+     * Every registry provider id whose stored row this harness can run on:
+     * connect provider first, then the other harness binding, then the vendor
+     * 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.
+     */
+    providerIds: readonly string[];
+    /** The provider id a sign-in for this harness is stored against. */
+    connectProvider: string;
+    /**
+     * The one id in `providerIds` that names the vendor rather than this
+     * harness's own binding. `providerIds` minus this is the set of bindings the
+     * harness resolves auth through, which is what a reader comparing a login's
+     * reach against the harness's own bindings has to compare with.
+     */
+    vendorProvider: string;
+    /**
+     * Those of `providerIds` the CLI's own login drives. `cursor-agent login`
+     * signs the CLI in and Cursor ACP runs on it; the Cursor SDK takes its key as
+     * an `Agent.create` argument and refuses a turn however signed in the CLI is.
+     */
+    machineLoginServes: readonly string[];
+};
+export declare const HARNESS_TABLE: Readonly<Record<HarnessId, HarnessRecord>>;
+export declare function isHarnessId(value: string): value is HarnessId;
+/**
+ * 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
+ * no harness to be listed under.
+ */
+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[];
+export {};