@sigrun/memory-honcho 0.0.0-stage → 0.1.1

package/dist/tools.js

@@ -0,0 +1,157 @@
+/**
+ * The three recall tools: `honcho_search`, `honcho_chat`, `honcho_remember`.
+ *
+ * All three:
+ * - resolve the calling conversation's owner from `host.conversations.meta`
+ *   (memoized in-process per conversation; ownerless conversations → `"user"`);
+ * - await `engine.establish(conversationId, owner)` first (the spec's second
+ *   clone trigger — a rebuilt client re-establishes from the ledger);
+ * - convert Honcho failures to `memory-honcho: Honcho unavailable (<message>)`.
+ *
+ * `honcho_remember` passes NO `sessionId` in v1: a remembered fact is a
+ * user-level conclusion, matching the cross-conversation recall ruling.
+ * The README documents the visibility caveat.
+ */
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-durable";
+/** The no-memory text returned by search (empty) and chat (null). */
+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);
+    return new Error(`memory-honcho: Honcho unavailable (${message})`);
+}
+/** Build the three recall tools. */
+export function createTools(deps) {
+    // Per-conversation owner memo: the owner does not change mid-conversation.
+    const ownerMemo = new Map();
+    async function resolveOwner(conversationId) {
+        const memoized = ownerMemo.get(conversationId);
+        if (memoized !== undefined)
+            return memoized;
+        const meta = await deps.host.conversations.meta(conversationId);
+        const owner = meta.owner ?? "user";
+        ownerMemo.set(conversationId, owner);
+        return owner;
+    }
+    /** Establish the session, then resolve the user peer. */
+    async function userPeer(conversationId) {
+        const owner = await resolveOwner(conversationId);
+        await deps.engine().then((engine) => engine.establish(conversationId, owner));
+        const client = deps.client();
+        if (client === undefined) {
+            throw new Error("memory-honcho: client not initialized");
+        }
+        return client.userPeerFor(owner);
+    }
+    /** Settings after the engine has resolved (guaranteed initialized). */
+    function currentSettings() {
+        const settings = deps.settings();
+        if (settings === undefined) {
+            throw new Error("memory-honcho: settings not initialized");
+        }
+        return settings;
+    }
+    const search = defineTool({
+        name: "honcho_search",
+        description: "Search the user's Honcho memory for messages relevant to the query. " +
+            "Returns matching messages, sliced to the preview length, annotated with " +
+            "their source conversation id.",
+        parameters: Type.Object({
+            query: Type.String({ description: "The search query." }),
+        }),
+        async execute(args, api, _context) {
+            try {
+                // Resolve the engine first so settings are initialized.
+                await deps.engine();
+                const settings = currentSettings();
+                const peer = await userPeer(Number(api.conversationId));
+                const results = await peer.search(args.query, {
+                    limit: settings.searchLimit,
+                });
+                if (results.length === 0) {
+                    return { output: [{ type: "text", text: NO_MEMORY_TEXT }] };
+                }
+                const lines = results.map((message) => {
+                    const slice = message.content.slice(0, settings.toolPreviewLength);
+                    const conversationId = message.metadata?.conversationId;
+                    const annotation = typeof conversationId === "number" || typeof conversationId === "string"
+                        ? ` (conversation ${conversationId})`
+                        : "";
+                    return `[${message.peerId}] ${slice}${annotation}`;
+                });
+                return { output: [{ type: "text", text: lines.join("\n") }] };
+            }
+            catch (error) {
+                throw honchoError(error);
+            }
+        },
+    });
+    const chat = defineTool({
+        name: "honcho_chat",
+        description: "Ask the agent's Honcho representation of the user a natural-language " +
+            "question. Returns the answer, or the no-memory text when there is none.",
+        parameters: Type.Object({
+            query: Type.String({ description: "The question to ask." }),
+            reasoningLevel: Type.Optional(Type.Union([
+                Type.Literal("minimal"),
+                Type.Literal("low"),
+                Type.Literal("medium"),
+                Type.Literal("high"),
+                Type.Literal("max"),
+            ], { description: "Reasoning level for the query; default \"low\"." })),
+        }),
+        async execute(args, api, _context) {
+            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, {
+                    target: targetPeer,
+                    reasoningLevel: args.reasoningLevel ?? "low",
+                });
+                return {
+                    output: [
+                        { type: "text", text: answer ?? NO_MEMORY_TEXT },
+                    ],
+                };
+            }
+            catch (error) {
+                throw honchoError(error);
+            }
+        },
+    });
+    const remember = defineTool({
+        name: "honcho_remember",
+        description: "Record a fact about the user as a Honcho conclusion. " +
+            "The fact is user-level (cross-conversation), not conversation-scoped.",
+        parameters: Type.Object({
+            content: Type.String({ description: "The fact to remember." }),
+        }),
+        async execute(args, api, _context) {
+            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({
+                    content: args.content,
+                });
+                return {
+                    output: [{ type: "text", text: "Remembered." }],
+                };
+            }
+            catch (error) {
+                throw honchoError(error);
+            }
+        },
+    });
+    return [search, chat, remember];
+}

package/dist/types.d.ts

@@ -0,0 +1,139 @@
+/**
+ * The memory-seam contract restated structurally.
+ *
+ * `RunSettledEventLike` and `MemoryEventApiLike` mirror the host contract
+ * (sigrun `src/harness/event-bus.ts` / `src/extension.ts`) — declared
+ * structurally, with NO core runtime import, so this module compiles against
+ * the `@sigrun/sigrun` devDependency's types without pinning a release.
+ * The host passes real values; anything satisfying these shapes works.
+ */
+/**
+ * The settled-run event as the handler consumes it: ids as plain numbers
+ * (pi-durable ids are branded numbers — structurally identical), and the
+ * answered outcome's `answer` narrowed to the one member the capture path
+ * reads (`content` blocks with `type`/`text` — the real `AssistantMessage`
+ * satisfies this).
+ */
+export type RunSettledEventLike = {
+    readonly conversationId: number;
+    /** The conversation owner at delivery; absent when the conversation is ownerless. */
+    readonly owner?: string;
+    readonly inputs: readonly number[];
+    readonly inputTexts: readonly string[];
+    readonly outcome: {
+        readonly status: "answered";
+        readonly answerEntryId: number;
+        readonly answer: {
+            readonly content: readonly {
+                readonly type: string;
+                readonly text?: string;
+            }[];
+        };
+    } | {
+        readonly status: "unanswered";
+        readonly reason: string;
+    };
+};
+/**
+ * The narrowed read surface a `runSettled` handler receives (the host's
+ * `MemoryEventApi`). Only `document` is typed concretely here — Task 5's
+ * selection gate is the only consumer; `entry`/`entries` are declared as
+ * unknown-typed members so fakes can implement the full contract without
+ * restating pi-durable's query/page generics.
+ */
+export type MemoryEventApiLike = {
+    readonly entry: unknown;
+    readonly entries: unknown;
+    document<T>(token: unknown, conversationId: number, context: unknown): Promise<Readonly<T> | undefined>;
+};
+/** One message inside a capture batch: the peer side, the text, and the batch-level metadata. */
+export type OutboxEntry = {
+    readonly peer: "user" | "agent";
+    readonly text: string;
+    readonly metadata: {
+        readonly conversationId: number;
+        readonly submissionIds: readonly number[];
+        readonly batchId: string;
+        /** Present on user entries of UNANSWERED runs. */
+        readonly unanswered?: true;
+    };
+};
+/** One capture batch, JSONL-appended to `data/outbox/capture.jsonl`. */
+export type OutboxRecord = {
+    readonly type: "capture";
+    readonly conversationId: number;
+    /** The resolved owner for this capture (`"user"` when the conversation is ownerless). */
+    readonly owner: string;
+    /** The run's answer anchor; set only for answered runs. */
+    readonly answerEntryId?: number;
+    readonly entries: readonly OutboxEntry[];
+    readonly batchId: string;
+    readonly status: "pending" | "delivered";
+    readonly createdAt: number;
+};
+/** One fork-mapping anchor: the run's `answerEntryId` → the Honcho message id delivery returned. */
+export type LedgerAnchor = {
+    readonly entryId: number;
+    readonly messageId: string;
+};
+/**
+ * Per-conversation bookkeeping, `state/ledger/<conversationId>.json`:
+ * correctness-relevant but not user content. `deliveredBatchIds` and
+ * `anchors` are bounded windows (folded oldest-first on write).
+ */
+export type Ledger = {
+    readonly conversationId: number;
+    readonly honchoSessionId?: string;
+    readonly clonedFrom?: number;
+    /** Why a fresh session was started instead of a clone ("none-window" / "none-empty"). */
+    readonly inherit?: string;
+    /** The owner resolved at the conversation's first captured run. */
+    readonly ownerAtFirstCapture: string;
+    readonly deliveredBatchIds: string[];
+    readonly anchors: LedgerAnchor[];
+};
+/**
+ * `state/forks/pending/<childId>.json`: written by `conversationForked`,
+ * resolved on clone. Resolved records are kept (a `resolvedAt` stamp) so a
+ * late, duplicate establish never re-clones.
+ */
+export type PendingForkRecord = {
+    readonly childId: number;
+    readonly parentId: number;
+    /** The fork point (entry id in the parent). */
+    readonly at: number;
+    readonly createdAt: number;
+    readonly resolvedAt?: number;
+};
+/**
+ * The cached representation snapshot, `cache/representations/<conversationId>.json`
+ * (SDK field names normalized: `peerRepresentation` → `userProfile`,
+ * `summary.content` → `projectSummary`).
+ */
+export type RepresentationSnapshot = {
+    readonly userProfile: string | null;
+    readonly projectSummary: string | null;
+    readonly fetchedAt: number;
+};
+/**
+ * `state/last-delivery.json`: the persistent marker of the newest DELIVERY
+ * (`at` = the delivered record's `createdAt`). The sweeper drops delivered
+ * records every 15 minutes, so the status route cannot derive
+ * `lastDeliveryAt` from retained records in steady state — the delivery
+ * engine writes this marker when it flips a record, inside the same outbox
+ * critical section as the flip (stores.ts / status.ts).
+ */
+export type LastDeliveryMarker = {
+    readonly at: number;
+};
+/**
+ * The worker-run bookkeeping the factory records and the status route
+ * projects. The ONE declaration lives here: `src/index.ts` (writer) and
+ * `src/status.ts` (reader) both alias it, so the two sides cannot drift.
+ */
+export type WorkerRunStatus = {
+    runs: number;
+    startedAt?: number;
+    endedAt?: number;
+    lastError?: string;
+};

package/dist/types.js

@@ -0,0 +1,10 @@
+/**
+ * The memory-seam contract restated structurally.
+ *
+ * `RunSettledEventLike` and `MemoryEventApiLike` mirror the host contract
+ * (sigrun `src/harness/event-bus.ts` / `src/extension.ts`) — declared
+ * structurally, with NO core runtime import, so this module compiles against
+ * the `@sigrun/sigrun` devDependency's types without pinning a release.
+ * The host passes real values; anything satisfying these shapes works.
+ */
+export {};

package/package.json

@@ -1,6 +1,58 @@
 {
-  "name": "@sigrun/memory-honcho",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+	"name": "@sigrun/memory-honcho",
+	"version": "0.1.1",
+	"description": "Honcho persistent-memory extension for sigrun (pi-durable)",
+	"type": "module",
+	"engines": {
+		"node": ">=22.19.0"
+	},
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"CHANGELOG.md"
+	],
+	"scripts": {
+		"test": "node scripts/check-manifest.mjs --expect-name @sigrun/memory-honcho && vitest run",
+		"typecheck": "tsc --noEmit",
+		"build": "tsc -p tsconfig.build.json",
+		"prepare": "npm run build"
+	},
+	"dependencies": {
+		"@honcho-ai/sdk": "2.1.2"
+	},
+	"peerDependencies": {
+		"@earendil-works/chord": "1.3.0 || 1.4.0",
+		"@earendil-works/pi-ai": "1.3.0 || 1.4.0",
+		"@earendil-works/pi-durable": "1.3.0 || 1.4.0"
+	},
+	"devDependencies": {
+		"@earendil-works/chord": "1.4.0",
+		"@earendil-works/pi-ai": "1.4.0",
+		"@earendil-works/pi-durable": "1.4.0",
+		"@sigrun/sigrun": "0.3.0",
+		"@types/node": "^26.6.4",
+		"tsx": "^4.23.15",
+		"typescript": "^7.0.2",
+		"vitest": "^5.0.3"
+	},
+	"license": "MIT",
+	"repository": {
+		"type": "github",
+		"url": "git+https://github.com/sigrun-ai/sigrun-memory-honcho.git"
+	},
+	"bugs": {
+		"url": "https://github.com/sigrun-ai/sigrun-memory-honcho/issues"
+	},
+	"homepage": "https://github.com/sigrun-ai/sigrun-memory-honcho#readme",
+	"publishConfig": {
+		"access": "public",
+		"provenance": true
+	}
 }