stitchkit 0.110.0 → 0.110.2

package/dist/{index-fnra8n1j.js → index-s2eybn7b.js}

@@ -13,18 +13,12 @@ import {
   parseToolCallArguments,
   toolResultFromError,
   observed
-} from "./index-73cz22ds.js";
+} from "./index-mha6b4vk.js";
 import {
   collectTools2,
   createToolRunner,
   formatToolError
-} from "./index-p6mvqcbq.js";
-import {
-  redact2
-} from "./index-e6c2spsd.js";
-import {
-  collectToolSurface
-} from "./index-61m15a18.js";
+} from "./index-ghwntn9n.js";
 import {
   DEFAULT_CORS_ALLOW_HEADERS2,
   DEFAULT_PROCESS_SIGNALS,
@@ -32,10 +26,16 @@ import {
   reportSignalError,
   guardSignalCallback
 } from "./index-yk4g8805.js";
+import {
+  redact2
+} from "./index-e6c2spsd.js";
+import {
+  collectToolSurface
+} from "./index-0d8m0kee.js";
 import {
   runWithRequestContext2,
   getRequestContext2
-} from "./index-y3nemndz.js";
+} from "./index-r6v4mc67.js";
 import {
   AppError2
 } from "./index-j9gxbztg.js";

package/dist/{index-njs9gvrh.js → index-s6d8zsha.js}

@@ -26,7 +26,7 @@ import {
 import {
   bindContract,
   mediaTypeEssence
-} from "./index-85qve8mq.js";
+} from "./index-pzw0fpek.js";
 import {
   assertPositiveSafeInteger
 } from "./index-0s4xebbg.js";
@@ -46,7 +46,7 @@ import {
   getRequestContext2,
   setRequestEndpoint2,
   setRequestError2
-} from "./index-y3nemndz.js";
+} from "./index-r6v4mc67.js";
 import {
   resolveTraceId2,
   resolveSocketIp2,
@@ -54,6 +54,10 @@ import {
   getClientInfo2,
   parseQueryParams
 } from "./index-kw1ws0cs.js";
+import {
+  isUnsafeKey,
+  safeJsonParse
+} from "./index-zsarb5xp.js";
 import {
   AppError2,
   badRequest2,
@@ -62,10 +66,6 @@ import {
 import {
   resolveTraceContext2
 } from "./index-yex7eg1v.js";
-import {
-  isUnsafeKey,
-  safeJsonParse
-} from "./index-zsarb5xp.js";
 import {
   isRecord,
   transportResult

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/dist/process/group-presence.d.ts

@@ -0,0 +1,3 @@
+/** A kernel absence is decisive; a Darwin permission refusal is still unknown. */
+export declare function processGroupExists(pid: number): boolean;
+//# sourceMappingURL=group-presence.d.ts.map

package/dist/process/group-presence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"group-presence.d.ts","sourceRoot":"","sources":["../../src/process/group-presence.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAWvD"}

package/dist/process/group-settlement.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"group-settlement.d.ts","sourceRoot":"","sources":["../../src/process/group-settlement.ts"],"names":[],"mappings":"AAGA,0FAA0F;AAC1F,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAQxE;AAmBD,mGAAmG;AACnG,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CASf"}
+{"version":3,"file":"group-settlement.d.ts","sourceRoot":"","sources":["../../src/process/group-settlement.ts"],"names":[],"mappings":"AAIA,0FAA0F;AAC1F,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAQxE;AAmBD,mGAAmG;AACnG,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CA0Bf"}

package/dist/process/group.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"group.d.ts","sourceRoot":"","sources":["../../src/process/group.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,KAAK,6BAA6B,EAAE,MAAM,YAAY,CAAC;AAGpF,+FAA+F;AAC/F,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO;IAYpE,MAAM;IACN,MAAM;EAIT;AAeD,gGAAgG;AAChG,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,OAAO,CASpF;AA+CD,sGAAsG;AACtG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,6BAA6B,CAAC;IAC/C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAmB/E;AAED,gGAAgG;AAChG,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,gBAAgB,GAAG;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,GAC/E,OAAO,CAAC,OAAO,CAAC,CAsBlB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,6BAA6B,CAAC;IACtC,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,OAAO,CAAC,CAyBnB;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,CAItE;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAMxF"}
+{"version":3,"file":"group.d.ts","sourceRoot":"","sources":["../../src/process/group.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,KAAK,6BAA6B,EAAE,MAAM,YAAY,CAAC;AAIpF,+FAA+F;AAC/F,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO;IAYpE,MAAM;IACN,MAAM;EAIT;AAeD,gGAAgG;AAChG,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,OAAO,CASpF;AAsCD,sGAAsG;AACtG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,6BAA6B,CAAC;IAC/C,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,gEAAgE;IAChE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,OAAO,CAAC,CAmB/E;AAED,gGAAgG;AAChG,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,gBAAgB,GAAG;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,CAAA;CAAE,GAC/E,OAAO,CAAC,OAAO,CAAC,CAsBlB;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,MAAM,EAAE,aAAa,CAAC;IACtB,MAAM,EAAE,6BAA6B,CAAC;IACtC,UAAU,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;IAC7B,KAAK,EAAE,OAAO,CAAC;CAChB,GAAG,OAAO,CAAC,OAAO,CAAC,CAyBnB;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,kBAAkB,CAItE;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAMxF"}

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/realtime.txt

@@ -0,0 +1,31 @@
+# stitchkit/realtime — stitchkit docs slice
+
+> Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
+> `llms.txt` in this package.
+
+Contains: API reference: `stitchkit/realtime`  (docs/api/reference.md)
+
+==============================================================================
+# API reference: `stitchkit/realtime`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/realtime`
+
+Hermes-safe realtime clients reuse the root transport and contract implementation. Both
+`createRealtimeClient` and `createSocketIOClient` require `peers.client` here; no default
+computed import enters this graph. Root clients retain their optional lazy runtime loader.
+
+```ts
+import { createRealtimeClient, defineRealtimeContract } from 'stitchkit/realtime';
+const client = createRealtimeClient(contract, {
+  url,
+  peers: { client: () => import('socket.io-client') },
+});
+```
+
+Native consumers import HTTP factories, `ApiError`, `createUrlBuilder`,
+`contractEndpointMatchers` and `uploadInChunks` from `stitchkit/http`; schema factories,
+`ContractDef` and `paginatedSchema` from `stitchkit/contract`; realtime factories,
+`RealtimeClient`, `defineRealtimeContract`, `InferRealtimeEventMap`, `createRetainedTopics`
+and `RetainedTopics` from `stitchkit/realtime`. `createQueryClientFactory` remains in
+`stitchkit/react`. Shared modules must use the same public leaves throughout their graph.

package/llms/stitchkit.txt

@@ -57,6 +57,7 @@ own, recorded as an ADR.
 |--------|--------|----------|-------|
 | `stitchkit` | browser **and** server | stable | `defineContract`, `createClient`, `createHttpClient`, `createSocketIOClient`, `parseSSE`, the error model |
 | `stitchkit/http` | browser, React Native/Hermes **and** server | evolving | typed HTTP client factories and `ApiError`, without optional realtime peers |
+| `stitchkit/realtime` | browser, React Native/Hermes **and** server | evolving | typed realtime clients and retained topics with a required explicit Socket.IO peer loader |
 | `stitchkit/contract` | browser **and** server | stable | the contract layer alone — `defineContract`, errors, pagination |
 | `stitchkit/live` | browser **and** server | evolving | `defineEvents` — topic declarations beside the operation contract — and watched reads: `createWatchClient`, the value/difference frame and its reassembly |
 | `stitchkit/primitives` | browser **and** server | evolving | generic values and declarations for lifecycle, access, audit, delivery and exports |

package/llms-full.txt

@@ -49,6 +49,7 @@ own, recorded as an ADR.
 |--------|--------|----------|-------|
 | `stitchkit` | browser **and** server | stable | `defineContract`, `createClient`, `createHttpClient`, `createSocketIOClient`, `parseSSE`, the error model |
 | `stitchkit/http` | browser, React Native/Hermes **and** server | evolving | typed HTTP client factories and `ApiError`, without optional realtime peers |
+| `stitchkit/realtime` | browser, React Native/Hermes **and** server | evolving | typed realtime clients and retained topics with a required explicit Socket.IO peer loader |
 | `stitchkit/contract` | browser **and** server | stable | the contract layer alone — `defineContract`, errors, pagination |
 | `stitchkit/live` | browser **and** server | evolving | `defineEvents` — topic declarations beside the operation contract — and watched reads: `createWatchClient`, the value/difference frame and its reassembly |
 | `stitchkit/primitives` | browser **and** server | evolving | generic values and declarations for lifecycle, access, audit, delivery and exports |
@@ -5764,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
@@ -21701,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 |
@@ -23338,3 +23402,24 @@ An HTTP-only entrypoint for browsers, React Native/Hermes and servers. It export
 import { createClients, createHttpClient } from 'stitchkit/http';
 import { defineContract } from 'stitchkit/contract';
 ```
+
+## `stitchkit/realtime`
+
+Hermes-safe realtime clients reuse the root transport and contract implementation. Both
+`createRealtimeClient` and `createSocketIOClient` require `peers.client` here; no default
+computed import enters this graph. Root clients retain their optional lazy runtime loader.
+
+```ts
+import { createRealtimeClient, defineRealtimeContract } from 'stitchkit/realtime';
+const client = createRealtimeClient(contract, {
+  url,
+  peers: { client: () => import('socket.io-client') },
+});
+```
+
+Native consumers import HTTP factories, `ApiError`, `createUrlBuilder`,
+`contractEndpointMatchers` and `uploadInChunks` from `stitchkit/http`; schema factories,
+`ContractDef` and `paginatedSchema` from `stitchkit/contract`; realtime factories,
+`RealtimeClient`, `defineRealtimeContract`, `InferRealtimeEventMap`, `createRetainedTopics`
+and `RetainedTopics` from `stitchkit/realtime`. `createQueryClientFactory` remains in
+`stitchkit/react`. Shared modules must use the same public leaves throughout their graph.

package/llms.txt

@@ -9,7 +9,7 @@ Build with stitchkit: define a contract once, then `implement` it and serve it (
 Load the slice for each entrypoint your code imports — `import … from 'stitchkit/server'` → `llms/server.txt`; the root `stitchkit` import → `llms/stitchkit.txt`. A slice holds that entrypoint's API reference section and the guide pages whose home it is; every guide lives in exactly one slice, and a slice that needs another's guide names it under "Also read". Each file is at most 50.0 KB; a longer one continues in numbered parts, each naming the next at its top. Moving across versions: load `llms/upgrading.txt` and the range slices it lists between your version and the target. `llms-full.txt` inlines everything; it is far larger than a context window, so do not read it whole.
 
 ## Entrypoint slices
-- **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 47.3 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 36.5 KB
+- **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 47.5 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 36.5 KB
 - **stitchkit/live**: [llms/live.txt](llms/live.txt) 21.2 KB
 - **stitchkit/react**: [llms/react.txt](llms/react.txt) 8.6 KB
 - **stitchkit/react/keyboard**: [llms/react-keyboard.txt](llms/react-keyboard.txt) 9.2 KB
@@ -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
@@ -60,6 +60,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
 - **stitchkit/process/owner-loss**: [llms/process-owner-loss.txt](llms/process-owner-loss.txt) 0.9 KB
 - **stitchkit/files/packaging**: [llms/files-packaging.txt](llms/files-packaging.txt) 3.5 KB
 - **stitchkit/http**: [llms/http.txt](llms/http.txt) 0.9 KB
+- **stitchkit/realtime**: [llms/realtime.txt](llms/realtime.txt) 1.4 KB
 
 ## Upgrading slices
 - **Upgrading — how to move across versions**: [llms/upgrading.txt](llms/upgrading.txt) 12.2 KB

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.110.0",
+  "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",
@@ -260,6 +260,10 @@
     "./http": {
       "types": "./dist/entrypoints/http.d.ts",
       "import": "./dist/entrypoints/http.js"
+    },
+    "./realtime": {
+      "types": "./dist/entrypoints/realtime.d.ts",
+      "import": "./dist/entrypoints/realtime.js"
     }
   },
   "publishConfig": {

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 };