@fusionkit/protocol 0.1.0

package/dist/trace.js

@@ -0,0 +1,248 @@
+/**
+ * fusion-trace-event.v1 — fire-and-forget observability emitter.
+ *
+ * This is the canonical TypeScript implementation of the standalone fusion-trace
+ * contract (see fusionkit `spec/fusion-trace`). It lives in `@fusionkit/protocol`
+ * (a dependency-free leaf) so the gateway, ensemble harness, the AI SDK worktree
+ * agent, and the CLI can all emit against the same shape without import cycles.
+ *
+ * Emission is a no-op unless `FUSION_TRACE_URL` or `FUSION_TRACE_DIR` is set, so
+ * normal runs are never blocked by, or coupled to, the collector.
+ */
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+export const FUSION_TRACE_EVENT_SCHEMA = "fusion-trace-event.v1";
+export const FUSION_TRACE_EVENT_VERSION = "1.0.0";
+export const TRACE_ID_HEADER = "x-fusion-trace-id";
+export const TRACE_SPAN_HEADER = "x-fusion-span-id";
+export const TRACE_PARENT_SPAN_HEADER = "x-fusion-parent-span-id";
+export const TRACE_CANDIDATE_HEADER = "x-fusion-candidate-id";
+/** Runtime-iterable mirrors of the closed unions (used by the validator). */
+export const FUSION_TRACE_COMPONENTS = [
+    "gateway",
+    "ensemble",
+    "agent",
+    "panel-model",
+    "judge",
+    "synthesis",
+    "cursor-bridge"
+];
+export const FUSION_TRACE_EVENT_TYPES = [
+    "session.started",
+    "session.finished",
+    "harness.candidate.started",
+    "harness.candidate.finished",
+    "trajectory.step",
+    "model.call.started",
+    "model.call.finished",
+    "judge.request",
+    "judge.thinking",
+    "judge.scored",
+    "judge.synthesis",
+    "judge.final",
+    "tool.execution",
+    "cursor.route",
+    "log"
+];
+export function newTraceId() {
+    return `trace_${randomUUID().replace(/-/g, "")}`;
+}
+export function newSpanId() {
+    return `span_${randomUUID().replace(/-/g, "").slice(0, 12)}`;
+}
+export function ambientTraceId() {
+    const value = process.env.FUSION_TRACE_ID;
+    return value && value.length > 0 ? value : undefined;
+}
+export class TraceEmitter {
+    url;
+    dir;
+    enabled;
+    seq = 0;
+    dirReady = false;
+    constructor(config) {
+        this.url = config?.url ?? process.env.FUSION_TRACE_URL ?? undefined;
+        this.dir = config?.dir ?? process.env.FUSION_TRACE_DIR ?? undefined;
+        this.enabled = Boolean(this.url || this.dir);
+    }
+    isEnabled() {
+        return this.enabled;
+    }
+    emit(input) {
+        if (!this.enabled)
+            return;
+        const traceId = input.traceId ?? ambientTraceId();
+        if (traceId === undefined)
+            return;
+        const event = {
+            schema: FUSION_TRACE_EVENT_SCHEMA,
+            schema_version: FUSION_TRACE_EVENT_VERSION,
+            trace_id: traceId,
+            span_id: input.spanId ?? newSpanId(),
+            seq: this.seq++,
+            ts: Date.now(),
+            component: input.component,
+            event_type: input.event_type,
+            ...(input.parentSpanId !== undefined ? { parent_span_id: input.parentSpanId } : {}),
+            ...(input.sessionId !== undefined ? { session_id: input.sessionId } : {}),
+            ...(input.candidateId !== undefined ? { candidate_id: input.candidateId } : {}),
+            ...(input.modelId !== undefined ? { model_id: input.modelId } : {}),
+            ...(input.payload !== undefined ? { payload: input.payload } : {})
+        };
+        this.writeJsonl(event);
+        void this.post(event);
+    }
+    writeJsonl(event) {
+        if (this.dir === undefined)
+            return;
+        try {
+            if (!this.dirReady) {
+                mkdirSync(this.dir, { recursive: true });
+                this.dirReady = true;
+            }
+            appendFileSync(join(this.dir, `${event.trace_id}.jsonl`), `${JSON.stringify(event)}\n`);
+        }
+        catch {
+            // best-effort durable fallback
+        }
+    }
+    async post(event) {
+        if (this.url === undefined)
+            return;
+        try {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 2_000);
+            await fetch(this.url, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ events: [event] }),
+                signal: controller.signal
+            }).catch(() => undefined);
+            clearTimeout(timeout);
+        }
+        catch {
+            // collector being down must never break a run
+        }
+    }
+}
+let defaultEmitter;
+export function getTraceEmitter() {
+    if (defaultEmitter === undefined)
+        defaultEmitter = new TraceEmitter();
+    return defaultEmitter;
+}
+export function emitTrace(input) {
+    getTraceEmitter().emit(input);
+}
+// ---- runtime validation (the formalized fusion-trace-event.v1 contract) ----
+function fail(message) {
+    throw new Error(`invalid fusion-trace-event.v1: ${message}`);
+}
+/**
+ * Assert that `value` is a well-formed wire `FusionTraceEvent`. Hand-written
+ * (Node-only, no deps) to match the `assertModelFusionRecord` style, so both the
+ * emitter side and the scope ingest boundary validate against one contract.
+ */
+export function assertFusionTraceEvent(value) {
+    if (typeof value !== "object" || value === null)
+        fail("event must be an object");
+    const event = value;
+    if (event.schema !== FUSION_TRACE_EVENT_SCHEMA)
+        fail(`schema must be "${FUSION_TRACE_EVENT_SCHEMA}"`);
+    if (typeof event.trace_id !== "string" || event.trace_id.length === 0)
+        fail("trace_id must be a non-empty string");
+    if (typeof event.span_id !== "string" || event.span_id.length === 0)
+        fail("span_id must be a non-empty string");
+    if (typeof event.seq !== "number" || !Number.isFinite(event.seq))
+        fail("seq must be a finite number");
+    if (typeof event.ts !== "number" || !Number.isFinite(event.ts))
+        fail("ts must be a finite number");
+    if (!FUSION_TRACE_COMPONENTS.includes(event.component)) {
+        fail(`unknown component "${String(event.component)}"`);
+    }
+    if (!FUSION_TRACE_EVENT_TYPES.includes(event.event_type)) {
+        fail(`unknown event_type "${String(event.event_type)}"`);
+    }
+    if (event.parent_span_id !== undefined && typeof event.parent_span_id !== "string") {
+        fail("parent_span_id must be a string when present");
+    }
+    for (const key of ["session_id", "candidate_id", "model_id"]) {
+        if (event[key] !== undefined && typeof event[key] !== "string")
+            fail(`${key} must be a string when present`);
+    }
+    if (event.payload !== undefined &&
+        (typeof event.payload !== "object" || event.payload === null || Array.isArray(event.payload))) {
+        fail("payload must be a plain object when present");
+    }
+}
+export function isFusionTraceEvent(value) {
+    try {
+        assertFusionTraceEvent(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ---- typed per-event payload builders (snake_case wire shape) ----
+//
+// One builder per emitted event keeps payload field names consistent across
+// every emit site and documents exactly what each event carries. The scope
+// collector reads these field names directly.
+export function judgeRequestPayload(input) {
+    return {
+        ...(input.judgeModel !== undefined ? { judge_model: input.judgeModel } : {}),
+        messages: input.messages,
+        trajectories: input.trajectories,
+        ...(input.tools !== undefined ? { tools: input.tools } : {}),
+        ...(input.toolChoice !== undefined ? { tool_choice: input.toolChoice } : {}),
+        ...(input.trajectoryIds !== undefined ? { trajectory_ids: input.trajectoryIds } : {}),
+        ...(input.turn !== undefined ? { turn: input.turn } : {})
+    };
+}
+/** An intermediate (tool-calling) judge step within a turn. */
+export function judgeThinkingPayload(input) {
+    return {
+        ...(input.rawAnalysis !== undefined ? { raw_analysis: input.rawAnalysis } : {}),
+        ...(input.toolCalls !== undefined ? { tool_calls: input.toolCalls } : {}),
+        ...(input.usage !== undefined ? { usage: input.usage } : {}),
+        ...(input.turn !== undefined ? { turn: input.turn } : {})
+    };
+}
+export function judgeFinalPayload(input) {
+    const finalOutput = input.finalOutput ?? input.content;
+    return {
+        ...(finalOutput !== undefined ? { final_output: finalOutput, record: { final_output: finalOutput } } : {}),
+        ...(input.content !== undefined ? { content: input.content } : {}),
+        ...(input.toolCalls !== undefined ? { tool_calls: input.toolCalls } : {}),
+        ...(input.usage !== undefined ? { usage: input.usage } : {}),
+        ...(input.httpStatus !== undefined ? { http_status: input.httpStatus } : {}),
+        ...(input.error !== undefined ? { error: input.error } : {}),
+        ...(input.turn !== undefined ? { turn: input.turn } : {})
+    };
+}
+export function modelCallStartedPayload(input) {
+    return {
+        model: input.model,
+        ...(input.systemPrompt !== undefined ? { system_prompt: input.systemPrompt } : {}),
+        ...(input.prompt !== undefined ? { prompt: input.prompt } : {}),
+        ...(input.tools !== undefined ? { tools: input.tools } : {}),
+        ...(input.turn !== undefined ? { turn: input.turn } : {})
+    };
+}
+export function modelCallFinishedPayload(input) {
+    return {
+        model: input.model,
+        ...(input.finalOutput !== undefined
+            ? { final_output: input.finalOutput, content_preview: input.finalOutput.slice(0, 280) }
+            : {}),
+        ...(input.usage !== undefined ? { usage: input.usage } : {}),
+        ...(input.finishReason !== undefined ? { finish_reason: input.finishReason } : {}),
+        ...(input.stepCount !== undefined ? { step_count: input.stepCount } : {}),
+        ...(input.toolCallCount !== undefined ? { tool_call_count: input.toolCallCount } : {}),
+        ...(input.latencyS !== undefined ? { latency_s: input.latencyS } : {}),
+        ...(input.error !== undefined ? { error: input.error } : {}),
+        ...(input.turn !== undefined ? { turn: input.turn } : {})
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,375 @@
+/**
+ * Warrant protocol types. These are the schemas marked for open
+ * publication in the spec (warrant.contract.v1, warrant.receipt.v1,
+ * warrant.event.v1, warrant.manifest.v1, warrant.policy.v1).
+ */
+import type { JsonValue } from "./jcs.js";
+import type { ExecutionSpec } from "./execution.js";
+export type RunStatus = "created" | "claimed" | "provisioning" | "running" | "awaiting_approval" | "completed" | "failed" | "cancelled";
+export type FailureClass = "policy_denied" | "consent_timeout" | "capability_mismatch" | "attestation_failed" | "secret_release_denied" | "capture_failed" | "transfer_failed" | "session_failed" | "side_effect_conflict" | "budget_exceeded";
+export type DisclosureMode = "none" | "metadata-only" | "redacted" | "minimal-context" | "full";
+export type CheckpointTier = "semantic" | "workspace";
+export type AttestationTier = "mock" | "standard" | "zdr" | "cpu-tee" | "cpu-gpu-tee";
+/**
+ * How the runner isolates the agent session, recorded honestly in receipts:
+ *
+ * - "process": a child process with a scrubbed environment and an egress
+ *   proxy. Enforcement is process-level — a malicious binary can ignore
+ *   proxy variables — but every attempt is recorded.
+ * - "hermetic": a simulated bash interpreter (just-bash) with a virtual
+ *   filesystem rooted in the workspace and interpreter-enforced network
+ *   allowlists. There are no real processes or sockets to escape with;
+ *   only the "command" harness can run here.
+ * - "vercel-sandbox": a Firecracker microVM (Vercel Sandbox) with
+ *   VM-level isolation and domain-based egress policy.
+ */
+export type SessionIsolation = "process" | "hermetic" | "vercel-sandbox";
+/**
+ * "command" is the harness for app-owned loops and the compute adapter:
+ * a single shell command executed inside a governed session. "mock" is the
+ * built-in test harness. "pi" is a host-runtime harness with no vendor CLI:
+ * it runs only through the AI SDK harness session backend, never as a
+ * spawned process. The rest are vendor CLIs wrapped as-is.
+ */
+export type AgentKind = "claude-code" | "codex" | "pi" | "mock" | "command";
+export type AgentSpec = {
+    kind: AgentKind;
+    version?: string;
+};
+export type TaskSpec = {
+    prompt: string;
+};
+export type RunnerSelector = {
+    pool: string;
+};
+export type ActorRef = {
+    kind: "human" | "service";
+    id: string;
+};
+export type KeyRef = {
+    keyId: string;
+    role: "org" | "plane" | "runner";
+};
+export type Signature = {
+    keyId: string;
+    alg: "ed25519";
+    signer: "org" | "plane" | "runner";
+    sig: string;
+};
+export type ManifestFile = {
+    path: string;
+    hash: string;
+    bytes: number;
+};
+export type WorkspaceManifest = {
+    version: "warrant.manifest.v1";
+    baseRef: string;
+    /** Hash of the git bundle blob containing history up to baseRef. */
+    bundleHash: string;
+    /** Hash of the binary diff blob for staged+unstaged changes, if any. */
+    dirtyDiffHash?: string;
+    /** Allowlisted untracked files, content-addressed. */
+    untrackedFiles: ManifestFile[];
+    /** Patterns that were denied capture; recorded so absence is provable. */
+    deniedPatterns: string[];
+    /** Paths that matched a deny pattern and were excluded. */
+    deniedPaths: string[];
+};
+export type SecretClaim = {
+    name: string;
+    scope: string;
+};
+export type NetworkPolicy = {
+    defaultDeny: boolean;
+    allowHosts: string[];
+};
+export type BudgetSpec = {
+    maxSpendUsd?: number;
+    maxDurationMin?: number;
+};
+export type RunContract = {
+    version: "warrant.contract.v1";
+    runId: string;
+    issuedAt: string;
+    issuer: KeyRef;
+    requestedBy: ActorRef;
+    approvedBy?: ActorRef[];
+    agent: AgentSpec;
+    task: TaskSpec;
+    runner: RunnerSelector;
+    workspace: WorkspaceManifest;
+    policyHash: string;
+    secrets: SecretClaim[];
+    network: NetworkPolicy;
+    budget: BudgetSpec;
+    disclosure: DisclosureMode;
+    /** Durable machine intent. If absent, legacy contracts derive execution from agent/task. */
+    execution?: ExecutionSpec;
+    /** Requested session isolation. Defaults to "process". */
+    isolation?: SessionIsolation;
+    /** Present when this run continues prior work from a handoff envelope. */
+    continuation?: ContinuationRef;
+    expiresAt: string;
+    signatures: Signature[];
+};
+export type DataClassRule = {
+    dataClass: string;
+    allowPools: string[];
+};
+export type SecretScopeRule = {
+    name: string;
+    scope: string;
+    pools: string[];
+};
+export type ConsentRule = {
+    when: "secret-release" | "any-run" | "agent-kind";
+    match?: string;
+    approvers: string[];
+};
+export type RetentionPolicy = {
+    receiptsDays: number;
+    artifactsDays: number;
+};
+export type Policy = {
+    version: "warrant.policy.v1";
+    runners: {
+        allowPools: string[];
+    };
+    agents: {
+        allow: AgentKind[];
+    };
+    dataClasses: DataClassRule[];
+    network: NetworkPolicy;
+    secrets: {
+        releasable: SecretScopeRule[];
+    };
+    budget: {
+        maxSpendUsd: number;
+        maxDurationMin: number;
+    };
+    consent: ConsentRule[];
+    retention: RetentionPolicy;
+};
+export type ArtifactKind = "diff" | "log" | "file" | "bundle" | "trace";
+export type RunEvent = {
+    type: "run.created";
+} | {
+    type: "run.claimed";
+    runnerId: string;
+    runnerKeyId: string;
+} | {
+    type: "workspace.materialized";
+    manifestHash: string;
+} | {
+    type: "policy.evaluated";
+    decision: "allow" | "ask";
+    reason: string;
+} | {
+    type: "consent.requested";
+    requirement: string;
+} | {
+    type: "consent.granted";
+    actor: ActorRef;
+} | {
+    type: "secret.released";
+    name: string;
+    scope: string;
+} | {
+    type: "command.executed";
+    argvHash: string;
+    exitCode: number;
+} | {
+    type: "file.changed";
+    path: string;
+    contentHash: string;
+} | {
+    type: "network.connected";
+    host: string;
+    decision: "allowed" | "blocked";
+} | {
+    type: "model.called";
+    provider: string;
+    model: string;
+} | {
+    type: "boundary.crossed";
+    direction: "out" | "in";
+    contentHash: string;
+    dataClass: string;
+} | {
+    type: "artifact.created";
+    kind: ArtifactKind;
+    hash: string;
+} | {
+    type: "checkpoint.created";
+    checkpointId: string;
+    tier: CheckpointTier;
+} | {
+    type: "run.completed";
+} | {
+    type: "run.failed";
+    failure: FailureClass;
+    message: string;
+} | {
+    type: "run.cancelled";
+    actor: ActorRef;
+};
+export type ChainedEvent = {
+    version: "warrant.event.v1";
+    seq: number;
+    ts: string;
+    /** Hash of the previous chained event; the genesis event uses the contract hash. */
+    prev: string;
+    event: RunEvent;
+    /** sha256 over canonical JSON of {seq, ts, prev, event}. */
+    hash: string;
+};
+export type RunnerIdentity = {
+    runnerId: string;
+    keyId: string;
+    pool: string;
+    attestationTier: AttestationTier;
+    /** How the session was actually isolated. Absent in older receipts means "process". */
+    isolation?: SessionIsolation;
+};
+export type SecretReleaseRecord = {
+    name: string;
+    scope: string;
+    ts: string;
+};
+export type NetworkAccessRecord = {
+    host: string;
+    decision: "allowed" | "blocked";
+};
+export type ModelUsageRecord = {
+    provider: string;
+    model: string;
+};
+export type DisclosureRecord = {
+    direction: "out" | "in";
+    contentHash: string;
+    dataClass: string;
+};
+export type Receipt = {
+    version: "warrant.receipt.v1";
+    runId: string;
+    contractHash: string;
+    runner: RunnerIdentity;
+    startedAt: string;
+    endedAt: string;
+    status: Extract<RunStatus, "completed" | "failed" | "cancelled">;
+    eventsHead: string;
+    eventCount: number;
+    workspaceIn: {
+        baseRef: string;
+        manifestHash: string;
+    };
+    workspaceOut: {
+        diffHash: string;
+        artifactHashes: string[];
+    };
+    secretsReleased: SecretReleaseRecord[];
+    networkAccessed: NetworkAccessRecord[];
+    modelsUsed: ModelUsageRecord[];
+    boundaryDisclosures: DisclosureRecord[];
+    costUsd?: number;
+    signatures: Signature[];
+};
+/**
+ * Handoff protocol objects (warrant.checkpoint.v1, warrant.envelope.v1).
+ *
+ * A checkpoint captures resumable state at a semantic boundary. An envelope
+ * is the portable description of a continuation: which checkpoint, which
+ * agent, which target, and under which conditions work should continue.
+ * Envelopes are content-addressed; the signed run contract pins the
+ * envelope hash, so the continuation provenance is covered by the plane
+ * signature without requiring requester-held keys.
+ */
+export type SemanticState = {
+    /** Blob hash of the captured transcript, if one was attached. */
+    transcriptHash?: string;
+    /** Blob hash of the tool-call journal (warrant.tooljournal.v1), if any. */
+    toolJournalHash?: string;
+    /** Short human-readable summary of where the work stands. */
+    note?: string;
+};
+/** One recorded tool invocation from an app-owned loop. */
+export type ToolCallRecord = {
+    seq: number;
+    ts: string;
+    toolName: string;
+    input: JsonValue;
+    output?: JsonValue;
+    error?: string;
+    durationMs: number;
+};
+/**
+ * Tool-call history captured at semantic boundaries (warrant.tooljournal.v1).
+ * Content-addressed and referenced from a checkpoint's semantic state, so a
+ * continuation carries what the loop's tools saw and did.
+ */
+export type ToolJournal = {
+    version: "warrant.tooljournal.v1";
+    entries: ToolCallRecord[];
+};
+export type Checkpoint = {
+    version: "warrant.checkpoint.v1";
+    checkpointId: string;
+    createdAt: string;
+    tier: CheckpointTier;
+    message?: string;
+    semantic?: SemanticState;
+    workspace?: WorkspaceManifest;
+    /** Lineage: the checkpoint this one descends from, if any. */
+    parent?: string;
+};
+export type HandoffSource = {
+    kind: "local";
+    actor: ActorRef;
+    host?: string;
+};
+export type HandoffTargetRef = {
+    kind: "runner-pool";
+    pool: string;
+};
+export type HandoffEnvelope = {
+    version: "warrant.envelope.v1";
+    envelopeId: string;
+    createdAt: string;
+    source: HandoffSource;
+    target: HandoffTargetRef;
+    checkpoint: Checkpoint;
+    agent: AgentSpec;
+    task: TaskSpec;
+    reason?: string;
+    secrets: SecretClaim[];
+    network: NetworkPolicy;
+    budget: BudgetSpec;
+    disclosure: DisclosureMode;
+    /** Durable machine intent for this continuation. */
+    execution?: ExecutionSpec;
+    /** Requested session isolation for the continuation. */
+    isolation?: SessionIsolation;
+};
+/** Reference embedded in a run contract when the run continues prior work. */
+export type ContinuationRef = {
+    envelopeHash: string;
+    checkpointId: string;
+    tier: CheckpointTier;
+};
+/** Self-contained bundle sufficient for fully offline verification. */
+export type ReceiptBundle = {
+    version: "warrant.bundle.v1";
+    contract: RunContract;
+    receipt: Receipt;
+    events: ChainedEvent[];
+    keys: {
+        planePublicKeyPem: string;
+        runnerPublicKeyPem: string;
+        orgPublicKeyPem?: string;
+    };
+};
+export declare class PolicyDeniedError extends Error {
+    readonly code: FailureClass;
+    readonly reasons: string[];
+    constructor(reasons: string[]);
+}

package/dist/types.js

@@ -0,0 +1,14 @@
+/**
+ * Warrant protocol types. These are the schemas marked for open
+ * publication in the spec (warrant.contract.v1, warrant.receipt.v1,
+ * warrant.event.v1, warrant.manifest.v1, warrant.policy.v1).
+ */
+export class PolicyDeniedError extends Error {
+    code = "policy_denied";
+    reasons;
+    constructor(reasons) {
+        super(`policy denied: ${reasons.join("; ")}`);
+        this.name = "PolicyDeniedError";
+        this.reasons = reasons;
+    }
+}

package/dist/validators.d.ts

@@ -0,0 +1,7 @@
+export declare const SECRET_NAME_PATTERN: RegExp;
+export declare const POOL_NAME_PATTERN: RegExp;
+export declare const WORKSPACE_RELATIVE_PATH_PATTERN: RegExp;
+export declare function parseSecretName(value: string): string;
+export declare function parsePoolName(value: string): string;
+export declare function parseHostAllowlistEntry(value: string): string;
+export declare function parseWorkspaceManifestPath(value: string): string;

package/dist/validators.js

@@ -0,0 +1,32 @@
+export const SECRET_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+export const POOL_NAME_PATTERN = /^[A-Za-z0-9_.:-]{1,128}$/;
+export const WORKSPACE_RELATIVE_PATH_PATTERN = /^(?!\/)(?![A-Za-z]:)(?!.*(?:^|\/)\.\.(?:\/|$))(?!.*\/\/)(?!.*\\)(?!.*\0).+$/;
+export function parseSecretName(value) {
+    if (!SECRET_NAME_PATTERN.test(value)) {
+        throw new Error(`secret name "${value}" must be a POSIX environment identifier`);
+    }
+    return value;
+}
+export function parsePoolName(value) {
+    if (!POOL_NAME_PATTERN.test(value)) {
+        throw new Error(`pool name "${value}" contains unsupported characters`);
+    }
+    return value;
+}
+export function parseHostAllowlistEntry(value) {
+    const trimmed = value.trim().toLowerCase().replace(/\.$/, "");
+    if (trimmed.length === 0 ||
+        trimmed.length > 253 ||
+        trimmed.includes("/") ||
+        trimmed.includes("@") ||
+        trimmed.includes(":")) {
+        throw new Error(`host allowlist entry "${value}" is not a bare host name`);
+    }
+    return trimmed;
+}
+export function parseWorkspaceManifestPath(value) {
+    if (!WORKSPACE_RELATIVE_PATH_PATTERN.test(value)) {
+        throw new Error(`workspace path "${value}" must be a safe relative path`);
+    }
+    return value;
+}

package/dist/vocabulary.d.ts

@@ -0,0 +1,12 @@
+import type { AgentKind, RunEvent, RunStatus } from "./types.js";
+export declare const RUN_STATUSES: readonly ["created", "claimed", "provisioning", "running", "awaiting_approval", "completed", "failed", "cancelled"];
+export declare const TERMINAL_RUN_STATUSES: readonly ["completed", "failed", "cancelled"];
+export declare const AGENT_KINDS: readonly ["claude-code", "codex", "pi", "mock", "command"];
+export declare const SESSION_ISOLATIONS: readonly ["process", "hermetic", "vercel-sandbox"];
+export declare const DISCLOSURE_MODES: readonly ["none", "metadata-only", "redacted", "minimal-context", "full"];
+export declare const CHECKPOINT_TIERS: readonly ["semantic", "workspace"];
+export declare const ACTOR_KINDS: readonly ["human", "service"];
+export declare const RUN_EVENT_TYPES: readonly RunEvent["type"][];
+export declare const HEX_HASH_PATTERN: RegExp;
+export declare function isTerminalStatus(status: RunStatus): boolean;
+export declare function isAgentKind(value: string): value is AgentKind;