pi-optchat 0.11.1 → 0.11.3

package/dist/durable/store.js

@@ -0,0 +1,167 @@
+import { isMime } from '../core/index.js';
+/** A Durable Object's SQLite refuses a row over 2 MB. A message's text is stored as JSON in parts of at most this many UTF-16 units,
+ * so a part is at most ~1.5 MB of UTF-8 however the text is written, and a huge pasted email still fits. */
+const PART = 512 * 1024;
+/** Log, tree and view rows carry their generation `g`: an import builds a new one beside the live one. `optchat_state` names the
+ * live one, the pending import's (`target`, NULL when none) and the last one handed out; the planned log is in `optchat_plan`.
+ * Images are shared. */
+const TABLES = `CREATE TABLE IF NOT EXISTS optchat_log (g INTEGER NOT NULL, i INTEGER NOT NULL, part INTEGER NOT NULL, meta TEXT, text TEXT NOT NULL, PRIMARY KEY (g, i, part));
+CREATE TABLE IF NOT EXISTS optchat_tree (g INTEGER NOT NULL, l INTEGER NOT NULL, i INTEGER NOT NULL, size INTEGER NOT NULL, text TEXT NOT NULL, PRIMARY KEY (g, l, i));
+CREATE TABLE IF NOT EXISTS optchat_view (g INTEGER PRIMARY KEY, json TEXT NOT NULL);
+CREATE TABLE IF NOT EXISTS optchat_images (name TEXT PRIMARY KEY, mime TEXT NOT NULL, data BLOB NOT NULL);
+CREATE TABLE IF NOT EXISTS optchat_state (id INTEGER PRIMARY KEY CHECK (id = 0), live INTEGER NOT NULL, last INTEGER NOT NULL DEFAULT 0, target INTEGER, mode TEXT, total INTEGER);
+CREATE TABLE IF NOT EXISTS optchat_plan (i INTEGER NOT NULL, part INTEGER NOT NULL, meta TEXT, text TEXT NOT NULL, PRIMARY KEY (i, part));
+INSERT OR IGNORE INTO optchat_state (id, live) VALUES (0, 0);`;
+/** Splits `text` every PART units, never between the two halves of a surrogate pair. */
+function parts(text) {
+    const result = [];
+    for (let at = 0; at < text.length;) {
+        let end = Math.min(text.length, at + PART);
+        if (end < text.length && /[\ud800-\udbff]/.test(text[end - 1]))
+            end--;
+        result.push(text.slice(at, end));
+        at = end;
+    }
+    return result;
+}
+/** An entry as rows of `(part, meta, text)`: its text as JSON in parts, its metadata on the first. */
+const rows = ({ text, ...meta }) => parts(JSON.stringify(text)).map((chunk, part) => [part, part ? null : JSON.stringify(meta), chunk]);
+/** Texts are stored as JSON, which keeps an unpaired surrogate that SQLite's TEXT would replace. A text that isn't there throws. */
+function texts(rows, what) {
+    const found = [...rows].map(row => typeof row.text === 'string' ? row.text : '');
+    if (!found.length)
+        throw new Error(`No ${what} in this store.`);
+    const text = JSON.parse(found.join(''));
+    if (typeof text !== 'string')
+        throw new Error(`Invalid ${what} in this store.`);
+    return text;
+}
+/** OptChat's memory in any Chord `SqliteDatabase`, such as Node's (`NodeSqliteDatabase`) or a Durable Object's. Give it the
+ * database Pi Durable's storage uses, so both share one queue: in a Durable Object, the `DurableObjectSqliteDatabase` over
+ * `ctx.storage` (direct `ctx.storage.sql` writes could be rolled back with a Pi transaction). `read` reads texts from the same
+ * database synchronously; it only reads rows whose writes have finished, so it needs no queue. Its tables are `optchat_*`, beside
+ * Pi's `pi_*`. Memory loads only metadata and node sizes; texts stay here. Messages are split so no row passes a Durable Object's
+ * 2 MB limit; images go to `images` when given, otherwise to `optchat_images`, one row each. */
+export class SqliteStore {
+    db;
+    read;
+    options;
+    #g = 0;
+    constructor(db, read, options = {}) {
+        this.db = db;
+        this.read = read;
+        this.options = options;
+    }
+    async load() {
+        await this.db.exec(TABLES);
+        if (this.options.generation !== undefined)
+            this.#g = this.options.generation;
+        else {
+            const state = await this.db.get('SELECT live, target FROM optchat_state');
+            this.#g = state?.live ?? 0;
+            // An old memory may still write to its generation until the object restarts after a switch, so old rows go only here.
+            await this.db.transaction(async (tx) => {
+                for (const table of ['log', 'tree', 'view'])
+                    await tx.run(`DELETE FROM optchat_${table} WHERE g NOT IN (?, ?)`, this.#g, state?.target ?? this.#g);
+            });
+        }
+        const log = await this.db.all('SELECT meta FROM optchat_log WHERE g = ? AND part = 0 ORDER BY i', this.#g);
+        const tree = await this.db.all('SELECT l, i, size FROM optchat_tree WHERE g = ?', this.#g);
+        const view = await this.db.get('SELECT json FROM optchat_view WHERE g = ?', this.#g);
+        return { entries: log.map(row => JSON.parse(row.meta)), tree, view: view?.json };
+    }
+    text(i) { return texts(this.read('SELECT text FROM optchat_log WHERE g = ? AND i = ? ORDER BY part', this.#g, i), `message ${i}`); }
+    summary({ l, i }) { return texts(this.read('SELECT text FROM optchat_tree WHERE g = ? AND l = ? AND i = ?', this.#g, l, i), `summary ${l}/${i}`); }
+    /** The primary key refuses a second message at an index, so a store that was not the last to append writes nothing. */
+    async append(entry) {
+        try {
+            await this.db.transaction(async (tx) => {
+                for (const row of rows(entry))
+                    await tx.run('INSERT INTO optchat_log (g, i, part, meta, text) VALUES (?, ?, ?, ?, ?)', this.#g, entry.i, ...row);
+            });
+        }
+        catch (error) {
+            if (await this.db.get('SELECT 1 FROM optchat_log WHERE g = ? AND i = ? AND part = 0', this.#g, entry.i))
+                throw new Error(`Someone else already saved message ${entry.i}; nothing was written.`, { cause: error });
+            throw error;
+        }
+    }
+    async appendNode(node) {
+        await this.db.run('INSERT OR REPLACE INTO optchat_tree (g, l, i, size, text) VALUES (?, ?, ?, ?, ?)', this.#g, node.l, node.i, node.size, JSON.stringify(node.text));
+    }
+    async saveView(view) {
+        await this.db.run('INSERT OR REPLACE INTO optchat_view (g, json) VALUES (?, ?)', this.#g, view);
+    }
+    async putImage(name, mimeType, data) {
+        if (this.options.images)
+            return this.options.images.putImage(name, mimeType, data);
+        await this.db.run('INSERT OR REPLACE INTO optchat_images (name, mime, data) VALUES (?, ?, ?)', name, mimeType, data);
+    }
+    async image(name) {
+        if (this.options.images)
+            return this.options.images.image(name);
+        const row = await this.db.get('SELECT mime, data FROM optchat_images WHERE name = ?', name);
+        return row && isMime(row.mime) ? { mimeType: row.mime, data: row.data } : undefined;
+    }
+}
+/** The rows `optchatImport` keeps: which generation is live, the pending import and its plan. */
+export function importTables(db, read) {
+    const state = async (tx = db) => {
+        await tx.exec(TABLES);
+        const row = await tx.get('SELECT live, target, mode, total FROM optchat_state');
+        const job = row?.target != null && row.mode && row.total != null ? { generation: row.target, mode: row.mode, total: row.total } : undefined;
+        return { live: row?.live ?? 0, job };
+    };
+    return {
+        state: () => state(),
+        /** Saves the plan, `entries` in order, made from generation `from`, and makes it the pending import of a new generation. A
+         * generation is never handed out twice, so a late call about a discarded one can't touch the next. Append's new generation starts with the live one's first `kept` messages, the nodes
+         * over them, and its view. Refused unless `from` is still live: an import went live since. */
+        stage: (from, mode, entries, kept) => db.transaction(async (tx) => {
+            const { live, job } = await state(tx);
+            if (job)
+                throw new Error('An import is pending: let it finish, or discard it.');
+            if (live !== from)
+                throw new Error('An import went live: restart before the next one.');
+            const generation = ((await tx.get('SELECT last FROM optchat_state'))?.last ?? live) + 1;
+            await tx.run('DELETE FROM optchat_plan');
+            let total = 0;
+            for (const entry of entries) {
+                total++;
+                for (const row of rows(entry))
+                    await tx.run('INSERT INTO optchat_plan (i, part, meta, text) VALUES (?, ?, ?, ?)', entry.i, ...row);
+            }
+            if (kept) {
+                // Nodes only over the messages copied: a message still being written isn't, and a node past the log would refuse to open.
+                // The view keeps its cached prefix; one that covers more than was copied is rebuilt.
+                await tx.run('INSERT INTO optchat_log (g, i, part, meta, text) SELECT ?, i, part, meta, text FROM optchat_log WHERE g = ? AND i < ?', generation, live, kept);
+                await tx.run(`INSERT INTO optchat_tree (g, l, i, size, text) SELECT ?, l, i, size, text FROM optchat_tree
+          WHERE g = ? AND ((i + 1) << l) <= (SELECT COUNT(*) FROM optchat_log WHERE g = ? AND part = 0)`, generation, live, generation);
+                await tx.run('INSERT INTO optchat_view (g, json) SELECT ?, json FROM optchat_view WHERE g = ?', generation, live);
+            }
+            await tx.run('UPDATE optchat_state SET last = ?, target = ?, mode = ?, total = ?', generation, generation, mode, total);
+            return { generation, mode, total };
+        }),
+        /** Planned message `i`, as saved; validated where it is used. */
+        planned(i) {
+            const [first] = read('SELECT meta FROM optchat_plan WHERE i = ? AND part = 0', i);
+            if (typeof first?.meta !== 'string')
+                throw new Error(`No planned message ${i} in this store.`);
+            return { ...JSON.parse(first.meta), text: texts(read('SELECT text FROM optchat_plan WHERE i = ? ORDER BY part', i), `planned message ${i}`) };
+        },
+        /** Makes `generation` live and drops its plan, in one transaction; refused if its import was discarded meanwhile. */
+        activate: (generation) => db.transaction(async (tx) => {
+            if ((await state(tx)).job?.generation !== generation)
+                throw new Error('The import was discarded.');
+            await tx.run('UPDATE optchat_state SET live = target, target = NULL, mode = NULL, total = NULL');
+            await tx.run('DELETE FROM optchat_plan');
+        }),
+        /** Drops the pending import if it is still `generation`'s; its rows go when the live store next loads. */
+        discard: (generation) => db.transaction(async (tx) => {
+            if ((await state(tx)).job?.generation !== generation)
+                return;
+            await tx.run('UPDATE optchat_state SET target = NULL, mode = NULL, total = NULL');
+            await tx.run('DELETE FROM optchat_plan');
+        }),
+    };
+}

package/docs/core.md

@@ -4,7 +4,7 @@
 
 Core imports nothing from Pi or Node at runtime: only `typebox` (the tools' schemas) and pi-ai's types. `test/core-boundary.test.ts` keeps it that way. Pi's packages are optional peer dependencies, so installing `pi-optchat` outside Pi pulls in none of them.
 
-It ships as TypeScript, like the extension, so the host needs a bundler (Wrangler, esbuild, tsx). A host that type-checks with `tsc` needs `allowImportingTsExtensions`.
+`pi-optchat/core` and `pi-optchat/durable` ship as compiled JavaScript with declarations, so a host needs no special tsconfig or bundler.
 
 ## What a host supplies
 

package/docs/durable.md

@@ -16,7 +16,7 @@ memoryExtension.attach(harness, context);
 
 With the Agents SDK's `PiHarness` this goes in its `harness` factory, which supplies `storage`, `context` and `onWake` and resumes the Harness when an alarm wakes the object. A host without it passes an `onWake` that arms an alarm, and calls `harness.resume()` on open and on each alarm, or a task owed from before an eviction never runs.
 
-`examples/durable-object` is a Worker built this way, importing `pi-optchat/core` and `pi-optchat/durable` as an app would (linked with `file:../..`), with the counters and endpoints its `proof.mjs` uses: it runs the Worker under `wrangler dev` with real model calls and checks a multi-turn chat, restarts and the cache.
+`examples/durable-object` is a Worker built this way, importing `pi-optchat/core` and `pi-optchat/durable` as an app would (linked with `file:../..`, so run `npm run build` in the repo first: the package's `./core` and `./durable` are the built `dist/`), with the counters and endpoints its `proof.mjs` uses: it runs the Worker under `wrangler dev` with real model calls and checks a multi-turn chat, restarts and the cache.
 
 ## How it works
 

package/package.json

@@ -1,11 +1,17 @@
 {
   "name": "pi-optchat",
-  "version": "0.11.1",
+  "version": "0.11.3",
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
-    "./core": "./src/core/index.ts",
-    "./durable": "./src/durable/index.ts",
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js"
+    },
+    "./durable": {
+      "types": "./dist/durable/index.d.ts",
+      "import": "./dist/durable/index.js"
+    },
     "./package.json": "./package.json"
   },
   "pi": {
@@ -16,10 +22,13 @@
   },
   "scripts": {
     "check": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
     "test": "tsx --import ./test/support.ts --test test/*.test.ts",
     "test:live": "tsx test/live.ts"
   },
   "devDependencies": {
+    "@cloudflare/workers-types": "^5.20261031.1",
     "@earendil-works/chord": "1.4.0",
     "@earendil-works/pi-agent-core": "1.4.0",
     "@earendil-works/pi-ai": "1.4.0",
@@ -80,6 +89,7 @@
   },
   "files": [
     "src",
+    "dist",
     "docs/*.md",
     "README.md",
     "LICENSE",

package/src/index.ts

@@ -47,7 +47,7 @@ async function printReply(text: string) {
     catch (error) { if (!record(error) || error.code !== 'EAGAIN') throw error; await new Promise(resolve => setTimeout(resolve, 10)); }
   }
 }
-interface Active { name: string; dir: string; config: ProfileConfig; memory: Memory; inbox: Inbox; children: Children; usage: UsageLedger; unlock: () => Promise<void> }
+interface Active { name: string; session: string; dir: string; config: ProfileConfig; memory: Memory; inbox: Inbox; children: Children; usage: UsageLedger; unlock: () => Promise<void> }
 
 /** OptChat's own version, read from the package.json beside src/ (in the checkout and the npm package alike); none if unreadable. */
 export const version = ((): string | undefined => {
@@ -73,6 +73,8 @@ export default function optchat(pi: ExtensionAPI) {
   let view: string | undefined;
   let prompt = '';
   let runStarted = false;
+  /** The run was started by a custom message (`sendMessage` with `triggerTurn` while idle): its first message is that input, shown or hidden. */
+  let wake = false;
   let fault: string | undefined;
   /** Reports not yet in memory. `count`: how many subagent reports the text joins. `batch`: held while the rest of that spawn runs, not sent yet.
    * `steered`: last sent into a running turn, where Esc or a dequeue can clear it from Pi's queue unseen. */
@@ -133,7 +135,12 @@ export default function optchat(pi: ExtensionAPI) {
   pi.on('thinking_level_select', (_event, ctx) => rememberMain(ctx));
   const restoreMain = async (ctx: ExtensionContext, { name, config: { main } }: Active) => {
     restored = undefined;
-    if (!main || pinnedModel || launch.models && !ctx.scopedModels.some(({ model }) => model.provider === main.provider && model.id === main.model)) return;
+    if (!main) {
+      // Nothing saved yet: record where Pi is, so later opens keep this model instead of following Pi's default.
+      if (!pinnedModel) rememberMain(ctx);
+      return;
+    }
+    if (pinnedModel || launch.models && !ctx.scopedModels.some(({ model }) => model.provider === main.provider && model.id === main.model)) return;
     const model = ctx.modelRegistry.find(main.provider, main.model), thinking = launch.thinking ?? main.thinking;
     restoring = true;
     try {
@@ -223,6 +230,10 @@ export default function optchat(pi: ExtensionAPI) {
   const openProfile = async (name: string, ctx: ExtensionContext) => {
     const dir = profilePath(name);
     if (!existsSync(dir)) throw new Error(`Profile ${name} does not exist. Use /optchat profile to create it.`);
+    // Pi's RPC mode binds extensions twice after new_session/switch_session/fork/clone (setRebindSession, then rebindSession()),
+    // so session_start can arrive again for the session this profile already serves. Taking the lock again would meet our own socket.
+    // Only the same session is kept: another session without a session_shutdown still fails loudly below.
+    if (active?.name === name && active.session === ctx.sessionManager.getSessionId()) { await restoreMain(ctx, active); status(ctx); return; }
     const unlock = await holdProfile(storeFor(dir), dir, name, `${name} · PID ${process.pid} · ${hostname()} · ${ctx.cwd}`, warning => ctx.ui.notify(warning, 'warning'));
     let openingMemory: Memory | undefined;
     try {
@@ -250,7 +261,7 @@ export default function optchat(pi: ExtensionAPI) {
         .filter(r => !loggedReports.has(reportReceipt(r.text)));
       atomicWrite(pending, JSON.stringify(reports));
       rememberProfile(name);
-      active = { name, dir, config, memory, inbox, children, usage, unlock }; fault = undefined; idle = () => ctx.isIdle();
+      active = { name, session: sessionId, dir, config, memory, inbox, children, usage, unlock }; fault = undefined; idle = () => ctx.isIdle();
       await restoreMain(ctx, active);
       if (ctx.mode === 'tui') unmountNavigation = mountNavigation(ctx, children, memory, shortcut, page => { void inspect(ctx, page); });
       // A one-shot run (`pi -p`, JSON) exits after its own prompt, which would end every conversation connected to it.
@@ -406,7 +417,7 @@ export default function optchat(pi: ExtensionAPI) {
   pi.on('before_agent_start', (event, ctx) => {
     if (!active) return; // Plain Pi run: leave Pi's own prompt untouched.
     const a = active;
-    flush(); run = []; logged = 0; keep = 0; view = undefined; runStarted = true;
+    flush(); run = []; logged = 0; keep = 0; view = undefined; runStarted = true; wake = event.messageType === 'custom';
     previous = a.config.previousExchange ? previousExchange(ctx.sessionManager.getBranch(), a.config.previousExchangeKB * 1000) : [];
     pi.appendEntry(RUN_BOUNDARY, { state: 'start' });
     // Pi's own prompt sections (AGENTS.md files, skills, cwd) stay; the profile's instructions go last.
@@ -420,7 +431,8 @@ export default function optchat(pi: ExtensionAPI) {
   pi.on('message_end', async (event, ctx) => {
     if (!active || !runStarted) return;
     const bounded = boundedMessage(event.message);
-    const message = asUser(bounded);
+    // Pi puts the message that starts a run first, before any context it or other extensions inject.
+    const message = asUser(bounded, wake); if (bounded.role !== 'system') wake = false;
     // Before the message is logged, so the image its text names is already there for zoom; zoom's own images are kept already.
     if (message.role === 'user' || message.role === 'toolResult' && message.toolName !== 'zoom') {
       try { await saveImages(active.memory.store, message.content); }

package/src/profiles.ts

@@ -13,7 +13,7 @@ export const isWindows = process.platform === 'win32';
 const PIPE_PREFIX = '\\\\.\\pipe\\';
 
 export const dataHome = () => resolve(process.env.OPTCHAT_HOME ?? join(homedir(), '.optchat'));
-/** `main` is the last model and thinking level picked in Pi while this profile was open; absent until one is picked. */
+/** `main` is the last model and thinking level picked in Pi while this profile was open, recorded on the first open too. */
 export interface ProfileConfig extends Settings { compactor: ModelChoice; subagent: ModelChoice; main?: ModelChoice }
 export const defaults: ProfileConfig = {
   compactor: { provider: 'anthropic', model: 'claude-sonnet-5-5', thinking: 'medium' },

package/src/transcript.ts

@@ -24,13 +24,13 @@ export function typedText(content: unknown) {
   const text = textContent(content, false);
   return { text, bare: text.replace(/\n\n\[Image[ :][^\n]*\](?:\n\[Image[ :][^\n]*\])*$/, '') };
 }
-/** Pi's convertToLlm sends every custom message to the model as a user message. A shown one is part of the chat, so it
- * becomes a user message here too; another extension's starts with "[customType] ", as the recipe marks background work, so
- * the compactor never takes it for the user's words. A hidden one (display false), such as context an extension injects
- * each turn, stays custom: the model still sees it, and memory and the replay leave it out. Reports reach the model and the
- * previous-exchange replay as user messages; memory logs them as `work`. */
-export function asUser(message: AgentMessage): AgentMessage {
-  if (message.role !== 'custom' || !message.display) return message;
+/** Pi's convertToLlm sends every custom message to the model as a user message. One that is shown, or that starts the run
+ * (`input`, shown or hidden), is part of the chat, so it becomes a user message here too; another extension's starts with
+ * "[customType] ", as the recipe marks background work, so the compactor never takes it for the user's words. Any other hidden
+ * one (display false), such as context an extension injects each turn, stays custom: the model still sees it, and memory and
+ * the replay leave it out. Reports reach the model and the previous-exchange replay as user messages; memory logs them as `work`. */
+export function asUser(message: AgentMessage, input = false): AgentMessage {
+  if (message.role !== 'custom' || !message.display && !input) return message;
   const { content, customType, timestamp } = message;
   if (customType === REPORT_TYPE) return { role: 'user', content, timestamp };
   const tag = `[${customType}] `;
@@ -57,7 +57,14 @@ export function previousExchange(branch: readonly SessionEntry[], limit = PREVIO
 function latestExchange(branch: readonly SessionEntry[]) {
   let end = -1;
   let legacyEnd = branch.length;
-  const messages = (entries: readonly SessionEntry[]) => entries.flatMap(entry => entry.type === 'message' ? [asUser(entry.message)] : entry.type === 'custom_message' ? [asUser({ role: 'custom', customType: entry.customType, content: entry.content, display: entry.display, timestamp: Date.parse(entry.timestamp) })] : []);
+  // A run's first message is its input, a hidden custom one too: Pi puts it before any context it or other extensions inject.
+  const messages = (entries: readonly SessionEntry[], run = false) => entries.flatMap(entry => {
+    const message: AgentMessage | undefined = entry.type === 'message' ? entry.message : entry.type === 'custom_message'
+      ? { role: 'custom', customType: entry.customType, content: entry.content, display: entry.display, timestamp: Date.parse(entry.timestamp) } : undefined;
+    if (!message) return [];
+    const input = run; if (message.role !== 'system') run = false;
+    return [asUser(message, input)];
+  });
   for (let i = branch.length - 1; i >= 0; i--) {
     const entry = branch[i];
     if (entry.type !== 'custom' || entry.customType !== RUN_BOUNDARY || !record(entry.data)) continue;
@@ -65,7 +72,7 @@ function latestExchange(branch: readonly SessionEntry[]) {
     if (entry.data.state === 'end') end = i;
     else if (entry.data.state === 'start') {
       if (end >= 0) {
-        const exchange = completedExchange(messages(branch.slice(i + 1, end)), imageRef);
+        const exchange = completedExchange(messages(branch.slice(i + 1, end), true), imageRef);
         if (exchange.length) return exchange;
       }
       end = -1;