@noopolis/daimon 0.1.2 → 0.2.1

package/dist/pi/cliSession.js

@@ -1,130 +1,71 @@
-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)));
+import { startMcp } from "./cliSessionMcp.js";
+import { reportEngineTaskClockGap } from "./engineTaskClock.js";
+import { redactCredentialError, redactCredentialText } from "../core/credentialRedaction.js";
+import { asGrokAuthenticationRejected, classifyGrokAuthenticationDiagnostic, GrokSubscriptionAuthenticationRejectedError } from "../runtime/grokAuthenticationError.js";
+import { readChild } from "./cliChildOutput.js";
+import { cliChildEnvironment } from "./cliEnvironment.js";
+import { spawnEngine } from "./cliEngineSpawn.js";
+import { registerCliMcpServer, renderAgyMcpAddArgs, renderAgyMcpRemoveArgs } from "./cliMcpRegistration.js";
+import { registerGrokHomeMcpServer } from "./grokHomeMcpRegistration.js";
+import { decodeAgyHeadlessTurn } from "./agyHeadlessResult.js";
+import { createCliTurnMeter, decodeCodexTurn, failedTurnOutcome, publishTurnRequests, publishTurnUsage } from "./cliTurnMetering.js";
+import { decodeGrokHeadlessResult } from "./grokHeadlessResult.js";
+import { terminateChild } from "./cliProcess.js";
+import { ensureRuntimeHome, ensureRuntimeHomeDirectory } from "../runtime/runtimeHomeLayout.js";
+/**
+ * The per-wake tool-call bound for AGY, and the one place it is decided.
+ *
+ * Codex and Grok leave this `undefined` — their only bound is the wake
+ * deadline. AGY does not get that treatment, for a measured reason: its
+ * terminal usage frame is the *sum* over the turn's model steps, and each tool
+ * step resends the whole context. The live capture is 13,796 total tokens for a
+ * tool-free turn and 45,381 for a turn with a single call against an
+ * empty-schema tool — one call roughly triples the wake. An unbounded loop on
+ * the one engine whose subscription quota is currently the operator's only
+ * working credential is a cost hazard, not a capability.
+ *
+ * 16 is chosen so a realistic wake is never truncated (read a few declared MCP
+ * tools, then send one or two Moltnet messages) while the worst case is bounded
+ * at roughly a quarter-million tokens instead of "whatever fits in 180s". The
+ * bound degrades gracefully rather than failing the wake: exceeding it returns
+ * `McpToolTurnLimitError` to the model as a tool *error*, so the agent can still
+ * finish its turn and reply.
+ */
+export const AGY_MAX_TOOL_TURNS = 16;
+export { DAIMON_CODEX_WAKE_TIMEOUT_MS_ENV, DAIMON_CODEX_WAKE_TOKEN_CEILING_ENV, DAIMON_ENGINE_WAKE_TIMEOUT_MS_ENV, DAIMON_ENGINE_WAKE_TOKEN_CEILING_ENV, DEFAULT_CODEX_WAKE_TIMEOUT_MS, DEFAULT_CODEX_WAKE_TOKEN_CEILING, resolveCodexWakeTimeoutMs, resolveCodexWakeTokenCeiling, resolveEngineWakeLimitOverrides } from "./engineWakeLimits.js";
+export const prepareCliRuntimeHome = async (runtimeHomePath) => {
+    if (runtimeHomePath === undefined)
+        return;
+    await ensureRuntimeHome(runtimeHomePath);
+    await Promise.all([".config", ".local/share", ".local/state", ".cache", ".tmp"]
+        .map((relative) => ensureRuntimeHomeDirectory(runtimeHomePath, relative)));
 };
 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);
-    });
+const captureCleanup = async (current, action) => {
     try {
-        await new Promise((resolve, reject) => {
-            httpServer.once("error", reject);
-            httpServer.listen(0, "127.0.0.1", () => resolve());
-        });
+        await action();
     }
     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;
+        return current ?? error;
     }
-    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"]
-    });
+    return current;
 };
+export { terminateChild } from "./cliProcess.js";
+export { CLI_ENGINE_MAX_DIAGNOSTIC_BYTES, CLI_ENGINE_MAX_OUTPUT_BYTES, readChild } from "./cliChildOutput.js";
 class CliSession {
     options;
     input;
     listeners = new Set();
+    setupChildren = new Set();
     disposed = false;
+    activeChild;
+    activeMount;
+    activeBrokerTurn;
+    mcpRegistration;
+    disposePromise;
+    wakeId;
     constructor(options, input) {
         this.options = options;
         this.input = input;
@@ -133,60 +74,216 @@ class CliSession {
         this.listeners.add(listener);
         return () => this.listeners.delete(listener);
     }
+    bindWake(event) {
+        this.wakeId = event?.id;
+    }
     async prompt(text) {
         if (this.disposed)
             throw new Error("CLI session is disposed");
-        const deadline = Date.now() + this.options.timeoutMs;
-        const secretValues = childSecretValues([
+        reportEngineTaskClockGap(this.options.engine);
+        await prepareCliRuntimeHome(this.input.runtimeHomePath);
+        const deadline = this.options.timeoutMs === undefined ? undefined : Date.now() + this.options.timeoutMs;
+        const environmentSecretValues = 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;
+        const stagedCredentialSecrets = await this.options.credentialSecretValues?.() ?? [];
+        const secretValues = [...environmentSecretValues, ...stagedCredentialSecrets];
+        let mount;
+        let registration;
+        let turnUsage;
+        // Kept beside the decoded turn so a wake that never reaches its decoder
+        // still owes the ledger the usage Codex already reported (`cliTurnMetering.ts`).
+        const meter = createCliTurnMeter();
+        // Codex's own `thread.started` frame, carried out of the stream so the
+        // wake's rollout can be found by identity rather than by recency.
+        let codexThreadId;
+        let instrumented = false;
+        const instrument = async () => {
+            if (instrumented)
+                return;
+            instrumented = true;
+            await publishTurnRequests(this.options.onCodexTurnRequests, codexThreadId);
+        };
         let child;
+        let output;
+        let cleanupFailure;
+        let promptFailure;
         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);
+            // Every CLI engine mounts the same tool surface. AGY used to be the one
+            // exception (`toolAccess: "none"`), which is exactly what made an AGY
+            // agent unable to reach Moltnet or a declared MCP server, and so unable
+            // to take part in an organization at all.
+            mount = await startMcp(this.input.customTools ?? [], this.options.maxToolTurns, deadline, this.options.onToolsMounted, (started) => {
+                this.activeMount = started;
+                if (this.disposed)
+                    void started.close();
+            });
+            this.ensureLive();
+            if (this.options.engine === "grok" && this.options.grokBrokerTurn !== undefined && mount !== undefined) {
+                const controller = new AbortController();
+                this.activeBrokerTurn = controller;
+                try {
+                    output = await this.options.grokBrokerTurn(`${this.options.identityPrompt ?? ""}${text}`, mount.endpoint, controller.signal);
+                }
+                finally {
+                    if (this.activeBrokerTurn === controller)
+                        this.activeBrokerTurn = undefined;
+                }
             }
-            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: []
+            else {
+                if (this.options.engine === "grok" && mount !== undefined) {
+                    await this.options.verifyExecutable?.();
+                    registration = await registerGrokHomeMcpServer({
+                        engineHomePath: this.options.engineHomePath,
+                        endpoint: mount.endpoint,
+                        ...(this.options.verifyGrokSandbox !== undefined ? { verify: this.options.verifyGrokSandbox } : {})
+                    });
+                    this.mcpRegistration = registration;
+                }
+                else if (this.options.engine === "agy" && mount !== undefined) {
+                    await this.options.verifyExecutable?.();
+                    registration = await registerCliMcpServer({
+                        addArgs: renderAgyMcpAddArgs(this.options.commandArgs, mount.endpoint),
+                        removeArgs: renderAgyMcpRemoveArgs(this.options.commandArgs),
+                        command: this.options.command ?? this.options.engine,
+                        cwd: this.input.cwd,
+                        env: cliChildEnvironment([
+                            ...(this.options.redactedEnvironmentNames ?? []),
+                            ...(this.input.daimonSecretEnvironmentNames ?? [])
+                        ], this.input.runtimeHomePath, {
+                            ...(this.options.dbusSessionBusAddress !== undefined ? { dbusSessionBusAddress: this.options.dbusSessionBusAddress } : {}),
+                            engine: this.options.engine,
+                            executablePath: this.options.command,
+                            engineHomePath: this.options.engineHomePath
+                        }),
+                        onChild: (setupChild) => { this.setupChildren.add(setupChild); },
+                        onChildSettled: (setupChild) => this.setupChildren.delete(setupChild),
+                        secretValues
+                    });
+                    this.mcpRegistration = registration;
+                }
+                this.ensureLive();
+                await this.options.verifyRuntimePaths?.();
+                await this.options.verifyExecutable?.();
+                await this.options.verifyGrokSandbox?.();
+                child = spawnEngine(this.options, `${this.options.identityPrompt ?? ""}${text}`, this.input, mount?.endpoint, this.wakeId);
+                this.activeChild = child;
+                // Attach terminal listeners synchronously. A fast local sentinel may
+                // exit before an asynchronous post-spawn authority recheck completes.
+                const outputPromise = readChild(child, deadline === undefined ? undefined : Math.max(1, deadline - Date.now()), secretValues, {
+                    failureClassifier: this.options.engine === "grok" ? classifyGrokAuthenticationDiagnostic : undefined,
+                    retainNdjson: this.options.engine === "codex" ? "codex" : undefined,
+                    retainStdoutTail: this.options.engine === "grok",
+                    timeoutErrorMessage: this.options.engine === "codex" && this.options.timeoutMs !== undefined
+                        ? `Codex wake exceeded its ${this.options.timeoutMs}ms per-wake wall-clock bound`
+                        : undefined,
+                    codexTokenCeiling: this.options.engine === "codex" ? this.options.codexTokenCeiling : undefined,
+                    onCodexTurnCompleted: meter.observeCodexTurnCompleted,
+                    onCodexThreadStarted: (threadId) => { codexThreadId = threadId; }
                 });
+                void outputPromise.catch(() => undefined);
+                await this.options.verifyRuntimePaths?.();
+                await this.options.verifyExecutable?.();
+                const childOutput = await outputPromise;
+                if (this.options.engine === "grok")
+                    output = decodeGrokHeadlessResult(childOutput);
+                else if (this.options.engine === "codex") {
+                    const decoded = decodeCodexTurn(childOutput);
+                    output = decoded.text;
+                    turnUsage = decoded.usage;
+                }
+                else if (this.options.engine === "agy") {
+                    const decoded = decodeAgyHeadlessTurn(childOutput);
+                    output = decoded.text;
+                    turnUsage = decoded.usage;
+                }
+                else
+                    output = childOutput;
+            }
+        }
+        catch (error) {
+            promptFailure = error;
         }
         finally {
-            if (child !== undefined)
-                terminate(child);
-            await mount?.close();
+            cleanupFailure = await captureCleanup(cleanupFailure, async () => { if (child !== undefined)
+                await terminateChild(child); });
+            if (this.activeChild === child)
+                this.activeChild = undefined;
+            let registrationClosed = registration === undefined;
+            cleanupFailure = await captureCleanup(cleanupFailure, async () => { await registration?.close(); registrationClosed = true; });
+            if (registrationClosed && this.mcpRegistration === registration)
+                this.mcpRegistration = undefined;
+            cleanupFailure = await captureCleanup(cleanupFailure, async () => { await mount?.close(); });
+            if (this.activeMount === mount)
+                this.activeMount = undefined;
+        }
+        const refreshedCredentialSecrets = await this.options.credentialSecretValues?.().catch(() => []) ?? [];
+        const finalSecrets = [...secretValues, ...refreshedCredentialSecrets];
+        // A wake that Codex reported usage for is metered whether or not it goes on
+        // to publish. Every throw below this point used to drop that spend on the
+        // floor, so a breached ceiling, an expired wall clock, a non-zero exit, or
+        // a turn judged unpublishable all cost money the ledger never saw.
+        const failure = promptFailure ?? cleanupFailure;
+        if (failure !== undefined) {
+            await publishTurnUsage(this.options.onTurnUsage, turnUsage ?? meter.reported(), failedTurnOutcome(failure));
+            // A wake that failed still made model requests and still paid for them,
+            // so its per-request shape is measured on exactly the paths its spend is.
+            await instrument();
         }
+        if (promptFailure !== undefined) {
+            const authRejection = this.options.engine === "grok" ? asGrokAuthenticationRejected(promptFailure) : undefined;
+            if (authRejection !== undefined)
+                throw new GrokSubscriptionAuthenticationRejectedError(cleanupFailure === undefined ? undefined : redactCredentialError(cleanupFailure, finalSecrets));
+            if (cleanupFailure !== undefined)
+                throw redactCredentialError(cleanupFailure, finalSecrets);
+            throw redactCredentialError(promptFailure, finalSecrets);
+        }
+        if (cleanupFailure !== undefined) {
+            if (this.options.engine === "grok" && asGrokAuthenticationRejected(cleanupFailure) !== undefined) {
+                throw new GrokSubscriptionAuthenticationRejectedError();
+            }
+            throw redactCredentialError(cleanupFailure, finalSecrets);
+        }
+        if (output === undefined)
+            return;
+        output = redactCredentialText(output, finalSecrets, 64 * 1024);
+        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: []
+            });
+        // Meter only after the turn has published.
+        await publishTurnUsage(this.options.onTurnUsage, turnUsage ?? meter.reported(), { status: "completed" });
+        await instrument();
     }
     dispose() {
         this.disposed = true;
         this.listeners.clear();
+        this.disposePromise ??= this.quiesce();
+    }
+    async disposeAsync() {
+        this.dispose();
+        await this.disposePromise;
+    }
+    ensureLive() {
+        if (this.disposed)
+            throw new Error("CLI session is disposed");
+    }
+    async quiesce() {
+        let cleanupFailure;
+        cleanupFailure = await captureCleanup(cleanupFailure, async () => { if (this.activeChild !== undefined)
+            await terminateChild(this.activeChild); });
+        this.activeBrokerTurn?.abort();
+        cleanupFailure = await captureCleanup(cleanupFailure, () => Promise.all([...this.setupChildren].map((child) => terminateChild(child))).then(() => undefined));
+        cleanupFailure = await captureCleanup(cleanupFailure, async () => { await this.mcpRegistration?.close(); });
+        cleanupFailure = await captureCleanup(cleanupFailure, async () => { await this.activeMount?.close(); });
+        if (cleanupFailure !== undefined)
+            throw cleanupFailure;
     }
 }
 export const createCliSessionFactory = (options) => async (input) => {
@@ -196,29 +293,10 @@ export const createCliSessionFactory = (options) => async (input) => {
         session: new CliSession(options, {
             cwd: input.cwd,
             customTools: input.customTools,
-            daimonSecretEnvironmentNames: input.daimonSecretEnvironmentNames
+            daimonSecretEnvironmentNames: input.daimonSecretEnvironmentNames,
+            runtimeHomePath: input.runtimeHomePath
         })
     };
 };
-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;
+export { runEngine, runEngineDetailed } from "./cliEngineRun.js";
+export { renderAgyArgs, renderCodexArgs, spawnEngine } from "./cliEngineSpawn.js";

package/dist/pi/cliSessionMcp.d.ts

@@ -0,0 +1,9 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+export declare const startMcp: (tools: ToolDefinition[], maxToolTurns: number | undefined, wakeDeadline: number | undefined, onToolsMounted: ((tools: readonly ToolDefinition[]) => void) | undefined, onStarted: (mount: {
+    endpoint: string;
+    close: () => Promise<void>;
+}) => void) => Promise<{
+    endpoint: string;
+    close: () => Promise<void>;
+}>;
+//# sourceMappingURL=cliSessionMcp.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cliSessionMcp.d.ts","sourceRoot":"","sources":["../../src/pi/cliSessionMcp.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEtE,eAAO,MAAM,QAAQ,GACnB,OAAO,cAAc,EAAE,EACvB,cAAc,MAAM,GAAG,SAAS,EAChC,cAAc,MAAM,GAAG,SAAS,EAChC,gBAAgB,CAAC,CAAC,KAAK,EAAE,SAAS,cAAc,EAAE,KAAK,IAAI,CAAC,GAAG,SAAS,EACxE,WAAW,CAAC,KAAK,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,KAAK,IAAI,KAC3E,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAkE1D,CAAC"}

package/dist/pi/cliSessionMcp.js

@@ -0,0 +1,80 @@
+import { randomUUID } from "node:crypto";
+import { createServer } from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { createPiToolMcpServer } from "../mcp/toolServer.js";
+export const startMcp = async (tools, maxToolTurns, wakeDeadline, onToolsMounted, onStarted) => {
+    onToolsMounted?.(tools);
+    const mcpServer = createPiToolMcpServer(tools, { maxToolTurns, wakeDeadline });
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID() });
+    const httpServer = createServer((request, response) => {
+        void transport.handleRequest(request, response);
+    });
+    let lifecycle = "starting";
+    let cancelled = false;
+    let endpoint = "";
+    let closePromise;
+    let settleStartup;
+    const startupSettled = new Promise((resolve) => { settleStartup = resolve; });
+    const close = () => closePromise ??= (async () => {
+        cancelled = true;
+        if (lifecycle !== "closed")
+            lifecycle = "closing";
+        // `listen()` begins synchronously but its callback is pending. Waiting for
+        // startup prevents dispose from returning while that callback can still bind.
+        await startupSettled;
+        await transport.close().catch(() => undefined);
+        await mcpServer.close().catch(() => undefined);
+        // `close` only stops accepting and then waits for every open connection,
+        // including the ones the transport has no record of and so cannot end (a
+        // socket opened before `initialize`, or a client pool's idle keep-alive
+        // socket, which relaying a turn through the broker MCP facade leaves
+        // behind). That wait is unbounded and sits on the wake's own completion
+        // path: measured, one such connection parked a finished broker turn with
+        // its result in hand and published nothing. By here this one wake's engine
+        // has returned, failed or been cancelled, so anything still connected is a
+        // leftover — see `AGENTS.md`, and the facade, which bounds itself the same
+        // way.
+        if (httpServer.listening)
+            await new Promise((resolve) => { httpServer.close(() => resolve()); httpServer.closeAllConnections(); });
+        lifecycle = "closed";
+    })();
+    const mount = { get endpoint() { return endpoint; }, close };
+    onStarted(mount);
+    let startupError;
+    try {
+        if (cancelled)
+            throw new Error("MCP startup was cancelled");
+        await mcpServer.connect(transport);
+        if (cancelled)
+            throw new Error("MCP startup was cancelled");
+        await new Promise((resolve, reject) => {
+            const onError = (error) => reject(error);
+            httpServer.once("error", onError);
+            httpServer.listen(0, "127.0.0.1", () => {
+                httpServer.off("error", onError);
+                // A disposer can run from a Server.prototype.listen interceptor before
+                // this callback. Never publish the server as live in that interleaving.
+                if (!cancelled)
+                    lifecycle = "listening";
+                resolve();
+            });
+        });
+        if (cancelled)
+            throw new Error("MCP startup was cancelled");
+        const address = httpServer.address();
+        if (address === null || typeof address === "string") {
+            throw new Error("MCP server did not receive an ephemeral port");
+        }
+        endpoint = `http://127.0.0.1:${address.port}/mcp`;
+        return mount;
+    }
+    catch (error) {
+        startupError = error;
+        throw error;
+    }
+    finally {
+        settleStartup();
+        if (cancelled || startupError !== undefined)
+            await close();
+    }
+};

package/dist/pi/cliTurnMetering.d.ts

@@ -0,0 +1,60 @@
+import type { AgyTurnUsage } from "./agyHeadlessResult.js";
+import { type CodexHeadlessTurn, type CodexTurnUsage } from "./codexHeadlessResult.js";
+import type { TurnUsageOutcome } from "../runtime/turnUsageLedger.js";
+/**
+ * What one CLI turn owes the usage ledger, and the rules for when it owes
+ * nothing.
+ *
+ * A wake that fails spends exactly the money a wake that publishes spends, so
+ * the engine's reported usage is metered on both paths and the row's outcome
+ * says which. A Codex wake that breached its per-wake token ceiling used to
+ * record nothing at all: the tokens it burned survived only as a number
+ * interpolated into the error message, and a timeout, a killed child, or a
+ * non-zero exit lost the figure entirely.
+ *
+ * The counterweight is that a number is never invented. A zero-filled row is
+ * byte-identical to a real zero and would silently poison every aggregate
+ * computed over the ledger, so "the engine reported nothing" stays absent.
+ */
+export type CliTurnMeter = Readonly<{
+    /** Wire this to `readChild`'s `onCodexTurnCompleted`. */
+    observeCodexTurnCompleted: (usage: CodexTurnUsage | undefined) => void;
+    /**
+     * The usage Codex reported mid-stream, for a wake that never reached its
+     * decoder.
+     *
+     * Trustworthy only under `decodeCodexHeadlessTurn`'s own rule: exactly one
+     * `turn.completed` frame. Codex may omit, repeat, or follow that frame with
+     * another, and two completions leave no defensible answer for which one the
+     * wake actually spent — so this declines rather than guessing, and no frame
+     * at all means nothing was reported and nothing is written.
+     */
+    reported: () => CodexTurnUsage | undefined;
+}>;
+export declare const createCliTurnMeter: () => CliTurnMeter;
+/**
+ * A turn Codex reported usage for but that the decoder refuses to publish is
+ * still a turn that spent tokens. Tagging the rejection is what lets the
+ * ledger row name why the wake failed instead of matching on message prose.
+ */
+export declare const decodeCodexTurn: (output: string) => CodexHeadlessTurn;
+/** The failed row's marker, named by the bound that actually fired. */
+export declare const failedTurnOutcome: (failure: unknown) => TurnUsageOutcome;
+/**
+ * Advisory: metering never fails, delays, or rewrites the wake it describes —
+ * the same ordering rule the Grok engine broker states in
+ * `finishBrokerTurnWithUsage`.
+ */
+export declare const publishTurnUsage: (sink: ((usage: AgyTurnUsage | CodexTurnUsage, outcome: TurnUsageOutcome) => Promise<void>) | undefined, usage: AgyTurnUsage | CodexTurnUsage | undefined, outcome: TurnUsageOutcome) => Promise<void>;
+/**
+ * Advisory per-request instrumentation, under the same ordering rule as
+ * {@link publishTurnUsage}: it never fails, delays, or rewrites the wake it
+ * describes.
+ *
+ * No thread id means Codex never announced one — an engine that is not Codex,
+ * a child killed before its first frame, or a future stream that renamed the
+ * event. Nothing is written in that case, because the alternative is guessing
+ * which rollout on disk belongs to this wake.
+ */
+export declare const publishTurnRequests: (sink: ((threadId: string) => Promise<void>) | undefined, threadId: string | undefined) => Promise<void>;
+//# sourceMappingURL=cliTurnMetering.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cliTurnMetering.d.ts","sourceRoot":"","sources":["../../src/pi/cliTurnMetering.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EAA2B,KAAK,iBAAiB,EAAE,KAAK,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAChH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAEtE;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC;IAClC,yDAAyD;IACzD,yBAAyB,EAAE,CAAC,KAAK,EAAE,cAAc,GAAG,SAAS,KAAK,IAAI,CAAC;IACvE;;;;;;;;;OASG;IACH,QAAQ,EAAE,MAAM,cAAc,GAAG,SAAS,CAAC;CAC5C,CAAC,CAAC;AAEH,eAAO,MAAM,kBAAkB,QAAO,YAUrC,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,QAAQ,MAAM,KAAG,iBAGhD,CAAC;AAEF,uEAAuE;AACvE,eAAO,MAAM,iBAAiB,GAAI,SAAS,OAAO,KAAG,gBACwB,CAAC;AAE9E;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAC3B,MAAM,CAAC,CAAC,KAAK,EAAE,YAAY,GAAG,cAAc,EAAE,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,EACtG,OAAO,YAAY,GAAG,cAAc,GAAG,SAAS,EAChD,SAAS,gBAAgB,KACxB,OAAO,CAAC,IAAI,CAGd,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,GAC9B,MAAM,CAAC,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,SAAS,EACvD,UAAU,MAAM,GAAG,SAAS,KAC3B,OAAO,CAAC,IAAI,CAGd,CAAC"}