@astrosheep/keiyaku 2.9.13 → 4.0.0

package/build/src/akuma/archetype.js

@@ -0,0 +1,188 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parseDocument } from "yaml";
+import { archetypeName } from "./identity.js";
+import { decodeProviderOptions } from "./provider.js";
+import { decodeProviderExecution, providerNamed } from "./providers/index.js";
+export class AkumaArchetypeError extends Error {
+    archetype;
+    searched;
+    reason;
+    kind = "akuma-archetype";
+    constructor(archetype, searched, reason) {
+        super(`Akuma archetype ${archetype} ${reason}\n${searched.map((path) => `searched ${path}`).join("\n")}`);
+        this.archetype = archetype;
+        this.searched = searched;
+        this.reason = reason;
+        this.name = "AkumaArchetypeError";
+    }
+}
+function archetypeDirectory(settings) {
+    const userPath = settings.scopes.user.path;
+    return userPath === undefined ? null : join(dirname(userPath), "akuma");
+}
+export function listArchetypes(input) {
+    const directory = archetypeDirectory(input.settings);
+    if (directory === null)
+        return [];
+    try {
+        return readdirSync(directory, { withFileTypes: true })
+            .flatMap((entry) => {
+            if (!entry.isFile())
+                return [];
+            const filename = entry.name;
+            if (!filename.endsWith(".md"))
+                return [];
+            const name = filename.slice(0, -3);
+            try {
+                return [archetypeName(name)];
+            }
+            catch {
+                return [];
+            }
+        })
+            .sort((left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right)));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+}
+function archetypeField(values, key, required = false) {
+    const value = values[key];
+    if (value === undefined && !required)
+        return undefined;
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new TypeError(`Archetype ${key} must be a nonblank string`);
+    }
+    return value;
+}
+function archetypeEnum(values, key, allowed) {
+    const value = archetypeField(values, key);
+    if (value === undefined)
+        return undefined;
+    if (!allowed.includes(value))
+        throw new TypeError(`Archetype ${key} must be one of ${allowed.join(", ")}`);
+    return value;
+}
+function decodeArchetype(name, path, markdown) {
+    const lines = markdown.split(/\r?\n/u);
+    if (lines[0]?.trim() !== "---")
+        throw new TypeError("Archetype must begin with YAML frontmatter");
+    const closing = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+    if (closing < 0)
+        throw new TypeError("Archetype frontmatter is not closed");
+    const document = parseDocument(lines.slice(1, closing).join("\n"), { uniqueKeys: true });
+    if (document.errors.length > 0)
+        throw new TypeError(`Archetype frontmatter is invalid: ${document.errors[0].message}`);
+    const decoded = document.toJS();
+    if (decoded === null || typeof decoded !== "object" || Array.isArray(decoded)) {
+        throw new TypeError("Archetype frontmatter must be one mapping");
+    }
+    const values = decoded;
+    const provider = archetypeField(values, "provider", true);
+    const model = archetypeField(values, "model");
+    const effort = archetypeField(values, "effort");
+    const access = archetypeEnum(values, "access", ["read", "write", "auto"]);
+    const network = archetypeEnum(values, "network", ["disabled", "enabled"]);
+    const description = archetypeField(values, "description");
+    const systemPrompt = lines.slice(closing + 1).join("\n");
+    return Object.freeze({
+        name,
+        path,
+        provider,
+        ...(description === undefined ? {} : { description }),
+        options: decodeProviderOptions({
+            ...(model === undefined ? {} : { model }),
+            ...(effort === undefined ? {} : { effort }),
+            ...(access === undefined ? {} : { access }),
+            ...(network === undefined ? {} : { network }),
+            systemPrompt,
+        }),
+    });
+}
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value : null;
+}
+function optionalProviderText(value, name, field) {
+    const selected = value[field];
+    if (selected === undefined)
+        return undefined;
+    if (typeof selected !== "string" || selected.trim().length === 0) {
+        throw new TypeError(`provider ${name} ${field} must be a nonblank string`);
+    }
+    return selected;
+}
+function configuredProvider(name, selected) {
+    const value = record(selected);
+    if (value === null)
+        throw new TypeError(`provider ${name} must be an object`);
+    const unknown = Object.keys(value).find((key) => !["kind", "description", "executable", "config", "env"].includes(key));
+    if (unknown !== undefined)
+        throw new TypeError(`provider ${name} has unknown field ${unknown}`);
+    optionalProviderText(value, name, "description");
+    return decodeProviderExecution({
+        name,
+        kind: value.kind,
+        ...(value.executable === undefined ? {} : { executable: value.executable }),
+        ...(value.config === undefined ? {} : { config: value.config }),
+        ...(value.env === undefined ? {} : { env: value.env }),
+    });
+}
+function providerExecution(settings, name) {
+    const view = settings.namespace("providers");
+    if (view.kind === "failed")
+        throw new TypeError(view.failures.map((failure) => `${failure.scope}: ${failure.diagnostic}`).join("; "));
+    const selected = view.entries.find((entry) => entry.name === name)?.value;
+    if (selected !== undefined)
+        return configuredProvider(name, selected);
+    if (name === "claude")
+        return Object.freeze({ name, kind: "claude-agent-sdk" });
+    if (name === "codex-app-server")
+        return Object.freeze({ name, kind: "codex-app-server" });
+    throw new TypeError(`unknown provider ${name}`);
+}
+function admitArchetype(archetype, settings) {
+    let execution;
+    try {
+        execution = providerExecution(settings, archetype.provider);
+    }
+    catch (error) {
+        if (error instanceof TypeError)
+            throw new AkumaArchetypeError(archetype.name, [archetype.path], `uses ${error.message}`);
+        throw error;
+    }
+    const adapter = providerNamed(execution);
+    const admission = adapter.admitOptions(archetype.options);
+    if (admission.kind === "refused") {
+        throw new AkumaArchetypeError(archetype.name, [archetype.path], `is unsupported: ${admission.diagnostic}`);
+    }
+    return Object.freeze({ ...archetype, provider: execution, adapter, options: admission.options });
+}
+export function loadArchetype(input) {
+    const name = archetypeName(input.name);
+    const directory = archetypeDirectory(input.settings);
+    if (directory === null)
+        throw new AkumaArchetypeError(name, [], "has no user Settings coordinate");
+    const path = join(directory, `${name}.md`);
+    let markdown;
+    try {
+        markdown = readFileSync(path, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new AkumaArchetypeError(name, [path], "was not found");
+        }
+        throw new AkumaArchetypeError(name, [path], `could not be read: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    try {
+        return admitArchetype(decodeArchetype(name, path, markdown), input.settings);
+    }
+    catch (error) {
+        if (error instanceof AkumaArchetypeError)
+            throw error;
+        throw new AkumaArchetypeError(name, [path], `is invalid: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

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

@@ -0,0 +1,20 @@
+import { type SessionFact, type Soul } from "./heart/index.js";
+import type { AkumaPaths } from "./identity.js";
+import { type ProviderAdapter } from "./provider.js";
+import { type RequestChildLaunch } from "./requests.js";
+import { type ProcessCollar } from "../runtime/proc/run.js";
+export type BodyLaunch = Readonly<{
+    paths: AkumaPaths;
+    seed?: Omit<Soul, "createdAt">;
+    birthSession?: Omit<SessionFact, "sequence">;
+    initialBody?: string;
+}>;
+type BodyRuntime = Readonly<{
+    collar: ProcessCollar;
+    now(): string;
+    putDownOwnTree(collar: ProcessCollar): Promise<void>;
+    spawnChild?(launch: RequestChildLaunch): Promise<ProcessCollar>;
+}>;
+export declare function driveAkumaBody(launch: BodyLaunch, adapter?: ProviderAdapter, runtime?: BodyRuntime): Promise<void>;
+export declare function spawnAkumaBody(launch: BodyLaunch): Promise<ProcessCollar>;
+export {};

package/build/src/akuma/body.js

@@ -0,0 +1,305 @@
+import { fileURLToPath } from "node:url";
+import { HeldAkumaLeash, advanceTell, appendActivity, breakBody, clearAbandonedControl, finishBodyIfIdle, heartExists, pauseRequested, readHeart, recordBody, recordSession, recordTurn, stopRequested, } from "./heart/index.js";
+import { encodeAgentEvent } from "./provider.js";
+import { providerNamed } from "./providers/index.js";
+import { BodyRequestPump, 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 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);
+    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 drive = await input.adapter.start({
+            prompt: input.prompt,
+            cwd,
+            options,
+            ...(session === undefined ? {} : { session }),
+            ...(requests === null ? {} : { requests: { dir: requests.directory } }),
+        });
+        if (requests !== null)
+            void drive.completion.then(() => requests.stopAdmission());
+        return { drive, requests, cwd, options, ...(session === undefined ? {} : { session }) };
+    }
+    catch (error) {
+        if (requests !== null)
+            await requests.close();
+        throw error;
+    }
+}
+async function consumeTurnDrive(input, active) {
+    const { drive, requests, cwd, options, session } = active;
+    let turnSession = session;
+    let entered = false;
+    const iterator = drive.events[Symbol.asyncIterator]();
+    let pending = iterator.next();
+    for (;;) {
+        if (stopRequested(input.paths) || pauseRequested(input.paths)) {
+            const draining = requests?.close();
+            try {
+                await drive.abort();
+            }
+            finally {
+                await draining;
+            }
+            return { kind: "stopped" };
+        }
+        const next = await Promise.race([
+            pending,
+            wait(LEASH_RETRY_MS).then(() => null),
+            ...(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, {
+            bodySequence: input.bodySequence,
+            event: encodeAgentEvent(event),
+            at,
+        });
+        if (!entered && input.tellId !== undefined) {
+            entered = true;
+            advanceTell(input.paths, input.tellId, "seen");
+            advanceTell(input.paths, input.tellId, "consumed");
+        }
+        pending = iterator.next();
+    }
+    const result = await drive.completion;
+    if (requests !== null)
+        await requests.close();
+    if (!entered && result.kind === "answered" && input.tellId !== undefined) {
+        advanceTell(input.paths, input.tellId, "seen");
+        advanceTell(input.paths, input.tellId, "consumed");
+    }
+    return result.kind === "answered"
+        ? { ...result, ...(turnSession === undefined ? {} : { session: turnSession }) }
+        : result;
+}
+async function driveTurn(input) {
+    const active = await startTurnDrive(input);
+    try {
+        return await consumeTurnDrive(input, active);
+    }
+    catch (error) {
+        const draining = active.requests?.close();
+        if (heartExists(input.paths)) {
+            await draining;
+            throw error;
+        }
+        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.death !== null)
+        return null;
+    if (before.soul !== null) {
+        clearAbandonedControl(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, bodySequence, result, completedAt) {
+    recordTurn(paths, {
+        bodySequence,
+        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, runtime) {
+    if (!await settlePredecessor(paths))
+        return null;
+    const body = recordBody(paths, { collar: runtime.collar, leashTakenAt: runtime.now() });
+    if (await settleBodyRequests(paths, soul, runtime.now) === "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, runtime);
+        if (body === null)
+            return;
+        let initial = launch.initialBody;
+        for (;;) {
+            const snapshot = readHeart(launch.paths);
+            if (snapshot.death !== null) {
+                breakBody(launch.paths, { sequence: body.sequence, end: "put-down", at: runtime.now() });
+                return;
+            }
+            const tell = initial === undefined ? snapshot.pending[0] : undefined;
+            const prompt = initial ?? tell?.body;
+            if (prompt === undefined) {
+                const finished = finishBodyIfIdle(launch.paths, { sequence: body.sequence, at: runtime.now() });
+                if (finished.kind === "finished")
+                    return;
+                continue;
+            }
+            if (tell !== undefined)
+                advanceTell(launch.paths, tell.id, "delivered");
+            const result = await driveTurn({
+                paths: launch.paths,
+                soul,
+                adapter: selected,
+                bodySequence: body.sequence,
+                runtimeSpawn: childSpawner(runtime),
+                prompt,
+                ...(tell === undefined ? {} : { tellId: tell.id }),
+                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 (persistTurn(launch.paths, body.sequence, 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/heart/facts.d.ts

@@ -0,0 +1,150 @@
+import type { AkuId } from "../identity.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";
+    executable?: string;
+    config?: Readonly<Record<string, unknown>>;
+    env?: Readonly<Record<string, string>>;
+}>;
+export type AkumaOrigin = Readonly<{
+    kind: "direct";
+}> | Readonly<{
+    kind: "request";
+    parentId: 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 ResumeCoordinate = Readonly<{
+    sessionId: 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 TurnFact = Readonly<{
+    sequence: number;
+    bodySequence: number;
+    outcome: TurnOutcome;
+    completedAt: string;
+}>;
+export type TellState = "recorded" | "delivered" | "seen" | "consumed" | "voided-by-death";
+export type TellFact = Readonly<{
+    id: string;
+    body: string;
+    state: TellState;
+    recordedAt: 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-dead" | "alive-after-sigkill" | "unavailable";
+export type DeathFact = Readonly<{
+    evidence: KillEvidence;
+    at: 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" | "dead";
+export type HeartSnapshot = Readonly<{
+    soul: Soul | null;
+    latestBody: BodyFact | null;
+    latestSession: SessionFact | null;
+    pending: readonly TellFact[];
+    death: DeathFact | null;
+}>;
+export declare function life(leashProbe: LeashProbe, collarProbe: CollarProbe, deathRow: DeathFact | null): AkumaLife;

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

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