@astrosheep/keiyaku 1.0.0 → 1.0.2

package/build/core/projection-generation-execution.js

@@ -0,0 +1,148 @@
+import { initializeConfig } from "../config/env.js";
+import { buildCallTermsV2 } from "../agents/call-terms_v2.js";
+import { parseResolvedAkumaLaunchSnapshot, } from "../agents/launch-snapshot_v2.js";
+import { revive, call } from "../agents/harness/index.js";
+import { readProjectionEvents } from "./projection-core.js";
+import { readProjectionIdentity } from "./projection-identity.js";
+import { selectValidStoredAgentEvents } from "./stored-agent-event.js";
+import { persistResponseHistory } from "./transcripts.js";
+function isObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function requireString(value, field) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new Error(`generation launch ${field} must be a non-blank string`);
+    }
+    return value;
+}
+function optionalString(value, field) {
+    return value === undefined ? undefined : requireString(value, field);
+}
+function requirePositiveSafeInteger(value, field) {
+    if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+        throw new Error(`generation launch ${field} must be a positive safe integer`);
+    }
+    return value;
+}
+function parseLaunchInputs(launch) {
+    const raw = launch.facts.inputs;
+    if (!isObject(raw))
+        throw new Error("generation launch inputs must be an object");
+    let launchSnapshot;
+    try {
+        launchSnapshot = parseResolvedAkumaLaunchSnapshot(raw.launchSnapshot);
+    }
+    catch (error) {
+        throw new Error(`generation launch launchSnapshot is invalid: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+    if (raw.persistProjectionResponse !== true && raw.persistProjectionResponse !== false) {
+        throw new Error("generation launch persistProjectionResponse must be boolean");
+    }
+    if (raw.session !== undefined && !isObject(raw.session)) {
+        throw new Error("generation launch session must be an object");
+    }
+    const evidenceCwd = optionalString(raw.evidenceCwd, "evidenceCwd");
+    const title = optionalString(raw.title, "title");
+    const context = optionalString(raw.context, "context");
+    const resumePath = optionalString(raw.resumePath, "resumePath");
+    return {
+        prompt: requireString(raw.prompt, "prompt"),
+        cwd: requireString(raw.cwd, "cwd"),
+        task: requireString(raw.task, "task"),
+        historyCwd: requireString(raw.historyCwd, "historyCwd"),
+        ...(evidenceCwd ? { evidenceCwd } : {}),
+        ...(title ? { title } : {}),
+        ...(context ? { context } : {}),
+        launchSnapshot,
+        idleTimeoutMs: requirePositiveSafeInteger(raw.idleTimeoutMs, "idleTimeoutMs"),
+        persistProjectionResponse: raw.persistProjectionResponse,
+        ...(raw.session ? { session: raw.session } : {}),
+        ...(resumePath ? { resumePath } : {}),
+    };
+}
+function persistenceError(error) {
+    return (error instanceof Error ? error.message : String(error))
+        .replace(/[\r\n]+/g, " ")
+        .trim() || "response persistence failed";
+}
+function responseTitle(executionId, title) {
+    return `${executionId.slice(-16)}-${title ?? "call"}-${executionId}`;
+}
+function asJsonObject(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function maximumValidEnvelopeTurn(projectionDirectory) {
+    const { events } = selectValidStoredAgentEvents(readProjectionEvents(projectionDirectory));
+    let maximum = 0;
+    for (const event of events) {
+        if (event.turn > maximum)
+            maximum = event.turn;
+    }
+    return maximum;
+}
+async function completionFacts(projectionDirectory, executionId, inputs, outcome) {
+    let persistence = {};
+    if (inputs.persistProjectionResponse) {
+        try {
+            if (!inputs.evidenceCwd) {
+                throw new Error("projection response persistence is missing evidenceCwd");
+            }
+            const pact = readProjectionIdentity(projectionDirectory);
+            persistence = await persistResponseHistory({
+                tool: "call",
+                cwd: inputs.historyCwd,
+                provenance: {
+                    authority: pact.authority,
+                    binding: pact.binding,
+                    evidenceCwd: inputs.evidenceCwd,
+                },
+                task: inputs.task,
+                response: outcome.finalMessage,
+                session: outcome.session,
+                launchSnapshot: inputs.launchSnapshot,
+                effectivePolicy: inputs.launchSnapshot.akuma.policy,
+                subagentName: inputs.launchSnapshot.akuma.name,
+                title: responseTitle(executionId, inputs.title),
+                ...(inputs.context ? { context: inputs.context } : {}),
+            });
+        }
+        catch (error) {
+            persistence = { responsePersistError: persistenceError(error) };
+        }
+    }
+    return asJsonObject({
+        completedAt: new Date().toISOString(),
+        finalMessage: outcome.finalMessage,
+        output: outcome.output,
+        diagnostics: outcome.diagnostics,
+        session: outcome.session,
+        warnings: outcome.warnings,
+        launchSnapshot: inputs.launchSnapshot,
+        effectivePolicy: inputs.launchSnapshot.akuma.policy,
+        ...(outcome.error ? { error: outcome.error } : {}),
+        ...persistence,
+    });
+}
+export async function executeProjectionGeneration(projectionDirectory, launch) {
+    const inputs = parseLaunchInputs(launch);
+    initializeConfig(process.env, inputs.cwd);
+    const terms = buildCallTermsV2(inputs.launchSnapshot, inputs.prompt, inputs.cwd, {
+        idleTimeoutMs: inputs.idleTimeoutMs,
+        projectionDir: projectionDirectory,
+        projectionExecutionId: launch.executionId,
+        projectionTellFence: launch.facts.tellFence ?? [],
+        initialTurn: maximumValidEnvelopeTurn(projectionDirectory),
+    });
+    const projection = inputs.session && inputs.resumePath
+        ? revive({ ...terms, session: inputs.session, resumePath: inputs.resumePath })
+        : call(terms);
+    const outcome = await projection.outcome;
+    return {
+        verdict: outcome.status === "completed"
+            ? "completed"
+            : outcome.status === "dismissed"
+                ? "dismissed"
+                : "failed",
+        facts: await completionFacts(projectionDirectory, launch.executionId, inputs, outcome),
+    };
+}

package/build/core/projection-generation-identity.js

@@ -0,0 +1,17 @@
+import { randomBytes } from "node:crypto";
+import * as path from "node:path";
+import { ProjectionStateError } from "./atomic-publish.js";
+import { createUlid } from "./ids.js";
+const EXECUTION_ID_PATTERN = /^[0-9A-HJKMNP-TV-Z]{26}$/;
+export function createProjectionExecutionId(nowMs = Date.now()) {
+    return createUlid(nowMs, [...randomBytes(10)]);
+}
+export function assertProjectionExecutionId(executionId) {
+    if (!EXECUTION_ID_PATTERN.test(executionId)) {
+        throw new ProjectionStateError(`invalid projection execution id: ${executionId}`);
+    }
+}
+export function executionStdioLogPath(projectionDirectory, executionId) {
+    assertProjectionExecutionId(executionId);
+    return path.join(projectionDirectory, `${executionId}.stdio.log`);
+}

package/build/core/projection-generation-launcher.js

@@ -0,0 +1,90 @@
+import { setTimeout as delay } from "node:timers/promises";
+import { openProjectionGenerationStore } from "./projection-generation-store.js";
+import { spawnProjectionGenerationRunner, } from "./projection-generation-process.js";
+export const PROJECTION_ADOPTION_TIMEOUT_MS = 4_000;
+export const PROJECTION_ADOPTION_POLL_MS = 20;
+function errorDetail(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function recordLaunchFailure(projectionDirectory, executionId, detail, stage) {
+    const store = openProjectionGenerationStore(projectionDirectory);
+    try {
+        return store.verdictIfOpen({
+            executionId,
+            verdict: "launch-failed",
+            facts: { stage, detail },
+        }).status === "committed";
+    }
+    finally {
+        store.close();
+    }
+}
+/** Spawn one committed launch and return only after its exact adoption row. */
+export async function startProjectionGeneration(projectionDirectory, executionId, dependencies = {}) {
+    const now = dependencies.now ?? Date.now;
+    const sleep = dependencies.sleep ?? ((milliseconds) => delay(milliseconds));
+    let child;
+    try {
+        child = spawnProjectionGenerationRunner(projectionDirectory, executionId, dependencies);
+    }
+    catch (error) {
+        const detail = `runner spawn failed: ${errorDetail(error)}`;
+        recordLaunchFailure(projectionDirectory, executionId, detail, "spawn");
+        return { status: "failed", detail };
+    }
+    const deadline = now() + PROJECTION_ADOPTION_TIMEOUT_MS;
+    for (;;) {
+        const observedAt = now();
+        const store = openProjectionGenerationStore(projectionDirectory);
+        try {
+            const current = store.readCurrentGeneration();
+            if (current?.launch.executionId !== executionId) {
+                return {
+                    status: "failed",
+                    detail: "launch stopped being current before adoption",
+                };
+            }
+            if (current.adoption)
+                return { status: "adopted", child };
+            if (current.verdict) {
+                return {
+                    status: "failed",
+                    detail: typeof current.verdict.facts.detail === "string"
+                        ? current.verdict.facts.detail
+                        : `launch ended as ${String(current.verdict.facts.state)}`,
+                };
+            }
+        }
+        finally {
+            store.close();
+        }
+        if (observedAt >= deadline)
+            break;
+        await sleep(Math.max(0, Math.min(PROJECTION_ADOPTION_POLL_MS, deadline - observedAt)));
+    }
+    const store = openProjectionGenerationStore(projectionDirectory);
+    try {
+        const current = store.readCurrentGeneration();
+        if (current?.launch.executionId === executionId && current.adoption) {
+            return { status: "adopted", child };
+        }
+    }
+    finally {
+        store.close();
+    }
+    const detail = "runner did not commit adoption before startup timeout";
+    if (!recordLaunchFailure(projectionDirectory, executionId, detail, "adoption")) {
+        const raced = openProjectionGenerationStore(projectionDirectory);
+        try {
+            const current = raced.readCurrentGeneration();
+            if (current?.launch.executionId === executionId && current.adoption) {
+                return { status: "adopted", child };
+            }
+        }
+        finally {
+            raced.close();
+        }
+    }
+    child.kill("SIGTERM");
+    return { status: "failed", detail };
+}

package/build/core/projection-generation-process.js

@@ -0,0 +1,43 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { spawn as nodeSpawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { executionStdioLogPath } from "./projection-generation-identity.js";
+const MODULE_FILE = fileURLToPath(import.meta.url);
+const PACKAGE_ROOT = path.resolve(path.dirname(MODULE_FILE), "..", "..");
+const RUNNER_ENTRY = MODULE_FILE.endsWith(".ts")
+    ? [process.execPath, "--import", "tsx", path.join(PACKAGE_ROOT, "src", "index.ts")]
+    : [process.execPath, path.join(PACKAGE_ROOT, "build", "index.js")];
+export function projectionGenerationRunnerArgv(projectionDirectory, executionId) {
+    return [
+        ...RUNNER_ENTRY,
+        "__keiyaku-wake",
+        path.resolve(projectionDirectory),
+        executionId,
+    ];
+}
+export function spawnProjectionGenerationRunner(projectionDirectory, executionId, dependencies = {}) {
+    const spawn = dependencies.spawn ?? nodeSpawn;
+    const openSync = dependencies.openSync ?? fs.openSync;
+    const closeSync = dependencies.closeSync ?? fs.closeSync;
+    const absoluteDirectory = path.resolve(projectionDirectory);
+    const [command, ...args] = projectionGenerationRunnerArgv(absoluteDirectory, executionId);
+    if (!command)
+        throw new Error("projection runner command is empty");
+    const logPath = executionStdioLogPath(absoluteDirectory, executionId);
+    const logFd = openSync(logPath, "a");
+    try {
+        const child = spawn(command, args, {
+            detached: true,
+            stdio: ["ignore", logFd, logFd],
+        });
+        if (child.pid === undefined) {
+            throw new Error("projection runner did not expose a process id");
+        }
+        child.unref();
+        return child;
+    }
+    finally {
+        closeSync(logFd);
+    }
+}

package/build/core/projection-generation-runner.js

@@ -0,0 +1,144 @@
+import { openProjectionGenerationStore, } from "./projection-generation-store.js";
+import { acquireProjectionRunnerLock, observeProjectionRunnerLock, } from "./projection-runner-lock.js";
+import { createProjectionExecutionId } from "./projection-generation-identity.js";
+import { applyContinuationEffort, } from "./projection-generation-continuation.js";
+function successorLaunchFacts(launch, completionFacts, effort, now) {
+    const { tellFence: _tellFence, ...inherited } = launch.facts;
+    const rawInputs = launch.facts.inputs;
+    const inputs = rawInputs
+        && typeof rawInputs === "object"
+        && !Array.isArray(rawInputs)
+        ? rawInputs
+        : {};
+    return {
+        ...inherited,
+        createdAt: new Date(now()).toISOString(),
+        launchedBy: "sweep-wake",
+        parentExecutionId: launch.executionId,
+        inputs: applyContinuationEffort({
+            ...inputs,
+            ...(completionFacts.session ? { session: completionFacts.session } : {}),
+            ...(typeof completionFacts.responsePath === "string"
+                ? { resumePath: completionFacts.responsePath }
+                : {}),
+        }, effort),
+    };
+}
+function normalizeTellFence(tellIds) {
+    return [...new Set(tellIds)].sort();
+}
+function errorDetail(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function acquireRunnerLockOrObserveDuplicate(projectionDirectory) {
+    try {
+        return acquireProjectionRunnerLock(projectionDirectory);
+    }
+    catch (error) {
+        if (observeProjectionRunnerLock(projectionDirectory).state === "held") {
+            return undefined;
+        }
+        throw error;
+    }
+}
+/**
+ * Own one exact generation from kernel-lock acquisition through its terminal
+ * transaction. Provider execution is injected so this actor never depends on
+ * harness, catalog, renderer, or mailbox storage details.
+ */
+export async function runProjectionGeneration(input) {
+    const now = input.now ?? Date.now;
+    const store = openProjectionGenerationStore(input.projectionDirectory);
+    let runnerLock;
+    let adopted = false;
+    let settled = false;
+    try {
+        const initial = store.readCurrentGeneration();
+        if (initial?.launch.executionId !== input.executionId
+            || initial.adoption
+            || initial.verdict) {
+            return { status: "rejected" };
+        }
+        runnerLock = acquireRunnerLockOrObserveDuplicate(input.projectionDirectory);
+        if (!runnerLock)
+            return { status: "duplicate" };
+        const adoption = store.adoptionIfCurrent({
+            executionId: input.executionId,
+            facts: { adoptedAt: new Date(now()).toISOString() },
+        });
+        if (adoption.status !== "committed")
+            return { status: "rejected" };
+        adopted = true;
+        const current = store.readCurrentGeneration();
+        if (current?.launch.executionId !== input.executionId) {
+            throw new Error("adopted generation stopped being current");
+        }
+        const execution = await input.execute(current.launch);
+        const pending = execution.verdict === "completed"
+            ? input.snapshotPendingTells()
+            : { tellIds: [] };
+        const tellFence = normalizeTellFence(pending.tellIds);
+        if (tellFence.length > 0) {
+            const successorExecutionId = createProjectionExecutionId(now());
+            const transition = store.handoff({
+                executionId: input.executionId,
+                completionFacts: execution.facts,
+                successorExecutionId,
+                successorFacts: successorLaunchFacts(current.launch, execution.facts, pending.effort, now),
+                tellFence,
+            });
+            if (transition.status !== "committed")
+                return { status: "rejected" };
+            settled = true;
+            // Handoff makes the predecessor terminal before life authority moves.
+            // A held projection lock must always mean that a current runner exists,
+            // so release it before the successor makes its one-shot acquisition.
+            runnerLock.close();
+            runnerLock = undefined;
+            try {
+                input.spawnSuccessor?.(successorExecutionId);
+            }
+            catch (error) {
+                store.verdictIfOpen({
+                    executionId: successorExecutionId,
+                    verdict: "launch-failed",
+                    facts: {
+                        stage: "spawn",
+                        detail: `successor runner spawn failed: ${errorDetail(error)}`,
+                    },
+                });
+            }
+            return { status: "handed-off", successorExecutionId };
+        }
+        const verdict = store.verdictIfOpen({
+            executionId: input.executionId,
+            verdict: execution.verdict,
+            facts: execution.facts,
+        });
+        if (verdict.status !== "committed")
+            return { status: "rejected" };
+        settled = true;
+        return { status: "completed" };
+    }
+    catch (error) {
+        if (adopted && !settled) {
+            store.verdictIfOpen({
+                executionId: input.executionId,
+                verdict: "failed",
+                facts: {
+                    failedAt: new Date(now()).toISOString(),
+                    detail: error instanceof Error ? error.message : String(error),
+                },
+            });
+        }
+        throw error;
+    }
+    finally {
+        try {
+            runnerLock?.close();
+        }
+        finally {
+            store.close();
+        }
+    }
+}

package/build/core/projection-generation-runtime.js

@@ -0,0 +1,15 @@
+import { executeProjectionGeneration } from "./projection-generation-execution.js";
+import { spawnProjectionGenerationRunner } from "./projection-generation-process.js";
+import { runProjectionGeneration } from "./projection-generation-runner.js";
+import { snapshotPendingTells } from "./projection-generation-continuation.js";
+export async function runProjectionGenerationRuntime(projectionDirectory, executionId) {
+    await runProjectionGeneration({
+        projectionDirectory,
+        executionId,
+        execute: (launch) => executeProjectionGeneration(projectionDirectory, launch),
+        snapshotPendingTells: () => snapshotPendingTells(projectionDirectory),
+        spawnSuccessor: (successorExecutionId) => {
+            spawnProjectionGenerationRunner(projectionDirectory, successorExecutionId);
+        },
+    });
+}