stitchkit 0.95.0 → 0.95.2

package/dist/index-tm88avnj.js

@@ -0,0 +1,221 @@
+import {
+  isRecord
+} from "./index-hffjpmq9.js";
+
+// src/application/file-state-store.ts
+import { mkdir, open, readdir, readFile, rename, stat, unlink } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+var ABANDONED_LOCK_MULTIPLIER = 10;
+var ABANDONED_HEARTBEATS = 30;
+var MIN_HEARTBEAT_MS = 10;
+var delay = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+async function missing(error) {
+  return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function existing(error) {
+  return error instanceof Error && "code" in error && error.code === "EEXIST";
+}
+async function ownerState(lockPath) {
+  let owner;
+  try {
+    owner = JSON.parse(await readFile(lockPath, "utf8"));
+  } catch {
+    return "unknown";
+  }
+  if (typeof owner !== "object" || owner === null || !("pid" in owner) || typeof owner.pid !== "number" || !Number.isSafeInteger(owner.pid) || owner.pid <= 0) {
+    return "unknown";
+  }
+  try {
+    process.kill(owner.pid, 0);
+    return "alive";
+  } catch (error) {
+    return error instanceof Error && "code" in error && error.code === "ESRCH" ? "gone" : "unknown";
+  }
+}
+async function sweepTemporaries(path, staleLockMs) {
+  const prefix = `${basename(path)}.tmp.`;
+  const directory = dirname(path);
+  let entries;
+  try {
+    entries = await readdir(directory);
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.startsWith(prefix))
+      continue;
+    const candidate = join(directory, entry);
+    const info = await stat(candidate).catch(() => null);
+    if (info && Date.now() - info.mtimeMs > staleLockMs) {
+      await unlink(candidate).catch(() => {
+        return;
+      });
+    }
+  }
+}
+async function reclaim(lockPath, observed, staleLockMs, abandonedAfterMs) {
+  const guardPath = `${lockPath}.reclaim`;
+  let guard;
+  try {
+    guard = await open(guardPath, "wx");
+  } catch (error) {
+    if (!existing(error))
+      throw error;
+    const orphan = await stat(guardPath).catch(() => null);
+    if (orphan && Date.now() - orphan.mtimeMs > staleLockMs) {
+      await unlink(guardPath).catch(() => {
+        return;
+      });
+    }
+    return false;
+  }
+  try {
+    const current = await stat(lockPath).catch(() => null);
+    if (!current || current.dev !== observed.dev || current.ino !== observed.ino || current.mtimeMs !== observed.mtimeMs) {
+      return false;
+    }
+    const owner = await ownerState(lockPath);
+    const age = Date.now() - current.mtimeMs;
+    if (owner !== "gone" && age < abandonedAfterMs)
+      return false;
+    await unlink(lockPath);
+    return true;
+  } finally {
+    await guard.close().catch(() => {
+      return;
+    });
+    await unlink(guardPath).catch(() => {
+      return;
+    });
+  }
+}
+function createFileStateStore(path, options) {
+  const lockPath = `${path}.lock`;
+  const lockTimeoutMs = options.lockTimeoutMs ?? 1e4;
+  const staleLockMs = options.staleLockMs ?? 3000;
+  const retryMs = options.retryMs ?? 10;
+  const heartbeatMs = Math.max(MIN_HEARTBEAT_MS, Math.floor(staleLockMs / 3));
+  const abandonedAfterMs = Math.max(staleLockMs * ABANDONED_LOCK_MULTIPLIER, heartbeatMs * ABANDONED_HEARTBEATS);
+  if (staleLockMs >= lockTimeoutMs) {
+    throw new Error(`[stitchkit] createFileStateStore: staleLockMs (${staleLockMs}) must be below lockTimeoutMs (${lockTimeoutMs}), or a crashed holder blocks every update until the timeout`);
+  }
+  let sweptTemporaries = false;
+  const parseFile = async () => {
+    let source;
+    try {
+      source = await readFile(path, "utf8");
+    } catch (error) {
+      if (await missing(error))
+        return null;
+      throw error;
+    }
+    try {
+      return options.schema.parse(JSON.parse(source));
+    } catch (error) {
+      await options.onCorrupt?.({ path, error });
+      if ((options.corrupt ?? "throw") === "empty")
+        return null;
+      throw error;
+    }
+  };
+  const acquire = async () => {
+    await mkdir(dirname(path), { recursive: true });
+    if (!sweptTemporaries) {
+      sweptTemporaries = true;
+      await sweepTemporaries(path, staleLockMs);
+    }
+    const deadline = Date.now() + lockTimeoutMs;
+    while (true) {
+      try {
+        const handle = await open(lockPath, "wx");
+        const token = crypto.randomUUID();
+        try {
+          await handle.writeFile(JSON.stringify({ token, pid: process.pid, acquiredAt: Date.now() }));
+          await handle.sync();
+        } catch (error) {
+          await handle.close().catch(() => {
+            return;
+          });
+          await unlink(lockPath).catch(() => {
+            return;
+          });
+          throw error;
+        }
+        return {
+          refresh: async () => {
+            const now = new Date;
+            await handle.utimes(now, now);
+          },
+          release: async () => {
+            await handle.close();
+            try {
+              const owner = JSON.parse(await readFile(lockPath, "utf8"));
+              if (isRecord(owner) && owner.token === token)
+                await unlink(lockPath);
+            } catch (error) {
+              if (!await missing(error))
+                throw error;
+            }
+          }
+        };
+      } catch (error) {
+        if (!existing(error))
+          throw error;
+        try {
+          const lock = await stat(lockPath);
+          if (Date.now() - lock.mtimeMs > staleLockMs) {
+            if (await reclaim(lockPath, lock, staleLockMs, abandonedAfterMs))
+              continue;
+          }
+        } catch (statError) {
+          if (await missing(statError))
+            continue;
+          throw statError;
+        }
+        if (Date.now() >= deadline) {
+          throw new Error(`[stitchkit] timed out acquiring state lock for ${path}`);
+        }
+        await delay(retryMs);
+      }
+    }
+  };
+  const write = async (state) => {
+    const validated = options.schema.parse(state);
+    const temporary = `${path}.tmp.${process.pid}.${crypto.randomUUID()}`;
+    const handle = await open(temporary, "wx");
+    try {
+      try {
+        await handle.writeFile(`${JSON.stringify(validated)}
+`);
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
+      await rename(temporary, path);
+    } catch (error) {
+      await unlink(temporary).catch(() => {
+        return;
+      });
+      throw error;
+    }
+  };
+  return {
+    read: parseFile,
+    async update(transition) {
+      const lock = await acquire();
+      const heartbeat = setInterval(() => void lock.refresh().catch(() => {
+        return;
+      }), heartbeatMs);
+      try {
+        const next = await transition(await parseFile());
+        await write(next.state);
+        return next.result;
+      } finally {
+        clearInterval(heartbeat);
+        await lock.release();
+      }
+    }
+  };
+}
+
+export { createFileStateStore };

package/dist/voice/phases.d.ts

@@ -0,0 +1,4 @@
+/** The phases of a live voice conversation, one vocabulary for every side of it. */
+export declare const LIVE_VOICE_PHASES: readonly ['opening', 'idle', 'hearing', 'thinking', 'speaking'];
+export type LiveVoicePhase = (typeof LIVE_VOICE_PHASES)[number];
+//# sourceMappingURL=phases.d.ts.map

package/dist/voice/phases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phases.d.ts","sourceRoot":"","sources":["../../src/voice/phases.ts"],"names":[],"mappings":"AAAA,oFAAoF;AACpF,eAAO,MAAM,iBAAiB,YAC5B,SAAS,EACT,MAAM,EACN,SAAS,EACT,UAAU,EACV,UAAU,CACF,CAAC;AACX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/voice/sentences.d.ts

@@ -0,0 +1,8 @@
+export declare class SentenceCutter {
+    private said;
+    /** The sentences finished since the previous call; with `final`, the rest of the turn too. */
+    next(text: string, final: boolean): string[];
+    /** Start a new turn. */
+    reset(): void;
+}
+//# sourceMappingURL=sentences.d.ts.map

package/dist/voice/sentences.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sentences.d.ts","sourceRoot":"","sources":["../../src/voice/sentences.ts"],"names":[],"mappings":"AAkBA,qBAAa,cAAc;IACzB,OAAO,CAAC,IAAI,CAAK;IAEjB,8FAA8F;IAC9F,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,EAAE,CAmB3C;IAED,wBAAwB;IACxB,KAAK,IAAI,IAAI,CAEZ;CACF"}

package/dist/voice/speakable.d.ts

@@ -0,0 +1,2 @@
+export declare function speakableText(markdown: string): string;
+//# sourceMappingURL=speakable.d.ts.map

package/dist/voice/speakable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"speakable.d.ts","sourceRoot":"","sources":["../../src/voice/speakable.ts"],"names":[],"mappings":"AAiBA,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAsBtD"}

package/dist/voice/speech-queue.d.ts

@@ -0,0 +1,42 @@
+export interface SpeechQueueOptions<Prepared> {
+    /** Synthesise one sentence. Aborted when the queue is cancelled. */
+    prepare: (text: string, signal: AbortSignal) => Promise<Prepared>;
+    /** Play one prepared sentence to its end. Aborted when the queue is cancelled. */
+    play: (prepared: Prepared, signal: AbortSignal) => Promise<void>;
+    /** Sentences prepared ahead of the one playing. Default 1; 0 prepares only after playing. */
+    lookahead?: number;
+    /** A sentence that failed to prepare or play is skipped; the queue goes on. */
+    onError?: (error: unknown, text: string) => void;
+    /** A prepared sentence that will never play — cancelled — to release what it holds. */
+    discard?: (prepared: Prepared) => void;
+}
+export declare class SpeechQueue<Prepared> {
+    private readonly options;
+    readonly done: Promise<void>;
+    private readonly lookahead;
+    private readonly pending;
+    private readonly ahead;
+    private current;
+    private playing;
+    private closed;
+    private cancelled;
+    private wake;
+    private stop;
+    private readonly stopped;
+    constructor(options: SpeechQueueOptions<Prepared>);
+    get isCancelled(): boolean;
+    get isSpeaking(): boolean;
+    /** Add one sentence. Blank text and anything after `close` or `cancel` is ignored. */
+    push(text: string): void;
+    /** The turn is over: say what is queued, then finish. */
+    close(): void;
+    /** Interrupted: abort the sentence playing and every synthesis, drop the rest. */
+    cancel(): void;
+    private notify;
+    /** Start synthesis up to the lookahead: the sentence playing or next, plus `lookahead`. */
+    private fill;
+    private run;
+    private report;
+    private release;
+}
+//# sourceMappingURL=speech-queue.d.ts.map

package/dist/voice/speech-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"speech-queue.d.ts","sourceRoot":"","sources":["../../src/voice/speech-queue.ts"],"names":[],"mappings":"AAYA,MAAM,WAAW,kBAAkB,CAAC,QAAQ;IAC1C,oEAAoE;IACpE,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;IAClE,kFAAkF;IAClF,IAAI,EAAE,CAAC,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACjE,6FAA6F;IAC7F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD,uFAAuF;IACvF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,IAAI,CAAC;CACxC;AAqBD,qBAAa,WAAW,CAAC,QAAQ;IAenB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAdpC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwB;IAC9C,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,IAAI,CAA6B;IACzC,OAAO,CAAC,IAAI,CAAqC;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAErB;IAEH,YAA6B,OAAO,EAAE,kBAAkB,CAAC,QAAQ,CAAC,EAOjE;IAED,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,IAAI,UAAU,IAAI,OAAO,CAExB;IAED,sFAAsF;IACtF,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAKvB;IAED,yDAAyD;IACzD,KAAK,IAAI,IAAI,CAGZ;IAED,kFAAkF;IAClF,MAAM,IAAI,IAAI,CAgBb;IAED,OAAO,CAAC,MAAM;IAId,2FAA2F;IAC3F,OAAO,CAAC,IAAI;YAaE,GAAG;IAmCjB,OAAO,CAAC,MAAM;IAQd,OAAO,CAAC,OAAO;CAOhB"}

package/llms/application-directory-inbox.txt

@@ -0,0 +1,9 @@
+# stitchkit/application/directory-inbox — 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: pointers only
+
+Also read:
+- see `llms/application.txt` for the Managed application kernel guide

package/llms/application.2.txt

@@ -299,6 +299,8 @@ cutovers are covered by the executable
 | `NotificationOutboxItem` / `NotificationOutboxReceipt` / `NotificationOutboxState` / `NotificationSend` / `NotificationFailureClassification` / `DroppedNotification` / `EnqueueNotification` | _type_ | versioned queue records, stable send identity and delivery decisions |
 | `notificationOutboxStateSchema` | function | strict persisted-state schema over an application payload schema |
 | `notificationOutboxResource` / `NotificationOutboxResource` / `NotificationOutboxResourceConfig` | function / _type_ | thin managed-resource scheduler over an outbox handle |
+| `createDirectoryInbox` (from `stitchkit/application/directory-inbox`) / `DirectoryInbox` / `DirectoryInboxConfig` / `DirectoryInboxDelivery` / `DirectoryInboxResource` | function / _type_ | managed resource delivering each `<name>.json` entry another program drops into a directory to the application at least once, after readiness; separate durable taken/done records, leases, bounded retry |
+| `DirectoryInboxStateSchema` / `DirectoryInboxState` / `DirectoryInboxRejection` / `DirectoryInboxRejectionReasonSchema` / `DirectoryInboxRejectionReason` | schema / _type_ | the inbox's claims, receipts and rejections (`invalid`, `too-large`, `attempt-limit`) |
 | `ApplicationHandle.restart` | method | replace one resource and everything that depends on it, leaving the rest of the graph running and the process epoch unchanged |
 | `ApplicationRestartInputSchema` / `ApplicationRestartInput` | schema / _type_ | the resource to replace, by id, and optionally `gracePeriodMs` / `forceTimeoutMs` for this restart — the application's own shutdown budget otherwise |
 | `ApplicationRestartResultSchema` / `ApplicationRestartResult` | schema / _type_ | the subtree that was actually taken down and brought back, in start order, with the outcome, the reason on anything but success, and how long it took |

package/llms/application.txt

@@ -905,7 +905,36 @@ deadline holds `stop()` — and so the resource's `force()` — for that one cal
 so give the transport a timeout. Superseding a key that is being sent right now
 does not recall it: the send completes, and only its receipt is not written.
 
-Both primitives depend on the structural `StateStore`. On a server,
+`createDirectoryInbox` is the receiving side for another program on the same
+host: it drops entries — a release transition, say — into a directory, and
+the application takes each one at least once. It is a managed resource of its
+own (`createDirectoryInbox({ id, directory, schema, handle })`, imported from
+`stitchkit/application/directory-inbox` because it touches files; its types
+and schemas are in `stitchkit/application`) and publishes a handle with
+`flush()` and `state()`. The producer writes each entry
+atomically as `<name>.json` — a temporary name, then a rename; names that start
+with a dot are never read. Entries are delivered in name order, and only after
+`activate`: none reaches the application before it is ready. `stopAdmission`
+stops taking new ones, `drain` waits for the one in flight, and `force` aborts
+the `signal` its handler was given.
+
+Taken and done are separate durable records. Before `handle` runs, the entry
+is claimed with a lease (`leaseMs`, default five minutes); after it returns,
+a receipt replaces the claim and only then is the file removed. A process that
+died mid-delivery leaves a claim, and the entry is taken again once the lease
+runs out — at least once, not exactly once, so a handler that sends somewhere
+should carry the entry's `key` as its idempotency key. A process that died
+after the receipt leaves only the file, which the next pass removes without
+delivering it again. A handler that throws is retried after a backoff from one
+second doubling to five minutes; an entry that fails `schema`, is over
+`maxEntryBytes` or was taken `maxAttempts` times (default 20 — the count
+survives restarts, so an entry whose handling kills the process is not taken
+forever) is moved to `rejected/` with its reason and reported to `onRejected`,
+and the entries after it keep flowing. The state lives in
+`<directory>/.inbox-state.json` under `createFileStateStore`'s inter-process
+lock unless a `store` is supplied.
+
+These primitives depend on the structural `StateStore`. On a server,
 `createFileStateStore` supplies the shared Zod-validated JSON adapter with an
 inter-process lock, unique temporary file, fsync and atomic rename. The lock
 is a file with a heartbeat: the holder refreshes its mtime every third of

package/llms/stitchkit.txt

@@ -73,6 +73,7 @@ own, recorded as an ADR.
 | `stitchkit/tracking` | browser **and** server | evolving | visitor-tracking mechanics — `createTrackingClient`, the tab-shared outbox, the page-leave beacon, attribution, the contract factory; no event vocabulary, no React |
 | `stitchkit/tracking/server` | server (Bun or Node) | evolving | the decisions a tracking backend makes — dispositions, visit lease over an application-owned store, active intervals, presence; no database |
 | `stitchkit/release` | browser **and** server | evolving | a page follows the release it was built for — `createReleaseMarker` on the server, `createReleaseWatcher` in the browser, the `X-Build-Id` header and a socket event between them |
+| `stitchkit/voice` | browser **and** server | evolving | the mechanics of a live voice reply — `SentenceCutter`, `speakableText`, a `SpeechQueue` that synthesises ahead and stops on interruption, the conversation phases |
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
@@ -95,6 +96,7 @@ own, recorded as an ADR.
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |
 | `stitchkit/application/diagnostic-journal` | server | evolving | the local diagnostic journal — the one part of the kernel that spawns, locks and writes files |
+| `stitchkit/application/directory-inbox` | server | evolving | the directory inbox — entries another program drops into a directory, delivered to the application at least once |
 
 Rule of thumb: browser code imports `stitchkit` and `stitchkit/react`; server
 code adds `stitchkit/server` (or `stitchkit/node` on Node) and opts into

package/llms/voice.txt

@@ -0,0 +1,106 @@
+# stitchkit/voice — 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: Guide: Voice  (docs/guide/voice.md) · API reference: `stitchkit/voice`  (docs/api/reference.md)
+
+==============================================================================
+# Guide: Voice  (docs/guide/voice.md)
+==============================================================================
+
+# Voice
+
+A live voice conversation with an agent repeats the same mechanics in every application
+that has one: the reply is cut into sentences while the model is still writing it, each
+sentence is stripped down to what can be said aloud, and a queue speaks them in order — and
+stops at once when the listener interrupts. `stitchkit/voice` is those mechanics, the same in
+the browser and on Bun or Node, with no dependencies. It is **evolving**.
+
+Speech recognition, synthesis providers, the microphone and the player stay with the
+application: the queue takes them as two functions.
+
+## Sentences while the reply streams
+
+```ts
+import { SentenceCutter, SpeechQueue, speakableText } from 'stitchkit/voice'
+
+const cutter = new SentenceCutter()
+
+for await (const text of reply) {           // the whole reply so far, on every chunk
+  for (const sentence of cutter.next(text, false)) say(sentence)
+}
+for (const sentence of cutter.next(finalText, true)) say(sentence) // the rest of the turn
+cutter.reset()                              // the next turn starts from zero
+```
+
+A sentence ends at `. ! ? …` (with any closing quote or bracket) followed by whitespace and a
+capital letter, a digit or an opening mark, or at a blank line between paragraphs. `3.5`,
+`т. е. так` and `e.g. this` are not cut; the end of the text is not the end of a sentence
+until `final`; nothing is cut inside a fenced code block, even one that is still open.
+
+## What is said
+
+`speakableText(markdown)` keeps what a reader sees and drops what cannot be said: headings,
+emphasis and list markers lose their delimiters, a link keeps its text and loses its
+address, and images, bare addresses, fenced code blocks and tables are dropped whole. It does
+not summarise. A sentence that was only code becomes `''`, and the queue ignores blank text.
+
+## Speaking in order, synthesising ahead
+
+```ts
+const queue = new SpeechQueue<Blob>({
+  prepare: (text, signal) => synthesise(text, { signal }),  // the whole clip
+  play: (clip, signal) => player.play(clip, { signal }),    // resolves when it has played
+  lookahead: 1,                                             // the default
+  onError: (error, text) => log.warn('sentence skipped', { error, text }),
+  discard: (clip) => release(clip),                         // prepared, never played
+})
+
+const say = (sentence: string) => queue.push(speakableText(sentence))
+
+// the turn is over: say what is queued, then `done` settles
+queue.close()
+// the listener interrupted: the playing sentence and every synthesis are aborted
+queue.cancel()
+await queue.done
+```
+
+While one sentence plays, up to `lookahead` more are already synthesising, so a synthesiser
+that returns the whole clip does not leave a gap the length of its synthesis between two
+sentences. `lookahead: 0` synthesises each sentence only after the previous one played.
+
+A sentence that fails to synthesise or to play is reported to `onError` and skipped; the
+queue goes on. `cancel()` aborts the signal of the sentence playing and of every synthesis in
+flight, drops the rest, calls `discard` for every clip that was prepared and will not play,
+and settles `done` without waiting for a `play` that ignores its signal. `isSpeaking` and
+`isCancelled` say where the queue is.
+
+## Phases
+
+```ts
+import { LIVE_VOICE_PHASES, type LiveVoicePhase } from 'stitchkit/voice'
+// 'opening' | 'idle' | 'hearing' | 'thinking' | 'speaking'
+```
+
+One vocabulary for every side of the conversation — the server that runs the agent and the
+page that shows the microphone — so a phase sent over the wire means the same on both ends.
+
+==============================================================================
+# API reference: `stitchkit/voice`  (docs/api/reference.md)
+==============================================================================
+
+## `stitchkit/voice`
+
+Isomorphic, dependency-free mechanics of a live voice conversation. Recognition, synthesis
+providers, the microphone and the player remain application-owned. See the
+[voice guide](../guide/voice.md).
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `SentenceCutter` | class | `next(text, final)` returns the sentences finished since the previous call of the reply streamed so far — never inside a fenced code block, never at `3.5` or `т. е.`; `reset()` starts a new turn |
+| `speakableText` | function | the visible text of Markdown without delimiters, link and image addresses, bare addresses, fenced code blocks or tables |
+| `SpeechQueue` / `SpeechQueueOptions` | class / _type_ | speak sentences in order with `lookahead` (default 1) synthesised while one plays; `close()` finishes the queue, `cancel()` aborts the playing sentence and every synthesis; a failed sentence is reported to `onError` and skipped |
+| `LIVE_VOICE_PHASES` / `LiveVoicePhase` | constant / _type_ | `opening`, `idle`, `hearing`, `thinking`, `speaking` |
+
+---

package/llms-full.txt

@@ -64,6 +64,7 @@ own, recorded as an ADR.
 | `stitchkit/tracking` | browser **and** server | evolving | visitor-tracking mechanics — `createTrackingClient`, the tab-shared outbox, the page-leave beacon, attribution, the contract factory; no event vocabulary, no React |
 | `stitchkit/tracking/server` | server (Bun or Node) | evolving | the decisions a tracking backend makes — dispositions, visit lease over an application-owned store, active intervals, presence; no database |
 | `stitchkit/release` | browser **and** server | evolving | a page follows the release it was built for — `createReleaseMarker` on the server, `createReleaseWatcher` in the browser, the `X-Build-Id` header and a socket event between them |
+| `stitchkit/voice` | browser **and** server | evolving | the mechanics of a live voice reply — `SentenceCutter`, `speakableText`, a `SpeechQueue` that synthesises ahead and stops on interruption, the conversation phases |
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
 | `stitchkit/oauth` | browser **and** server | evolving | provider-neutral Authorization Code + PKCE request and one-shot callback transaction mechanics |
 | `stitchkit/google` | server (Bun or Node) | evolving | optional Google code exchange and verified OIDC identity adapter |
@@ -86,6 +87,7 @@ own, recorded as an ADR.
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |
 | `stitchkit/application/diagnostic-journal` | server | evolving | the local diagnostic journal — the one part of the kernel that spawns, locks and writes files |
+| `stitchkit/application/directory-inbox` | server | evolving | the directory inbox — entries another program drops into a directory, delivered to the application at least once |
 
 Rule of thumb: browser code imports `stitchkit` and `stitchkit/react`; server
 code adds `stitchkit/server` (or `stitchkit/node` on Node) and opts into
@@ -7151,7 +7153,36 @@ deadline holds `stop()` — and so the resource's `force()` — for that one cal
 so give the transport a timeout. Superseding a key that is being sent right now
 does not recall it: the send completes, and only its receipt is not written.
 
-Both primitives depend on the structural `StateStore`. On a server,
+`createDirectoryInbox` is the receiving side for another program on the same
+host: it drops entries — a release transition, say — into a directory, and
+the application takes each one at least once. It is a managed resource of its
+own (`createDirectoryInbox({ id, directory, schema, handle })`, imported from
+`stitchkit/application/directory-inbox` because it touches files; its types
+and schemas are in `stitchkit/application`) and publishes a handle with
+`flush()` and `state()`. The producer writes each entry
+atomically as `<name>.json` — a temporary name, then a rename; names that start
+with a dot are never read. Entries are delivered in name order, and only after
+`activate`: none reaches the application before it is ready. `stopAdmission`
+stops taking new ones, `drain` waits for the one in flight, and `force` aborts
+the `signal` its handler was given.
+
+Taken and done are separate durable records. Before `handle` runs, the entry
+is claimed with a lease (`leaseMs`, default five minutes); after it returns,
+a receipt replaces the claim and only then is the file removed. A process that
+died mid-delivery leaves a claim, and the entry is taken again once the lease
+runs out — at least once, not exactly once, so a handler that sends somewhere
+should carry the entry's `key` as its idempotency key. A process that died
+after the receipt leaves only the file, which the next pass removes without
+delivering it again. A handler that throws is retried after a backoff from one
+second doubling to five minutes; an entry that fails `schema`, is over
+`maxEntryBytes` or was taken `maxAttempts` times (default 20 — the count
+survives restarts, so an entry whose handling kills the process is not taken
+forever) is moved to `rejected/` with its reason and reported to `onRejected`,
+and the entries after it keep flowing. The state lives in
+`<directory>/.inbox-state.json` under `createFileStateStore`'s inter-process
+lock unless a `store` is supplied.
+
+These primitives depend on the structural `StateStore`. On a server,
 `createFileStateStore` supplies the shared Zod-validated JSON adapter with an
 inter-process lock, unique temporary file, fsync and atomic rename. The lock
 is a file with a heartbeat: the holder refreshes its mtime every third of
@@ -12603,6 +12634,88 @@ session query with `cache`; the generic starter does not invent a `getSession`
 endpoint or cookie vocabulary.
 
 
+==============================================================================
+# Guide: Voice  (docs/guide/voice.md)
+==============================================================================
+
+# Voice
+
+A live voice conversation with an agent repeats the same mechanics in every application
+that has one: the reply is cut into sentences while the model is still writing it, each
+sentence is stripped down to what can be said aloud, and a queue speaks them in order — and
+stops at once when the listener interrupts. `stitchkit/voice` is those mechanics, the same in
+the browser and on Bun or Node, with no dependencies. It is **evolving**.
+
+Speech recognition, synthesis providers, the microphone and the player stay with the
+application: the queue takes them as two functions.
+
+## Sentences while the reply streams
+
+```ts
+import { SentenceCutter, SpeechQueue, speakableText } from 'stitchkit/voice'
+
+const cutter = new SentenceCutter()
+
+for await (const text of reply) {           // the whole reply so far, on every chunk
+  for (const sentence of cutter.next(text, false)) say(sentence)
+}
+for (const sentence of cutter.next(finalText, true)) say(sentence) // the rest of the turn
+cutter.reset()                              // the next turn starts from zero
+```
+
+A sentence ends at `. ! ? …` (with any closing quote or bracket) followed by whitespace and a
+capital letter, a digit or an opening mark, or at a blank line between paragraphs. `3.5`,
+`т. е. так` and `e.g. this` are not cut; the end of the text is not the end of a sentence
+until `final`; nothing is cut inside a fenced code block, even one that is still open.
+
+## What is said
+
+`speakableText(markdown)` keeps what a reader sees and drops what cannot be said: headings,
+emphasis and list markers lose their delimiters, a link keeps its text and loses its
+address, and images, bare addresses, fenced code blocks and tables are dropped whole. It does
+not summarise. A sentence that was only code becomes `''`, and the queue ignores blank text.
+
+## Speaking in order, synthesising ahead
+
+```ts
+const queue = new SpeechQueue<Blob>({
+  prepare: (text, signal) => synthesise(text, { signal }),  // the whole clip
+  play: (clip, signal) => player.play(clip, { signal }),    // resolves when it has played
+  lookahead: 1,                                             // the default
+  onError: (error, text) => log.warn('sentence skipped', { error, text }),
+  discard: (clip) => release(clip),                         // prepared, never played
+})
+
+const say = (sentence: string) => queue.push(speakableText(sentence))
+
+// the turn is over: say what is queued, then `done` settles
+queue.close()
+// the listener interrupted: the playing sentence and every synthesis are aborted
+queue.cancel()
+await queue.done
+```
+
+While one sentence plays, up to `lookahead` more are already synthesising, so a synthesiser
+that returns the whole clip does not leave a gap the length of its synthesis between two
+sentences. `lookahead: 0` synthesises each sentence only after the previous one played.
+
+A sentence that fails to synthesise or to play is reported to `onError` and skipped; the
+queue goes on. `cancel()` aborts the signal of the sentence playing and of every synthesis in
+flight, drops the rest, calls `discard` for every clip that was prepared and will not play,
+and settles `done` without waiting for a `play` that ignores its signal. `isSpeaking` and
+`isCancelled` say where the queue is.
+
+## Phases
+
+```ts
+import { LIVE_VOICE_PHASES, type LiveVoicePhase } from 'stitchkit/voice'
+// 'opening' | 'idle' | 'hearing' | 'thinking' | 'speaking'
+```
+
+One vocabulary for every side of the conversation — the server that runs the agent and the
+page that shows the microphone — so a phase sent over the wire means the same on both ends.
+
+
 ==============================================================================
 # Guide: GeoIP  (docs/guide/geo.md)
 ==============================================================================
@@ -16978,6 +17091,8 @@ cutovers are covered by the executable
 | `NotificationOutboxItem` / `NotificationOutboxReceipt` / `NotificationOutboxState` / `NotificationSend` / `NotificationFailureClassification` / `DroppedNotification` / `EnqueueNotification` | _type_ | versioned queue records, stable send identity and delivery decisions |
 | `notificationOutboxStateSchema` | function | strict persisted-state schema over an application payload schema |
 | `notificationOutboxResource` / `NotificationOutboxResource` / `NotificationOutboxResourceConfig` | function / _type_ | thin managed-resource scheduler over an outbox handle |
+| `createDirectoryInbox` (from `stitchkit/application/directory-inbox`) / `DirectoryInbox` / `DirectoryInboxConfig` / `DirectoryInboxDelivery` / `DirectoryInboxResource` | function / _type_ | managed resource delivering each `<name>.json` entry another program drops into a directory to the application at least once, after readiness; separate durable taken/done records, leases, bounded retry |
+| `DirectoryInboxStateSchema` / `DirectoryInboxState` / `DirectoryInboxRejection` / `DirectoryInboxRejectionReasonSchema` / `DirectoryInboxRejectionReason` | schema / _type_ | the inbox's claims, receipts and rejections (`invalid`, `too-large`, `attempt-limit`) |
 | `ApplicationHandle.restart` | method | replace one resource and everything that depends on it, leaving the rest of the graph running and the process epoch unchanged |
 | `ApplicationRestartInputSchema` / `ApplicationRestartInput` | schema / _type_ | the resource to replace, by id, and optionally `gracePeriodMs` / `forceTimeoutMs` for this restart — the application's own shutdown budget otherwise |
 | `ApplicationRestartResultSchema` / `ApplicationRestartResult` | schema / _type_ | the subtree that was actually taken down and brought back, in start order, with the outcome, the reason on anything but success, and how long it took |
@@ -18268,6 +18383,21 @@ signal stay with the application. → ADR 0167 — [guide](../guide/release.md)
 
 ---
 
+## `stitchkit/voice`
+
+Isomorphic, dependency-free mechanics of a live voice conversation. Recognition, synthesis
+providers, the microphone and the player remain application-owned. See the
+[voice guide](../guide/voice.md).
+
+| Export | Kind | Summary |
+|--------|------|---------|
+| `SentenceCutter` | class | `next(text, final)` returns the sentences finished since the previous call of the reply streamed so far — never inside a fenced code block, never at `3.5` or `т. е.`; `reset()` starts a new turn |
+| `speakableText` | function | the visible text of Markdown without delimiters, link and image addresses, bare addresses, fenced code blocks or tables |
+| `SpeechQueue` / `SpeechQueueOptions` | class / _type_ | speak sentences in order with `lookahead` (default 1) synthesised while one plays; `close()` finishes the queue, `cancel()` aborts the playing sentence and every synthesis; a failed sentence is reported to `onError` and skipped |
+| `LIVE_VOICE_PHASES` / `LiveVoicePhase` | constant / _type_ | `opening`, `idle`, `hearing`, `thinking`, `speaking` |
+
+---
+
 ## `stitchkit/geo`
 
 Server-only managed GeoIP generations. Applications own database acquisition,