@astrosheep/keiyaku 2.9.13 → 4.0.1

package/build/src/akuma/body.js

@@ -0,0 +1,417 @@
+import { fileURLToPath } from "node:url";
+import { HeldAkumaLeash, appendActivity, beginTurn, breakBody, endTurn, finishBodyIfIdle, heartExists, pauseRequested, readHeart, recordBody, recordSession, recordTellDeliveries, recordTellReceipt, stopRequested, } from "./heart/index.js";
+import { encodeAgentEvent } from "./provider.js";
+import { providerNamed } from "./providers/index.js";
+import { BodyRequestPump, clearBodyRequestTransport, settleBodyRequests, } from "./requests.js";
+import { currentProcessCollar, probeProcessTree, putDownProcessTree, spawnDetachedProcess, } from "../runtime/proc/run.js";
+const LEASH_RETRY_MS = 25;
+function wait(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+function serializeEffects() {
+    let tail = Promise.resolve();
+    return async (effect) => {
+        const before = tail;
+        let release;
+        tail = new Promise((resolve) => { release = resolve; });
+        await before;
+        try {
+            return await effect();
+        }
+        finally {
+            release();
+        }
+    };
+}
+function missing(error) {
+    return error.code === "ENOENT";
+}
+function turnRecipe(paths, soul) {
+    const latest = readHeart(paths).latestSession;
+    const admitted = latest?.provider === soul.provider.name ? latest : undefined;
+    const session = admitted?.coordinate;
+    return {
+        cwd: admitted?.cwd ?? soul.cwd,
+        options: admitted?.options ?? soul.options,
+        ...(session === undefined ? {} : { session }),
+    };
+}
+async function takeLeash(paths) {
+    for (;;) {
+        try {
+            const leash = HeldAkumaLeash.try(paths);
+            if (leash !== null)
+                return leash;
+        }
+        catch (error) {
+            if (missing(error))
+                return null;
+            throw error;
+        }
+        await wait(LEASH_RETRY_MS);
+    }
+}
+async function settlePredecessor(paths) {
+    const predecessor = readHeart(paths).latestBody;
+    if (predecessor === null)
+        return true;
+    const probe = probeProcessTree(predecessor.collar);
+    if (probe.kind === "gone")
+        return true;
+    if (probe.kind === "unverifiable")
+        return false;
+    const evidence = await putDownProcessTree(predecessor.collar);
+    return evidence !== "unavailable" && evidence !== "alive-after-sigkill";
+}
+async function startTurnDrive(input) {
+    const { cwd, options, session } = turnRecipe(input.paths, input.soul);
+    if (session !== undefined && input.adapter.resume === undefined)
+        return { kind: "resume-unsupported" };
+    const turn = beginTurn(input.paths, {
+        bodySequence: input.bodySequence,
+        startedAt: input.now(),
+        ...(input.call === undefined ? {} : { call: input.call }),
+    });
+    const requests = input.soul.confinement.kind === "declared"
+        ? new BodyRequestPump({
+            paths: input.paths,
+            parent: input.soul,
+            bodySequence: input.bodySequence,
+            now: input.now,
+            spawn: input.runtimeSpawn,
+        })
+        : null;
+    try {
+        const driveInput = {
+            body: input.body,
+            launchTells: input.launchTells.map((tell) => ({ id: tell.id, text: tell.body })),
+            cwd,
+            options,
+            ...(requests === null ? {} : { requests: { dir: requests.directory } }),
+        };
+        const selected = session === undefined
+            ? await input.adapter.start({ ...driveInput, session: { kind: "fresh" } })
+            : await input.adapter.resume({ ...driveInput, session: { kind: "resume", coordinate: session } });
+        if (input.launchTells.length > 0) {
+            recordTellDeliveries(input.paths, input.launchTells.map((tell) => ({
+                tellId: tell.id,
+                route: "launch",
+                turnSequence: turn.sequence,
+                fence: selected.admission.fence,
+                deliveredAt: input.now(),
+            })));
+        }
+        if (requests !== null)
+            void selected.completion.then(() => requests.stopAdmission());
+        return { turnSequence: turn.sequence, drive: selected, requests, cwd, options,
+            ...(session === undefined ? {} : { resume: session }) };
+    }
+    catch (error) {
+        if (requests !== null)
+            await requests.close();
+        const diagnostic = error instanceof Error ? error.message : String(error);
+        endTurn(input.paths, {
+            turnSequence: turn.sequence,
+            outcome: { kind: "failed", diagnostic },
+            completedAt: input.now(),
+        });
+        return { kind: "start-failed", turnSequence: turn.sequence, diagnostic };
+    }
+}
+function pumpReceipts(input, turnSequence, drive, writeWitness) {
+    return (async () => {
+        if (drive.receipts === undefined)
+            return;
+        for await (const receipt of drive.receipts) {
+            await writeWitness(() => recordTellReceipt(input.paths, receipt.evidence === "exact"
+                ? { ...receipt, receivedAt: input.now() }
+                : { ...receipt, turnSequence, receivedAt: input.now() }));
+        }
+    })();
+}
+async function submitPendingLiveTells(input, turnSequence, drive, attempted, writeWitness) {
+    if (drive.tell === undefined)
+        return "live";
+    for (const tell of readHeart(input.paths).pending) {
+        if (attempted.has(tell.id))
+            continue;
+        attempted.add(tell.id);
+        const outcome = await writeWitness(async () => {
+            const submission = await drive.tell({ id: tell.id, text: tell.body });
+            if (submission.kind === "turn-ended")
+                return "turn-ended";
+            recordTellDeliveries(input.paths, [{
+                    tellId: tell.id,
+                    route: "live",
+                    turnSequence,
+                    fence: submission.fence,
+                    receipt: drive.receipts === undefined ? "unavailable" : "required",
+                    deliveredAt: input.now(),
+                }]);
+            return "accepted";
+        });
+        if (outcome === "turn-ended")
+            return "turn-ended";
+    }
+    return "live";
+}
+async function consumeTurnDrive(input, active) {
+    const { turnSequence, drive, requests, cwd, options, resume } = active;
+    let turnSession = resume;
+    const attempted = new Set(input.launchTells.map((tell) => tell.id));
+    const writeWitness = serializeEffects();
+    const receiptPump = pumpReceipts(input, turnSequence, drive, writeWitness);
+    const receiptFailure = receiptPump.then(() => new Promise(() => { }), (error) => Promise.reject(error));
+    const iterator = drive.events[Symbol.asyncIterator]();
+    let pending = iterator.next();
+    let liveTells = true;
+    try {
+        for (;;) {
+            if (stopRequested(input.paths, input.bodySequence) || pauseRequested(input.paths)) {
+                const draining = requests?.close();
+                try {
+                    await drive.abort();
+                }
+                finally {
+                    await draining;
+                    await receiptPump;
+                }
+                return { kind: "stopped" };
+            }
+            if (liveTells) {
+                liveTells = await submitPendingLiveTells(input, turnSequence, drive, attempted, writeWitness) === "live";
+            }
+            const next = await Promise.race([
+                pending,
+                wait(LEASH_RETRY_MS).then(() => null),
+                receiptFailure,
+                ...(requests === null ? [] : [requests.failure]),
+            ]);
+            if (next === null)
+                continue;
+            if (next.done)
+                break;
+            const event = next.value;
+            const at = input.now();
+            if (event.type === "session") {
+                turnSession = event.coordinate;
+                recordSession(input.paths, {
+                    provider: input.soul.provider.name,
+                    coordinate: event.coordinate,
+                    cwd,
+                    options,
+                    admittedAt: at,
+                });
+            }
+            appendActivity(input.paths, {
+                turnSequence,
+                event: encodeAgentEvent(event),
+                at,
+            });
+            pending = iterator.next();
+        }
+        const result = await drive.completion;
+        await receiptPump;
+        if (requests !== null)
+            await requests.close();
+        return result.kind === "answered"
+            ? { ...result, ...(turnSession === undefined ? {} : { session: turnSession }) }
+            : result;
+    }
+    catch (error) {
+        const draining = requests?.close();
+        try {
+            await drive.abort();
+        }
+        catch { /* the pump failure owns the turn result */ }
+        try {
+            await receiptPump;
+        }
+        catch { /* preserve the first pump failure */ }
+        try {
+            await draining;
+        }
+        catch { /* preserve the first pump failure */ }
+        return { kind: "failed", diagnostic: error instanceof Error ? error.message : String(error) };
+    }
+}
+async function driveTurn(input) {
+    let active;
+    try {
+        const started = await startTurnDrive(input);
+        if ("kind" in started)
+            return started;
+        active = started;
+    }
+    catch (error) {
+        if (!heartExists(input.paths))
+            return { kind: "heart-gone" };
+        throw error;
+    }
+    try {
+        return { ...await consumeTurnDrive(input, active), turnSequence: active.turnSequence };
+    }
+    catch (error) {
+        const draining = active.requests?.close();
+        if (heartExists(input.paths)) {
+            await draining;
+            return { kind: "failed", diagnostic: error instanceof Error ? error.message : String(error),
+                turnSequence: active.turnSequence };
+        }
+        try {
+            await active.drive.abort();
+        }
+        catch { /* the heart loss still owns shutdown */ }
+        try {
+            await draining;
+        }
+        catch { /* the vanished heart owns the request loss */ }
+        return { kind: "heart-gone" };
+    }
+}
+function bornSoul(launch, leash, now) {
+    const before = readHeart(launch.paths);
+    if (before.soul !== null) {
+        leash.clearPause(launch.paths);
+        return before.soul;
+    }
+    if (launch.seed === undefined)
+        throw new Error("Akuma wake has no born soul");
+    const candidate = { ...launch.seed, createdAt: now };
+    if (leash.birth(launch.paths, candidate, launch.birthSession) === "sealed")
+        return null;
+    const born = readHeart(launch.paths).soul;
+    if (born === null || born.id !== candidate.id) {
+        throw new Error("Akuma birth identity does not match its directory");
+    }
+    return born;
+}
+function launchCwd(launch) {
+    if (launch.seed !== undefined)
+        return launch.seed.cwd;
+    const snapshot = readHeart(launch.paths);
+    const soul = snapshot.soul;
+    if (soul === null)
+        throw new Error("Akuma wake has no born soul");
+    return snapshot.latestSession?.provider === soul.provider.name
+        ? snapshot.latestSession.cwd
+        : soul.cwd;
+}
+function persistTurn(paths, turnSequence, result, completedAt) {
+    endTurn(paths, {
+        turnSequence,
+        outcome: result.kind === "answered" && result.session !== undefined
+            ? { kind: "answered", historyId: result.historyId, session: result.session, answer: result.answer }
+            : result.kind === "answered"
+                ? { kind: "failed", diagnostic: "Provider answered without a resumable session" }
+                : { kind: "failed", diagnostic: result.diagnostic },
+        completedAt,
+    });
+    return result.kind === "answered" && result.session === undefined ? "failed" : result.kind;
+}
+function defaultRuntime() {
+    return {
+        collar: currentProcessCollar(),
+        now: () => new Date().toISOString(),
+        putDownOwnTree: async (collar) => { await putDownProcessTree(collar); },
+        spawnChild: async (launch) => await spawnAkumaBody(launch),
+    };
+}
+function childSpawner(runtime) {
+    return runtime.spawnChild ?? spawnAkumaBody;
+}
+async function beginBody(paths, soul, leash, runtime) {
+    if (!await settlePredecessor(paths))
+        return null;
+    leash.settleStop(paths);
+    const body = recordBody(paths, { collar: runtime.collar, leashTakenAt: runtime.now() });
+    const requests = await settleBodyRequests(paths, soul, runtime.now);
+    clearBodyRequestTransport(paths);
+    if (requests === "settled")
+        return body;
+    breakBody(paths, { sequence: body.sequence, end: "broke-off", at: runtime.now() });
+    return null;
+}
+export async function driveAkumaBody(launch, adapter, runtime = defaultRuntime()) {
+    const leash = await takeLeash(launch.paths);
+    if (leash === null)
+        return;
+    try {
+        const soul = bornSoul(launch, leash, runtime.now());
+        if (soul === null)
+            return;
+        const selected = adapter ?? providerNamed(soul.provider);
+        const body = await beginBody(launch.paths, soul, leash, runtime);
+        if (body === null)
+            return;
+        let initial = launch.initialBody;
+        for (;;) {
+            const snapshot = readHeart(launch.paths);
+            const launchTells = snapshot.pending;
+            if (initial === undefined && launchTells.length === 0) {
+                const finished = finishBodyIfIdle(launch.paths, { sequence: body.sequence, at: runtime.now() });
+                if (finished.kind === "finished")
+                    return;
+                continue;
+            }
+            const result = await driveTurn({
+                paths: launch.paths,
+                soul,
+                adapter: selected,
+                bodySequence: body.sequence,
+                runtimeSpawn: childSpawner(runtime),
+                body: initial ?? "",
+                ...(initial === undefined ? {} : { call: initial }),
+                launchTells,
+                now: runtime.now,
+            });
+            if (result.kind === "heart-gone") {
+                await runtime.putDownOwnTree(runtime.collar);
+                return;
+            }
+            if (result.kind === "stopped") {
+                breakBody(launch.paths, { sequence: body.sequence, end: "put-down", at: runtime.now() });
+                return;
+            }
+            if (result.kind === "resume-unsupported") {
+                breakBody(launch.paths, { sequence: body.sequence, end: "broke-off", at: runtime.now() });
+                return;
+            }
+            if (result.kind === "start-failed") {
+                breakBody(launch.paths, { sequence: body.sequence, end: "broke-off", at: runtime.now() });
+                return;
+            }
+            if (persistTurn(launch.paths, result.turnSequence, result, runtime.now()) === "failed") {
+                breakBody(launch.paths, { sequence: body.sequence, end: "broke-off", at: runtime.now() });
+                return;
+            }
+            initial = undefined;
+        }
+    }
+    catch (error) {
+        if (heartExists(launch.paths))
+            throw error;
+        await runtime.putDownOwnTree(runtime.collar);
+    }
+    finally {
+        leash.release();
+    }
+}
+export async function spawnAkumaBody(launch) {
+    const encoded = Buffer.from(JSON.stringify(launch), "utf8").toString("base64url");
+    return await spawnDetachedProcess({
+        argv: [process.execPath, ...process.execArgv, fileURLToPath(import.meta.url), encoded],
+        cwd: launchCwd(launch),
+        log: launch.paths.log,
+    });
+}
+async function main() {
+    const encoded = process.argv[2];
+    if (encoded === undefined)
+        throw new TypeError("Akuma body launch payload is missing");
+    const launch = JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+    await driveAkumaBody(launch);
+}
+if (process.argv[1] !== undefined && fileURLToPath(import.meta.url) === process.argv[1]) {
+    await main();
+}

package/build/src/akuma/coordinate.d.ts

@@ -0,0 +1,9 @@
+export type ResumeCoordinate = Readonly<{
+    sessionId: string;
+    sessionFile?: never;
+}> | Readonly<{
+    sessionFile: string;
+    sessionId?: string;
+}>;
+export declare function decodeResumeCoordinate(value: unknown): ResumeCoordinate | null;
+export declare function encodeResumeCoordinate(coordinate: ResumeCoordinate): unknown;

package/build/src/akuma/coordinate.js

@@ -0,0 +1,22 @@
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value : null;
+}
+export function decodeResumeCoordinate(value) {
+    const coordinate = record(value);
+    if (coordinate === null)
+        return null;
+    const keys = Object.keys(coordinate);
+    if (typeof coordinate.sessionFile === "string" && coordinate.sessionFile.trim().length > 0
+        && (coordinate.sessionId === undefined || (typeof coordinate.sessionId === "string" && coordinate.sessionId.trim().length > 0))
+        && keys.every((key) => key === "sessionFile" || key === "sessionId")) {
+        return { sessionFile: coordinate.sessionFile, ...(coordinate.sessionId === undefined ? {} : { sessionId: coordinate.sessionId }) };
+    }
+    return typeof coordinate.sessionId === "string" && coordinate.sessionId.trim().length > 0 && keys.length === 1
+        ? { sessionId: coordinate.sessionId } : null;
+}
+export function encodeResumeCoordinate(coordinate) {
+    return "sessionFile" in coordinate
+        ? { sessionFile: coordinate.sessionFile, ...(coordinate.sessionId === undefined ? {} : { sessionId: coordinate.sessionId }) }
+        : { sessionId: coordinate.sessionId };
+}

package/build/src/akuma/heart/facts.d.ts

@@ -0,0 +1,202 @@
+import type { AkuId } from "../identity.js";
+import type { ResumeCoordinate } from "../coordinate.js";
+export type { ResumeCoordinate } from "../coordinate.js";
+export type Confinement = Readonly<{
+    kind: "unconfined";
+}> | Readonly<{
+    kind: "declared";
+    writableRoots: readonly string[];
+}>;
+export type ProviderOptions = Readonly<{
+    model?: string;
+    effort?: string;
+    access?: "read" | "write" | "auto";
+    network?: "disabled" | "enabled";
+    systemPrompt?: string;
+}>;
+export type ProviderExecution = Readonly<{
+    name: string;
+    kind: "claude-agent-sdk" | "codex-app-server" | "opencode-sdk" | "pi";
+    executable?: string;
+    config?: Readonly<Record<string, unknown>>;
+    env?: Readonly<Record<string, string>>;
+}>;
+export type AkumaOrigin = Readonly<{
+    kind: "direct";
+}> | Readonly<{
+    kind: "request";
+    parent: AkuId;
+    requestId: string;
+}> | Readonly<{
+    kind: "fork";
+    parent: AkuId;
+    at: string;
+}>;
+export type Soul = Readonly<{
+    id: AkuId;
+    archetype: string;
+    description?: string;
+    provider: ProviderExecution;
+    options: ProviderOptions;
+    cwd: string;
+    origin: AkumaOrigin;
+    confinement: Confinement;
+    createdAt: string;
+}>;
+export type RequestRecipe = Pick<Soul, "description" | "provider" | "options" | "confinement">;
+export type Collar = Readonly<{
+    pid: number;
+    processGroup: number;
+    spawnedAt: string;
+}>;
+export type BodyEnd = "exited" | "broke-off" | "put-down";
+export type BodyFact = Readonly<{
+    sequence: number;
+    collar: Collar;
+    leashTakenAt: string;
+    end?: BodyEnd;
+    endedAt?: string;
+}>;
+export type SessionFact = Readonly<{
+    sequence: number;
+    provider: string;
+    coordinate: ResumeCoordinate;
+    cwd: string;
+    options: ProviderOptions;
+    admittedAt: string;
+}>;
+export type ForkPoint = Readonly<{
+    historyId: string;
+    session: ResumeCoordinate;
+    provider: string;
+    cwd: string;
+    options: ProviderOptions;
+}>;
+export type TurnOutcome = Readonly<{
+    kind: "answered";
+    historyId: string;
+    session: ResumeCoordinate;
+    answer: string;
+}> | Readonly<{
+    kind: "failed";
+    diagnostic: string;
+}>;
+export type TurnStartFact = Readonly<{
+    kind: "turn-start";
+    sequence: number;
+    bodySequence: number;
+    startedAt: string;
+}>;
+export type TurnEndFact = Readonly<{
+    kind: "turn-end";
+    sequence: number;
+    turnSequence: number;
+    outcome: TurnOutcome;
+    completedAt: string;
+}>;
+export type TurnFact = TurnStartFact & Readonly<{
+    end?: TurnEndFact;
+}>;
+export type CallFact = Readonly<{
+    kind: "call";
+    sequence: number;
+    turnSequence: number;
+    body: string;
+    at: string;
+}>;
+export type TellDelivery = Readonly<{
+    turnSequence: number;
+    route: "launch" | "live";
+    receipt?: "unavailable" | "required";
+    deliveredAt: string;
+}>;
+export type TellFact = Readonly<{
+    kind: "tell";
+    sequence: number;
+    id: string;
+    body: string;
+    recordedAt: string;
+    state: "pending" | "told";
+    deliveries: readonly TellDelivery[];
+}>;
+export type TellDeliveryInput = Readonly<{
+    tellId: string;
+    turnSequence: number;
+    fence: string;
+    deliveredAt: string;
+}> & (Readonly<{
+    route: "launch";
+}> | Readonly<{
+    route: "live";
+    receipt: "unavailable" | "required";
+}>);
+export type TellReceiptInput = Readonly<{
+    kind: string;
+    receivedAt: string;
+}> & (Readonly<{
+    evidence: "exact";
+    tellId: string;
+}> | Readonly<{
+    evidence: "fence";
+    turnSequence: number;
+    fence: string;
+}>);
+export type RequestInput = Readonly<{
+    id: string;
+    archetype: string;
+    body: string;
+    cwd?: string;
+    world: string;
+    recipe: RequestRecipe;
+}>;
+export type RequestFact = RequestInput & Readonly<{
+    admittedAt: string;
+}> & (Readonly<{
+    state: "admitted";
+}> | Readonly<{
+    state: "reserved";
+    child: AkuId;
+}> | Readonly<{
+    state: "served";
+    child: AkuId;
+}> | Readonly<{
+    state: "refused";
+    diagnostic: string;
+}> | Readonly<{
+    state: "voided";
+    evidence: string;
+}>);
+export type KillEvidence = "killed" | "already-killed" | "alive-after-sigkill" | "unavailable";
+export type KillFact = Readonly<{
+    sequence: number;
+    bodySequence: number;
+    evidence: "killed";
+    at: string;
+}>;
+export type StopFact = Readonly<{
+    bodySequence: number;
+    requestedAt: string;
+}>;
+export type SealFact = Readonly<{
+    evidence: string;
+    at: string;
+}>;
+export type LeashProbe = "held" | "free";
+export type CollarProbe = Readonly<{
+    kind: "gone";
+    end: BodyEnd | null;
+}> | Readonly<{
+    kind: "alive";
+}> | Readonly<{
+    kind: "unverifiable";
+    diagnostic: string;
+}>;
+export type AkumaLife = "running" | "asleep" | "stranded" | "headless" | "killed";
+export type HeartSnapshot = Readonly<{
+    soul: Soul | null;
+    latestBody: BodyFact | null;
+    latestSession: SessionFact | null;
+    pending: readonly TellFact[];
+    latestKill: KillFact | null;
+}>;
+export declare function life(leashProbe: LeashProbe, collarProbe: CollarProbe, latestBody: BodyFact | null, latestKill: KillFact | null): AkumaLife;

package/build/src/akuma/heart/facts.js

@@ -0,0 +1,9 @@
+export function life(leashProbe, collarProbe, latestBody, latestKill) {
+    if (leashProbe === "held")
+        return "running";
+    if (collarProbe.kind !== "gone")
+        return "headless";
+    if (latestBody !== null && latestKill?.bodySequence === latestBody.sequence)
+        return "killed";
+    return collarProbe.end === "exited" ? "asleep" : "stranded";
+}