poe-code 3.0.183 → 3.0.185

package/packages/memory/dist/ingest.d.ts

@@ -0,0 +1,3 @@
+import type { IngestOptions, IngestResult, MemoryRoot } from "./types.js";
+export declare const INGEST_PROMPT_VERSION = "v1";
+export declare function ingest(root: MemoryRoot, opts: IngestOptions): Promise<IngestResult>;

package/packages/memory/dist/ingest.js

@@ -0,0 +1,118 @@
+import * as fs from "node:fs/promises";
+import path from "node:path";
+import { cacheEnabled, configuredTimeout, resolveAgent } from "@poe-code/poe-code-config";
+import { computeIngestKey, readCacheEntry, writeCacheEntry } from "./cache.js";
+import { MEMORY_INDEX_RELPATH } from "./paths.js";
+import { reconcile, snapshot } from "./reconcile.js";
+import { computeTokenStats } from "./tokens.js";
+export const INGEST_PROMPT_VERSION = "v1";
+export async function ingest(root, opts) {
+    const source = await materializeSource(opts.source);
+    const indexMdBytes = await fs.readFile(path.join(root, MEMORY_INDEX_RELPATH));
+    const configOptions = {
+        fs: fs,
+        filePath: path.join(inferRepoRoot(root), "poe-code.json")
+    };
+    const agentId = (await resolveAgent(configOptions, opts.agent ?? null)) ?? opts.agent ?? "claude-code";
+    const key = computeIngestKey({
+        sourceBytes: source.bytes,
+        indexMdBytes,
+        promptTemplateVersion: INGEST_PROMPT_VERSION,
+        agentId
+    });
+    if (!opts.force && (await cacheEnabled(configOptions))) {
+        const hit = await readCacheEntry(root, key);
+        if (hit !== null) {
+            return {
+                diff: { created: [], updated: [], deleted: [] },
+                exitCode: 0,
+                durationMs: 0,
+                cacheHit: true,
+                tokens: await computeTokenStats(root)
+            };
+        }
+    }
+    const prompt = buildIngestPrompt(root, source.label, source.text);
+    if (opts.dryRun) {
+        console.log(prompt);
+        return {
+            diff: { created: [], updated: [], deleted: [] },
+            exitCode: 0,
+            durationMs: 0,
+            cacheHit: false,
+            tokens: await computeTokenStats(root)
+        };
+    }
+    const before = await snapshot(root);
+    let exitCode = 1;
+    let durationMs = 0;
+    let timeoutError;
+    try {
+        const spawnFn = opts.spawnFn;
+        const result = await runWithTimeout(spawnFn?.(agentId, prompt) ?? Promise.resolve({ exitCode: 0, durationMs: 0 }), opts.timeoutMs ?? (await configuredTimeout(configOptions)));
+        exitCode = result.exitCode;
+        durationMs = result.durationMs;
+    }
+    catch (error) {
+        timeoutError = error instanceof Error ? error : new Error(String(error));
+    }
+    const diff = await reconcile(root, before, "ingest", opts.reason ?? `ingest ${source.label}`);
+    const tokens = await computeTokenStats(root);
+    if (timeoutError !== undefined) {
+        throw timeoutError;
+    }
+    if (!opts.noCacheWrite && (await cacheEnabled(configOptions)) && exitCode === 0) {
+        await writeCacheEntry(root, {
+            key,
+            ingestedAt: new Date().toISOString(),
+            sourceLabel: source.label,
+            diff,
+            exitCode,
+            durationMs,
+            memoryTokens: tokens.memoryTokens,
+            sourceTokens: tokens.sourceTokens,
+            promptTemplateVersion: INGEST_PROMPT_VERSION,
+            agentId
+        });
+    }
+    return { diff, exitCode, durationMs, cacheHit: false, tokens };
+}
+function buildIngestPrompt(root, sourceLabel, sourceText) {
+    return [
+        `Prompt version: ${INGEST_PROMPT_VERSION}`,
+        `Memory root: ${root}`,
+        `Source: ${sourceLabel}`,
+        "Update memory pages under pages/ only. Do not edit INDEX.md directly.",
+        "Add confidence tags to non-trivial claims.",
+        "",
+        sourceText
+    ].join("\n");
+}
+async function materializeSource(source) {
+    if (source.kind === "file") {
+        const bytes = await fs.readFile(source.absPath);
+        return {
+            label: source.absPath,
+            bytes,
+            text: bytes.toString("utf8")
+        };
+    }
+    throw new Error("URL ingest not implemented yet.");
+}
+function inferRepoRoot(root) {
+    return path.resolve(root, "..", "..");
+}
+async function runWithTimeout(promise, timeoutMs) {
+    return await new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error(`ingest timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}

package/packages/memory/dist/init.d.ts

@@ -0,0 +1,2 @@
+import type { MemoryRoot } from "./types.js";
+export declare function initMemory(root: MemoryRoot): Promise<void>;

package/packages/memory/dist/init.js

@@ -0,0 +1,24 @@
+import * as fs from "node:fs/promises";
+import path from "node:path";
+import { MEMORY_INDEX_RELPATH, MEMORY_LOG_RELPATH, MEMORY_PAGES_DIR_RELPATH } from "./paths.js";
+export async function initMemory(root) {
+    await fs.mkdir(path.join(root, MEMORY_PAGES_DIR_RELPATH), { recursive: true });
+    await writeFileIfMissing(path.join(root, MEMORY_INDEX_RELPATH), "# Memory index\n");
+    await writeFileIfMissing(path.join(root, MEMORY_LOG_RELPATH), "");
+}
+async function writeFileIfMissing(filePath, content) {
+    try {
+        await fs.writeFile(filePath, content, { encoding: "utf8", flag: "wx" });
+    }
+    catch (error) {
+        if (!hasErrorCode(error, "EEXIST")) {
+            throw error;
+        }
+    }
+}
+function hasErrorCode(error, code) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === code);
+}

package/packages/memory/dist/install.d.ts

@@ -0,0 +1,18 @@
+import type { ApplyOptions as McpApplyOptions } from "../../agent-mcp-config/dist/index.js";
+import type { FileSystem, MutationObservers } from "../../config-mutations/dist/index.js";
+import type { MemoryInstallResult } from "./types.js";
+export type MemoryInstallOptions = {
+    agent: string;
+    skillContent: string;
+    fs: FileSystem;
+    cwd: string;
+    homeDir: string;
+    platform: McpApplyOptions["platform"];
+    scope?: "local" | "global";
+    skillOnly?: boolean;
+    mcpOnly?: boolean;
+    allowWrites?: boolean;
+    dryRun?: boolean;
+    observers?: MutationObservers;
+};
+export declare function installMemory(options: MemoryInstallOptions): Promise<MemoryInstallResult>;

package/packages/memory/dist/install.js

@@ -0,0 +1,50 @@
+import { installSkill } from "@poe-code/agent-skill-config";
+import { configure } from "@poe-code/agent-mcp-config";
+const SKILL_NAME = "poe-code-memory";
+export async function installMemory(options) {
+    if (options.skillOnly && options.mcpOnly) {
+        throw new Error("--skill-only and --mcp-only cannot be combined.");
+    }
+    const scope = options.scope ?? "local";
+    let skillPath;
+    if (!options.mcpOnly) {
+        const installed = await installSkill(options.agent, {
+            name: SKILL_NAME,
+            content: options.skillContent
+        }, {
+            fs: options.fs,
+            cwd: options.cwd,
+            homeDir: options.homeDir,
+            scope,
+            dryRun: options.dryRun,
+            observers: options.observers
+        });
+        skillPath = installed.displayPath;
+    }
+    let mcpConfigPath;
+    if (!options.skillOnly) {
+        await configure(options.agent, {
+            name: SKILL_NAME,
+            config: {
+                transport: "stdio",
+                command: "poe-code",
+                args: options.allowWrites ? ["memory-mcp", "--allow-writes"] : ["memory-mcp"]
+            }
+        }, {
+            fs: options.fs,
+            homeDir: options.homeDir,
+            platform: options.platform,
+            dryRun: options.dryRun,
+            observers: options.observers
+        });
+        mcpConfigPath = options.agent === "codex"
+            ? `${options.homeDir}/.config/codex/mcp-config.json`
+            : `${options.homeDir}/.mcp.json`;
+    }
+    return {
+        skillInstalled: !options.mcpOnly,
+        mcpConfigured: !options.skillOnly,
+        skillPath,
+        mcpConfigPath
+    };
+}

package/packages/memory/dist/lock.d.ts

@@ -0,0 +1,19 @@
+import type { MemoryRoot } from "./types.js";
+interface LockFileSystem {
+    readFile(path: string, encoding: BufferEncoding): Promise<string>;
+    unlink(path: string): Promise<void>;
+    writeFile(path: string, data: string, options?: {
+        encoding?: BufferEncoding;
+        flag?: string;
+    }): Promise<void>;
+}
+export interface LockOptions {
+    fs?: LockFileSystem;
+    isPidRunning?: (pid: number) => boolean;
+    maxTimeoutMs?: number;
+    minTimeoutMs?: number;
+    pid?: number;
+    retries?: number;
+}
+export declare function withLock<TResult>(root: MemoryRoot, run: () => Promise<TResult> | TResult, options?: LockOptions): Promise<TResult>;
+export {};

package/packages/memory/dist/lock.js

@@ -0,0 +1,102 @@
+import * as fsPromises from "node:fs/promises";
+import path from "node:path";
+import { MEMORY_LOCK_RELPATH } from "./paths.js";
+function createDefaultFs() {
+    return {
+        readFile: (filePath, encoding) => fsPromises.readFile(filePath, encoding),
+        unlink: fsPromises.unlink,
+        writeFile: (filePath, data, options) => fsPromises.writeFile(filePath, data, options)
+    };
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function hasErrorCode(error, code) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === code);
+}
+function lockDelay(attempt, minTimeoutMs, maxTimeoutMs) {
+    return Math.min(maxTimeoutMs, minTimeoutMs * Math.pow(2, attempt));
+}
+function parsePid(input) {
+    const value = input.trim();
+    if (value.length === 0) {
+        return undefined;
+    }
+    for (const char of value) {
+        if (char < "0" || char > "9") {
+            return undefined;
+        }
+    }
+    const pid = Number.parseInt(value, 10);
+    return Number.isSafeInteger(pid) && pid > 0 ? pid : undefined;
+}
+function isPidRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return !hasErrorCode(error, "ESRCH");
+    }
+}
+async function removeLockFile(fs, lockPath) {
+    try {
+        await fs.unlink(lockPath);
+    }
+    catch (error) {
+        if (!hasErrorCode(error, "ENOENT")) {
+            throw error;
+        }
+    }
+}
+async function readLockPid(fs, lockPath) {
+    try {
+        return parsePid(await fs.readFile(lockPath, "utf8"));
+    }
+    catch (error) {
+        if (hasErrorCode(error, "ENOENT")) {
+            return null;
+        }
+        throw error;
+    }
+}
+export async function withLock(root, run, options = {}) {
+    const fs = options.fs ?? createDefaultFs();
+    const lockPath = path.join(root, MEMORY_LOCK_RELPATH);
+    const pid = options.pid ?? process.pid;
+    const retries = options.retries ?? 20;
+    const minTimeoutMs = options.minTimeoutMs ?? 25;
+    const maxTimeoutMs = options.maxTimeoutMs ?? 250;
+    const pidIsRunning = options.isPidRunning ?? isPidRunning;
+    for (let attempt = 0; attempt <= retries; attempt += 1) {
+        try {
+            await fs.writeFile(lockPath, `${pid}\n`, { encoding: "utf8", flag: "wx" });
+            try {
+                return await run();
+            }
+            finally {
+                await removeLockFile(fs, lockPath);
+            }
+        }
+        catch (error) {
+            if (!hasErrorCode(error, "EEXIST")) {
+                throw error;
+            }
+        }
+        const existingPid = await readLockPid(fs, lockPath);
+        if (existingPid === null) {
+            continue;
+        }
+        if (existingPid === undefined || !pidIsRunning(existingPid)) {
+            await removeLockFile(fs, lockPath);
+            continue;
+        }
+        if (attempt < retries) {
+            await sleep(lockDelay(attempt, minTimeoutMs, maxTimeoutMs));
+        }
+    }
+    throw new Error(`Failed to acquire memory lock at "${lockPath}".`);
+}

package/packages/memory/dist/mcp.d.ts

@@ -0,0 +1,7 @@
+import type { Server } from "../../tiny-stdio-mcp-server/dist/index.js";
+import type { McpServerOptions } from "./types.js";
+export declare function startMemoryMcpServer(opts: McpServerOptions): Promise<{
+    stop: () => Promise<void>;
+    server: Server;
+}>;
+export declare function printMcpConfig(): string;

package/packages/memory/dist/mcp.js

@@ -0,0 +1,58 @@
+import { createServer, defineSchema } from "tiny-stdio-mcp-server";
+import { appendToPage } from "./write.js";
+import { listPages, readPage } from "./pages.js";
+import { searchMemory } from "./search.js";
+import { statusOf } from "./status.js";
+export async function startMemoryMcpServer(opts) {
+    const server = createServer({
+        name: "poe-code-memory",
+        version: "0.0.1"
+    });
+    server.tool("list_pages", "List memory pages.", defineSchema({}), async () => ({
+        pages: (await listPages(opts.root)).map((page) => ({
+            rel_path: page.relPath,
+            description: page.frontmatter.description ?? ""
+        }))
+    }));
+    server.tool("read_page", "Read a memory page.", defineSchema({ rel_path: { type: "string" } }), async ({ rel_path }) => {
+        const page = await readPage(opts.root, rel_path);
+        return {
+            rel_path: page.relPath,
+            frontmatter: page.frontmatter,
+            body: page.body,
+            bytes: page.bytes
+        };
+    });
+    server.tool("search_memory", "Search memory pages.", defineSchema({
+        query: { type: "string" },
+        limit: { type: "number", optional: true }
+    }), async ({ query, limit }) => {
+        const hits = await searchMemory(opts.root, query);
+        return { hits: typeof limit === "number" ? hits.slice(0, limit) : hits };
+    });
+    server.tool("status", "Show memory status.", defineSchema({}), async () => statusOf(opts.root));
+    if (opts.allowWrites) {
+        server.tool("append_to_page", "Append content to a memory page.", defineSchema({
+            rel_path: { type: "string" },
+            content: { type: "string" },
+            reason: { type: "string" }
+        }), async ({ rel_path, content, reason }) => ({
+            diff: await appendToPage(opts.root, rel_path, content, { reason })
+        }));
+    }
+    return {
+        server,
+        stop: async () => { },
+    };
+}
+export function printMcpConfig() {
+    return JSON.stringify({
+        mcpServers: {
+            "poe-code-memory": {
+                type: "stdio",
+                command: "poe-code",
+                args: ["memory-mcp"]
+            }
+        }
+    }, null, 2);
+}

package/packages/memory/dist/pages.d.ts

@@ -0,0 +1,4 @@
+import type { MemoryPage, MemoryRoot } from "./types.js";
+export declare function listPages(root: MemoryRoot): Promise<MemoryPage[]>;
+export declare function readPage(root: MemoryRoot, relPath: string): Promise<MemoryPage>;
+export declare function collectMarkdownRelPaths(root: MemoryRoot, startRelPath?: string): Promise<string[]>;

package/packages/memory/dist/pages.js

@@ -0,0 +1,92 @@
+import * as fs from "node:fs/promises";
+import path from "node:path";
+import { parseFrontmatter } from "./frontmatter.js";
+import { assertSafeRelPath, MEMORY_CACHE_DIR_RELPATH, MEMORY_LOCK_RELPATH, MEMORY_PAGES_DIR_RELPATH } from "./paths.js";
+export async function listPages(root) {
+    const relPaths = await collectMarkdownRelPaths(root, MEMORY_PAGES_DIR_RELPATH);
+    const pages = await Promise.all(relPaths.map(async (relPath) => readPage(root, relPath)));
+    return pages.sort((left, right) => left.relPath.localeCompare(right.relPath));
+}
+export async function readPage(root, relPath) {
+    const normalizedRelPath = assertMarkdownRelPath(relPath);
+    const absPath = path.join(root, normalizedRelPath);
+    const [content, stat] = await Promise.all([fs.readFile(absPath, "utf8"), fs.stat(absPath)]);
+    try {
+        const parsed = parseFrontmatter(content);
+        return {
+            relPath: normalizedRelPath,
+            frontmatter: parsed.frontmatter,
+            body: parsed.body,
+            bytes: Buffer.byteLength(content),
+            mtimeMs: stat.mtimeMs
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`Failed to parse frontmatter for "${normalizedRelPath}": ${message}`);
+        return {
+            relPath: normalizedRelPath,
+            frontmatter: {},
+            body: content,
+            bytes: Buffer.byteLength(content),
+            mtimeMs: stat.mtimeMs
+        };
+    }
+}
+export async function collectMarkdownRelPaths(root, startRelPath = "") {
+    const relPaths = [];
+    await collectMarkdownRelPathsInto(root, startRelPath, relPaths);
+    return relPaths.sort((left, right) => left.localeCompare(right));
+}
+async function collectMarkdownRelPathsInto(root, currentRelPath, relPaths) {
+    const absPath = path.join(root, currentRelPath);
+    let entryNames;
+    try {
+        entryNames = await fs.readdir(absPath);
+    }
+    catch (error) {
+        if (isMissing(error)) {
+            return;
+        }
+        throw error;
+    }
+    for (const entryName of entryNames.sort((left, right) => left.localeCompare(right))) {
+        const entryRelPath = currentRelPath.length === 0 ? entryName : path.posix.join(currentRelPath, entryName);
+        const entryAbsPath = path.join(root, entryRelPath);
+        const entryStat = await fs.stat(entryAbsPath);
+        if (entryStat.isDirectory()) {
+            if (entryName === MEMORY_CACHE_DIR_RELPATH) {
+                continue;
+            }
+            await collectMarkdownRelPathsInto(root, entryRelPath, relPaths);
+            continue;
+        }
+        if (!entryStat.isFile()) {
+            continue;
+        }
+        if (!isMarkdownPath(entryRelPath)) {
+            if (entryName === MEMORY_LOCK_RELPATH) {
+                continue;
+            }
+            console.warn(`Skipping non-markdown memory file "${entryRelPath}".`);
+            continue;
+        }
+        relPaths.push(entryRelPath);
+    }
+}
+function assertMarkdownRelPath(relPath) {
+    const normalizedRelPath = assertSafeRelPath(relPath);
+    if (!isMarkdownPath(normalizedRelPath)) {
+        throw new Error(`Expected a markdown path, received "${relPath}".`);
+    }
+    return normalizedRelPath;
+}
+function isMarkdownPath(relPath) {
+    return path.posix.extname(relPath).toLowerCase() === ".md";
+}
+function isMissing(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}

package/packages/memory/dist/paths.d.ts

@@ -0,0 +1,12 @@
+import type { MemoryRoot } from "./types.js";
+export declare const MEMORY_INDEX_RELPATH = "INDEX.md";
+export declare const MEMORY_LOG_RELPATH = "LOG.md";
+export declare const MEMORY_LOCK_RELPATH = ".lock";
+export declare const MEMORY_PAGES_DIR_RELPATH = "pages";
+export declare const MEMORY_CACHE_DIR_RELPATH = ".cache";
+export declare const MEMORY_INGEST_CACHE_DIR_RELPATH = ".cache/ingest";
+export declare class MemoryPathError extends Error {
+    constructor(message: string);
+}
+export declare function resolveMemoryRoot(cwd: string): MemoryRoot;
+export declare function assertSafeRelPath(input: string): string;

package/packages/memory/dist/paths.js

@@ -0,0 +1,34 @@
+import path from "node:path";
+export const MEMORY_INDEX_RELPATH = "INDEX.md";
+export const MEMORY_LOG_RELPATH = "LOG.md";
+export const MEMORY_LOCK_RELPATH = ".lock";
+export const MEMORY_PAGES_DIR_RELPATH = "pages";
+export const MEMORY_CACHE_DIR_RELPATH = ".cache";
+export const MEMORY_INGEST_CACHE_DIR_RELPATH = `${MEMORY_CACHE_DIR_RELPATH}/ingest`;
+export class MemoryPathError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "MemoryPathError";
+    }
+}
+export function resolveMemoryRoot(cwd) {
+    return path.resolve(cwd, ".poe-code", "memory");
+}
+export function assertSafeRelPath(input) {
+    const trimmed = input.trim();
+    if (trimmed.length === 0) {
+        throw new MemoryPathError("Expected a non-empty relative path.");
+    }
+    const slashNormalized = trimmed.replaceAll("\\", "/");
+    if (path.posix.isAbsolute(slashNormalized) || path.win32.isAbsolute(slashNormalized)) {
+        throw new MemoryPathError(`Expected a relative path, received absolute path "${input}".`);
+    }
+    const normalized = path.posix.normalize(slashNormalized);
+    if (normalized === "." || normalized.length === 0) {
+        throw new MemoryPathError("Expected a relative path to a file or directory.");
+    }
+    if (normalized === ".." || normalized.startsWith("../")) {
+        throw new MemoryPathError(`Relative path "${input}" cannot escape the memory root.`);
+    }
+    return normalized;
+}

package/packages/memory/dist/query.d.ts

@@ -0,0 +1,10 @@
+import type { MemoryPage, MemoryRoot, QueryOptions, QueryResult } from "./types.js";
+export type QueryContext = {
+    prompt: string;
+    selectedPages: MemoryPage[];
+    tokensUsed: number;
+    truncated: boolean;
+};
+export declare function queryMemory(root: MemoryRoot, options: QueryOptions): Promise<QueryResult>;
+export declare function selectQueryContext(root: MemoryRoot, question: string, budget: number): Promise<QueryContext>;
+export declare function rankPagesForQuery(pages: MemoryPage[], question: string): MemoryPage[];