@claxedo/agent-runtime-contract 0.8.0

package/dist/question-answers.d.ts

@@ -0,0 +1,13 @@
+import type { AgentQuestionAnswer } from "./content";
+export type QuestionAnswerSource = {
+    question: string;
+    optionLabels: string[];
+    multiple: boolean;
+};
+/**
+ * A harness reports one answer per question as a single string, joining a multi-select
+ * with `", "`, which loses the selection boundaries. Splitting unconditionally would cut
+ * a free-text answer at its first comma, so the declared option labels decide: a value
+ * that is itself a label, or that does not split cleanly into labels, is one answer.
+ */
+export declare function reconstructQuestionAnswers(questions: QuestionAnswerSource[], answers: Record<string, unknown>): AgentQuestionAnswer[];

package/dist/session-group.d.ts

@@ -0,0 +1,37 @@
+import { type SessionHarness } from "./harnesses";
+import type { PromptModel } from "./sessions";
+/** The slots a Tasks preset resolves. A group names at most one entry per slot. */
+export declare const SESSION_GROUP_SLOTS: readonly ["primary", "planning", "implementation", "review"];
+export type SessionGroupSlot = (typeof SESSION_GROUP_SLOTS)[number];
+export type SessionGroupEntry = {
+    harness: SessionHarness;
+    model: PromptModel;
+    /** Absent leaves the choice with the model's own default. */
+    effort?: string;
+};
+export type SessionModelGroup = Partial<Record<SessionGroupSlot, SessionGroupEntry>>;
+export type SessionModelGroupParse = {
+    group: SessionModelGroup;
+} | {
+    field: string;
+    message: string;
+};
+export declare function isSessionGroupSlot(value: string): value is SessionGroupSlot;
+/**
+ * The machine-readable group a session was created under.
+ *
+ * A malformed slot is refused by name rather than dropped: a group that quietly
+ * lost a slot on the way in resolves a later delegation to the wrong model.
+ */
+export declare function parseSessionModelGroup(input: unknown): SessionModelGroupParse;
+/**
+ * A slot's effort as a session create body spells it. The runtime's field is
+ * `variant` because a harness may accept a thinking level that is not an
+ * effort, so every caller resolving a slot translates here instead of by hand.
+ */
+export declare function sessionVariantForEffort(effort: string | undefined): {
+    variant?: string;
+};
+export declare function sessionModelGroupJson(group: SessionModelGroup | null | undefined): string | null;
+/** A row written by an older build, or corrupted, reads back as no group at all. */
+export declare function parseStoredSessionModelGroup(json: string | null | undefined): SessionModelGroup | undefined;

package/dist/sessions.d.ts

@@ -0,0 +1,166 @@
+import type { ExecutionAvailability } from "./availability";
+import type { AgentAgentPartInput, AgentFilePartInput, AgentTextPartInput } from "./content";
+export type AgentWorkspaceIdentity = {
+    workspaceId: string;
+    directory: string;
+};
+/**
+ * The complete identity required for any provider-owned execution operation.
+ * `upstreamSessionId` is opaque: Claxedo stores and forwards it but never
+ * parses it or uses it to discover sessions.
+ */
+export type AgentWorkspaceExecutionBinding = AgentWorkspaceIdentity & {
+    scope?: "workspace";
+    sessionId: string;
+    connectionId: string;
+    upstreamSessionId: string;
+};
+export type AgentExecutionBinding = AgentWorkspaceExecutionBinding;
+export type AgentExecutionBindingField = keyof AgentExecutionBinding;
+export type AgentExecutionBindingExpectation = Readonly<{
+    scope?: "workspace";
+    sessionId: string;
+    workspaceId?: string;
+    directory: string;
+    connectionId: string;
+    upstreamSessionId: string;
+}>;
+export type AgentSession = {
+    id: string;
+    workspaceId?: string;
+    title?: string | null;
+    slug?: string;
+    version?: string;
+    directory?: string;
+    parentID?: string;
+    rootID?: string;
+    projectID?: string;
+    tags?: unknown[];
+    attachments?: unknown[];
+    metadata?: Record<string, unknown>;
+    time?: {
+        created: number;
+        updated?: number;
+        archived?: number;
+    };
+    status?: string | null;
+    lastTurn?: AgentTurnOutcome;
+    executionAvailability?: ExecutionAvailability;
+    harnessPayload?: unknown;
+};
+export type AgentPresentationSession = AgentSession & {
+    tags?: string[];
+    slug: string;
+    projectID: string;
+    workspaceID?: string;
+    directory: string;
+    path?: string;
+    parentID?: string;
+    summary?: {
+        additions: number;
+        deletions: number;
+        files: number;
+        diffs?: import("./content").AgentSnapshotFileDiff[];
+    };
+    cost?: number;
+    tokens?: {
+        input: number;
+        output: number;
+        reasoning: number;
+        cache: {
+            read: number;
+            write: number;
+        };
+    };
+    share?: {
+        url: string;
+    };
+    title: string;
+    agent?: string;
+    model?: {
+        id: string;
+        providerID: string;
+        variant?: string;
+    };
+    version: string;
+    permission?: Array<{
+        permission: string;
+        pattern: string;
+        action: "allow" | "deny" | "ask";
+    }>;
+    revert?: {
+        messageID: string;
+        partID?: string;
+        snapshot?: string;
+        diff?: string;
+    };
+    time: {
+        created: number;
+        updated: number;
+        archived?: number;
+    };
+};
+export type AgentTurnOutcome = ({
+    status: "completed";
+    completedAt: number;
+    reason?: string;
+} | {
+    status: "failed";
+    completedAt: number;
+    error: string;
+} | {
+    status: "cancelled";
+    completedAt: number;
+    reason?: string;
+}) & {
+    assistantMessageId?: string;
+};
+export type PromptModel = {
+    providerID: string;
+    modelID: string;
+};
+export type PromptFormat = {
+    type: "json_schema";
+    name?: string;
+    schema?: unknown;
+    strict?: boolean;
+    provider_payload?: unknown;
+} | {
+    type: string;
+    provider_payload?: unknown;
+    [key: string]: unknown;
+};
+export type PromptInput = {
+    parts: Array<AgentTextPartInput | AgentFilePartInput | AgentAgentPartInput>;
+    userMessageId?: string;
+    /** Existing user intent that owns a provider-initiated continuation. */
+    parentMessageId?: string;
+    assistantMessageId: string;
+    agent: string;
+    model: PromptModel;
+    tools?: Record<string, boolean>;
+    format?: PromptFormat;
+    system?: string;
+    variant?: string;
+    permissionMode?: string;
+    /**
+     * What to do when the session is already running a turn. `steer` hands this
+     * prompt to that turn; `queue` holds it for the next one. Absent means the
+     * caller wants a turn of its own and will take an admission conflict.
+     */
+    delivery?: PromptDeliveryRequest;
+    author?: AgentMessageAuthor;
+};
+export type PromptDeliveryRequest = "steer" | "queue";
+/** How a prompt was admitted. `start` ran it as a turn of its own. */
+export type PromptDelivery = "start" | PromptDeliveryRequest;
+export type AgentMessageAuthor = {
+    id: string;
+    name: string;
+    avatarUrl?: string;
+    kind: "human" | "agent";
+};
+export declare function connectionIdForHarness(harness: {
+    id: string;
+    access: string;
+}): string;

package/dist/tool-names.d.ts

@@ -0,0 +1,3 @@
+export declare function canonicalToolName(name: string): string;
+/** The alias spellings themselves, for consumers that register one entry per name. */
+export declare function toolNameAliases(): ReadonlyArray<readonly [alias: string, target: string]>;

package/dist/usage-windows.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The Claxedo name for each plan-usage window slot a vendor reports.
+ *
+ * Data only, and in the contract package because four readers spell the same
+ * three windows differently — the HTTP verifier, the Codex app-server
+ * self-report, the machine-wide probe and the Claude event adapter — and a
+ * window named one way by the writer and another by the reader draws as two
+ * plans.
+ */
+/**
+ * Per harness, because one table across vendors would label half of them
+ * wrongly: `primary_window` is a session for Codex and the whole billing cycle
+ * for Cursor. A harness, or a slot, that is not listed keeps the vendor's own
+ * field name — inventing a tier name for it would rot on the next vendor change
+ * without anything failing.
+ */
+export declare const USAGE_WINDOW_NAMES: Readonly<Record<string, Readonly<Record<string, string>>>>;
+/**
+ * Codex's own usage read names a window by its declared `limit_window_seconds`
+ * rather than by the slot it arrives in: a free plan gets only the weekly
+ * window, delivered in the primary slot.
+ */
+export declare const CODEX_WINDOW_NAME_BY_SECONDS: Readonly<Record<number, string>>;

package/dist/values.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Structural guards for values crossing a boundary into the contract types.
+ *
+ * A payload arriving as JSON, an IPC message, or a database row is `unknown`.
+ * These guards are how it becomes typed: they narrow by checking, so nothing
+ * downstream has to assert.
+ */
+export { asRecord, isRecord } from "@claxedo/helpers/guards";
+/** The non-empty string `value` holds, or `undefined`. */
+export declare function asText(value: unknown): string | undefined;

package/package.json

@@ -0,0 +1,53 @@
+{
+  "type": "module",
+  "description": "Dependency-free canonical contracts for Claxedo agent sessions, content, execution, errors, and events",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kyashrathore/Claxedo.git",
+    "directory": "packages/agent-runtime-contract"
+  },
+  "keywords": [
+    "claxedo",
+    "agents",
+    "contracts",
+    "sessions",
+    "events"
+  ],
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "development": "./src/index.ts",
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "files": [
+    "README.md",
+    "LICENSE",
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "name": "@claxedo/agent-runtime-contract",
+  "version": "0.8.0",
+  "scripts": {
+    "build": "bun build src/index.ts --target=browser --format=esm --outfile=dist/index.mjs && tsc -p tsconfig.build.json",
+    "test:node": "node --test scripts/package.test.mjs",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test src",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@claxedo/helpers": "0.1.0"
+  },
+  "devDependencies": {
+    "@tsconfig/bun": "1.0.9",
+    "@types/bun": "1.3.13",
+    "typescript": "catalog:"
+  }
+}