@hraness/xcb 0.9.1

package/dist/browser-session.d.ts

@@ -0,0 +1,161 @@
+import { type ChildProcessWithoutNullStreams } from "node:child_process";
+/**
+ * Per-account browser-session custody. Interactive provider sign-in runs inside
+ * one fixed, privately owned browser profile per provider account: cookies and
+ * site state persist across launches under that profile, so a returning account
+ * is already signed in and a new account never shares another account's
+ * session. The profile directory, never its contents, is the custody boundary:
+ * this module creates it privately, binds it to the exact account identity,
+ * serializes launches through an exclusive durable lock, bounds every launch
+ * through a hash-chained journal, and requires proven process exit plus group
+ * absence before releasing the lock. A stale lock is a recovery requirement,
+ * never permission to take over.
+ *
+ * No credentials, cookies, page contents, or browser output are read, returned,
+ * or logged. The provider supplies only the initial navigation URL; the host
+ * supplies the admitted executable. This module cannot prove a rendered page,
+ * a completed sign-in, or provider account state — it proves custody.
+ */
+export type BrowserSessionBinding = Readonly<{
+    /** Namespace label for the account's provider family, e.g. "codex". This is
+     * an identifier, not provider admission or a closed routing union. */
+    provider: string;
+    accountId: string;
+    owner: string;
+    /** The caller's current account-lease fence at launch time. */
+    leaseGeneration: number;
+    /** This launch's process fence; increments per session process. */
+    processGeneration: number;
+}>;
+export type BrowserSessionRuntimeAdmission = Readonly<{
+    /** Absolute canonical path of the reviewed browser executable. */
+    executablePath: string;
+    /** Observed version evidence, recorded verbatim. */
+    version: string;
+    /** SHA-256 of the reviewed executable bytes, re-verified at launch. */
+    sha256: string;
+}>;
+export type BrowserSessionOptions = Readonly<{
+    binding: BrowserSessionBinding;
+    /** Host-owned private root, mode 0700, canonical and user-only. */
+    stateRoot: string;
+    runtime: BrowserSessionRuntimeAdmission;
+    /** Optional initial navigation. https only; no userinfo or fragment policy
+     * is relaxed. Omitted launches open the browser's default blank page. */
+    url?: string;
+    /** Whole preparation deadline, 1 to 120000 milliseconds. */
+    startupTimeoutMs?: number;
+    /** Maximum session lifetime before a graceful close begins, 60000 to
+     * 3600000 milliseconds; default 900000. A login browser must not linger. */
+    maxSessionMs?: number;
+    /** Ambient environment the GUI-attach allowlist filters. Defaults to
+     * `process.env`; trusted hosts and tests pass an explicit map. */
+    environment?: Readonly<Record<string, string | undefined>>;
+}>;
+export type BrowserSessionSpawn = Readonly<{
+    executable: string;
+    args: readonly string[];
+    cwd: string;
+    env: Readonly<Record<string, string>>;
+    detached: true;
+    stdio: readonly ["pipe", "pipe", "pipe"];
+}>;
+/** Trusted system seam for synthetic process tests. This is not a plugin, an
+ * agent tool, a configuration input, or a sandboxing decision. */
+export interface BrowserSessionSystem {
+    spawn(request: BrowserSessionSpawn): ChildProcessWithoutNullStreams;
+    processGroup(pid: number): number | null;
+    signalGroup(pgid: number, signal: "SIGTERM" | "SIGKILL" | 0): boolean;
+}
+export type BrowserSessionPhase = "preparing" | "launch-pending" | "running" | "recovery-required" | "closed";
+export type BrowserSessionReceipt = Readonly<{
+    schema: "xcb.browser-session.v1";
+    binding: BrowserSessionBinding;
+    productionQualified: false;
+    browserVersion: string;
+    browserSha256: string;
+    launchAttempted: boolean;
+    pid: number | null;
+    pgid: number | null;
+    rootExited: boolean;
+    groupAbsent: boolean;
+    stdoutJoined: boolean;
+    stderrJoined: boolean;
+    lockReleased: boolean;
+    forcedExit: boolean;
+    gracefulExit: boolean;
+    journalPath: string | null;
+    phase: BrowserSessionPhase;
+    failures: readonly string[];
+}>;
+export type BrowserSessionCloseReceipt = Readonly<{
+    binding: BrowserSessionBinding;
+    processExited: boolean;
+    processGroupStopped: boolean;
+    stdoutEnded: boolean;
+    stderrEnded: boolean;
+    gracefulExit: boolean;
+}>;
+export interface BrowserSessionPort {
+    readonly binding: BrowserSessionBinding;
+    /** Resolves once the launch is proven running; rejects on refused launch. */
+    readonly ready: Promise<void>;
+    /** Resolves when the session has fully closed, however it ended. */
+    readonly closed: Promise<BrowserSessionCloseReceipt>;
+    receipt(): BrowserSessionReceipt;
+    /** Graceful close bound to the exact session binding: SIGTERM so the
+     * profile flushes, SIGKILL fallback, then proven exit, group absence, and
+     * stream joins before lock release. A mismatched binding refuses. */
+    close(request: {
+        binding: BrowserSessionBinding;
+        deadlineMs?: number;
+    }): Promise<BrowserSessionCloseReceipt>;
+}
+/** Fixed Chromium-family launch argv for the account's own profile. The
+ * password store stays profile-local (`basic`) so cookies never touch the
+ * system keyring and no interactive prompt can stall a managed launch; sync is
+ * disabled so the session cannot join a vendor account; crash/restore bubbles
+ * are suppressed so a recovered profile opens cleanly. */
+export declare function browserSessionArgv(input: {
+    executable: string;
+    profile: string;
+    url?: string;
+}): readonly string[];
+export declare function browserSessionEnvironment(ambient: Readonly<Record<string, string | undefined>>, input: {
+    home: string;
+    tmp: string;
+}): Record<string, string>;
+/**
+ * Recovers a session directory whose launch lock outlived its process. The
+ * caller proves the recorded process is stopped; this function then removes
+ * the stale lock and the browser's singleton trio so the profile opens
+ * cleanly. It never deletes cookies, history, or the binding marker, and it
+ * refuses to run while any lock holder could be alive.
+ */
+export declare function recoverBrowserSession(input: Readonly<{
+    stateRoot: string;
+    provider: string;
+    accountId: string;
+    proveStopped(binding: BrowserSessionBinding): Promise<boolean>;
+}>): Promise<{
+    recovered: true;
+}>;
+/**
+ * Destroys one account's whole browser-session directory as a unit — profile,
+ * cookies, markers, locks, and run journals — after proving no launch lock is
+ * held by a live process. This is the sign-out/revocation boundary; it is
+ * never implied by a close, an expiry, or a failed launch.
+ */
+export declare function purgeBrowserSession(input: Readonly<{
+    stateRoot: string;
+    provider: string;
+    accountId: string;
+    proveStopped(binding: BrowserSessionBinding): Promise<boolean>;
+}>): Promise<{
+    purged: true;
+}>;
+/** Synchronous custody handle; preparation and launch proceed asynchronously.
+ * The caller must already hold the matching account lease. Callers pass only
+ * the admitted executable, the account binding, and an optional https URL —
+ * profile, environment, and argv are owned here. */
+export declare function createBrowserSession(options: BrowserSessionOptions, trustedSystem?: BrowserSessionSystem): BrowserSessionPort;

package/dist/canonical-json.d.ts

@@ -0,0 +1,2 @@
+export declare function canonicalJson(value: unknown): string;
+export declare function canonicalJsonSha256(value: unknown): string;

package/dist/capabilities.d.ts

@@ -0,0 +1,72 @@
+export type CapabilityJson = null | boolean | number | string | readonly CapabilityJson[] | CapabilityObject;
+export type CapabilityObject = {
+    readonly [key: string]: CapabilityJson;
+};
+export declare const CAPABILITY_LIMITS: Readonly<{
+    tools: 64;
+    schemaBytes: number;
+    manifestBytes: number;
+    inputBytes: number;
+    outputBytes: number;
+    depth: 16;
+    nodes: 8192;
+    objectKeys: 256;
+    arrayItems: 4096;
+    calls: 256;
+    pendingCalls: 32;
+}>;
+export type CapabilityDescriptor = Readonly<{
+    name: string;
+    description: string;
+    inputSchema: CapabilityObject;
+}>;
+export type CapabilityProfileIdentity = Readonly<{
+    id: string;
+    version: number;
+    digest: string;
+}>;
+export type CapabilityProfile = CapabilityProfileIdentity & Readonly<{
+    tools: readonly CapabilityDescriptor[];
+}>;
+export type CapabilityContext = Readonly<{
+    workspaceId: string;
+    runId: string;
+    signal: AbortSignal;
+    /** Trusted handlers must recheck immediately before each effect, including
+     * after their own awaits, and retain their conditional-write/authority gates. */
+    assertActive(): void;
+}>;
+export type CapabilityTool = CapabilityDescriptor & Readonly<{
+    /** Trusted code enforces the complete semantic contract. Schema descriptors
+     * are not evaluated as a JSON Schema program by this broker. */
+    parseInput(input: CapabilityObject): CapabilityJson;
+    execute(input: CapabilityJson, context: CapabilityContext): unknown | Promise<unknown>;
+}>;
+export interface CapabilityBroker {
+    readonly profile: CapabilityProfile;
+    readonly workspaceId: string;
+    readonly runId: string;
+    invoke(name: unknown, input: unknown): Promise<CapabilityJson>;
+    assertActive(): void;
+    revoke(): void;
+    /** Revoke immediately and join all admitted handlers. This does not prove
+     * that an external provider process or controller has stopped. */
+    close(): Promise<void>;
+}
+/** The digest covers this ordered declarative manifest, not executable handler
+ * code, credentials or OS confinement. Runtime provenance is a separate gate. */
+export declare function createCapabilityProfile(options: {
+    id: string;
+    version: number;
+    tools: readonly CapabilityTool[];
+}): CapabilityProfile;
+/** Match the exact host-created profile against adapter qualification. A
+ * deserialized lookalike has no registered trusted implementation authority. */
+export declare function assertCapabilityProfile(profile: CapabilityProfile, expected: CapabilityProfileIdentity): void;
+export declare function createCapabilityBroker(options: {
+    profile: CapabilityProfile;
+    workspaceId: string;
+    runId: string;
+    isActive(): boolean;
+    signal?: AbortSignal;
+}): CapabilityBroker;

package/dist/claude-api-models.d.ts

@@ -0,0 +1,24 @@
+import type { ClaudeApiKeyResolver } from "./claude-sdk.ts";
+import { type ClaudeApiClient } from "./claude-api-transport.ts";
+import { type ModelCatalog } from "./models.ts";
+export type ClaudePriceCatalog = Readonly<{
+    observedAt: number;
+    models: readonly Readonly<{
+        id: string;
+        inputUsdPerMillion: number;
+        outputUsdPerMillion: number;
+        classifierEligible: boolean;
+    }>[];
+}>;
+export type ClaudeModelDiscoveryOptions = Readonly<{
+    credentials: ClaudeApiKeyResolver;
+    accountId: string;
+    priceCatalog: ClaudePriceCatalog;
+    signal: AbortSignal;
+    now?: () => number;
+}>;
+/** Lists availability only. It never sends a model prompt or invents provider prices. */
+export declare function discoverClaudeModels(options: ClaudeModelDiscoveryOptions): Promise<ModelCatalog>;
+/** Internal test seam: transport cannot be selected by owner/contact configuration. */
+export declare function parseClaudePriceCatalog(value: unknown, now?: number): ClaudePriceCatalog;
+export declare function discoverWithClient(client: ClaudeApiClient, prices: ClaudePriceCatalog, signal: AbortSignal, now: () => number): Promise<ModelCatalog>;

package/dist/claude-api-transport.d.ts

@@ -0,0 +1,5 @@
+import Anthropic from "@anthropic-ai/sdk";
+export declare const CLAUDE_API_SDK_VERSION = "0.127.0";
+export type ClaudeApiClient = Pick<Anthropic, "messages" | "models">;
+/** Internal host transport. Public setup never accepts a custom endpoint or fetch. */
+export declare function claudeApiClient(key: string, signal: AbortSignal, networkFetch?: (input: string, init: RequestInit) => Promise<Response>): ClaudeApiClient;

package/dist/claude-api.d.ts

@@ -0,0 +1,23 @@
+import type { ClaudeApiKeyResolver } from "./claude-sdk.ts";
+import { type ClaudeApiClient } from "./claude-api-transport.ts";
+import { type ModelCatalog } from "./models.ts";
+import { type AgentAdapter, type RuntimeQualification } from "./runtime.ts";
+export type ClaudeApiAdapterOptions = Readonly<{
+    /** Trusted host's reviewed compiled entrypoint; never owner/contact configuration. */
+    runtimeArtifact: Readonly<{
+        entrypoint: string;
+        sha256: string;
+    }>;
+    credentials: ClaudeApiKeyResolver;
+    modelCatalog: (accountId: string) => Promise<ModelCatalog>;
+    now?: () => number;
+    maxTurns?: number;
+    maxOutputTokens?: number;
+    deadlineMs?: number;
+    /** Conservative local reservation at supplied prices; not a provider billing cap. */
+    maxBudgetUsd?: number;
+}>;
+/** This is Claude API, not Claude Code, and never launches a process or loads CLI settings. */
+export declare function createClaudeApiAdapter(options: ClaudeApiAdapterOptions): Promise<AgentAdapter>;
+/** Internal fixture seam. Production account configuration cannot replace the client. */
+export declare function apiAdapter(options: Omit<ClaudeApiAdapterOptions, "runtimeArtifact">, qualification: RuntimeQualification, clientFor: (key: string, signal: AbortSignal) => ClaudeApiClient): AgentAdapter;

package/dist/claude-credentials.d.ts

@@ -0,0 +1,13 @@
+import type { ClaudeApiKeyResolver } from "./claude-sdk.ts";
+/**
+ * Explicit host-owned account bindings for unattended local use. Only selected
+ * environment variables are read, at invocation time. No ambient provider key,
+ * personal provider home, subscription token or account discovery is consulted.
+ * A desktop Keychain integration can implement the same withApiKey interface.
+ */
+export declare function createEnvironmentClaudeApiKeyResolver(bindings: Readonly<Record<string, string>>, readEnvironment?: (name: string) => string | undefined): ClaudeApiKeyResolver;
+/** Explicit owner-selected files, never contact configuration or provider-home discovery. */
+export declare function createFileClaudeApiKeyResolver(options: Readonly<{
+    directory: string;
+    bindings: Readonly<Record<string, string>>;
+}>): ClaudeApiKeyResolver;

package/dist/claude-options.d.ts

@@ -0,0 +1,10 @@
+import type { Options } from "@anthropic-ai/claude-agent-sdk";
+type HostInputs = Pick<Options, "abortController" | "cwd" | "env" | "model" | "maxTurns" | "maxBudgetUsd" | "pathToClaudeCodeExecutable" | "spawnClaudeCodeProcess" | "mcpServers"> & {
+    brokerToolNames: readonly string[];
+    systemPrompt?: string;
+};
+/** Shared with the explicit native qualification harness; never accepts model configuration. */
+export declare function restrictedClaudeOptions({ brokerToolNames, systemPrompt, ...host }: HostInputs): Options;
+/** Keep task text out of the native CLI's slash/bang command parser. */
+export declare function literalClaudePrompt(prompt: string): string;
+export {};

package/dist/claude-sdk.d.ts

@@ -0,0 +1,48 @@
+import { type SDKSystemMessage } from "@anthropic-ai/claude-agent-sdk";
+import { type BoundedProviderProcessFactory } from "./provider-process.ts";
+import { type ToolBroker } from "./broker.ts";
+import { type AgentAdapter, type AgentRunRequest, type RuntimeQualification } from "./runtime.ts";
+export declare const CLAUDE_SDK_VERSION = "0.3.278";
+/** The CLI release the bundled SDK package declares as its build pair — the
+ * manifest check uses this; installed-binary admission uses the floor below. */
+export declare const CLAUDE_SDK_CODE_VERSION = "2.1.278";
+/** Oldest admitted installed Claude Code release within major 2. Admission
+ * still binds the exact inspected version and executable SHA-256 into the
+ * qualification record, and the init assertion re-proves the effective
+ * boundary on every run; the floor only decides which binaries doctor may
+ * admit, so routine CLI patch/minor releases stop revoking the product. */
+export declare const CLAUDE_CODE_MIN_VERSION = "2.1.268";
+export declare const CLAUDE_CODE_MAX_MAJOR = 2;
+export declare function claudeCodeVersionAdmitted(version: string): boolean;
+/** Host-only credential use: never pass a subscription token, personal config home, or credential file. */
+export interface ClaudeApiKeyResolver {
+    withApiKey<T>(accountId: string, signal: AbortSignal, use: (apiKey: string) => Promise<T>): Promise<T>;
+}
+export interface ClaudeSdkAdapterOptions {
+    runtime: Readonly<{
+        executablePath: string;
+        executableSha256: string;
+        cliVersion: string;
+    }>;
+    /** Existing physical mode-0700 directory owned by this user, outside all contact folders. */
+    stateRoot: string;
+    credentials: ClaudeApiKeyResolver;
+    qualification: RuntimeQualification;
+    /** Trusted host seam beneath the unchanged SDK restrictions. No native
+     * package is selected implicitly; omitted retains the existing process owner. */
+    processFactory?: BoundedProviderProcessFactory;
+    now?: () => number;
+    maxTurns?: number;
+    maxBudgetUsd?: number;
+    deadlineMs?: number;
+}
+export declare function inspectClaudeSdkRuntime(runtime: ClaudeSdkAdapterOptions["runtime"]): Promise<Readonly<{
+    executablePath: string;
+    executableSha256: string;
+    sdkSha256: string;
+    runtimeDigest: string;
+    runtimeVersion: string;
+}>>;
+export declare function assertClaudeInitialization(value: SDKSystemMessage, request: AgentRunRequest, broker: ToolBroker, cwd: string): void;
+/** A real SDK subprocess adapter. Qualification is independent host evidence, never inferred from a response. */
+export declare function createClaudeSdkAdapter(options: ClaudeSdkAdapterOptions): AgentAdapter;

package/dist/claude-task-adapter.d.ts

@@ -0,0 +1,65 @@
+import { type ClaudeApiKeyResolver } from "./claude-sdk.ts";
+import { type BoundedProviderProcessFactory } from "./provider-process.ts";
+import { type AgentTaskAdapter, type AgentTaskRoute, type TaskRuntimeQualification } from "./task-runtime.ts";
+export type ClaudeTaskAuthentication = "api" | "subscription";
+/** Returns the account's long-lived Claude subscription OAuth token
+ * (`sk-ant-oat…`) for one task, or fails closed. The host owns storage; the
+ * token reaches the provider only through CLAUDE_CODE_OAUTH_TOKEN env. */
+export type ClaudeSubscriptionTokenResolver = (accountId: string, signal: AbortSignal) => Promise<string>;
+/** Display-channel callbacks for one run. Deliberately not part of the
+ * execution request: the events are observational, never admission or custody
+ * evidence. The host owns the object and may swap handlers between turns —
+ * each property is read at emit time. */
+export type ClaudeTaskEvents = {
+    /** Assistant text as the provider completes each content block (bounded). */
+    onAssistantText?: ((text: string) => void) | undefined;
+    /** Provider-declared error text from a failed result envelope (bounded). */
+    onProviderError?: ((text: string) => void) | undefined;
+};
+export type ClaudeTaskAdapterOptions = Readonly<{
+    route: AgentTaskRoute;
+    runtime: Readonly<{
+        executablePath: string;
+        executableSha256: string;
+        cliVersion: string;
+    }>;
+    /** Existing physical mode-0700 directory owned by this user, outside all workspaces. */
+    stateRoot: string;
+    /** Persistent physical mode-0700 directory holding the managed Claude
+     * configuration and subscription credentials. */
+    authDirectory: string;
+    /** Required when `authentication` is `"api"`. */
+    credentials?: ClaudeApiKeyResolver;
+    /** Required when `authentication` is `"subscription"`. */
+    subscriptionToken?: ClaudeSubscriptionTokenResolver;
+    /** Optional display channel; kept by reference and read per emit. */
+    events?: ClaudeTaskEvents;
+    authentication: ClaudeTaskAuthentication;
+    qualification: TaskRuntimeQualification;
+    /** System prompt for the host's own product surface. */
+    systemPrompt: string;
+    processFactory?: BoundedProviderProcessFactory;
+    now?: () => number;
+    maxTurns?: number;
+    maxBudgetUsd?: number;
+    deadlineMs?: number;
+}>;
+/** The adapter's stable runtime identity for one authentication mode and exact
+ * inspected binary (digest + admitted version). Hosts bind qualification
+ * records to this digest. */
+export declare function claudeTaskRuntimeIdentity(input: Readonly<{
+    executableSha256: string;
+    cliVersion: string;
+    authentication: ClaudeTaskAuthentication;
+}>): Readonly<{
+    version: string;
+    digest: string;
+}>;
+/**
+ * Claude Code through the Agent SDK as an application-profile task adapter. The
+ * model's entire tool surface is the capability broker; subscription auth uses
+ * the managed CLAUDE_CONFIG_DIR written by `xcb-compat auth claude`, while API
+ * auth keeps the key-resolver seam. No native tools, hooks, plugins, skills or
+ * inherited configuration reach the provider.
+ */
+export declare function createClaudeTaskAdapter(options: ClaudeTaskAdapterOptions): AgentTaskAdapter;