@sigrun/memory-honcho 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,64 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.1] - 2026-10-31
+
+### Fixed
+
+- `establish` adds session peers via the SDK's tuple form
+  (`[[peerId, {observeMe, observeOthers}]]`) instead of the documented
+  map form — the SDK's client-side zod union rejects the map form, so
+  every first-capture establishment failed against a real server
+  (verified live against honcho v3.0.9).
+
+## [0.1.0] - 2026-10-31
+### Added
+- Honcho persistent-memory extension for sigrun (pi-durable). Every
+  settled run (answered and unanswered) appends one capture batch to a
+  durable JSONL outbox under a module-level mutex, then kicks
+  fire-and-forget delivery; per-conversation selection gating reads the
+  conversation's `AgentDoc.extensions` (array-form exclusion skips
+  capture; positive verdicts memoized per conversation).
+- Delivery engine: per-conversation serialization chains; lazy session
+  establishment (get-or-create `sigrun-<conversationId>` with map-form
+  peer observation config and `summary`/`dream` enabled); batchId
+  dedup via the ledger's delivered-batch window; fork anchors
+  (sigrun entry id → Honcho message id) folded on delivery; an
+  accepted send-then-crash duplicate window documented.
+- Fork continuity: `conversationForked` writes a durable pending-fork
+  record with zero network; the child's first delivery clones the
+  parent's Honcho session at the newest anchor at-or-before the fork
+  point (`pickCloneAnchor`: clone / fresh-session `none-window` /
+  `none-empty`), with clone-duplicate mitigation by write-ahead fork
+  records and status-route session counts.
+- Cron job `outbox-sweep` (`*/15 * * * *`, task action
+  `honcho-outbox-sweep`): fork-first establishment, per-conversation
+  redelivery, then compaction — delivered records dropped, over-retention
+  pending records dropped with a per-record warning.
+- Representation cache + two prompt sections (`long-term-memory`,
+  `honcho-memory`) rendering synchronously from the cache; leading-edge
+  refresh at first delivery; wake-only worker `honcho-representations`
+  (`conversationIdle`/`conversationArchived`) re-refreshes the woken
+  conversation through the memoized engine client.
+- Recall tools `honcho_search` (author-scoped `Peer.search`),
+  `honcho_chat` (peer-pair dialectic, no session scope), and
+  `honcho_remember` (session-less `conclusionsOf` write — the
+  README documents the visibility caveat).
+- Status route `GET /v1/ext/memory-honcho/status` (`auth: "user"`):
+  config summary with the key projected to a `configured` boolean,
+  `lastDeliveryAt` from the persistent `state/last-delivery.json`
+  marker (falling back to retained-record derivation), outbox/ledger/
+  fork/session counts, and worker bookkeeping — best-effort, degrading
+  to zeroed counts on a corrupt file rather than failing the request.
+- `userDeleted`: departure notice only — no data movement (peers are
+  server-side Honcho state; transfer is Honcho-side or deferred).
+- `harnessShutdown` drains delivery chains under a 25s deadline.
+- Settings/secret resolution: `resolveSettings` (eleven keys with
+  defaults and numeric validation) and `resolveApiKey` (stored
+  `api-key` secret, then env `SIGRUN_EXT_MEMORY_HONCHO_API_KEY`) —
+  both read live per use, so a key written after boot applies at the
+  next event without a restart.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael MacLeod
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,104 @@
-# Temporary Holding Version
+# @sigrun/memory-honcho
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Honcho persistent-memory extension for [sigrun](https://github.com/sigrun-ai/sigrun) (pi-durable).
+
+Sigrun's memory seam delivers every settled run to this extension, which captures both halves of the turn into a durable on-disk outbox and delivers them to [Honcho](https://github.com/plastic-labs/honcho) — cross-conversation, peer-level memory: Honcho derives a representation of each user from every conversation the agent shared with them, and this extension recalls through tools and renders a per-conversation prompt section from a cached copy of that representation.
+
+Why Honcho over a local file store: derivation (dreams, summaries, peer representations) runs **server-side** — the client's only jobs are capture delivery and representation refresh, both scheduled here; nothing else is ported.
+
+## Install
+
+```jsonc
+// settings.json (sigrun config dir) — the UNIFIED extensions list:
+// install + load in one place; npm specifiers
+// ("@sigrun/memory-honcho@^0.1.0") and the file: form below are the
+// same list.
+{
+	"extensions": ["file:/path/to/sigrun-memory-honcho"]
+}
+```
+
+## Configuration
+
+**API key** — resolution order, fresh read per use (stored wins without restart):
+
+1. the stored secret: section `api-key` in `<configDir>/secrets.json`, then
+2. the `SIGRUN_EXT_MEMORY_HONCHO_API_KEY` environment variable.
+
+With no key configured, captures still append to the outbox and the sweeper delivers them once a key appears — a key added after boot applies at the next event, no restart.
+
+**Settings** — `<configDir>/settings/memory-honcho.json`, all optional (defaults in parentheses), read live per use: `workspaceId` (`"sigrun"`), `agentPeerId` (`"sigrun"`), `baseUrl` (the Honcho SDK default — omit for honcho.dev), `contextTokens` (1200), `maxMessageLength` (8000), `searchLimit` (8), `toolPreviewLength` (500), `representationTtlMs` (600000), `outboxRetentionDays` (30), `deliveredBatchWindow` (200), `anchorWindow` (1000). Operator caution: changing `workspaceId` or `baseUrl` after first capture leaves stale sessions in the old workspace.
+
+## On-disk layout
+
+The host hands the extension three store roots; writes are atomic (temp + rename):
+
+- `data/outbox/capture.jsonl` — the durable outbox, the **only durable copy** of not-yet-delivered conversation content (the backed-up bucket).
+- `state/ledger/<conversationId>.json` — per-conversation bookkeeping: the Honcho session mapping, the delivered-batchId window (dedup), and the fork anchors (sigrun entry id → Honcho message id).
+- `state/forks/pending/<childId>.json` — fork-mapping records, written by the fork handler with zero network, resolved on clone.
+- `state/last-delivery.json` — the persistent newest-delivery marker the status route reads (the sweeper drops delivered records, so the marker is the surviving source in steady state).
+- `cache/representations/<conversationId>.json` — the representation snapshots the prompt section renders.
+
+## Capture semantics
+
+Every settled run (answered **and** unanswered) appends one outbox record with the user inputs and the answer, then kicks fire-and-forget delivery; a missing key skips only the kick — the sweeper delivers later. Delivery is per-conversation chain-serialized; the delivered-batchId window in the ledger makes redelivery idempotent.
+
+**Selection gating:** the conversation's per-conversation extension selection is read per settle. The array form (`{extensions: ["…"]}`) selects exactly its members — an array not naming `@sigrun/memory-honcho` skips capture. The object form (`{add, remove}`) edits the host default and does not exclude this extension — a `remove` of us is a no-op, because we are not host-default. Positive verdicts are memoized per conversation (a `false` is re-read on the next event, so a mid-conversation opt-in captures). **Residual, accepted for v1:** an array-form opt-out issued *after* a positive verdict keeps capturing until the process restarts.
+
+**Pending-input visibility:** `runSettled` fires on settle — inputs queued or typed mid-run are invisible to capture until the run settles.
+
+## Recall tools
+
+- **`honcho_search`** (`query`) — workspace-wide search over the calling user's own messages, across conversations. **Author-scoped, stated honestly:** `Peer.search` returns messages with that peer as *author* — user text only, never assistant answers; assistant recall lives in `honcho_chat` and the section representation.
+- **`honcho_chat`** (`query`, `reasoningLevel?`) — a dialectic query over the agent peer's full representation of the calling user (no session scope).
+- **`honcho_remember`** (`content`) — writes a conclusion about the calling user (`conclusionsOf`), **with no `sessionId`**: a remembered fact is user-level, not conversation-level, matching the cross-conversation recall ruling. **Visibility caveat (not yet live-verified):** whether a session-less conclusion appears in the session-scoped representation the prompt section renders depends on Honcho's default `limitToSession` behavior; if it is scoped out, a remembered fact may not surface in the section — the tool would need to stamp the calling session's id.
+
+**Privacy boundary (qualified):** `honcho_search` is author-scoped — one user's search returns only messages captured under their own peer. `honcho_chat` and representations are **peer-pair-scoped**: the agent peer's representation of a user derives from every session where the agent observed that user — *including shared conversations*, where `observeOthers` derives over co-participants' turns too. In a multi-user deployment with shared conversations, a `honcho_chat` answer can therefore reflect another user's turns from a co-observed session (Honcho's own derivation semantics, not a sigrun leak). Single-user deployments are unaffected. Peer ids ARE the sigrun usernames — stable, not anonymizing.
+
+## Fork semantics
+
+A sigrun fork writes a durable pending-fork record (zero network); the child's first capture establishes its Honcho session as a **clone** of the parent's session, cut at the parent's fork anchor — the child inherits the parent's Honcho history to the fork point.
+
+**What clone buys (honest premise):** the SDK documents `clone` as a copy of the session's *messages* ("up to and including that message"); nothing promises conclusions or derived representations are copied. The child's representations are **re-derived server-side** from the cloned messages. The value is transcript continuity for derivation, not pre-warmed conclusions. (Live verification of what clone copies is outstanding; the design does not depend on the stronger reading.)
+
+**Granularity limit (accepted):** only assistant answers carry Honcho anchors — a fork at a user input entry clones to the answer *before* it, so the child's Honcho history may miss the trailing user input that sigrun's transcript includes.
+
+**Fork precondition:** the pending-fork record must exist when the child first captures — a conversation forked **before** this extension was loaded has no record and starts a fresh session (no history).
+
+## Jobs and worker
+
+- **Cron job `outbox-sweep`** (`*/15 * * * *`) — the delivery engine of record: resolves pending forks, delivers each conversation's pending records, then compacts (delivered records are dropped; pending records older than `outboxRetentionDays` are dropped with a warning per record). The sweep keeps working when Honcho is down — failures are per-conversation and the next sweep retries.
+- **Wake-only worker `honcho-representations`** (`conversationIdle`, `conversationArchived`) — re-refreshes the woken conversation's representation cache, which the two prompt sections (`long-term-memory`, `honcho-memory`) render synchronously. A delivered conversation with no cache also refreshes once at delivery (the leading edge).
+
+## Status route
+
+`GET /v1/ext/memory-honcho/status` (`auth: "user"`): config summary (never key material — the key projects to a `configured` boolean), newest-delivery time (`lastDeliveryAt`, from the persistent marker), pending outbox count, ledger/session counts (session counts make the accepted clone-duplicate window operator-visible), pending-fork count, and the extension's own worker bookkeeping (last-run, last-error — the route cannot read the host's `/v1/meta` worker projection). Caveats: the counts are **global** across users — the route answers for the whole deployment to any authenticated user; and a corrupt store file degrades that bucket's counts to zero rather than failing the request.
+
+## Troubleshooting
+
+- **Honcho down** — captures stay pending in the outbox; the sweeper retries every 15 minutes. Sections render the last-good cache. Tool calls throw a clean error naming the extension.
+- **Key added after boot** — nothing to restart: secrets and settings are re-read per use, so the next settled run delivers (and the sweeper drains the backlog).
+- **A fork child has no history** — check the fork precondition above: the fork must happen while this extension is loaded.
+
+## Limitations
+
+- `honcho_search` is author-scoped: it returns the user's *own* messages only — assistant answers are reachable through `honcho_chat` and the section representation, not through search.
+- Chat and representations are peer-pair-scoped: in a multi-user deployment with shared conversations, a `honcho_chat` answer can reflect another user's turns from a co-observed session (Honcho's derivation semantics). Operators who need a hard boundary would drop `observeOthers` (a future setting).
+- Fork clone = transcript continuity: the child inherits the parent's messages to the fork point and Honcho re-derives conclusions and representations from them — conclusions are session-scoped and are *not* copied by the clone.
+- `honcho_remember` writes a session-less (global) conclusion; whether it surfaces in the session-scoped representation depends on Honcho's `limitToSession` default — not yet live-verified.
+- Pending-input visibility: capture sees a run's inputs only at settle.
+- Fork precondition: a conversation forked before this extension was loaded starts with a fresh Honcho session.
+- **Queue-overflow capture loss (accepted, host posture):** under host event-queue overflow the oldest queued event is dropped — a dropped settle is a run the extension never sees, so its capture batch is permanently lost (the outbox cannot recover an event it never received).
+- **Clone duplicate window (accepted):** a clone that succeeds server-side but crashes before the ledger write retries into a duplicate full-history session — rare, bounded to one duplicate per crash, and non-corrupting (the ledger points at exactly one session); the status route's session count makes duplicates operator-visible.
+- **Jobs-posture caveat:** a task-action job whose run dies un-settled (harness close mid-run) leaves the host's job-run record `running` until restart — the host has no staleness sweep; this extension's sweeper is exposed to it like every task-action job.
+
+## Development
+
+```sh
+npm install
+npm test            # manifest check + vitest
+npm run typecheck   # tsc --noEmit
+npm run build       # tsc -> dist/ (commit the result)
+```
+
+`dist/` is committed by design — git-source installs load `dist/index.js` with no build step. Tests own their literals: synthetic users, a fake Honcho SDK, no real keys, no live Honcho.

package/dist/capture.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The capture batch builder: turn one settled run into one outbox record.
+ *
+ * Pure — no I/O, no Honcho. The filtering rules (spec §Capture):
+ * user texts first, in admission order, skipping empty and over-cap texts;
+ * then, when the run answered AND the answer text survives the same filter,
+ * one agent entry. Unanswered runs tag their user entries `unanswered: true`
+ * and carry no agent entry and no `answerEntryId`. `undefined` when nothing
+ * survives the filter (an all-empty batch is pure outbox churn).
+ */
+import type { OutboxRecord, RunSettledEventLike } from "./types.js";
+/**
+ * Build the outbox record for one settled run, or `undefined` when no
+ * non-empty, under-cap text survives. `owner` is pre-resolved by the caller
+ * (ownerless conversations arrive as `"user"`).
+ */
+export declare function buildCaptureBatch(event: RunSettledEventLike, owner: string, maxMessageLength: number): OutboxRecord | undefined;

package/dist/capture.js

@@ -0,0 +1,61 @@
+/**
+ * The capture batch builder: turn one settled run into one outbox record.
+ *
+ * Pure — no I/O, no Honcho. The filtering rules (spec §Capture):
+ * user texts first, in admission order, skipping empty and over-cap texts;
+ * then, when the run answered AND the answer text survives the same filter,
+ * one agent entry. Unanswered runs tag their user entries `unanswered: true`
+ * and carry no agent entry and no `answerEntryId`. `undefined` when nothing
+ * survives the filter (an all-empty batch is pure outbox churn).
+ */
+import { createHash } from "node:crypto";
+/**
+ * Build the outbox record for one settled run, or `undefined` when no
+ * non-empty, under-cap text survives. `owner` is pre-resolved by the caller
+ * (ownerless conversations arrive as `"user"`).
+ */
+export function buildCaptureBatch(event, owner, maxMessageLength) {
+    const batchId = createHash("sha256")
+        .update(`${event.conversationId}:${event.inputs[0] ?? ""}:${event.inputs.length}`)
+        .digest("hex");
+    const metadata = {
+        conversationId: event.conversationId,
+        submissionIds: event.inputs,
+        batchId,
+    };
+    const entries = [];
+    for (const text of event.inputTexts) {
+        if (text === "" || text.length > maxMessageLength)
+            continue;
+        entries.push({
+            peer: "user",
+            text,
+            metadata: event.outcome.status === "unanswered"
+                ? { ...metadata, unanswered: true }
+                : metadata,
+        });
+    }
+    let answerEntryId;
+    if (event.outcome.status === "answered") {
+        const answerText = event.outcome.answer.content
+            .filter((block) => block.type === "text")
+            .map((block) => (block.type === "text" ? (block.text ?? "") : ""))
+            .join("");
+        if (answerText !== "" && answerText.length <= maxMessageLength) {
+            answerEntryId = event.outcome.answerEntryId;
+            entries.push({ peer: "agent", text: answerText, metadata });
+        }
+    }
+    if (entries.length === 0)
+        return undefined;
+    return {
+        type: "capture",
+        conversationId: event.conversationId,
+        owner,
+        ...(answerEntryId === undefined ? {} : { answerEntryId }),
+        entries,
+        batchId,
+        status: "pending",
+        createdAt: Date.now(),
+    };
+}

package/dist/chains.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Per-label serialization chains (the pi port's `enqueue` pattern).
+ *
+ * Work appended under a label runs strictly after the previously queued
+ * work for that label settles, so Honcho saves for one conversation
+ * happen in order without racing. The caller's promise settles with the
+ * work's own result; the internal TAIL promise never rejects (it
+ * self-catches and reports via `console.error` labeled with the chain
+ * name), so one failing save cannot poison the conversation's queue.
+ */
+type Work<T> = () => Promise<T>;
+export declare function chain<T>(label: string, work: Work<T>): Promise<T>;
+/**
+ * Drain hook for `harnessShutdown`: resolves once every tail live at
+ * call time has settled.
+ */
+export declare function chainTails(): Promise<void[]>;
+export {};

package/dist/chains.js

@@ -0,0 +1,33 @@
+/**
+ * Per-label serialization chains (the pi port's `enqueue` pattern).
+ *
+ * Work appended under a label runs strictly after the previously queued
+ * work for that label settles, so Honcho saves for one conversation
+ * happen in order without racing. The caller's promise settles with the
+ * work's own result; the internal TAIL promise never rejects (it
+ * self-catches and reports via `console.error` labeled with the chain
+ * name), so one failing save cannot poison the conversation's queue.
+ */
+const tails = new Map();
+export function chain(label, work) {
+    const run = (tails.get(label) ?? Promise.resolve()).then(work);
+    // The tail self-catches: a rejection is reported once here and never
+    // propagates into the next queued item (which would re-report it).
+    const tail = run.then(() => undefined, (error) => {
+        console.error(`memory-honcho: chain "${label}" work failed`, error);
+    });
+    tails.set(label, tail);
+    void tail.then(() => {
+        // Drop the tail once settled, unless newer work already extended it.
+        if (tails.get(label) === tail)
+            tails.delete(label);
+    });
+    return run;
+}
+/**
+ * Drain hook for `harnessShutdown`: resolves once every tail live at
+ * call time has settled.
+ */
+export function chainTails() {
+    return Promise.all([...tails.values()]);
+}

package/dist/config.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Settings and secret resolution for @sigrun/memory-honcho.
+ *
+ * Both readers are structural slices of `host.stores`; values are read
+ * LIVE per call (never memoized) so setting/key changes apply at next
+ * use without a restart.
+ */
+export interface SettingsReader {
+    get(): Promise<Record<string, unknown>>;
+}
+export interface SecretsReader {
+    get(key: string): Promise<string | undefined>;
+}
+export interface HonchoSettings {
+    agentPeerId: string;
+    baseUrl: string | undefined;
+    workspaceId: string;
+    contextTokens: number;
+    maxMessageLength: number;
+    searchLimit: number;
+    toolPreviewLength: number;
+    representationTtlMs: number;
+    outboxRetentionDays: number;
+    deliveredBatchWindow: number;
+    anchorWindow: number;
+}
+export declare function resolveSettings(stores: SettingsReader): Promise<HonchoSettings>;
+export declare function resolveApiKey(secrets: SecretsReader): Promise<string | undefined>;

package/dist/config.js

@@ -0,0 +1,43 @@
+/**
+ * Settings and secret resolution for @sigrun/memory-honcho.
+ *
+ * Both readers are structural slices of `host.stores`; values are read
+ * LIVE per call (never memoized) so setting/key changes apply at next
+ * use without a restart.
+ */
+const API_KEY_ENV = "SIGRUN_EXT_MEMORY_HONCHO_API_KEY";
+function stringSetting(value, fallback) {
+    return typeof value === "string" && value !== "" ? value : fallback;
+}
+function integerSetting(value, fallback) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0
+        ? value
+        : fallback;
+}
+export async function resolveSettings(stores) {
+    const raw = await stores.get();
+    return {
+        agentPeerId: stringSetting(raw.agentPeerId, "sigrun"),
+        baseUrl: typeof raw.baseUrl === "string" && raw.baseUrl !== ""
+            ? raw.baseUrl
+            : undefined,
+        workspaceId: stringSetting(raw.workspaceId, "sigrun"),
+        contextTokens: integerSetting(raw.contextTokens, 1200),
+        maxMessageLength: integerSetting(raw.maxMessageLength, 8000),
+        searchLimit: integerSetting(raw.searchLimit, 8),
+        toolPreviewLength: integerSetting(raw.toolPreviewLength, 500),
+        representationTtlMs: integerSetting(raw.representationTtlMs, 600_000),
+        outboxRetentionDays: integerSetting(raw.outboxRetentionDays, 30),
+        deliveredBatchWindow: integerSetting(raw.deliveredBatchWindow, 200),
+        anchorWindow: integerSetting(raw.anchorWindow, 1000),
+    };
+}
+export async function resolveApiKey(secrets) {
+    const stored = await secrets.get("api-key");
+    if (typeof stored === "string" && stored.trim() !== "")
+        return stored;
+    const env = process.env[API_KEY_ENV];
+    if (typeof env === "string" && env !== "")
+        return env;
+    return undefined;
+}

package/dist/delivery.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The delivery engine: session establishment (with the fork clone rules)
+ * and outbox delivery.
+ *
+ * Every public method runs inside the conversation's serialization chain
+ * (`client.for(id).chain`) — the spec's one-chain-per-conversation rule,
+ * so establishment and delivery never race and the double-clone race
+ * cannot happen.
+ *
+ * `deliverPending` acquires the outbox mutex exactly once per flow
+ * (`withOutbox` around the read → ledger flip → rewrite cycle); it never
+ * nests a second `withOutbox` inside it (the mutex is not re-entrant),
+ * and the sweeper (Task 7) calls it per conversation OUTSIDE any outbox
+ * lock — lock acquisition lives in one place per flow. A flipped batch
+ * also updates the `state/last-delivery.json` marker in the same critical
+ * section (the status route's newest-delivery read survives the sweeper's
+ * delivered-record drop that way).
+ */
+import type { HonchoSettings } from "./config.js";
+import type { HonchoClient } from "./honcho.js";
+import type { ExtensionStores } from "./stores.js";
+export interface DeliveryHooks {
+    /** Leading-edge hook (Task 8 injects the refresh kick); default no-op. */
+    onDelivered?(conversationId: number): Promise<void> | void;
+    /**
+     * Test seam: deliver the batch but skip the ledger write — the accepted
+     * crash window between a successful `addMessages` and the ledger flip,
+     * whose cost is a re-sent (duplicate) batch on the next pass.
+     */
+    failAfterSend?: boolean;
+}
+export declare class DeliveryEngine {
+    #private;
+    constructor(client: HonchoClient, stores: ExtensionStores, settings: HonchoSettings, hooks?: DeliveryHooks);
+    /**
+     * Establish the conversation's Honcho session: plain get-or-create, or
+     * a clone-with-mapping when a pending-fork record points at a parent
+     * ledger with a usable anchor. Idempotent (chain-serialized).
+     */
+    establish(conversationId: number, owner: string): Promise<void>;
+    /**
+     * Deliver this conversation's pending outbox records, oldest first.
+     * Delivered batches flip status, fold their batchId into the ledger's
+     * delivered window, and fold a fork anchor ONLY when an agent entry was
+     * in the batch — keyed by THAT agent entry's returned `Message.id`
+     * (unanswered and user-only batches fold no anchor).
+     */
+    deliverPending(conversationId: number, owner: string): Promise<void>;
+    /**
+     * Fire-and-forget delivery (the capture path's posture): self-catching,
+     * logs rather than rejecting. Establishment is LAZY (spec §Capture: the
+     * capture path runs the establishment path inside the fire-and-forget
+     * attempt) — `establish` inside the attempt is chain-serialized ahead of
+     * the delivery, is a no-op when the conversation is already established,
+     * and re-marks a rebuilt client that lost its in-memory session promise.
+     */
+    kick(conversationId: number, owner: string): void;
+}