@noopolis/daimon 0.1.0 → 0.1.2

package/dist/pi/cliSession.d.ts

@@ -0,0 +1,46 @@
+import type { ChildProcess } from "node:child_process";
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { PiSessionLike } from "./piAgentHandle.js";
+import type { PiSessionFactoryInput } from "./piHarness.js";
+export type CliEngineKind = "agy" | "codex" | "grok";
+export type CliEngineOptions = {
+    readonly commandArgs?: readonly string[];
+    readonly command?: string;
+    readonly maxToolTurns: number;
+    readonly onToolsMounted?: (tools: readonly ToolDefinition[]) => void;
+    readonly timeoutMs: number;
+    readonly redactedEnvironmentNames?: readonly string[];
+} & ({
+    readonly engine: "codex" | "grok";
+} | {
+    /** AGY has no MCP client. Selecting this state explicitly permits tool-free participation. */
+    readonly engine: "agy";
+    readonly toolAccess: "none";
+});
+type SessionInput = {
+    readonly cwd: string;
+    readonly customTools?: ToolDefinition[];
+    readonly daimonSecretEnvironmentNames?: readonly string[];
+};
+export declare const readChild: (child: ChildProcess, timeoutMs: number, secretValues: readonly string[]) => Promise<string>;
+export declare const renderCodexArgs: (options: Pick<CliEngineOptions, "commandArgs">, cwd: string, endpoint: string | undefined, sandbox?: string) => string[];
+export declare const spawnEngine: (options: CliEngineOptions, prompt: string, input: SessionInput, endpoint: string | undefined) => ChildProcess;
+export declare const createCliSessionFactory: (options: CliEngineOptions) => (input: PiSessionFactoryInput) => Promise<{
+    session: PiSessionLike;
+}>;
+export interface EngineRunResult {
+    readonly durationMs: number;
+    readonly outputChars: number;
+    readonly promptChars: number;
+    readonly text: string;
+}
+export declare const runEngineDetailed: (engine: CliEngineKind, prompt: string, paths: {
+    readonly workspacePath: string;
+    readonly runtimeHomePath?: string;
+}) => Promise<EngineRunResult>;
+export declare const runEngine: (engine: CliEngineKind, prompt: string, paths: {
+    readonly workspacePath: string;
+    readonly runtimeHomePath?: string;
+}) => Promise<string>;
+export {};
+//# sourceMappingURL=cliSession.d.ts.map

package/dist/pi/cliSession.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cliSession.d.ts","sourceRoot":"","sources":["../../src/pi/cliSession.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAItE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAC;AAG5D,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,OAAO,GAAG,MAAM,CAAC;AAErD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,WAAW,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,KAAK,IAAI,CAAC;IACrE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,wBAAwB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvD,GAAG,CAAC;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC;CACnC,GAAG;IACF,8FAA8F;IAC9F,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B,CAAC,CAAC;AAEH,KAAK,YAAY,GAAG;IAClB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,cAAc,EAAE,CAAC;IACxC,QAAQ,CAAC,4BAA4B,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3D,CAAC;AAgCF,eAAO,MAAM,SAAS,GAAI,OAAO,YAAY,EAAE,WAAW,MAAM,EAAE,cAAc,SAAS,MAAM,EAAE,KAAG,OAAO,CAAC,MAAM,CAyBhH,CAAC;AAiDH,eAAO,MAAM,eAAe,GAC1B,SAAS,IAAI,CAAC,gBAAgB,EAAE,aAAa,CAAC,EAC9C,KAAK,MAAM,EACX,UAAU,MAAM,GAAG,SAAS,EAC5B,UAAS,MAAiE,KACzE,MAAM,EACyC,CAAC;AAEnD,eAAO,MAAM,WAAW,GACtB,SAAS,gBAAgB,EACzB,QAAQ,MAAM,EACd,OAAO,YAAY,EACnB,UAAU,MAAM,GAAG,SAAS,KAC3B,YA2BF,CAAC;AAsEF,eAAO,MAAM,uBAAuB,GAAI,SAAS,gBAAgB,MAC/D,OAAO,qBAAqB,KAC3B,OAAO,CAAC;IAAE,OAAO,EAAE,aAAa,CAAA;CAAE,CASpC,CAAC;AAEF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,iBAAiB,GAC5B,QAAQ,aAAa,EACrB,QAAQ,MAAM,EACd,OAAO;IAAE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,KAC3E,OAAO,CAAC,eAAe,CAkBzB,CAAC;AAEF,eAAO,MAAM,SAAS,GACpB,QAAQ,aAAa,EACrB,QAAQ,MAAM,EACd,OAAO;IAAE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,KAC3E,OAAO,CAAC,MAAM,CAA0D,CAAC"}

package/dist/pi/cliSession.js

@@ -0,0 +1,224 @@
+import { randomUUID } from "node:crypto";
+import { createServer } from "node:http";
+import { spawn } from "node:child_process";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createPiToolMcpServer } from "../mcp/toolServer.js";
+import { redactTraceText } from "./turnTrace.js";
+const childEnvironment = (redactedNames) => {
+    const redacted = new Set(redactedNames);
+    return Object.fromEntries(Object.entries(process.env).filter(([name]) => !redacted.has(name)));
+};
+const childSecretValues = (redactedNames) => redactedNames
+    .map((name) => process.env[name])
+    .filter((value) => typeof value === "string" && value.length > 0);
+const redactChildOutput = (value, secretValues) => {
+    let redacted = redactTraceText(value);
+    for (const secret of secretValues)
+        redacted = redacted.split(secret).join("[REDACTED]");
+    return redacted;
+};
+const childDiagnostic = (stdout, stderr, secretValues) => {
+    const output = stderr.trim().length > 0 ? stderr : stdout;
+    const redacted = redactChildOutput(output, secretValues).trim();
+    return redacted.length > 0 ? `: ${redacted}` : "";
+};
+const terminate = (child) => {
+    if (!child.killed)
+        child.kill("SIGTERM");
+};
+export const readChild = (child, timeoutMs, secretValues) => new Promise((resolve, reject) => {
+    const stdout = [];
+    const stderr = [];
+    child.stdout?.on("data", (chunk) => stdout.push(chunk));
+    child.stderr?.on("data", (chunk) => stderr.push(chunk));
+    const timer = setTimeout(() => {
+        terminate(child);
+        reject(new Error("CLI engine timed out"));
+    }, timeoutMs);
+    child.once("error", (error) => {
+        clearTimeout(timer);
+        reject(error);
+    });
+    child.once("close", (code, signal) => {
+        clearTimeout(timer);
+        if (code === 0) {
+            resolve(Buffer.concat(stdout).toString("utf8").trim());
+        }
+        else {
+            reject(new Error(`CLI engine exited ${code ?? signal}${childDiagnostic(Buffer.concat(stdout).toString("utf8"), Buffer.concat(stderr).toString("utf8"), secretValues)}`));
+        }
+    });
+});
+const startMcp = async (tools, maxToolTurns, wakeDeadline, onToolsMounted) => {
+    onToolsMounted?.(tools);
+    const mcpServer = createPiToolMcpServer(tools, { maxToolTurns, wakeDeadline });
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID() });
+    await mcpServer.connect(transport);
+    const httpServer = createServer((request, response) => {
+        void transport.handleRequest(request, response);
+    });
+    try {
+        await new Promise((resolve, reject) => {
+            httpServer.once("error", reject);
+            httpServer.listen(0, "127.0.0.1", () => resolve());
+        });
+    }
+    catch (error) {
+        await transport.close().catch(() => undefined);
+        await mcpServer.close().catch(() => undefined);
+        throw error;
+    }
+    const address = httpServer.address();
+    if (address === null || typeof address === "string") {
+        await new Promise((resolve) => httpServer.close(() => resolve()));
+        await transport.close();
+        await mcpServer.close();
+        throw new Error("MCP server did not receive an ephemeral port");
+    }
+    const close = async () => {
+        await transport.close().catch(() => undefined);
+        await mcpServer.close().catch(() => undefined);
+        await new Promise((resolve) => httpServer.close(() => resolve()));
+    };
+    return { endpoint: `http://127.0.0.1:${address.port}/mcp`, close };
+};
+const addGrokServer = async (endpoint, cwd, env, command, commandArgs, secretValues) => {
+    const child = spawn(command, [...commandArgs, "mcp", "add", "--transport", "http", "--scope", "project", "daimon", endpoint], {
+        cwd,
+        env,
+        stdio: ["ignore", "pipe", "pipe"]
+    });
+    await readChild(child, 30_000, secretValues);
+};
+export const renderCodexArgs = (options, cwd, endpoint, sandbox = process.env.DAIMON_CODEX_SANDBOX ?? "danger-full-access") => [...(options.commandArgs ?? []), "exec", "--sandbox", sandbox, "--skip-git-repo-check", "--color", "never", "-C", cwd,
+    "-c", `mcp_servers.daimon.url=${endpoint}`, "-"];
+export const spawnEngine = (options, prompt, input, endpoint) => {
+    const command = options.command ?? options.engine;
+    const env = childEnvironment([
+        ...(options.redactedEnvironmentNames ?? []),
+        ...(input.daimonSecretEnvironmentNames ?? [])
+    ]);
+    if (options.engine === "codex") {
+        const args = renderCodexArgs(options, input.cwd, endpoint);
+        const child = spawn(command, args, { cwd: input.cwd, env, stdio: ["pipe", "pipe", "pipe"] });
+        child.stdin.on("error", () => undefined);
+        child.stdin.write(prompt);
+        child.stdin.end();
+        return child;
+    }
+    if (options.engine === "grok") {
+        return spawn(command, [...(options.commandArgs ?? []), "--single", prompt, "--max-turns", String(options.maxToolTurns), "--no-memory",
+            "--disable-web-search", "--cwd", input.cwd, "--output-format", "plain"], {
+            cwd: input.cwd,
+            env,
+            stdio: ["ignore", "pipe", "pipe"]
+        });
+    }
+    return spawn(command, [...(options.commandArgs ?? []), "--print", prompt, "--print-timeout", `${options.timeoutMs}ms`], {
+        cwd: input.cwd,
+        env,
+        stdio: ["ignore", "pipe", "pipe"]
+    });
+};
+class CliSession {
+    options;
+    input;
+    listeners = new Set();
+    disposed = false;
+    constructor(options, input) {
+        this.options = options;
+        this.input = input;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    async prompt(text) {
+        if (this.disposed)
+            throw new Error("CLI session is disposed");
+        const deadline = Date.now() + this.options.timeoutMs;
+        const secretValues = childSecretValues([
+            ...(this.options.redactedEnvironmentNames ?? []),
+            ...(this.input.daimonSecretEnvironmentNames ?? [])
+        ]);
+        const needsMcp = this.options.engine !== "agy";
+        const mount = needsMcp
+            ? await startMcp(this.input.customTools ?? [], this.options.maxToolTurns, deadline, this.options.onToolsMounted)
+            : undefined;
+        let child;
+        try {
+            if (this.options.engine === "grok" && mount !== undefined) {
+                await addGrokServer(mount.endpoint, this.input.cwd, childEnvironment([
+                    ...(this.options.redactedEnvironmentNames ?? []),
+                    ...(this.input.daimonSecretEnvironmentNames ?? [])
+                ]), this.options.command ?? "grok", this.options.commandArgs ?? [], secretValues);
+            }
+            child = spawnEngine(this.options, text, this.input, mount?.endpoint);
+            const output = await readChild(child, Math.max(1, deadline - Date.now()), secretValues);
+            for (const listener of this.listeners)
+                listener({
+                    type: "turn_end",
+                    message: {
+                        role: "assistant",
+                        content: [{ type: "text", text: output }],
+                        api: "openai-completions",
+                        provider: "openai",
+                        model: "cli",
+                        usage: {
+                            input: 0,
+                            output: 0,
+                            cacheRead: 0,
+                            cacheWrite: 0,
+                            totalTokens: 0,
+                            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 }
+                        },
+                        stopReason: "stop",
+                        timestamp: Date.now()
+                    },
+                    toolResults: []
+                });
+        }
+        finally {
+            if (child !== undefined)
+                terminate(child);
+            await mount?.close();
+        }
+    }
+    dispose() {
+        this.disposed = true;
+        this.listeners.clear();
+    }
+}
+export const createCliSessionFactory = (options) => async (input) => {
+    if (input.cwd === undefined)
+        throw new Error("CLI session cwd is required");
+    return {
+        session: new CliSession(options, {
+            cwd: input.cwd,
+            customTools: input.customTools,
+            daimonSecretEnvironmentNames: input.daimonSecretEnvironmentNames
+        })
+    };
+};
+export const runEngineDetailed = async (engine, prompt, paths) => {
+    const startedAt = Date.now();
+    const options = engine === "agy"
+        ? { engine, maxToolTurns: 1, timeoutMs: 180_000, toolAccess: "none" }
+        : { engine, maxToolTurns: 2, timeoutMs: 180_000 };
+    const session = new CliSession(options, { cwd: paths.workspacePath });
+    let text = "";
+    const unsubscribe = session.subscribe((event) => {
+        if (event.type !== "turn_end")
+            return;
+        if (!("content" in event.message))
+            return;
+        text = Array.isArray(event.message.content)
+            ? event.message.content.filter((entry) => entry.type === "text").map((entry) => entry.text).join("")
+            : event.message.content;
+    });
+    await session.prompt(prompt);
+    unsubscribe();
+    session.dispose();
+    return { durationMs: Date.now() - startedAt, outputChars: text.length, promptChars: prompt.length, text };
+};
+export const runEngine = async (engine, prompt, paths) => (await runEngineDetailed(engine, prompt, paths)).text;

package/dist/pi/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./auth.js";
+export * from "./cliSession.js";
+export * from "./modelConfig.js";
+export * from "./piAgentHandle.js";
+export * from "./piHarness.js";
+export * from "./rawTrainingCapture.js";
+export * from "./turnCausal.js";
+export * from "./worldTools.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/pi/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/pi/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,yBAAyB,CAAC;AACxC,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC"}

package/dist/pi/index.js

@@ -0,0 +1,8 @@
+export * from "./auth.js";
+export * from "./cliSession.js";
+export * from "./modelConfig.js";
+export * from "./piAgentHandle.js";
+export * from "./piHarness.js";
+export * from "./rawTrainingCapture.js";
+export * from "./turnCausal.js";
+export * from "./worldTools.js";

package/dist/pi/memoryTools.d.ts

@@ -0,0 +1,69 @@
+import { Type } from "@earendil-works/pi-ai";
+import { type ToolDefinition } from "@earendil-works/pi-coding-agent";
+import type { MemoryPrepareTurnResult, MemoryRuntime, MemoryToolExecutionContext, MemoryWakeMode } from "@noopolis/mneme";
+export interface PiMemoryToolContextRef {
+    current?: MemoryToolExecutionContext;
+    observeTool?: (event: PiMemoryToolTraceEvent) => void;
+}
+export interface PiMemoryToolTraceEvent {
+    contentCount?: number;
+    decision?: string;
+    durationMs: number;
+    error?: string;
+    kind: "memory";
+    name: string;
+    redactionCount?: number;
+    status: "completed" | "failed";
+}
+interface PiMemoryToolInput {
+    agentId: string;
+    memory: MemoryRuntime;
+    contextRef: PiMemoryToolContextRef;
+    mode?: MemoryWakeMode;
+}
+type PiMemoryTool = ToolDefinition<any, unknown>;
+export declare const createTrustedPiMemoryToolContext: (input: {
+    agentId: string;
+    memory: MemoryRuntime;
+    mode: MemoryWakeMode;
+    prepared: MemoryPrepareTurnResult;
+    threadId: string;
+    wakeId: string;
+}) => MemoryToolExecutionContext;
+export declare function canonicalToolFieldNames(name: string, representation?: unknown): string[];
+export declare const MEMORY_TOOL_ARGUMENT_FIELDS: Readonly<Record<string, ReadonlySet<string>>>;
+export declare const schemaFor: (name: string) => Type.TObject<{
+    scope: Type.TString;
+    query: Type.TString;
+    limit: Type.TOptional<Type.TNumber>;
+}> | Type.TObject<{
+    query: Type.TString;
+    limit: Type.TOptional<Type.TNumber>;
+    active_scope: Type.TOptional<Type.TString>;
+}> | Type.TObject<{
+    scope: Type.TString;
+    kind: Type.TString;
+    content: Type.TObject<{
+        kind: Type.TString;
+    }>;
+    visibility: Type.TString;
+    sensitivity: Type.TString;
+    source_type: Type.TString;
+    confidence: Type.TOptional<Type.TNumber>;
+    memory_id: Type.TOptional<Type.TString>;
+}> | Type.TObject<{
+    scope: Type.TString;
+    horizon: Type.TOptional<Type.TNumber>;
+}> | Type.TObject<{
+    scope: Type.TString;
+    memory_id: Type.TString;
+    reason: Type.TOptional<Type.TString>;
+}> | Type.TObject<{
+    scope: Type.TString;
+    event_ids: Type.TArray<Type.TString>;
+    reason: Type.TOptional<Type.TString>;
+}>;
+export declare const createPiMemoryTools: (input: PiMemoryToolInput) => PiMemoryTool[];
+export declare const piMemoryToolNames: (tools: PiMemoryTool[]) => string[];
+export {};
+//# sourceMappingURL=memoryTools.d.ts.map

package/dist/pi/memoryTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoryTools.d.ts","sourceRoot":"","sources":["../../src/pi/memoryTools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAC7C,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAQlF,OAAO,KAAK,EAEV,uBAAuB,EACvB,aAAa,EACb,0BAA0B,EAE1B,cAAc,EACf,MAAM,iBAAiB,CAAC;AAEzB,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,EAAE,0BAA0B,CAAC;IACrC,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,sBAAsB,KAAK,IAAI,CAAC;CACvD;AAED,MAAM,WAAW,sBAAsB;IACrC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,QAAQ,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,WAAW,GAAG,QAAQ,CAAC;CAChC;AAED,UAAU,iBAAiB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,aAAa,CAAC;IACtB,UAAU,EAAE,sBAAsB,CAAC;IACnC,IAAI,CAAC,EAAE,cAAc,CAAC;CACvB;AAED,KAAK,YAAY,GAAG,cAAc,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;AAyCjD,eAAO,MAAM,gCAAgC,GAAI,OAAO;IACtD,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,aAAa,CAAC;IACtB,IAAI,EAAE,cAAc,CAAC;IACrB,QAAQ,EAAE,uBAAuB,CAAC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB,KAAG,0BAqBH,CAAC;AAqBF,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,OAAO,GAAG,MAAM,EAAE,CAaxF;AAED,eAAO,MAAM,2BAA2B,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAInF,CAAC;AAqBJ,eAAO,MAAM,SAAS,GAAI,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgDrC,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAAI,OAAO,iBAAiB,KAAG,YAAY,EAuCxE,CAAC;AAEJ,eAAO,MAAM,iBAAiB,GAAI,OAAO,YAAY,EAAE,KAAG,MAAM,EAChC,CAAC"}

package/dist/pi/memoryTools.js

@@ -0,0 +1,190 @@
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { canonicalScopeKey, createMemoryToolDescriptors, memoryScopeId, schemaForModelToolName } from "@noopolis/mneme";
+const MAX_ALLOWED_SCOPES = 32;
+const MEMORY_PRINCIPAL_SCOPES = new Set([
+    "artifact",
+    "global",
+    "pair",
+    "role",
+    "room",
+    "task",
+    "team"
+]);
+const trustedAllowedScopes = (agentId, prepared) => {
+    if (!Array.isArray(prepared.allowedScopes)
+        || prepared.allowedScopes.length === 0
+        || prepared.allowedScopes.length > MAX_ALLOWED_SCOPES) {
+        throw new Error("prepared memory turn requires a bounded finite scope set");
+    }
+    const scopes = prepared.allowedScopes.map((scope) => {
+        if (typeof scope !== "string" || scope !== canonicalScopeKey(scope)
+            || scope.length > 512 || /[\u0000-\u001f\u007f]/u.test(scope)) {
+            throw new Error("prepared memory turn contains an invalid scope");
+        }
+        return scope;
+    });
+    const agentPrefix = canonicalScopeKey(`agent:${agentId}/scope:`);
+    if (new Set(scopes).size !== scopes.length || scopes.some((scope) => !scope.startsWith(agentPrefix))) {
+        throw new Error("prepared memory turn contains a foreign or duplicate scope");
+    }
+    const activeScope = canonicalScopeKey(memoryScopeId(prepared.principal));
+    if (!scopes.includes(activeScope)) {
+        throw new Error("prepared memory turn omits its active principal scope");
+    }
+    return Object.freeze([...scopes]);
+};
+export const createTrustedPiMemoryToolContext = (input) => {
+    if (input.prepared.principal.agentId !== input.agentId
+        || input.memory.authority.bankId !== input.agentId) {
+        throw new Error("prepared memory authority does not match the Pi agent");
+    }
+    if (!MEMORY_PRINCIPAL_SCOPES.has(input.prepared.principal.scope)) {
+        throw new Error("prepared memory turn contains an invalid principal scope");
+    }
+    const principal = Object.freeze({ ...input.prepared.principal });
+    const activeScope = canonicalScopeKey(memoryScopeId(principal));
+    return Object.freeze({
+        allowedScopes: trustedAllowedScopes(input.agentId, input.prepared),
+        audienceKey: activeScope,
+        authority: input.memory.authority,
+        conversationScope: activeScope,
+        mode: input.mode,
+        principal,
+        threadId: input.threadId,
+        transport: "in_process",
+        wakeId: input.wakeId
+    });
+};
+const requireTrustedContext = (agentId, contextRef) => {
+    const context = contextRef.current;
+    if (context === undefined
+        || context.principal.agentId !== agentId
+        || context.authority?.bankId !== agentId
+        || !Array.isArray(context.allowedScopes)) {
+        throw new Error("Pi memory tool requires the active trusted turn context");
+    }
+    return context;
+};
+const textContent = (result) => ({
+    content: [{ type: "text", text: JSON.stringify(result) }],
+    details: result
+});
+export function canonicalToolFieldNames(name, representation) {
+    const source = arguments.length >= 2 ? representation : schemaForModelToolName(name);
+    if (source !== null && typeof source === "object") {
+        const candidate = source;
+        const fields = candidate.shape !== undefined ? candidate.shape : source;
+        if (fields !== null && typeof fields === "object" && !Array.isArray(fields)) {
+            const names = Object.keys(fields);
+            if (names.length > 0) {
+                return names;
+            }
+        }
+    }
+    throw new Error(`@noopolis/mneme returned no usable field contract for memory tool ${name}`);
+}
+export const MEMORY_TOOL_ARGUMENT_FIELDS = Object.fromEntries(createMemoryToolDescriptors({}, { mode: "dream" })
+    .map(({ modelName }) => [modelName, new Set(canonicalToolFieldNames(modelName))]));
+const requireExactModelArguments = (toolName, params) => {
+    if (typeof params !== "object" || params === null || Array.isArray(params)) {
+        throw new Error("Pi memory tool arguments must be an object");
+    }
+    const allowed = MEMORY_TOOL_ARGUMENT_FIELDS[toolName];
+    if (allowed === undefined) {
+        throw new Error(`Pi memory tool ${toolName} has no argument contract`);
+    }
+    for (const field of Reflect.ownKeys(params)) {
+        if (typeof field !== "string" || !allowed.has(field)) {
+            throw new Error(`Pi memory tool ${toolName} received unexpected top-level argument ${String(field)}`);
+        }
+    }
+};
+const contentSchema = Type.Object({
+    kind: Type.String({ description: "Memory content kind: text, claim, decision, artifact, or relationship." })
+}, { additionalProperties: true });
+export const schemaFor = (name) => {
+    if (name === "memory_search") {
+        return Type.Object({
+            scope: Type.String({ description: "Scope alias or canonical scope id. Use current, global, or all when appropriate." }),
+            query: Type.String({ description: "Search query." }),
+            limit: Type.Optional(Type.Number({ description: "Maximum result count." }))
+        }, { additionalProperties: false });
+    }
+    if (name === "memory_locate") {
+        return Type.Object({
+            query: Type.String({ description: "What to locate in memory." }),
+            limit: Type.Optional(Type.Number({ description: "Maximum candidate count." })),
+            active_scope: Type.Optional(Type.String({ description: "Optional active scope hint." }))
+        }, { additionalProperties: false });
+    }
+    if (name === "memory_register") {
+        return Type.Object({
+            scope: Type.String({ description: "Scope alias or canonical scope id where the memory belongs." }),
+            kind: Type.String({ description: "Memory content kind." }),
+            content: contentSchema,
+            visibility: Type.String({ description: "private, pair, team, room, global, public, or sealed." }),
+            sensitivity: Type.String({ description: "normal, sensitive, or secret." }),
+            source_type: Type.String({ description: "Source label for the registered memory." }),
+            confidence: Type.Optional(Type.Number({ description: "Confidence from 0 to 1." })),
+            memory_id: Type.Optional(Type.String({ description: "Existing memory chain id for a new revision." }))
+        }, { additionalProperties: false });
+    }
+    if (name === "memory_summarize") {
+        return Type.Object({
+            scope: Type.String({ description: "Scope alias or canonical scope id to summarize." }),
+            horizon: Type.Optional(Type.Number({ description: "Approximate number of recent memories to include." }))
+        }, { additionalProperties: false });
+    }
+    if (name === "memory_promote") {
+        return Type.Object({
+            scope: Type.String({ description: "Scope alias or canonical scope id the memory belongs to." }),
+            memory_id: Type.String({ description: "Current memory chain head to promote." }),
+            reason: Type.Optional(Type.String({ description: "Why this memory is being promoted." }))
+        }, { additionalProperties: false });
+    }
+    if (name === "memory_forget") {
+        return Type.Object({
+            scope: Type.String({ description: "Scope alias or canonical scope id for the tombstone." }),
+            event_ids: Type.Array(Type.String(), { description: "Memory event ids to tombstone." }),
+            reason: Type.Optional(Type.String({ description: "Why these memories should be forgotten." }))
+        }, { additionalProperties: false });
+    }
+    throw new Error(`Unknown Pi memory tool: ${name}`);
+};
+export const createPiMemoryTools = (input) => createMemoryToolDescriptors(input.memory.kernel, { mode: input.mode ?? "awake" }).map((descriptor) => defineTool({
+    name: descriptor.modelName,
+    label: descriptor.label,
+    description: descriptor.description,
+    promptSnippet: descriptor.promptSnippet,
+    promptGuidelines: descriptor.promptGuidelines,
+    parameters: schemaFor(descriptor.modelName),
+    async execute(_toolCallId, params) {
+        const startedAt = Date.now();
+        try {
+            requireExactModelArguments(descriptor.modelName, params);
+            const result = await descriptor.invoke(params, requireTrustedContext(input.agentId, input.contextRef));
+            input.contextRef.observeTool?.({
+                contentCount: result.content.length,
+                decision: result.decision,
+                durationMs: Date.now() - startedAt,
+                kind: "memory",
+                name: descriptor.modelName,
+                redactionCount: result.content.reduce((total, content) => total + content.redactions.length, 0),
+                status: "completed"
+            });
+            return textContent(result);
+        }
+        catch (error) {
+            input.contextRef.observeTool?.({
+                durationMs: Date.now() - startedAt,
+                error: error instanceof Error ? error.message : String(error),
+                kind: "memory",
+                name: descriptor.modelName,
+                status: "failed"
+            });
+            throw error;
+        }
+    }
+}));
+export const piMemoryToolNames = (tools) => tools.map((tool) => tool.name);

package/dist/pi/modelRegistry.d.ts

@@ -0,0 +1,13 @@
+import { AuthStorage, ModelRegistry } from "@earendil-works/pi-coding-agent";
+import type { HarnessModelSpec } from "../core/types.js";
+export interface PiModelRegistryOptions {
+    model?: {
+        auth?: HarnessModelSpec["auth"];
+        endpoint?: HarnessModelSpec["endpoint"];
+        provider: string;
+        name: string;
+    };
+    modelsPath?: string;
+}
+export declare const createPiModelRegistry: (authStorage: AuthStorage, options: PiModelRegistryOptions) => ModelRegistry;
+//# sourceMappingURL=modelRegistry.d.ts.map

package/dist/pi/modelRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"modelRegistry.d.ts","sourceRoot":"","sources":["../../src/pi/modelRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,aAAa,EACd,MAAM,iCAAiC,CAAC;AAEzC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAIzD,MAAM,WAAW,sBAAsB;IACrC,KAAK,CAAC,EAAE;QACN,IAAI,CAAC,EAAE,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAChC,QAAQ,CAAC,EAAE,gBAAgB,CAAC,UAAU,CAAC,CAAC;QACxC,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,eAAO,MAAM,qBAAqB,GAChC,aAAa,WAAW,EACxB,SAAS,sBAAsB,KAC9B,aAkBF,CAAC"}

package/dist/pi/modelRegistry.js

@@ -0,0 +1,19 @@
+import { ModelRegistry } from "@earendil-works/pi-coding-agent";
+import { resolvePiHarnessModel } from "./modelConfig.js";
+export const createPiModelRegistry = (authStorage, options) => {
+    const registry = options.modelsPath
+        ? ModelRegistry.create(authStorage, options.modelsPath)
+        : ModelRegistry.inMemory(authStorage);
+    if (!options.modelsPath && options.model?.endpoint) {
+        const { modelsConfig } = resolvePiHarnessModel(options.model);
+        for (const [provider, config] of Object.entries(modelsConfig.providers)) {
+            registry.registerProvider(provider, {
+                api: config.api,
+                apiKey: config.apiKey,
+                baseUrl: config.baseUrl,
+                models: config.models
+            });
+        }
+    }
+    return registry;
+};

package/dist/pi/piAgentHandle.d.ts

@@ -0,0 +1,45 @@
+import type { AgentHandle, AgentStatus, WakeEvent, WakeResult } from "../core/types.js";
+import { type PiMemoryToolContextRef } from "./memoryTools.js";
+import { stampTurnInputSubmitted, stampTurnOutputCompleted } from "./turnCausal.js";
+import { type WakeAcceptanceStoreLike } from "./wakeAcceptance.js";
+import { persistPiTurnTrace, type PiTurnTraceModel } from "./turnTrace.js";
+import { type PiRawTrainingCaptureOptions, type PiRawTrainingCaptureRef } from "./rawTrainingCapture.js";
+import { type PiWorldToolContextRef } from "./worldNudge.js";
+import { type PiWorldTrajectoryIdentity } from "./worldTrajectory.js";
+import { type PiNativeSessionCreator, type PiSession, type PiSessionCreator, type PiSessionLike } from "./piAgentWakeSupport.js";
+import { type MemoryRuntime } from "@noopolis/mneme";
+export type { PiSession, PiSessionLike, PiSessionCreator, PiNativeSessionCreator } from "./piAgentWakeSupport.js";
+export type WakeAcceptanceInput = {
+    runWake?: typeof stampTurnInputSubmitted;
+    completeTurn?: typeof stampTurnOutputCompleted;
+    traceTurn?: typeof persistPiTurnTrace;
+    createWakeAcceptance?: (runtimeHomePath: string, agentId: string) => WakeAcceptanceStoreLike;
+};
+export declare class PiAgentHandle implements AgentHandle {
+    readonly id: string;
+    private readonly session;
+    private readonly createSession;
+    private readonly runtimeHomePath;
+    private readonly traceModel;
+    private readonly memory?;
+    private readonly memoryToolContext?;
+    private readonly worldToolContext?;
+    private readonly rawTrainingCaptureRef?;
+    private readonly rawTrainingCaptureOptions?;
+    private readonly worldTrajectoryIdentity?;
+    private readonly piSessionForRawCapture?;
+    private state;
+    private lastWakeAt;
+    private lastError;
+    private readonly wakeDeliveryQueue;
+    private readonly stampTurnInputSubmitted;
+    private readonly stampTurnOutputCompleted;
+    private readonly persistTrace;
+    constructor(id: string, session: PiSession, createSession: PiNativeSessionCreator, runtimeHomePath: string, traceModel: PiTurnTraceModel, memory?: MemoryRuntime, memoryToolContext?: PiMemoryToolContextRef, dependencies?: WakeAcceptanceInput, worldToolContext?: PiWorldToolContextRef, rawTrainingCaptureRef?: PiRawTrainingCaptureRef, rawTrainingCaptureOptions?: PiRawTrainingCaptureOptions, worldTrajectoryIdentity?: PiWorldTrajectoryIdentity, rawTrainingCaptureSession?: PiSession);
+    constructor(id: string, session: PiSessionLike, createSession: PiSessionCreator, runtimeHomePath: string, traceModel: PiTurnTraceModel, memory?: MemoryRuntime, memoryToolContext?: PiMemoryToolContextRef, dependencies?: WakeAcceptanceInput, worldToolContext?: PiWorldToolContextRef, rawTrainingCaptureRef?: never, rawTrainingCaptureOptions?: never, worldTrajectoryIdentity?: PiWorldTrajectoryIdentity, rawTrainingCaptureSession?: never);
+    wake(event: WakeEvent): Promise<WakeResult>;
+    private runWake;
+    status(): AgentStatus;
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=piAgentHandle.d.ts.map

package/dist/pi/piAgentHandle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"piAgentHandle.d.ts","sourceRoot":"","sources":["../../src/pi/piAgentHandle.ts"],"names":[],"mappings":"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"}