@sigrun/memory-honcho 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -5,6 +5,49 @@ 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.2] - 2026-11-03
+
+### Fixed
+
+- Worker `endedAt` bookkeeping: the `engineClient === undefined` early
+  return inside the refresh gate skipped `status.endedAt`, leaving the
+  status route with a started-but-never-ended run. The gate now falls
+  through to the shared `endedAt` write.
+- Worker `lastError` writer cap: tested (the 500-char slice in the
+  catch block was untested).
+- Dead `#settings` field on `DeliveryEngine` removed (never read; the
+  engine resolves settings live per call site).
+- `honchoError` no longer nests the extension prefix on internal guard
+  errors (e.g. "client not initialized" already carries it).
+- Duplicate client-undefined guards in `honcho_chat` and
+  `honcho_remember` extracted to a shared `clientOrThrow` helper.
+- Missing-API-key warn-once flag is factory-scoped (was module-global,
+  which made test order observable).
+- Delivery-kick catch log aligned with the sweeper's per-conversation
+  catch shape (same prefix, conversation id, error).
+
+### Added
+
+- `makeLeadingEdgeHook` exported from `src/index.ts` — the composition
+  test uses the factory instead of re-implementing the hook body
+  verbatim (drift risk).
+- README limitation: the `honcho-representations` worker can be frozen
+  on Windows (observed in homelab deployments; the leading-edge refresh
+  and the sweep job keep the cache fresh regardless).
+- Code comment documenting the accepted duplicate-refresh window on
+  overlapping deliveries (bounded by the per-conversation chain,
+  last-write-wins, one extra refresh per conversation lifetime).
+
+## [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

package/README.md

@@ -91,6 +91,7 @@ A sigrun fork writes a durable pending-fork record (zero network); the child's f
 - **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.
+- **Windows: the `honcho-representations` worker can be frozen.** On Windows, the host's worker scheduling can leave a wake-only worker idle even when conversations are idle/archived (observed in homelab deployments; mechanism not yet root-caused). The representation cache stays fresh through the leading-edge refresh at delivery and the `outbox-sweep` job's deliveries — the worker's idle-wake refresh is a convenience, not the only lane.
 
 ## Development
 

package/dist/delivery.d.ts

@@ -15,6 +15,15 @@
  * 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).
+ *
+ * **Accepted duplicate-refresh window (stays):** two deliveries in quick
+ * succession (e.g. a capture kick + the sweeper) can each trigger a
+ * leading-edge representation refresh when the cache is absent — the
+ * check-then-refresh in `onDelivered` is not atomic with the delivery.
+ * Bounded by the per-conversation chain (refreshes queue behind each
+ * other, never overlap); last-write-wins is safe because the refresh
+ * is idempotent (same session, same server-side state). The window is
+ * one extra refresh per conversation lifetime, at first delivery only.
  */
 import type { HonchoSettings } from "./config.js";
 import type { HonchoClient } from "./honcho.js";
@@ -31,7 +40,7 @@ export interface DeliveryHooks {
 }
 export declare class DeliveryEngine {
     #private;
-    constructor(client: HonchoClient, stores: ExtensionStores, settings: HonchoSettings, hooks?: DeliveryHooks);
+    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

package/dist/delivery.js

@@ -15,6 +15,15 @@
  * 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).
+ *
+ * **Accepted duplicate-refresh window (stays):** two deliveries in quick
+ * succession (e.g. a capture kick + the sweeper) can each trigger a
+ * leading-edge representation refresh when the cache is absent — the
+ * check-then-refresh in `onDelivered` is not atomic with the delivery.
+ * Bounded by the per-conversation chain (refreshes queue behind each
+ * other, never overlap); last-write-wins is safe because the refresh
+ * is idempotent (same session, same server-side state). The window is
+ * one extra refresh per conversation lifetime, at first delivery only.
  */
 import { pickCloneAnchor } from "./fork-rules.js";
 /** The session configuration applied on get-or-create AND on clones. */
@@ -25,12 +34,14 @@ const SESSION_CONFIGURATION = {
 export class DeliveryEngine {
     #client;
     #stores;
-    #settings;
     #hooks;
-    constructor(client, stores, settings, hooks = {}) {
+    constructor(client, stores, 
+    // The settings parameter is accepted but not stored: every value the
+    // engine needs is resolved live at the call site (the factory's
+    // live-settings seam), so a stale snapshot would be a bug source.
+    _settings, hooks = {}) {
         this.#client = client;
         this.#stores = stores;
-        this.#settings = settings;
         this.#hooks = hooks;
     }
     /**
@@ -227,24 +238,25 @@ export class DeliveryEngine {
         void this.establish(conversationId, owner)
             .then(() => this.deliverPending(conversationId, owner))
             .catch((error) => {
-            console.error(`memory-honcho: delivery kick failed for conversation ${conversationId}`, error);
+            // Same log shape as the sweeper's per-conversation catches —
+            // one prefix, conversation id, then the error.
+            console.error(`memory-honcho: delivery failed for conversation ${conversationId}`, error);
         });
     }
-    /** Get-or-create `sigrun-<id>` with the map-form observe config. */
+    /** Get-or-create `sigrun-<id>` with the per-peer observe config. */
     async #getOrCreate(conversationId, owner) {
         const session = await this.#client.session(`sigrun-${conversationId}`);
         const userPeer = await this.#client.userPeerFor(owner);
         const agentPeer = await this.#client.agentPeer();
-        // The SDK's map form carries the per-peer observation config (the
-        // array form carries none).
-        const peers = {
-            [userPeer.id]: { observeMe: true, observeOthers: true },
-            [agentPeer.id]: { observeMe: true, observeOthers: true },
-        };
-        // SAFETY: the runtime accepts the map form (the SDK docs and its own
-        // PeerAdditionToApiSchema zod union include it); only the declared
-        // PeerAddition type predates it.
-        await session.addPeers(peers);
+        // The SDK's zod union (PeerAdditionSchema) does NOT accept the
+        // documented map form — only string | Peer | array | tuple. The
+        // tuple form [peerId, config] transforms to the API's per-peer
+        // observe config (verified live 2026-10-31 against honcho v3.0.9:
+        // tuple-array 200s, map form fails client-side validation).
+        await session.addPeers([
+            [userPeer.id, { observeMe: true, observeOthers: true }],
+            [agentPeer.id, { observeMe: true, observeOthers: true }],
+        ]);
         await session.setConfiguration(SESSION_CONFIGURATION);
         return session;
     }

package/dist/index.d.ts

@@ -38,5 +38,21 @@ export interface FactoryDeps {
     createEngine?: (client: HonchoClient, stores: ExtensionStores, settings: HonchoSettings, hooks: DeliveryHooks) => DeliveryEngine;
     createClient?: (settings: HonchoSettings, apiKey: string | undefined) => HonchoClient;
 }
+/**
+ * The leading-edge hook: a delivered conversation whose representation
+ * cache is ABSENT refreshes once (a present cache is fresh enough — the
+ * idle worker owns re-refreshes). The delivery engine calls the hook OUT
+ * of the conversation chain, so this refresh chains behind the delivery
+ * that just settled (never a circular wait). Failures log and are
+ * swallowed: a failed refresh must never fault the delivery it rode in on.
+ *
+ * Extracted for the composition test (T8 parked minor): the test uses the
+ * same factory instead of re-implementing the body verbatim.
+ */
+export declare function makeLeadingEdgeHook(opts: {
+    readonly stores: () => Promise<ExtensionStores>;
+    readonly client: HonchoClient;
+    readonly settings: HonchoSettings;
+}): DeliveryHooks;
 export declare function createHonchoMemory(host: SigrunHost, deps?: FactoryDeps): SigrunExtensionResultLike;
 export default createHonchoMemory;

package/dist/index.js

@@ -37,13 +37,19 @@ import { createTools } from "./tools.js";
 const EXTENSION_NAME = "@sigrun/memory-honcho";
 /** The shutdown drain deadline (spec: 25s under the host's shutdown budget). */
 const DRAIN_DEADLINE_MS = 25_000;
-/** The missing-API-key notice fires once per process, not per event. */
-let missingKeyWarned = false;
-function warnMissingKeyOnce() {
-    if (missingKeyWarned)
-        return;
-    missingKeyWarned = true;
-    console.warn("memory-honcho: no API key (secrets 'api-key' or SIGRUN_EXT_MEMORY_HONCHO_API_KEY) — capturing to the outbox without delivery");
+/**
+ * The missing-API-key notice fires once per FACTORY INSTANCE, not per
+ * event. Factory-scoped (not module-global) so tests that create multiple
+ * instances in any order each see the warning.
+ */
+function createWarnMissingKeyOnce() {
+    let warned = false;
+    return () => {
+        if (warned)
+            return;
+        warned = true;
+        console.warn("memory-honcho: no API key (secrets 'api-key' or SIGRUN_EXT_MEMORY_HONCHO_API_KEY) — capturing to the outbox without delivery");
+    };
 }
 /**
  * Structural equality over the resolved settings (an engine rebuild is
@@ -62,10 +68,40 @@ function settingsEqual(a, b) {
         a.deliveredBatchWindow === b.deliveredBatchWindow &&
         a.anchorWindow === b.anchorWindow);
 }
+/**
+ * The leading-edge hook: a delivered conversation whose representation
+ * cache is ABSENT refreshes once (a present cache is fresh enough — the
+ * idle worker owns re-refreshes). The delivery engine calls the hook OUT
+ * of the conversation chain, so this refresh chains behind the delivery
+ * that just settled (never a circular wait). Failures log and are
+ * swallowed: a failed refresh must never fault the delivery it rode in on.
+ *
+ * Extracted for the composition test (T8 parked minor): the test uses the
+ * same factory instead of re-implementing the body verbatim.
+ */
+export function makeLeadingEdgeHook(opts) {
+    return {
+        onDelivered: async (conversationId) => {
+            const store = await opts.stores();
+            if (store.readRepresentationSync(conversationId) !== undefined)
+                return;
+            const ledger = store.readLedgerSync(conversationId);
+            if (ledger === undefined)
+                return;
+            try {
+                await refreshRepresentation(opts.client, store, opts.settings, conversationId, ledger.ownerAtFirstCapture);
+            }
+            catch (error) {
+                console.error(`memory-honcho: leading-edge representation refresh failed for conversation ${conversationId}`, error);
+            }
+        },
+    };
+}
 export function createHonchoMemory(host, deps = {}) {
     const settingsStore = host.stores.settings;
     const secretsStore = host.stores.secrets;
     const paths = host.stores.paths;
+    const warnMissingKeyOnce = createWarnMissingKeyOnce();
     // Lazily constructed on first use — settings/key are resolved at that
     // moment, so configuration written after boot still applies.
     let storesPromise;
@@ -127,22 +163,11 @@ export function createHonchoMemory(host, deps = {}) {
             // so this refresh chains behind the delivery that just settled
             // (never a circular wait). Failures log and are swallowed: a
             // failed refresh must never fault the delivery it rode in on.
-            const hooks = {
-                onDelivered: async (conversationId) => {
-                    const store = await stores();
-                    if (store.readRepresentationSync(conversationId) !== undefined)
-                        return;
-                    const ledger = store.readLedgerSync(conversationId);
-                    if (ledger === undefined)
-                        return;
-                    try {
-                        await refreshRepresentation(client, store, settings, conversationId, ledger.ownerAtFirstCapture);
-                    }
-                    catch (error) {
-                        console.error(`memory-honcho: leading-edge representation refresh failed for conversation ${conversationId}`, error);
-                    }
-                },
-            };
+            const hooks = makeLeadingEdgeHook({
+                stores,
+                client,
+                settings,
+            });
             return (deps.createEngine ?? ((c, st, s, h) => new DeliveryEngine(c, st, s, h)))(client, await stores(), settings, hooks);
         })();
         enginePromise = building;
@@ -284,11 +309,11 @@ export function createHonchoMemory(host, deps = {}) {
                                     // snapshot; skip quietly. `engineClient` is set
                                     // alongside the engine the `instanceof` check
                                     // just confirmed.
-                                    if (engineClient === undefined)
-                                        return;
-                                    const conversation = engineClient.for(String(conversationId));
-                                    if (conversation.hasSession()) {
-                                        await refreshRepresentation(engineClient, store, engineSettings, conversationId, ledger.ownerAtFirstCapture);
+                                    if (engineClient !== undefined) {
+                                        const conversation = engineClient.for(String(conversationId));
+                                        if (conversation.hasSession()) {
+                                            await refreshRepresentation(engineClient, store, engineSettings, conversationId, ledger.ownerAtFirstCapture);
+                                        }
                                     }
                                 }
                             }

package/dist/tools.js

@@ -19,6 +19,10 @@ const NO_MEMORY_TEXT = "No relevant memory found.";
 /** Wrap a Honcho failure with the extension's error prefix. */
 function honchoError(error) {
     const message = error instanceof Error ? error.message : String(error);
+    // Internal guard errors already carry the extension prefix; wrapping
+    // them again would nest it.
+    if (message.startsWith("memory-honcho: "))
+        return new Error(message);
     return new Error(`memory-honcho: Honcho unavailable (${message})`);
 }
 /** Build the three recall tools. */
@@ -38,11 +42,19 @@ export function createTools(deps) {
     async function userPeer(conversationId) {
         const owner = await resolveOwner(conversationId);
         await deps.engine().then((engine) => engine.establish(conversationId, owner));
+        return clientOrThrow().userPeerFor(owner);
+    }
+    /** The agent peer, after the client is guaranteed. */
+    async function agentPeer() {
+        return clientOrThrow().agentPeer();
+    }
+    /** The client, or a clean error (the factory wires a live accessor). */
+    function clientOrThrow() {
         const client = deps.client();
         if (client === undefined) {
             throw new Error("memory-honcho: client not initialized");
         }
-        return client.userPeerFor(owner);
+        return client;
     }
     /** Settings after the engine has resolved (guaranteed initialized). */
     function currentSettings() {
@@ -105,12 +117,8 @@ export function createTools(deps) {
             try {
                 const conversationId = Number(api.conversationId);
                 const targetPeer = await userPeer(conversationId);
-                const client = deps.client();
-                if (client === undefined) {
-                    throw new Error("memory-honcho: client not initialized");
-                }
-                const agentPeer = await client.agentPeer();
-                const answer = await agentPeer.chat(args.query, {
+                const agent = await agentPeer();
+                const answer = await agent.chat(args.query, {
                     target: targetPeer,
                     reasoningLevel: args.reasoningLevel ?? "low",
                 });
@@ -136,12 +144,8 @@ export function createTools(deps) {
             try {
                 const conversationId = Number(api.conversationId);
                 const targetPeer = await userPeer(conversationId);
-                const client = deps.client();
-                if (client === undefined) {
-                    throw new Error("memory-honcho: client not initialized");
-                }
-                const agentPeer = await client.agentPeer();
-                await agentPeer.conclusionsOf(targetPeer).create({
+                const agent = await agentPeer();
+                await agent.conclusionsOf(targetPeer).create({
                     content: args.content,
                 });
                 return {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sigrun/memory-honcho",
-	"version": "0.1.0",
+	"version": "0.1.2",
 	"description": "Honcho persistent-memory extension for sigrun (pi-durable)",
 	"type": "module",
 	"engines": {
@@ -55,4 +55,4 @@
 		"access": "public",
 		"provenance": true
 	}
-}
+}