@codemem/pi-extension 0.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) CodeMem contributors
+
+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

@@ -0,0 +1,90 @@
+# @codemem/pi-extension
+
+Pi coding-agent extension for [codemem](https://github.com/kunickiaj/codemem): session ingest and turn-local memory injection.
+
+## Install
+
+```bash
+npm i -g codemem
+codemem setup
+```
+
+`codemem setup` auto-detects pi and appends `npm:@codemem/pi-extension@<version>` to `~/.pi/agent/settings.json` `packages`. Useful flags:
+
+| Flag | Purpose |
+| --- | --- |
+| `--pi-only` | Only configure pi |
+| `--pi-mcp` | Opt into MCP via third-party `pi-mcp-adapter` (writes `mcp.json` only when detected) |
+| `--pi-extension-path <path>` | Dev: write a local-path `packages` entry instead of the npm pin |
+
+Dev / local-path install (equivalent to `--pi-extension-path`):
+
+```json
+{
+  "packages": ["/absolute/path/to/codemem/packages/pi-extension"]
+}
+```
+
+Build first so `dist/index.js` exists (`pnpm --filter @codemem/pi-extension build`).
+
+**Uninstall:** remove the `@codemem/pi-extension` packages entry and restart pi. The shared memory store is left intact.
+
+## What it does
+
+- **Ingest** — captures pi session events (`session_start`/`session_shutdown`, user/assistant messages, tool calls/results) into codemem with `source: "pi"` via `POST /api/pi-hooks` (compat alias over the canonical ingest envelope), falling back to `codemem pi-hook-ingest` (spool when offline).
+- **Injection** — on `before_agent_start`, appends a `## codemem memories` block to the **turn-local** `systemPrompt` (never the persistent `message` channel).
+- **Tools** — registers the 14 `memory_*` tools natively (HTTP preferred, CLI fallback). Every HTTP operation first proves the viewer is target-aware (`GET /api/prompt-pack-profile` must report this process's `db_path` + `identity_target`) and re-sends the target on the query, so a foreign or stale older viewer on the port is never trusted (409 or unproven → targeted CLI path). Non-idempotent `memory_remember` does NOT CLI-replay on ambiguous HTTP failures (timeout/5xx/reset after send). No `pi-mcp-adapter` needed. Skipped when `pi.tools_mode` is `mcp-adapter`.
+- **Compaction** — pi-only observe-only boundary: `session_before_compact` flushes extraction; never returns a custom compaction summary.
+- **Fork/resume** — re-keys stream identity on every `session_start`; durable cursors via `pi.appendEntry`.
+- **Cross-agent** — one shared, project-scoped store. Memories from OpenCode/Claude/Codex inject into pi and the reverse.
+- **Dashboard** — pi rows appear in the source-agnostic feed/sessions/projects tabs with no extra setup.
+
+## Observer derivation (v1)
+
+Setup can fill unset `observer_*` keys from pi's API-key providers (cheap-model-first). Credentials stay in memory only and are never written to codemem config. OAuth-only installs get an explicit `unconfigured (oauth-only)` status — never a silent failure. Set `observer_provider` / `observer_model` explicitly when needed. Explicit `observer_*` config/env always wins.
+
+## Configuration
+
+Read from `~/.config/codemem/config.json` under the `pi` object, with `CODEMEM_PI_*` env overrides.
+
+| Key / env | Default | Meaning |
+| --- | --- | --- |
+| `pi.tools_mode` / `CODEMEM_PI_TOOLS_MODE` | `native` | `native` registers tools here; `mcp-adapter` skips native registration (use pi-mcp-adapter + `codemem mcp`) |
+| `pi.inject_prompts` / `CODEMEM_PI_INJECT_PROMPTS` | `true` | Append pack to system prompt on each turn |
+| `pi.file_context` / `CODEMEM_PI_FILE_CONTEXT` | `true` | Attach file-related memories when pi `read`s a tracked file |
+
+Shared viewer / inject knobs (same as other clients):
+
+| Env | Default | Meaning |
+| --- | --- | --- |
+| `CODEMEM_VIEWER_HOST` | `127.0.0.1` | Viewer host |
+| `CODEMEM_VIEWER_PORT` | `38888` | Viewer port |
+| `CODEMEM_VIEWER` | `1` | Enable viewer use |
+| `CODEMEM_VIEWER_AUTO` | `1` | Auto-start `codemem serve start` when needed |
+| `CODEMEM_RAW_EVENTS_BACKOFF_MS` | `10000` | Backoff after HTTP stream failure before retrying |
+| `CODEMEM_INJECT_LIMIT` | `8` | Pack item limit |
+| `CODEMEM_INJECT_TOKEN_BUDGET` | `800` | Pack token budget |
+| `CODEMEM_INJECT_MAX_CHARS` | `16000` | Max injection block chars |
+
+Example config:
+
+```json
+{
+  "pi": {
+    "tools_mode": "native",
+    "inject_prompts": true,
+    "file_context": true
+  }
+}
+```
+
+## Lifecycle
+
+Per pi extension rules: the factory only wires handlers. Viewer auto-start and other session resources begin on `session_start` and clean up idempotently on `session_shutdown`. Session state is re-keyed from `ctx.sessionManager.getSessionId()` on every `session_start`; durable ingest cursors persist via `pi.appendEntry`.
+
+## Peer dependencies
+
+- `@earendil-works/pi-coding-agent` (extension host)
+- `typebox` (tool parameter schemas)
+
+No `@codemem/core` or native modules load inside the pi process.

package/dist/client.d.ts

@@ -0,0 +1,99 @@
+/**
+ * PiCodememClient — HTTP preferred, CLI exec fallback.
+ * Never opens the store or imports @codemem/core.
+ */
+import type { PiExtensionConfig } from "./config.js";
+import { type ViewerRuntime } from "./viewer.js";
+/** pi AgentToolResult shape (content + required details). */
+export type ToolResultContent = {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    details: Record<string, unknown>;
+};
+export declare function textResult(text: string, details?: Record<string, unknown>): ToolResultContent;
+export declare function errorResult(message: string, details?: Record<string, unknown>): ToolResultContent;
+export declare function jsonResult(value: unknown): ToolResultContent;
+export declare function isToolErrorResult(result: ToolResultContent): boolean;
+export type IngestOutcome = {
+    ok: boolean;
+    via: "http" | "cli" | "skipped";
+    inserted?: number;
+    skipped?: number;
+};
+export type ExecCodememFn = (args: string[], opts?: {
+    stdin?: string;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    cwd?: string;
+}) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+/**
+ * Memory-pack fetch result. `preformatted` tells the caller whether `text` is
+ * already the full `## codemem memories` block (CLI pi-hook-inject) or bare
+ * pack text (HTTP /api/pack, CLI pack --json) that must be framed via
+ * formatPiInjectionBlock. Never sniff the memory text to decide framing.
+ */
+export type PackFetch = {
+    text: string;
+    preformatted: boolean;
+};
+/** CLI budget for pack/inject and file-context queries (was a 3s probe). */
+export declare const CLI_PACK_TIMEOUT_MS = 8000;
+/**
+ * Independent CLI budget for boundary flushes — a drain + LLM finish can
+ * exceed the short HTTP ingest timeout, so it must not reuse httpTimeoutMs.
+ */
+export declare const BOUNDARY_CLI_TIMEOUT_MS = 30000;
+export declare class PiCodememClient {
+    readonly config: PiExtensionConfig;
+    readonly runtime: ViewerRuntime;
+    cwd: string;
+    project: string | null;
+    sessionId: string | null;
+    /** Injectable for tests; defaults to spawning the codemem CLI. */
+    execImpl: ExecCodememFn | null;
+    constructor(config: PiExtensionConfig, runtime: ViewerRuntime, opts?: {
+        cwd?: string;
+        project?: string | null;
+        sessionId?: string | null;
+        execImpl?: ExecCodememFn | null;
+    });
+    rekey(sessionId: string, cwd: string, project: string | null): void;
+    ensureViewer(signal?: AbortSignal): Promise<boolean>;
+    /**
+     * POST /api/pi-hooks then CLI `codemem pi-hook-ingest` fallback.
+     * Honors stream backoff like the opencode plugin.
+     *
+     * Boundary events (`session_before_compact`, `session_shutdown`) always go
+     * through the CLI: HTTP can acknowledge a flush-only payload as
+     * `{inserted:0,skipped:1}` without ever running `flushRawEvents`. The CLI's
+     * `shouldForcePiBoundaryFlush` path performs the actual extraction flush
+     * (with spool fallback).
+     */
+    ingest(payload: Record<string, unknown>, signal?: AbortSignal): Promise<IngestOutcome>;
+    private tryHttpIngest;
+    private tryCliIngest;
+    /** Profile-proven POST /api/pack, then CLI pi-hook-inject / pack --json fallback. */
+    fetchPackText(context: string, signal?: AbortSignal): Promise<PackFetch>;
+    private tryHttpPack;
+    execCodemem(args: string[], opts?: {
+        stdin?: string;
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<{
+        stdout: string;
+        stderr: string;
+    }>;
+    /**
+     * Project label from the nearest Git root: walks up for a directory `.git`,
+     * or a `gitdir:` file (linked worktree) resolved back to the primary
+     * checkout. Mirrors `resolveProject` in packages/core/src/project.ts —
+     * implemented locally so the runtime never imports @codemem/core.
+     */
+    static projectFromCwd(cwd: string): string | null;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EASN,KAAK,aAAa,EAElB,MAAM,aAAa,CAAC;AAErB,6DAA6D;AAC7D,MAAM,MAAM,iBAAiB,GAAG;IAC/B,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC,CAAC;AAEF,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,iBAAiB,CAK7F;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,iBAAiB,CAKjG;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,iBAAiB,CAE5D;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAEpE;AAED,MAAM,MAAM,aAAa,GAAG;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ,GAAG,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG,CAC3B,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,KAC7E,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,OAAO,CAAC;CACtB,CAAC;AAOF,4EAA4E;AAC5E,eAAO,MAAM,mBAAmB,OAAQ,CAAC;AAEzC;;;GAGG;AACH,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAkB9C,qBAAa,eAAe;IAC3B,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,kEAAkE;IAClE,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IAE/B,YACC,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,aAAa,EACtB,IAAI,GAAE;QACL,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACxB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,QAAQ,CAAC,EAAE,aAAa,GAAG,IAAI,CAAC;KAC3B,EAQN;IAED,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAIlE;IAEK,YAAY,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC,CAEzD;IAED;;;;;;;;;OASG;IACG,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,CAmC3F;YAEa,aAAa;YAwCb,YAAY;IAgC1B,qFAAqF;IAC/E,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,SAAS,CAAC,CAqC7E;YAEa,WAAW;IAuBnB,WAAW,CAChB,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GACrE,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CA+C7C;IAED;;;;;OAKG;IACH,MAAM,CAAC,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAUhD;CACD"}

package/dist/config.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Pi extension config: ~/.config/codemem/config.json `pi.*` + CODEMEM_PI_* env.
+ *
+ * Thin client — does not import @codemem/core. Reads the JSON file directly.
+ */
+export type PiToolsMode = "native" | "mcp-adapter";
+export type PiExtensionConfig = {
+    toolsMode: PiToolsMode;
+    injectPrompts: boolean;
+    fileContext: boolean;
+    viewerHost: string;
+    viewerPort: number;
+    viewerEnabled: boolean;
+    viewerAutoStart: boolean;
+    rawEventsBackoffMs: number;
+    rawEventsStatusCheckMs: number;
+    injectLimit: number;
+    injectTokenBudget: number;
+    injectMaxChars: number;
+    httpTimeoutMs: number;
+};
+/**
+ * Load extension config. Safe to call from the factory (sync file read only).
+ */
+export declare function loadPiExtensionConfig(env?: NodeJS.ProcessEnv): PiExtensionConfig;
+/** Test helper: defaults without touching the filesystem. */
+export declare function defaultPiExtensionConfig(overrides?: Partial<PiExtensionConfig>): PiExtensionConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,aAAa,CAAC;AAEnD,MAAM,MAAM,iBAAiB,GAAG;IAC/B,SAAS,EAAE,WAAW,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,WAAW,EAAE,OAAO,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,OAAO,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;IACzB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,sBAAsB,EAAE,MAAM,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;CACtB,CAAC;AA2JF;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,iBAAiB,CAuC7F;AAED,6DAA6D;AAC7D,wBAAgB,wBAAwB,CACvC,SAAS,GAAE,OAAO,CAAC,iBAAiB,CAAM,GACxC,iBAAiB,CAEnB"}

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @codemem/pi-extension — pi coding-agent extension factory.
+ *
+ * Lifecycle (pi enforced):
+ *   - Factory body wires handlers only. No sockets/timers/watchers/child processes.
+ *   - Viewer auto-start begins on session_start (or first need).
+ *   - Idempotent cleanup on session_shutdown.
+ *   - Re-key session state from ctx.sessionManager.getSessionId() every session_start.
+ *   - Durable ingest cursors via pi.appendEntry.
+ *
+ * Surfaces:
+ *   - Ingest → POST /api/pi-hooks → CLI pi-hook-ingest
+ *   - Injection → before_agent_start systemPrompt append only (never message)
+ *   - Tools → pi.registerTool × 14 when pi.tools_mode === "native"
+ *   - session_before_compact → flush signal only (never return compaction)
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type ExecCodememFn } from "./client.js";
+/** @internal test helper — inject codemem CLI behavior without spawning. */
+export declare function __setTestExecImpl(fn: ExecCodememFn | null): void;
+/**
+ * Extension factory. Default export required by pi package loader.
+ */
+export default function codememPiExtension(pi: ExtensionAPI): void;
+export { errorResult, jsonResult, PiCodememClient, textResult } from "./client.js";
+export { defaultPiExtensionConfig, loadPiExtensionConfig } from "./config.js";
+export { MEMORY_LEARN_PAYLOAD } from "./learn.js";
+export { buildBeforeCompactPayload, buildMessageEndPayload, buildSessionShutdownPayload, buildSessionStartPayload, buildToolCallPayload, buildToolResultPayload, CODEMEM_MEMORIES_HEADER, extractMessageRole, extractMessageText, formatPiInjectionBlock, stableMessageEntryId, } from "./payloads.js";
+export { expectedToolNames, registerMemoryTools } from "./tools.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,OAAO,KAAK,EAEX,YAAY,EAQZ,MAAM,iCAAiC,CAAC;AACzC,OAAO,EAEN,KAAK,aAAa,EAIlB,MAAM,aAAa,CAAC;AAsBrB,4EAA4E;AAC5E,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,aAAa,GAAG,IAAI,GAAG,IAAI,CAEhE;AA0ZD;;GAEG;AACH,MAAM,CAAC,OAAO,UAAU,kBAAkB,CAAC,EAAE,EAAE,YAAY,GAAG,IAAI,CA2BjE;AA2CD,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEnF,OAAO,EAAE,wBAAwB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,EACN,yBAAyB,EACzB,sBAAsB,EACtB,2BAA2B,EAC3B,wBAAwB,EACxB,oBAAoB,EACpB,sBAAsB,EACtB,uBAAuB,EACvB,kBAAkB,EAClB,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,GACpB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC"}