poe-code 3.0.184 → 3.0.185

package/packages/memory/dist/query.js

@@ -0,0 +1,130 @@
+import * as fs from "node:fs/promises";
+import path from "node:path";
+import { countTokens } from "tokenfill";
+import { resolveAgent } from "@poe-code/poe-code-config";
+import { listPages } from "./pages.js";
+import { MEMORY_INDEX_RELPATH } from "./paths.js";
+export async function queryMemory(root, options) {
+    const pages = await listPages(root);
+    if (pages.length === 0) {
+        return {
+            answer: "",
+            citations: [],
+            tokensUsed: 0,
+            budget: options.budget,
+            exitCode: 0
+        };
+    }
+    const configOptions = {
+        fs: fs,
+        filePath: path.join(inferRepoRoot(root), "poe-code.json")
+    };
+    const agentId = (await resolveAgent(configOptions, options.agent ?? null)) ?? options.agent ?? "claude-code";
+    const context = await selectQueryContext(root, options.question, options.budget);
+    const spawnFn = options.spawnFn;
+    const result = (await spawnFn?.(agentId, context.prompt)) ?? {
+        answer: "",
+        citations: [],
+        tokensUsed: context.tokensUsed,
+        budget: options.budget,
+        exitCode: 0
+    };
+    return {
+        answer: result.answer,
+        citations: result.citations,
+        tokensUsed: result.tokensUsed,
+        budget: options.budget,
+        exitCode: result.exitCode
+    };
+}
+export async function selectQueryContext(root, question, budget) {
+    const [indexText, pages] = await Promise.all([
+        fs.readFile(path.join(root, MEMORY_INDEX_RELPATH), "utf8"),
+        listPages(root)
+    ]);
+    const indexTokens = countTokens(indexText);
+    if (indexTokens > budget) {
+        throw new Error(`budget too small; needs at least ${indexTokens} tokens`);
+    }
+    const rankedPages = rankPagesForQuery(pages, question);
+    const selectedPages = [];
+    let tokensUsed = indexTokens;
+    let truncated = false;
+    for (const page of rankedPages) {
+        const pageTokens = countTokens(renderPageContext(page));
+        if (tokensUsed + pageTokens > budget) {
+            truncated = true;
+            continue;
+        }
+        selectedPages.push(page);
+        tokensUsed += pageTokens;
+    }
+    return {
+        prompt: buildQueryPrompt(question, indexText, selectedPages),
+        selectedPages,
+        tokensUsed,
+        truncated
+    };
+}
+export function rankPagesForQuery(pages, question) {
+    const terms = tokenize(question);
+    const documents = pages.map((page) => {
+        const text = [page.relPath, page.frontmatter.name ?? "", page.frontmatter.description ?? "", page.body]
+            .join("\n")
+            .toLowerCase();
+        const tokens = tokenize(text);
+        const counts = new Map();
+        for (const token of tokens) {
+            counts.set(token, (counts.get(token) ?? 0) + 1);
+        }
+        return { page, counts, size: tokens.length };
+    });
+    const docFrequency = new Map();
+    for (const term of terms) {
+        let count = 0;
+        for (const document of documents) {
+            if ((document.counts.get(term) ?? 0) > 0) {
+                count += 1;
+            }
+        }
+        docFrequency.set(term, count);
+    }
+    return documents
+        .map((document) => ({
+        page: document.page,
+        score: terms.reduce((total, term) => {
+            const tf = (document.counts.get(term) ?? 0) / Math.max(document.size, 1);
+            const idf = Math.log((documents.length + 1) / ((docFrequency.get(term) ?? 0) + 1)) + 1;
+            return total + tf * idf;
+        }, 0)
+    }))
+        .sort((left, right) => right.score - left.score || left.page.relPath.localeCompare(right.page.relPath))
+        .map((entry) => entry.page);
+}
+function buildQueryPrompt(question, indexText, pages) {
+    const renderedPages = pages.map((page) => renderPageContext(page)).join("\n\n");
+    return [
+        "Answer using only the provided memory pages.",
+        "Cite pages and sections with [rel_path §section]. If memory does not answer the question, say so.",
+        "No tools are available.",
+        "",
+        `Question: ${question}`,
+        "",
+        "INDEX.md",
+        indexText,
+        "",
+        renderedPages
+    ].join("\n");
+}
+function renderPageContext(page) {
+    return [`FILE: ${page.relPath}`, page.body].join("\n");
+}
+function tokenize(text) {
+    return text
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((token) => token.length > 0);
+}
+function inferRepoRoot(root) {
+    return path.resolve(root, "..", "..");
+}

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

@@ -0,0 +1,9 @@
+import type { LogVerb, MemoryDiff, MemoryRoot, MemorySnapshot, SourceRef } from "./types.js";
+export declare function snapshot(root: MemoryRoot): Promise<MemorySnapshot>;
+export declare function reconcile(root: MemoryRoot, before: MemorySnapshot, _verb: LogVerb, detail: string): Promise<MemoryDiff>;
+export declare function renderIndex(entries: Array<{
+    relPath: string;
+    description: string;
+}>): string;
+export declare function appendLogEntries(root: MemoryRoot, diff: MemoryDiff, detail: string, timestamp?: string): Promise<void>;
+export declare function denormalizeSources(markdown: string): SourceRef[];

package/packages/memory/dist/reconcile.js

@@ -0,0 +1,138 @@
+import { createHash } from "node:crypto";
+import * as fs from "node:fs/promises";
+import path from "node:path";
+import { parseClaims } from "./confidence.js";
+import { parseFrontmatter, serializeFrontmatter, serializeSourceRef } from "./frontmatter.js";
+import { initMemory } from "./init.js";
+import { collectMarkdownRelPaths, listPages } from "./pages.js";
+import { MEMORY_INDEX_RELPATH, MEMORY_LOG_RELPATH, MEMORY_PAGES_DIR_RELPATH } from "./paths.js";
+export async function snapshot(root) {
+    const pages = Object.fromEntries(await Promise.all((await collectMarkdownRelPaths(root, MEMORY_PAGES_DIR_RELPATH)).map(async (relPath) => [
+        relPath,
+        hashContent(await fs.readFile(path.join(root, relPath), "utf8"))
+    ])));
+    return { pages };
+}
+export async function reconcile(root, before, _verb, detail) {
+    await initMemory(root);
+    const timestamp = new Date().toISOString();
+    const currentPages = await Promise.all((await collectMarkdownRelPaths(root, MEMORY_PAGES_DIR_RELPATH)).map(async (relPath) => {
+        const absPath = path.join(root, relPath);
+        const markdown = await fs.readFile(absPath, "utf8");
+        const parsed = parsePageMarkdown(relPath, markdown);
+        const normalizedFrontmatter = withDenormalizedSources(parsed.frontmatter, parsed.body);
+        const normalizedMarkdown = serializeFrontmatter(normalizedFrontmatter, parsed.body);
+        const changed = before.pages[relPath] !== hashContent(normalizedMarkdown);
+        const nextMarkdown = changed
+            ? serializeFrontmatter({
+                ...normalizedFrontmatter,
+                lastTouchedAt: timestamp
+            }, parsed.body)
+            : normalizedMarkdown;
+        return {
+            relPath,
+            changed,
+            currentMarkdown: markdown,
+            nextMarkdown
+        };
+    }));
+    await Promise.all(currentPages
+        .filter((page) => page.currentMarkdown !== page.nextMarkdown)
+        .map((page) => fs.writeFile(path.join(root, page.relPath), page.nextMarkdown, "utf8")));
+    const diff = diffSnapshots(before, await snapshot(root));
+    await writeIndex(root);
+    await appendLogEntries(root, diff, detail, timestamp);
+    return diff;
+}
+export function renderIndex(entries) {
+    if (entries.length === 0) {
+        return "# Memory index\n";
+    }
+    return [
+        "# Memory index",
+        "",
+        ...entries.map(({ relPath, description }) => {
+            const pageName = relPath.slice(`${MEMORY_PAGES_DIR_RELPATH}/`.length).replace(/\.md$/i, "");
+            return description.length === 0
+                ? `- [${pageName}](${relPath})`
+                : `- [${pageName}](${relPath}) — ${description}`;
+        }),
+        ""
+    ].join("\n");
+}
+export async function appendLogEntries(root, diff, detail, timestamp = new Date().toISOString()) {
+    const entries = [
+        ...diff.updated.map((relPath) => formatLogLine(timestamp, "update", relPath, detail)),
+        ...diff.deleted.map((relPath) => formatLogLine(timestamp, "delete", relPath, detail)),
+        ...diff.created.map((relPath) => formatLogLine(timestamp, "create", relPath, detail))
+    ];
+    if (entries.length === 0) {
+        return;
+    }
+    const logPath = path.join(root, MEMORY_LOG_RELPATH);
+    const existing = await fs.readFile(logPath, "utf8");
+    const separator = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
+    await fs.writeFile(logPath, `${existing}${separator}${entries.join("\n")}\n`, "utf8");
+}
+export function denormalizeSources(markdown) {
+    const seen = new Map();
+    for (const claim of parseClaims(parsePageMarkdown("inline-memory-page", markdown).body)) {
+        const source = "source" in claim.tag ? claim.tag.source : undefined;
+        if (source === undefined) {
+            continue;
+        }
+        seen.set(serializeSourceRef(source), source);
+    }
+    return Array.from(seen.entries())
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([, source]) => source);
+}
+async function writeIndex(root) {
+    const index = renderIndex((await listPages(root)).map((page) => ({
+        relPath: page.relPath,
+        description: page.frontmatter.description ?? ""
+    })));
+    await fs.writeFile(path.join(root, MEMORY_INDEX_RELPATH), index, "utf8");
+}
+function parsePageMarkdown(relPath, markdown) {
+    try {
+        return parseFrontmatter(markdown);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`Failed to parse frontmatter for "${relPath}": ${message}`);
+        return {
+            frontmatter: {},
+            body: markdown
+        };
+    }
+}
+function withDenormalizedSources(frontmatter, body) {
+    const sources = denormalizeSources(body);
+    return {
+        ...frontmatter,
+        ...(sources.length === 0 ? { sources: undefined } : { sources })
+    };
+}
+function diffSnapshots(before, after) {
+    const created = Object.keys(after.pages)
+        .filter((relPath) => before.pages[relPath] === undefined)
+        .sort((left, right) => left.localeCompare(right));
+    const updated = Object.keys(after.pages)
+        .filter((relPath) => before.pages[relPath] !== undefined && before.pages[relPath] !== after.pages[relPath])
+        .sort((left, right) => left.localeCompare(right));
+    const deleted = Object.keys(before.pages)
+        .filter((relPath) => after.pages[relPath] === undefined)
+        .sort((left, right) => left.localeCompare(right));
+    return {
+        created,
+        updated,
+        deleted
+    };
+}
+function formatLogLine(timestamp, verb, relPath, detail) {
+    return `- ${timestamp}  **${verb}** \`${relPath}\` — ${detail}`;
+}
+function hashContent(content) {
+    return createHash("sha256").update(content).digest("hex");
+}

package/packages/memory/dist/resolve-root.d.ts

@@ -0,0 +1,11 @@
+import type { FileSystem } from "../../config-mutations/dist/index.js";
+import type { MemoryRoot } from "./types.js";
+export declare const MEMORY_ROOT_ENV_VAR = "POE_CODE_MEMORY_ROOT";
+export interface ResolveConfiguredMemoryRootOptions {
+    cwd: string;
+    env: Record<string, string | undefined>;
+    fs: FileSystem;
+    configPath: string;
+    projectConfigPath?: string;
+}
+export declare function resolveConfiguredMemoryRoot(options: ResolveConfiguredMemoryRootOptions): Promise<MemoryRoot>;

package/packages/memory/dist/resolve-root.js

@@ -0,0 +1,22 @@
+import path from "node:path";
+import { configuredMemoryRoot } from "@poe-code/poe-code-config";
+import { resolveMemoryRoot } from "./paths.js";
+export const MEMORY_ROOT_ENV_VAR = "POE_CODE_MEMORY_ROOT";
+export async function resolveConfiguredMemoryRoot(options) {
+    const envOverride = options.env[MEMORY_ROOT_ENV_VAR]?.trim();
+    if (envOverride && envOverride.length > 0) {
+        return resolveAgainstCwd(options.cwd, envOverride);
+    }
+    const configOverride = (await configuredMemoryRoot({
+        fs: options.fs,
+        filePath: options.configPath,
+        projectFilePath: options.projectConfigPath
+    }))?.trim();
+    if (configOverride && configOverride.length > 0) {
+        return resolveAgainstCwd(options.cwd, configOverride);
+    }
+    return resolveMemoryRoot(options.cwd);
+}
+function resolveAgainstCwd(cwd, value) {
+    return path.isAbsolute(value) ? value : path.resolve(cwd, value);
+}

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

@@ -0,0 +1,2 @@
+import type { MemoryRoot, SearchHit } from "./types.js";
+export declare function searchMemory(root: MemoryRoot, query: string): Promise<SearchHit[]>;

package/packages/memory/dist/search.js

@@ -0,0 +1,29 @@
+import * as fs from "node:fs/promises";
+import path from "node:path";
+import { collectMarkdownRelPaths } from "./pages.js";
+export async function searchMemory(root, query) {
+    const normalizedQuery = query.trim();
+    if (normalizedQuery.length === 0) {
+        throw new Error("Search query cannot be empty.");
+    }
+    const relPaths = await collectMarkdownRelPaths(root);
+    const hits = [];
+    for (const relPath of relPaths) {
+        const content = await fs.readFile(path.join(root, relPath), "utf8");
+        if (content.length === 0) {
+            continue;
+        }
+        const lines = content.replaceAll("\r\n", "\n").split("\n");
+        for (const [index, line] of lines.entries()) {
+            if (!line.includes(normalizedQuery)) {
+                continue;
+            }
+            hits.push({
+                relPath,
+                lineNumber: index + 1,
+                line
+            });
+        }
+    }
+    return hits;
+}

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

@@ -0,0 +1,7 @@
+import type { MemoryRoot } from "./types.js";
+export declare function statusOf(root: MemoryRoot): Promise<{
+    pageCount: number;
+    totalBytes: number;
+    lastWriteAt: string | null;
+    initialized: boolean;
+}>;

package/packages/memory/dist/status.js

@@ -0,0 +1,46 @@
+import * as fs from "node:fs/promises";
+import path from "node:path";
+import { MEMORY_PAGES_DIR_RELPATH } from "./paths.js";
+import { collectMarkdownRelPaths } from "./pages.js";
+export async function statusOf(root) {
+    if (!(await pathExists(root))) {
+        return {
+            pageCount: 0,
+            totalBytes: 0,
+            lastWriteAt: null,
+            initialized: false
+        };
+    }
+    const [pageRelPaths, markdownRelPaths] = await Promise.all([
+        collectMarkdownRelPaths(root, MEMORY_PAGES_DIR_RELPATH),
+        collectMarkdownRelPaths(root)
+    ]);
+    let totalBytes = 0;
+    let lastWriteAtMs = Number.NEGATIVE_INFINITY;
+    for (const relPath of markdownRelPaths) {
+        const stat = await fs.stat(path.join(root, relPath));
+        totalBytes += stat.size;
+        lastWriteAtMs = Math.max(lastWriteAtMs, stat.mtimeMs);
+    }
+    return {
+        pageCount: pageRelPaths.length,
+        totalBytes,
+        lastWriteAt: Number.isFinite(lastWriteAtMs) ? new Date(lastWriteAtMs).toISOString() : null,
+        initialized: true
+    };
+}
+async function pathExists(targetPath) {
+    try {
+        await fs.stat(targetPath);
+        return true;
+    }
+    catch (error) {
+        if (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}

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

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

package/packages/memory/dist/tokens.js

@@ -0,0 +1,71 @@
+import * as fs from "node:fs/promises";
+import path from "node:path";
+import { countTokens } from "tokenfill";
+import { listPages } from "./pages.js";
+export async function computeTokenStats(root) {
+    if (!(await pathExists(root))) {
+        return {
+            memoryTokens: 0,
+            sourceTokens: 0,
+            reductionRatio: 0,
+            missingSources: []
+        };
+    }
+    const pages = await listPages(root);
+    let memoryTokens = 0;
+    const sourcePaths = new Set();
+    for (const page of pages) {
+        memoryTokens += countTokens(page.body);
+        for (const source of page.frontmatter.sources ?? []) {
+            const normalized = source.path.trim();
+            if (normalized.length > 0) {
+                sourcePaths.add(normalized);
+            }
+        }
+    }
+    const repoRoot = path.resolve(root, "..", "..");
+    let sourceTokens = 0;
+    const missingSources = [];
+    for (const sourcePath of sourcePaths) {
+        const absPath = path.isAbsolute(sourcePath)
+            ? sourcePath
+            : path.resolve(repoRoot, sourcePath);
+        try {
+            const content = await fs.readFile(absPath, "utf8");
+            sourceTokens += countTokens(content);
+        }
+        catch (error) {
+            if (isMissing(error)) {
+                missingSources.push(sourcePath);
+                continue;
+            }
+            throw error;
+        }
+    }
+    missingSources.sort((left, right) => left.localeCompare(right));
+    const reductionRatio = sourceTokens === 0 ? 0 : sourceTokens / Math.max(memoryTokens, 1);
+    return {
+        memoryTokens,
+        sourceTokens,
+        reductionRatio,
+        missingSources
+    };
+}
+async function pathExists(targetPath) {
+    try {
+        await fs.stat(targetPath);
+        return true;
+    }
+    catch (error) {
+        if (isMissing(error)) {
+            return false;
+        }
+        throw error;
+    }
+}
+function isMissing(error) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === "ENOENT");
+}

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

@@ -0,0 +1,155 @@
+export type MemoryRoot = string;
+export type PageFrontmatter = {
+    name?: string;
+    description?: string;
+    lastTouchedAt?: string;
+    sources?: SourceRef[];
+};
+export type SourceRef = {
+    path: string;
+    startLine?: number;
+    endLine?: number;
+};
+export type ConfidenceVerb = "extracted" | "inferred" | "ambiguous";
+export type ConfidenceTag = {
+    verb: "extracted";
+    source: SourceRef;
+    note?: string;
+} | {
+    verb: "inferred";
+    confidence: number;
+    source?: SourceRef;
+    note?: string;
+} | {
+    verb: "ambiguous";
+    reason: string;
+};
+export type TaggedClaim = {
+    tag: ConfidenceTag;
+    body: string;
+    lineNumber: number;
+};
+export type PageWithClaims = MemoryPage & {
+    claims: TaggedClaim[];
+};
+export type MemoryPage = {
+    relPath: string;
+    frontmatter: PageFrontmatter;
+    body: string;
+    bytes: number;
+    mtimeMs: number;
+};
+export type IndexEntry = {
+    relPath: string;
+    description: string;
+};
+export type LogVerb = "create" | "update" | "delete" | "ingest" | "lint";
+export type LogEntry = {
+    timestamp: string;
+    verb: LogVerb;
+    relPath?: string;
+    detail: string;
+};
+export type MemoryDiff = {
+    created: string[];
+    updated: string[];
+    deleted: string[];
+};
+export type MemorySnapshot = {
+    pages: Record<string, string>;
+};
+export type SearchHit = {
+    relPath: string;
+    lineNumber: number;
+    line: string;
+};
+export type IngestSource = {
+    kind: "file";
+    absPath: string;
+} | {
+    kind: "url";
+    url: string;
+};
+export type SpawnFn<TResult = unknown> = (agent: string, prompt: string) => Promise<TResult>;
+export type IngestOptions = {
+    source: IngestSource;
+    agent?: string;
+    reason?: string;
+    timeoutMs?: number;
+    dryRun?: boolean;
+    force?: boolean;
+    noCacheWrite?: boolean;
+    spawnFn?: SpawnFn;
+};
+export type LintOptions = {
+    fix?: boolean;
+    agent?: string;
+    timeoutMs?: number;
+    dryRun?: boolean;
+    spawnFn?: SpawnFn;
+};
+export type IngestResult = {
+    diff: MemoryDiff;
+    exitCode: number;
+    durationMs: number;
+    cacheHit: boolean;
+    tokens: TokenStats;
+};
+export type LintResult = {
+    diff: MemoryDiff;
+    issues: string[];
+    exitCode: number;
+    durationMs: number;
+    tokens: TokenStats;
+};
+export type IngestCacheKey = string;
+export type IngestCacheEntry = {
+    key: IngestCacheKey;
+    ingestedAt: string;
+    sourceLabel: string;
+    diff: MemoryDiff;
+    exitCode: number;
+    durationMs: number;
+    memoryTokens: number;
+    sourceTokens: number;
+    promptTemplateVersion: string;
+    agentId: string;
+};
+export type TokenStats = {
+    memoryTokens: number;
+    sourceTokens: number;
+    reductionRatio: number;
+    missingSources: string[];
+};
+export type McpServerOptions = {
+    root: MemoryRoot;
+    allowWrites: boolean;
+};
+export type MemoryInstallResult = {
+    skillInstalled: boolean;
+    mcpConfigured: boolean;
+    skillPath?: string;
+    mcpConfigPath?: string;
+};
+export type QueryOptions = {
+    question: string;
+    budget: number;
+    agent?: string;
+    spawnFn?: SpawnFn;
+};
+export type QueryCitation = {
+    relPath: string;
+    section?: string;
+    confidence: ConfidenceVerb;
+};
+export type QueryResult = {
+    answer: string;
+    citations: QueryCitation[];
+    tokensUsed: number;
+    budget: number;
+    exitCode: number;
+};
+export type ExplainResult = QueryResult & {
+    inboundPages: string[];
+    outboundSources: SourceRef[];
+};

package/packages/memory/dist/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,9 @@
+import type { MemoryDiff, MemoryRoot, PageFrontmatter } from "./types.js";
+export declare function writePage(root: MemoryRoot, relPath: string, body: string, opts: {
+    frontmatter?: PageFrontmatter;
+    reason: string;
+}): Promise<MemoryDiff>;
+export declare function appendToPage(root: MemoryRoot, relPath: string, content: string, opts: {
+    reason: string;
+}): Promise<MemoryDiff>;
+export declare function clearMemory(root: MemoryRoot): Promise<void>;