stitchkit 0.110.1 → 0.110.2

package/dist/index-snef22zr.js

@@ -0,0 +1,94 @@
+// src/durability/contract.ts
+import { z } from "zod";
+var DURABILITY_STEP_EVENT_KIND2 = "durability/step";
+var DURABILITY_PARK_EVENT_KIND = "durability/park";
+var DURABILITY_EVENT_EVENT_KIND = "durability/event";
+var DURABILITY_EFFECT_EVENT_KIND = "durability/effect";
+var StepEventPayloadSchema = z.object({
+  runId: z.string().min(1),
+  stepName: z.string().min(1),
+  encoded: z.string()
+});
+var SleepParkSchema = z.object({
+  runId: z.string().min(1),
+  kind: z.literal("sleep"),
+  name: z.string().min(1),
+  deadline: z.number()
+});
+var WaitParkSchema = z.object({
+  runId: z.string().min(1),
+  kind: z.literal("wait"),
+  event: z.string().min(1),
+  id: z.string().min(1)
+});
+var ParkEventPayloadSchema = z.discriminatedUnion("kind", [
+  SleepParkSchema,
+  WaitParkSchema
+]);
+var DeliveredEventPayloadSchema = z.object({
+  runId: z.string().min(1),
+  event: z.string().min(1),
+  id: z.string().min(1),
+  encoded: z.string()
+});
+var EffectIdentity = { runId: z.string().min(1), effectName: z.string().min(1) };
+var EffectEventPayloadSchema = z.discriminatedUnion("phase", [
+  z.object({ ...EffectIdentity, phase: z.literal("intent") }),
+  z.object({
+    ...EffectIdentity,
+    phase: z.literal("accepted"),
+    encoded: z.string(),
+    via: z.enum(["run", "reconcile"])
+  }),
+  z.object({ ...EffectIdentity, phase: z.literal("uncertain") })
+]);
+
+class StepResultDecodeError2 extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "StepResultDecodeError";
+  }
+}
+
+class StepResultNotSerializableError2 extends Error {
+  constructor(stepName, cause) {
+    super(`Step "${stepName}" returned a value that is not JSON-serializable`, {
+      cause
+    });
+    this.name = "StepResultNotSerializableError";
+  }
+}
+
+class StepAbortedError2 extends Error {
+  constructor(stepName) {
+    super(`Step "${stepName}" was aborted before it started`);
+    this.name = "StepAbortedError";
+  }
+}
+
+class EffectUnresolvedError2 extends Error {
+  effectName;
+  reason;
+  constructor(effectName, reason, options) {
+    super(`Effect "${effectName}" is unresolved (${reason}); its intent stands`, options);
+    this.effectName = effectName;
+    this.reason = reason;
+    this.name = "EffectUnresolvedError";
+  }
+}
+
+class ParkRecordDecodeError2 extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "ParkRecordDecodeError";
+  }
+}
+
+class ParkAbortedError2 extends Error {
+  constructor(park) {
+    super(`Park "${park}" was aborted before it was satisfied`);
+    this.name = "ParkAbortedError";
+  }
+}
+
+export { DURABILITY_STEP_EVENT_KIND2, DURABILITY_PARK_EVENT_KIND, DURABILITY_EVENT_EVENT_KIND, DURABILITY_EFFECT_EVENT_KIND, StepEventPayloadSchema, ParkEventPayloadSchema, DeliveredEventPayloadSchema, EffectEventPayloadSchema, StepResultDecodeError2, StepResultNotSerializableError2, StepAbortedError2, EffectUnresolvedError2, ParkRecordDecodeError2, ParkAbortedError2 };

package/dist/{index-c0hffcmj.js → index-zbssway3.js}

@@ -5,7 +5,7 @@ import {
   AgentRecoverableDescriptorSchema2,
   AgentRecoverablePageSchema2,
   canonicalAgentJson2
-} from "./index-0gs4ymfj.js";
+} from "./index-6qeqdz0z.js";
 import {
   AgentMessageSchema2,
   AgentRunSchema2
@@ -18,7 +18,7 @@ import {
   AgentHistoryMutationSchema2,
   appendEventIn,
   createAgentRuntimeStore2
-} from "./index-d2h99n7d.js";
+} from "./index-s2bgwsyr.js";
 import {
   AgentConversationPageSchema2,
   AgentConversationMessagePageSchema2
@@ -63,6 +63,14 @@ function sqliteConversationPurge(database) {
   if (table === null || table === undefined)
     return;
   return {
+    async isEmpty(transaction, conversationId) {
+      for (const table of OWNED_TABLES) {
+        const row = transaction.prepare(`SELECT 1 FROM ${table} WHERE conversation_id = ? LIMIT 1`).get(conversationId);
+        if (row !== null && row !== undefined)
+          return false;
+      }
+      return transaction.prepare("SELECT 1 FROM stitchkit_agent_runtime_children WHERE parent_conversation_id = ? OR child_conversation_id = ? LIMIT 1").get(conversationId, conversationId) == null;
+    },
     async isPurged(transaction, conversationId) {
       const row = transaction.prepare("SELECT conversation_id FROM stitchkit_agent_runtime_purged WHERE conversation_id = ?").get(conversationId);
       return row !== null && row !== undefined;
@@ -629,6 +637,15 @@ var sqliteArchive = {
 
 // src/agent-runtime/sqlite-history.ts
 var sqliteHistory = {
+  async restore(transaction, input) {
+    const compacted = new Set(input.compactedMessageIds);
+    for (const [position, message] of input.messages.entries()) {
+      if (message.conversationId !== input.conversationId)
+        throw new TypeError("Restored history has a foreign conversation");
+      transaction.prepare(`INSERT INTO stitchkit_agent_runtime_messages
+        (conversation_id, id, position, active, payload) VALUES (?, ?, ?, ?, ?)`).run(input.conversationId, message.id, position, compacted.has(message.id) ? 0 : 1, encodeJson(message));
+    }
+  },
   async load(transaction, conversationId) {
     return transaction.prepare(`
         SELECT payload FROM stitchkit_agent_runtime_messages

package/llms/agent-runtime.3.txt

@@ -31,6 +31,9 @@ Server-only optional application runtime. See the
 | `AgentMessageSchema` / `AgentRunSchema` / `AgentSnapshotSchema` | schema | versioned canonical engine records |
 | `AgentRunQueuePrioritySchema` | schema | durable opt-in priority for queued `interrupt-next` runs |
 | `AgentRuntimeStore` | _type_ | aggregate CAS transaction boundary for message, run and compaction mutations |
+| `BranchAgentConversationInputSchema` / `BranchAgentConversationInput` | schema / _type_ | strict branch request: stable request key, empty destination, settled conversation boundary or archive bytes, fresh artifact authorization |
+| `AgentConversationBranchReceiptSchema` / `AgentConversationBranchReceipt` | schema / _type_ | durable lineage: request fingerprint, source/destination identities, source sequence/version/digest and creation time |
+| `AgentConversationBranchResultSchema` / `AgentConversationBranchResult` | schema / _type_ | `created` or `duplicate` with the same durable receipt; `AgentRuntimeStore.branchConversation` is optional for hand-written stores |
 | `createAgentRuntimeStore` | function | build the aggregate store from one coherent transaction driver; framework owns every state transition |
 | `AgentRuntimeStoreDriver` | _type_ | ORM-neutral transaction over a bounded head, normalized runs/admissions, product history, a **required** `events: { append, list }` ledger table, an optional `archive: { export, import }` for driver-owned durable payloads, and indexed run recovery; optional `{ access: 'read' }` selects a coherent read transaction while absent options remain write-safe |
 | `recordAgentRetryDecision` / `AgentRetryPolicy` | function / _type_ | `loop.retry` policy and the ledger record of a retry decision: explicit retryability and backoff at a durable provider-step boundary |

package/llms/agent-runtime.txt

@@ -567,6 +567,66 @@ failed attempt's reported usage stays in the run's spend. Transient events —
 deltas, reasoning, `attempt-reset` — are numbered from 1 per run, counting only
 what was published, so a cursor sees no gap on an ordinary stream.
 
+### Branch or restore with a new identity
+
+Use `store.branchConversation()` to create an independent conversation. `importConversation()`
+restores the original identity and is not a fork. The built-in memory and SQLite stores and
+`createAgentRuntimeStore()` expose branching; a hand-written `AgentRuntimeStore` can advertise this
+optional capability. The host authorizes the caller's source/archive access and destination
+creation before calling this trusted store boundary.
+
+```ts
+const copy = await sqlite.store.branchConversation({
+  requestKey: 'branch-request-1',
+  destinationConversationId: 'new-conversation',
+  source: { kind: 'conversation', conversationId: 'original', throughRunId: 'finished-run' },
+  // Required when selected history has spills: an explicit policy for this destination.
+  artifactAuthorization: { operation: 'read', path: 'approved-destination-workspace' },
+})
+
+const restored = await sqlite.store.branchConversation({
+  requestKey: 'restore-request-1',
+  destinationConversationId: 'restored-as-new',
+  source: { kind: 'archive', bytes: archiveBytes },
+})
+```
+
+`throughRunId` selects its exact terminal/abandon event. Omit it to include the settled tip and
+compaction recorded after the last run. The selected prefix must contain no queued or acquired
+runs. A later active source run does not prevent branching an earlier settled prefix. A migrated
+baseline has no earlier per-run event boundary; it can be copied at its settled tip.
+
+The result is `{ outcome: 'created' | 'duplicate', receipt }`. Keep the receipt: it binds source
+and destination identity, source kind, exact `sourceSeq`/`sourceVersion`, `sourceDigest`, request
+fingerprint and creation time. A retry with the same destination/key and selector returns the
+original receipt even after the source advances or the destination continues. Changing the
+request conflicts; no existing destination is overwritten. Archive fingerprints bind the supplied
+bytes. The source digest binds the selected canonical events, artifacts and reconstructed snapshot.
+Run update timestamps reconstructed from events use their recorded `occurredAt`. Abandon transitions
+retain the full failed assistant in the same event; a legacy archive must retain that exact assistant
+in its runtime snapshot, otherwise copying refuses instead of inventing historical content or time.
+
+No provider or tool runs during copying. The next ordinary runtime `submit` continues the copied
+history. All engine identities and typed references are new, including repeated references to one
+spill. Compacted content stays in the event history and SQLite inactive rows; the model reads the
+same active summaries. A hash-only checkpoint is historical digest evidence, marked
+`sourceSha256`; a later full terminal record must settle its content.
+
+A branch grants no source authority. Terminal run owners/fences and approval signatures are
+removed. State, schedules, children, retries, sandbox, approval rejection and durability facts are
+retained as inert `runtime/branch-observation` records; they cannot repopulate operational state
+or pending effects. Spills discard source authorization and require the explicit fresh
+`artifactAuthorization`; normal destination read authorization still applies. No cached projection,
+schedule row or child relation is cloned.
+
+The store validates the complete archive before writing: contiguous events, a matching runtime
+snapshot, known typed forms, reference closure, and spill bytes/digests. Unsupported provider
+envelopes, encrypted invocation payloads, unknown event versions, arbitrary cached projections,
+missing artifacts and undocumented reference fields in opaque JSON refuse atomically. They need
+an owner-defined transfer codec; never recursively rewrite internal JSON in the application.
+Third-party drivers must provide atomic write transactions and archive support for spills;
+`history.restore` is required for migrated baselines with inactive rows.
+
 ### Event ledger, projections and durable capabilities
 
 `AgentRuntimeStore` exposes bounded `readEvents`, declared `appendEvent`, canonical

package/llms-full.txt

@@ -5765,6 +5765,66 @@ failed attempt's reported usage stays in the run's spend. Transient events —
 deltas, reasoning, `attempt-reset` — are numbered from 1 per run, counting only
 what was published, so a cursor sees no gap on an ordinary stream.
 
+### Branch or restore with a new identity
+
+Use `store.branchConversation()` to create an independent conversation. `importConversation()`
+restores the original identity and is not a fork. The built-in memory and SQLite stores and
+`createAgentRuntimeStore()` expose branching; a hand-written `AgentRuntimeStore` can advertise this
+optional capability. The host authorizes the caller's source/archive access and destination
+creation before calling this trusted store boundary.
+
+```ts
+const copy = await sqlite.store.branchConversation({
+  requestKey: 'branch-request-1',
+  destinationConversationId: 'new-conversation',
+  source: { kind: 'conversation', conversationId: 'original', throughRunId: 'finished-run' },
+  // Required when selected history has spills: an explicit policy for this destination.
+  artifactAuthorization: { operation: 'read', path: 'approved-destination-workspace' },
+})
+
+const restored = await sqlite.store.branchConversation({
+  requestKey: 'restore-request-1',
+  destinationConversationId: 'restored-as-new',
+  source: { kind: 'archive', bytes: archiveBytes },
+})
+```
+
+`throughRunId` selects its exact terminal/abandon event. Omit it to include the settled tip and
+compaction recorded after the last run. The selected prefix must contain no queued or acquired
+runs. A later active source run does not prevent branching an earlier settled prefix. A migrated
+baseline has no earlier per-run event boundary; it can be copied at its settled tip.
+
+The result is `{ outcome: 'created' | 'duplicate', receipt }`. Keep the receipt: it binds source
+and destination identity, source kind, exact `sourceSeq`/`sourceVersion`, `sourceDigest`, request
+fingerprint and creation time. A retry with the same destination/key and selector returns the
+original receipt even after the source advances or the destination continues. Changing the
+request conflicts; no existing destination is overwritten. Archive fingerprints bind the supplied
+bytes. The source digest binds the selected canonical events, artifacts and reconstructed snapshot.
+Run update timestamps reconstructed from events use their recorded `occurredAt`. Abandon transitions
+retain the full failed assistant in the same event; a legacy archive must retain that exact assistant
+in its runtime snapshot, otherwise copying refuses instead of inventing historical content or time.
+
+No provider or tool runs during copying. The next ordinary runtime `submit` continues the copied
+history. All engine identities and typed references are new, including repeated references to one
+spill. Compacted content stays in the event history and SQLite inactive rows; the model reads the
+same active summaries. A hash-only checkpoint is historical digest evidence, marked
+`sourceSha256`; a later full terminal record must settle its content.
+
+A branch grants no source authority. Terminal run owners/fences and approval signatures are
+removed. State, schedules, children, retries, sandbox, approval rejection and durability facts are
+retained as inert `runtime/branch-observation` records; they cannot repopulate operational state
+or pending effects. Spills discard source authorization and require the explicit fresh
+`artifactAuthorization`; normal destination read authorization still applies. No cached projection,
+schedule row or child relation is cloned.
+
+The store validates the complete archive before writing: contiguous events, a matching runtime
+snapshot, known typed forms, reference closure, and spill bytes/digests. Unsupported provider
+envelopes, encrypted invocation payloads, unknown event versions, arbitrary cached projections,
+missing artifacts and undocumented reference fields in opaque JSON refuse atomically. They need
+an owner-defined transfer codec; never recursively rewrite internal JSON in the application.
+Third-party drivers must provide atomic write transactions and archive support for spills;
+`history.restore` is required for migrated baselines with inactive rows.
+
 ### Event ledger, projections and durable capabilities
 
 `AgentRuntimeStore` exposes bounded `readEvents`, declared `appendEvent`, canonical
@@ -21702,6 +21762,9 @@ Server-only optional application runtime. See the
 | `AgentMessageSchema` / `AgentRunSchema` / `AgentSnapshotSchema` | schema | versioned canonical engine records |
 | `AgentRunQueuePrioritySchema` | schema | durable opt-in priority for queued `interrupt-next` runs |
 | `AgentRuntimeStore` | _type_ | aggregate CAS transaction boundary for message, run and compaction mutations |
+| `BranchAgentConversationInputSchema` / `BranchAgentConversationInput` | schema / _type_ | strict branch request: stable request key, empty destination, settled conversation boundary or archive bytes, fresh artifact authorization |
+| `AgentConversationBranchReceiptSchema` / `AgentConversationBranchReceipt` | schema / _type_ | durable lineage: request fingerprint, source/destination identities, source sequence/version/digest and creation time |
+| `AgentConversationBranchResultSchema` / `AgentConversationBranchResult` | schema / _type_ | `created` or `duplicate` with the same durable receipt; `AgentRuntimeStore.branchConversation` is optional for hand-written stores |
 | `createAgentRuntimeStore` | function | build the aggregate store from one coherent transaction driver; framework owns every state transition |
 | `AgentRuntimeStoreDriver` | _type_ | ORM-neutral transaction over a bounded head, normalized runs/admissions, product history, a **required** `events: { append, list }` ledger table, an optional `archive: { export, import }` for driver-owned durable payloads, and indexed run recovery; optional `{ access: 'read' }` selects a coherent read transaction while absent options remain write-safe |
 | `recordAgentRetryDecision` / `AgentRetryPolicy` | function / _type_ | `loop.retry` policy and the ledger record of a retry decision: explicit retryability and backoff at a durable provider-step boundary |

package/llms.txt

@@ -25,7 +25,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/primitives**: [llms/primitives.txt](llms/primitives.txt) 11.7 KB
 - **stitchkit/server**: [llms/server.txt](llms/server.txt) 45.3 KB → [llms/server.2.txt](llms/server.2.txt) 14.6 KB → [llms/server.3.txt](llms/server.3.txt) 45.6 KB → [llms/server.4.txt](llms/server.4.txt) 38.3 KB → [llms/server.5.txt](llms/server.5.txt) 22.1 KB
 - **stitchkit/observability**: [llms/observability.txt](llms/observability.txt) 45.9 KB
-- **stitchkit/agent-runtime**: [llms/agent-runtime.txt](llms/agent-runtime.txt) 37.1 KB → [llms/agent-runtime.2.txt](llms/agent-runtime.2.txt) 46.7 KB → [llms/agent-runtime.3.txt](llms/agent-runtime.3.txt) 34.7 KB
+- **stitchkit/agent-runtime**: [llms/agent-runtime.txt](llms/agent-runtime.txt) 41.0 KB → [llms/agent-runtime.2.txt](llms/agent-runtime.2.txt) 46.7 KB → [llms/agent-runtime.3.txt](llms/agent-runtime.3.txt) 35.4 KB
 - **stitchkit/agent-runtime/testing**: [llms/agent-runtime-testing.txt](llms/agent-runtime-testing.txt) 2.6 KB
 - **stitchkit/agent-runtime/harness**: [llms/agent-runtime-harness.txt](llms/agent-runtime-harness.txt) 11.0 KB
 - **stitchkit/agent-runtime/coding-tools**: [llms/agent-runtime-coding-tools.txt](llms/agent-runtime-coding-tools.txt) 5.0 KB

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.110.1",
+  "version": "0.110.2",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",

package/dist/index-8ks9b85e.js

@@ -1,129 +0,0 @@
-import {
-  AppError2,
-  STITCH_ERROR_STATUS2
-} from "./index-j9gxbztg.js";
-
-// src/agent-runtime/sandbox.ts
-import { z } from "zod";
-var AgentSandboxRestrictionSchema2 = z.enum([
-  "network-denied",
-  "write-contained",
-  "secrets-hidden",
-  "process-contained"
-]);
-var AgentSandboxGradeSchema2 = z.discriminatedUnion("grade", [
-  z.object({ grade: z.literal("full"), restrictions: z.array(AgentSandboxRestrictionSchema2) }).strict(),
-  z.object({
-    grade: z.literal("partial"),
-    restrictions: z.array(AgentSandboxRestrictionSchema2),
-    gaps: z.array(AgentSandboxRestrictionSchema2)
-  }).strict(),
-  z.object({ grade: z.literal("unavailable"), reason: z.string().min(1) }).strict()
-]);
-var probes = new WeakMap;
-var PROBE_FAILED = "sandbox probe failed";
-var PROBE_INVALID = "sandbox probe returned no valid grade";
-async function runProbe(sandbox) {
-  let value;
-  try {
-    value = await sandbox.probe();
-  } catch (cause) {
-    return { grade: { grade: "unavailable", reason: PROBE_FAILED }, cause };
-  }
-  const parsed = AgentSandboxGradeSchema2.safeParse(value);
-  if (parsed.success)
-    return { grade: parsed.data };
-  return { grade: { grade: "unavailable", reason: PROBE_INVALID }, cause: parsed.error };
-}
-function probeAgentProcessSandboxOutcome(sandbox, options = {}) {
-  if (options.refresh)
-    probes.delete(sandbox);
-  const present = probes.get(sandbox);
-  if (present)
-    return present;
-  const pending = runProbe(sandbox);
-  probes.set(sandbox, pending);
-  return pending;
-}
-async function probeAgentProcessSandbox2(sandbox, options = {}) {
-  const fresh = options.refresh === true || !probes.has(sandbox);
-  const outcome = await probeAgentProcessSandboxOutcome(sandbox, options);
-  if (fresh && outcome.cause !== undefined) {
-    process.emitWarning(new Error("Sandbox probe failed", { cause: outcome.cause }));
-  }
-  return outcome.grade;
-}
-function missingSandboxRestrictions2(grade, required) {
-  if (grade.grade === "unavailable")
-    return required;
-  const present = new Set(grade.restrictions);
-  return required.filter((restriction) => !present.has(restriction));
-}
-async function recordAgentSandboxProbe2(input) {
-  const grade = await probeAgentProcessSandbox2(input.sandbox);
-  const missing = missingSandboxRestrictions2(grade, input.required);
-  await input.store.appendEvent({
-    conversationId: input.conversationId,
-    kind: "sandbox/probed",
-    payload: {
-      result: grade,
-      required: [...input.required],
-      missing: [...missing]
-    }
-  });
-  return grade;
-}
-
-// src/agent-runtime/coding-tool-refusals.ts
-function codingRefusal(code, message, options = {}) {
-  throw new AppError2(code, {
-    message,
-    status: STITCH_ERROR_STATUS2[code],
-    details: { message, ...options.details },
-    hint: options.hint,
-    ..."cause" in options && { cause: options.cause }
-  });
-}
-function codingPathRefusal(code, message, path, options = {}) {
-  codingRefusal(code, message, {
-    details: { path, ...options.details },
-    ...options.hint && { hint: options.hint }
-  });
-}
-function refuseMissingCodingPath(error, relative) {
-  const code = error?.code;
-  if (error instanceof Error && error.message.includes("is not a regular file")) {
-    codingPathRefusal("BAD_REQUEST", "This path is not a regular file", relative, {
-      hint: "Use list_directory to see what is here."
-    });
-  }
-  if (code === "ENOENT") {
-    codingPathRefusal("NOT_FOUND", "This path does not exist", relative, {
-      hint: "Use list_directory or glob to find the right path."
-    });
-  }
-  if (code === "ENOTDIR") {
-    codingPathRefusal("BAD_REQUEST", "A segment of this path is not a directory", relative, {
-      hint: "Check the path with list_directory."
-    });
-  }
-  if (code === "ELOOP") {
-    codingPathRefusal("FORBIDDEN", "This path is a symlink, which is not followed", relative, {
-      hint: "Read or write the target directly, by its own workspace-relative path."
-    });
-  }
-  if (code === "EISDIR") {
-    codingPathRefusal("BAD_REQUEST", "This path is not a regular file", relative, {
-      hint: "Use list_directory to see what is here."
-    });
-  }
-  throw error;
-}
-function refuseUnknownSpillReference(reference) {
-  codingRefusal("SPILL_REFERENCE_UNKNOWN", `No spilled output is held under \`${reference}\``, {
-    details: { reference },
-    hint: "Use the reference returned by the command that spilled its output, not a session or call id."
-  });
-}
-
-export { AgentSandboxRestrictionSchema2, AgentSandboxGradeSchema2, probeAgentProcessSandboxOutcome, probeAgentProcessSandbox2, missingSandboxRestrictions2, recordAgentSandboxProbe2, codingRefusal, codingPathRefusal, refuseMissingCodingPath, refuseUnknownSpillReference };