@claxedo/agent-runtime-contract 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Claxedo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# `@claxedo/agent-runtime-contract`
+
+Dependency-free canonical contracts for Claxedo agent sessions: execution
+bindings, content and message shapes, capabilities, connection descriptors,
+errors, file references, and the runtime event model. Every Claxedo runtime
+package (`@claxedo/agent-event-runtime`, `@claxedo/agent-sdk-runtime`,
+`@claxedo/workspace-runtime`) and every client that speaks to them imports
+these types from here, so the wire contract has exactly one owner.
+
+## Install
+
+```sh
+npm install @claxedo/agent-runtime-contract
+```
+
+## Usage
+
+```ts
+import { assertAgentExecutionBinding, AGENT_RUNTIME_CONTRACT_VERSION } from "@claxedo/agent-runtime-contract"
+
+const binding = assertAgentExecutionBinding({
+  scope: "central",
+  directory: "",
+  sessionId: "central-1",
+  connectionId: "native:pi",
+  upstreamSessionId: "pi-1",
+})
+```
+
+The package ships plain ESM plus type declarations and has no runtime
+dependencies, so it loads under Node without a TypeScript loader.
+
+## Versioning
+
+`agent-runtime-contract` rides the runtime version track with the other
+runtime packages (see `script/PUBLISH-ORDER.md` in the repository). A contract
+change that consumers must react to bumps `AGENT_RUNTIME_CONTRACT_VERSION`.

package/dist/availability.d.ts

@@ -0,0 +1,42 @@
+export type ExecutionAvailability = {
+    status: "available";
+} | {
+    status: "selection-required";
+    selection: "harness" | "model";
+} | {
+    status: "offline";
+    message: string;
+} | {
+    status: "unsupported";
+    operation: string;
+} | {
+    status: "unavailable";
+    message: string;
+    connectionId?: string;
+} | {
+    status: "upstream-error";
+    message: string;
+    connectionId?: string;
+};
+export type AgentRuntimeStatus = {
+    type: "idle";
+} | {
+    type: "busy";
+} | {
+    type: "retry";
+    attempt: number;
+    message: string;
+    next: number;
+    action?: {
+        reason: string;
+        provider: string;
+        title: string;
+        message: string;
+        label: string;
+        link?: string;
+    };
+} | {
+    type: "recovering";
+    kind: "process_restart";
+    message: string;
+};

package/dist/capabilities.d.ts

@@ -0,0 +1,31 @@
+export type AgentModel = {
+    providerId: string;
+    modelId: string;
+    name: string;
+    description?: string;
+};
+export type ModelSelection = {
+    status: "required";
+    models: AgentModel[];
+} | {
+    status: "optional";
+    models?: AgentModel[];
+} | {
+    status: "unsupported";
+};
+export type AgentCapabilities = {
+    harness: string;
+    modelSelection: ModelSelection;
+    abort: boolean;
+    reconnect: boolean;
+    replay: boolean;
+    permissions: boolean;
+    questions: boolean;
+    todos: boolean;
+    commands: boolean;
+    fork: boolean;
+    revert: boolean;
+    unrevert: boolean;
+    configOptions: boolean;
+    subagents: boolean;
+};

package/dist/claims.d.ts

@@ -0,0 +1,31 @@
+/**
+ * What a vendor's login document says about the account it belongs to.
+ *
+ * Pure parsing over a JWT's claims, and here rather than beside either reader:
+ * the credential authority asks it to name a stored account, and the Codex
+ * harness asks it of the auth file the CLI wrote. Two copies drifted on which
+ * claim they would accept, and an account id read one way and written the other
+ * spends one subscription's token against another's plan.
+ */
+/**
+ * The account's email address out of a login document's claims.
+ *
+ * Which claim holds it depends on the issuer and on which token is present: a
+ * ChatGPT `id_token` carries `email`, an access token often carries only
+ * `preferred_username`, and the `https://api.openai.com/auth` namespace keeps
+ * its own copy. The `@` test is what separates an address from a bare
+ * username, which `preferred_username` is free to be.
+ *
+ * A secret that is not a JWT names no account — never an error, because a
+ * credential without an email is ordinary.
+ */
+export declare function emailFromClaims(input: Record<string, unknown> | undefined): string | undefined;
+/**
+ * The ChatGPT account a login document names.
+ *
+ * This is what tells the Codex backend which plan a token spends, and a login
+ * often carries it only inside the `id_token`. An organization list is the last
+ * resort: a login that names no account id still belongs to the first
+ * organization its claims list.
+ */
+export declare function accountIdFromClaims(input: Record<string, unknown> | undefined): string | undefined;

package/dist/connections.d.ts

@@ -0,0 +1,21 @@
+import type { AgentCapabilities, ModelSelection } from "./capabilities";
+export type ConnectionReadiness = "ready" | "unavailable" | "disabled";
+export type HarnessConnectionCapabilities = Omit<AgentCapabilities, "harness" | "modelSelection">;
+/** Public discovery metadata. Provider configuration and credentials stay on the host. */
+export type HarnessConnectionRef = {
+    connectionId: string;
+    label: string;
+    enabled: boolean;
+    readiness: ConnectionReadiness;
+    capabilities: HarnessConnectionCapabilities;
+    modelSelection?: ModelSelection;
+};
+export type HarnessConnectionsCatalog = {
+    status: "supported";
+    connections: HarnessConnectionRef[];
+} | {
+    status: "unsupported";
+    reason: string;
+};
+export declare function decodeHarnessConnectionsCatalog(value: unknown): HarnessConnectionsCatalog;
+export declare function decodeModelSelection(value: unknown): ModelSelection;

package/dist/content.d.ts

@@ -0,0 +1,411 @@
+import type { AgentMessageAuthor } from "./sessions";
+/** Token accounting, reported identically by assistant messages and step-finish parts. */
+export type AgentTokenUsage = {
+    total?: number;
+    input: number;
+    output: number;
+    reasoning: number;
+    cache: {
+        read: number;
+        write: number;
+    };
+};
+/** The provider/model pair a message was produced with. */
+export type AgentModelRef = {
+    providerID: string;
+    modelID: string;
+    variant?: string;
+};
+export type AgentMessageError = {
+    name: string;
+    data: Record<string, unknown> & {
+        message?: string;
+    };
+};
+export type AgentOutputFormat = {
+    type: "text";
+} | {
+    type: "json_schema";
+    schema: Record<string, unknown>;
+    retryCount?: number;
+};
+export type AgentUserMessage = {
+    id: string;
+    sessionID: string;
+    role: "user";
+    time: {
+        created: number;
+    };
+    format?: AgentOutputFormat;
+    summary?: {
+        title?: string;
+        body?: string;
+        diffs: AgentSnapshotFileDiff[];
+    };
+    agent: string;
+    model: AgentModelRef;
+    system?: string;
+    tools?: Record<string, boolean>;
+    claxedo?: {
+        author: AgentMessageAuthor;
+    };
+};
+export type AgentAssistantMessage = {
+    id: string;
+    sessionID: string;
+    role: "assistant";
+    time: {
+        created: number;
+        completed?: number;
+    };
+    error?: AgentMessageError;
+    parentID: string;
+    modelID: string;
+    providerID: string;
+    mode: string;
+    agent: string;
+    path: {
+        cwd: string;
+        root: string;
+    };
+    summary?: boolean;
+    cost: number;
+    tokens: AgentTokenUsage;
+    structured?: unknown;
+    variant?: string;
+    finish?: string;
+};
+/** Message information rendered by transcript and navigation surfaces. */
+export type AgentPresentationMessage = AgentUserMessage | AgentAssistantMessage;
+export type AgentMessageInfo = {
+    id: string;
+    role: string;
+    sessionID: string;
+    parentID?: string;
+    time?: {
+        created: number;
+        completed?: number;
+    };
+    providerID?: string;
+    modelID?: string;
+    model?: AgentModelRef;
+    agent?: string;
+    mode?: string;
+    path?: {
+        cwd: string;
+        root: string;
+    };
+    cost?: number;
+    tokens?: AgentTokenUsage;
+    tools?: Record<string, boolean>;
+    system?: string;
+    variant?: string;
+    format?: unknown;
+    finish?: string;
+    error?: AgentMessageError;
+    claxedo?: {
+        author: AgentMessageAuthor;
+    };
+    harnessPayload?: unknown;
+    [key: string]: unknown;
+};
+export type AgentMessage = {
+    info: AgentMessageInfo;
+    parts: AgentContentPart[];
+    harnessPayload?: unknown;
+};
+type AgentPartBase<Type extends string> = {
+    id: string;
+    sessionID: string;
+    messageID: string;
+    type: Type;
+};
+export type AgentTextPart = AgentPartBase<"text"> & {
+    text: string;
+    synthetic?: boolean;
+    ignored?: boolean;
+    time?: {
+        start: number;
+        end?: number;
+    };
+    metadata?: Record<string, unknown>;
+};
+export type AgentReasoningPart = AgentPartBase<"reasoning"> & {
+    text: string;
+    time: {
+        start: number;
+        end?: number;
+    };
+    metadata?: Record<string, unknown>;
+};
+export type AgentFilePartSourceText = {
+    value: string;
+    start: number;
+    end: number;
+};
+export type AgentFilePartRange = {
+    start: {
+        line: number;
+        character: number;
+    };
+    end: {
+        line: number;
+        character: number;
+    };
+};
+export type AgentFileSource = {
+    type: "file";
+    text: AgentFilePartSourceText;
+    path: string;
+};
+export type AgentSymbolSource = {
+    type: "symbol";
+    text: AgentFilePartSourceText;
+    path: string;
+    range: AgentFilePartRange;
+    name: string;
+    kind: number;
+};
+export type AgentResourceSource = {
+    type: "resource";
+    text: AgentFilePartSourceText;
+    clientName: string;
+    uri: string;
+};
+export type AgentFilePartSource = AgentFileSource | AgentSymbolSource | AgentResourceSource;
+/**
+ * Where a file part's bytes are when `url` does not carry them. A workspace
+ * file is read by path when the view needs it; unretained bytes were dropped
+ * at capture and only their size survives, so a view can say how large the
+ * image was instead of rendering a broken one.
+ */
+export type AgentFileLocation = {
+    kind: "workspace-file";
+    path: string;
+} | {
+    kind: "unretained";
+    bytes: number;
+};
+export type AgentFilePart = AgentPartBase<"file"> & {
+    mime: string;
+    filename?: string;
+    url: string;
+    location?: AgentFileLocation;
+    source?: AgentFilePartSource;
+};
+export type AgentTextPartInput = Omit<AgentTextPart, "id" | "sessionID" | "messageID"> & {
+    id?: string;
+};
+export type AgentFilePartInput = Omit<AgentFilePart, "id" | "sessionID" | "messageID"> & {
+    id?: string;
+};
+export type AgentAgentPartInput = Omit<AgentAgentPart, "id" | "sessionID" | "messageID"> & {
+    id?: string;
+};
+export type AgentToolState = {
+    status: "pending";
+    input: Record<string, unknown>;
+    raw: string;
+} | {
+    status: "running";
+    input: Record<string, unknown>;
+    title?: string;
+    metadata?: Record<string, unknown>;
+    time: {
+        start: number;
+    };
+} | {
+    status: "completed";
+    input: Record<string, unknown>;
+    output: string;
+    title: string;
+    metadata: Record<string, unknown>;
+    time: {
+        start: number;
+        end: number;
+        compacted?: number;
+    };
+    attachments?: AgentFilePart[];
+} | {
+    status: "error";
+    input: Record<string, unknown>;
+    error: string;
+    metadata?: Record<string, unknown>;
+    time: {
+        start: number;
+        end: number;
+    };
+};
+export type AgentToolPart = AgentPartBase<"tool"> & {
+    callID: string;
+    tool: string;
+    state: AgentToolState;
+    metadata?: Record<string, unknown>;
+};
+/**
+ * Whether a tool name spawns a subagent. Every harness spelling — Claude's `Agent`,
+ * the runtime's own `create_subagent`, bare or MCP-prefixed — canonicalises to `task`,
+ * so the alias table is the one place a new spelling is added. Both the event runtime's
+ * tool-intent mapping and the transcript's grouping ask this question here, because a
+ * name known to only one of them is a subagent that renders as a generic tool row.
+ *
+ * Callers pass the tool name as the part carries it; matching is case-insensitive
+ * because only the client-presentation projection canonicalises case.
+ */
+export declare function isSubagentSpawnToolName(toolName: string): boolean;
+export type AgentSubtaskPart = AgentPartBase<"subtask"> & {
+    prompt: string;
+    description: string;
+    agent: string;
+    model?: {
+        providerID: string;
+        modelID: string;
+    };
+    command?: string;
+};
+export type AgentStepStartPart = AgentPartBase<"step-start"> & {
+    snapshot?: string;
+};
+export type AgentStepFinishPart = AgentPartBase<"step-finish"> & {
+    reason: string;
+    snapshot?: string;
+    cost: number;
+    tokens: AgentTokenUsage;
+};
+export type AgentSnapshotPart = AgentPartBase<"snapshot"> & {
+    snapshot: string;
+};
+export type AgentPatchPart = AgentPartBase<"patch"> & {
+    hash: string;
+    files: string[];
+};
+export type AgentAgentPart = AgentPartBase<"agent"> & {
+    name: string;
+    source?: {
+        value: string;
+        start: number;
+        end: number;
+    };
+};
+export type AgentRetryPart = AgentPartBase<"retry"> & {
+    attempt: number;
+    error: AgentMessageError;
+    time: {
+        created: number;
+    };
+};
+export type AgentCompactionPart = AgentPartBase<"compaction"> & {
+    auto: boolean;
+    overflow?: boolean;
+    tail_start_id?: string;
+};
+export type AgentHandoffPart = AgentPartBase<"handoff"> & {
+    from: {
+        id: string;
+        access: string;
+        connection?: unknown;
+    };
+    to: {
+        id: string;
+        access: string;
+        connection?: unknown;
+    };
+};
+export type AgentContentPart = AgentTextPart | AgentReasoningPart | AgentFilePart | AgentToolPart | AgentSubtaskPart | AgentStepStartPart | AgentStepFinishPart | AgentSnapshotPart | AgentPatchPart | AgentAgentPart | AgentRetryPart | AgentCompactionPart | AgentHandoffPart;
+export type AgentPromptResponse = {
+    info: AgentAssistantMessage;
+    parts: AgentContentPart[];
+};
+export type AgentTodo = {
+    /** Provider-issued task identity, retained for incremental native updates. */
+    id?: string;
+    content: string;
+    status: string;
+    priority: string;
+};
+export type AgentQuestionOption = {
+    label: string;
+    description: string;
+};
+export type AgentQuestionInfo = {
+    question: string;
+    header: string;
+    options: AgentQuestionOption[];
+    multiple?: boolean;
+    custom?: boolean;
+};
+export type AgentQuestionAnswer = string[];
+export type AgentPermission = {
+    id: string;
+    sessionID: string;
+    tool?: {
+        messageID: string;
+        callID: string;
+    };
+    title?: string;
+    permission: string;
+    patterns: string[];
+    always: string[];
+    metadata: Record<string, unknown>;
+    time?: {
+        created?: number;
+    };
+    harnessPayload?: unknown;
+};
+export type AgentQuestion = {
+    id: string;
+    sessionID: string;
+    questions: AgentQuestionInfo[];
+    tool?: {
+        messageID: string;
+        callID: string;
+    };
+    harnessPayload?: unknown;
+};
+export type AgentCommand = {
+    name: string;
+    content?: string;
+    description?: string;
+    harnessPayload?: unknown;
+};
+export type AgentAgent = {
+    name: string;
+    description?: string;
+    mode?: string;
+    harnessPayload?: unknown;
+};
+export type AgentConfigOption = {
+    id: string;
+    name?: string;
+    type?: string;
+    category?: string;
+    currentValue?: unknown;
+    description?: string;
+    selectOptions?: Array<{
+        id: string;
+        name?: string;
+        description?: string;
+        value?: unknown;
+        connected?: boolean;
+        harnessPayload?: unknown;
+    }>;
+    harnessPayload?: unknown;
+};
+export type AgentSnapshotFileDiff = {
+    file?: string;
+    patch?: string;
+    additions: number;
+    deletions: number;
+    status?: "added" | "deleted" | "modified";
+};
+/** Is `value` one of the content parts the contract declares? */
+export declare function isAgentContentPart(value: unknown): value is AgentContentPart;
+/** The content part `value` holds, or `undefined` when it is not one. */
+export declare function parseAgentContentPart(value: unknown): AgentContentPart | undefined;
+/** Is `value` the identifying header every message carries? */
+export declare function isAgentMessageInfo(value: unknown): value is AgentMessageInfo;
+/** Is `value` a message — a valid header and a list of parts the contract declares? */
+export declare function isAgentMessage(value: unknown): value is AgentMessage;
+/** The message `value` holds, or `undefined` when it is not one. */
+export declare function parseAgentMessage(value: unknown): AgentMessage | undefined;
+export {};

package/dist/credential-broker-errors.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Every refusal Claxedo's credential broker answers with: the one line each
+ * says, and which side of the turn it blames.
+ *
+ * One table because two readers act on these codes — the broker writes them,
+ * and the runtime that classifies a failed turn decides from them what to tell
+ * the operator. A second hand-kept copy could only disagree, and disagreeing
+ * here means telling someone to replace a working account for a request their
+ * harness should never have made.
+ *
+ * `fault` is that decision. The HTTP status cannot stand in for it: 403 is the
+ * answer both for a credential the broker will not serve and for a route the
+ * binding does not allow.
+ */
+export declare const CREDENTIAL_BROKER_ERRORS: {
+    readonly binding_route_required: {
+        readonly fault: "harness";
+        readonly message: "The credential broker serves binding paths only";
+    };
+    readonly runtime_token_required: {
+        readonly fault: "harness";
+        readonly message: "The request carried no runtime token, or two that disagree";
+    };
+    readonly runtime_token_invalid: {
+        readonly fault: "credential";
+        readonly message: "The runtime token could not be verified";
+    };
+    readonly binding_not_permitted: {
+        readonly fault: "harness";
+        readonly message: "This runtime token does not name that binding";
+    };
+    readonly binding_unavailable: {
+        readonly fault: "credential";
+        readonly message: "The binding names no account this runtime can spend";
+    };
+    readonly credential_unavailable: {
+        readonly fault: "credential";
+        readonly message: "The account behind this binding has no readable value";
+    };
+    readonly binding_destination_invalid: {
+        readonly fault: "harness";
+        readonly message: "The binding's destination is not a usable vendor origin";
+    };
+    readonly binding_injection_invalid: {
+        readonly fault: "harness";
+        readonly message: "The binding names a header the broker cannot set";
+    };
+    readonly request_outside_policy: {
+        readonly fault: "harness";
+        readonly message: "The request is outside the routes this binding allows";
+    };
+    readonly upstream_unavailable: {
+        readonly fault: "model";
+        readonly message: "The vendor could not be reached";
+    };
+    readonly upstream_redirect_refused: {
+        readonly fault: "model";
+        readonly message: "The vendor answered with a redirect, which the broker does not follow";
+    };
+    readonly broker_authority_unavailable: {
+        readonly fault: "harness";
+        readonly message: "The credential authority could not be reached";
+    };
+    /** Answered by the mounts in front of the broker, in the broker's vocabulary. */
+    readonly loopback_required: {
+        readonly fault: "harness";
+        readonly message: "The credential broker answers loopback callers only";
+    };
+};
+export type CredentialBrokerErrorCode = keyof typeof CREDENTIAL_BROKER_ERRORS;
+/**
+ * The code a message carries.
+ *
+ * The JSON body a harness echoed first: one that retried names its earlier
+ * failure in its own prose, and the verdict belongs to the response it gave up
+ * on. The bare code in that prose is the fallback, for a harness that
+ * summarises the body rather than quoting it.
+ */
+export declare function credentialBrokerErrorCode(message: string): CredentialBrokerErrorCode | undefined;
+export declare function isCredentialBrokerErrorCode(value: string): value is CredentialBrokerErrorCode;