@astrosheep/keiyaku 2.8.4 → 2.9.0

package/build/core/call/context.js

@@ -0,0 +1,238 @@
+import * as fs from "fs/promises";
+import { FlowError } from "../../flow-error.js";
+import { isGitRepo } from "../../git/branches.js";
+import { createGit, wrapGitError } from "../../git/core.js";
+import { AddressResolutionError, buildResolutionAttempt, buildUncommissionedAddress, buildUncommissionedRepositoryAddress, resolveContractAddress, withResolvedAddress, } from "../addressing.js";
+import { findOpenArcView } from "../arc.js";
+import { readLedger } from "../ledger.js";
+import { deriveContractState, isTerminalState } from "../status/lifecycle.js";
+import { contractPresentedByWorktree, contractWorktreePathFromBind, stableRepoRoot } from "../worktree-path.js";
+async function findWorktreePathForContract(cwd, contractId) {
+    const git = createGit(cwd);
+    let output;
+    try {
+        output = await git.raw(["worktree", "list", "--porcelain"]);
+    }
+    catch (error) {
+        throw wrapGitError("worktree list --porcelain", error, cwd);
+    }
+    let currentPath;
+    for (const line of output.split(/\r?\n/)) {
+        if (line.startsWith("worktree ")) {
+            currentPath = line.slice("worktree ".length);
+            continue;
+        }
+        if (line === `branch refs/heads/keiyaku/${contractId}`) {
+            return currentPath;
+        }
+    }
+    return undefined;
+}
+async function resolveWorkspaceCwd(cwd, contractId, bind) {
+    const repoRoot = cwd;
+    if (bind.data.workspace === "here")
+        return repoRoot;
+    const listedWorktreePath = await findWorktreePathForContract(cwd, contractId);
+    const worktreePath = listedWorktreePath ?? await contractWorktreePathFromBind(repoRoot, contractId, bind);
+    let stat;
+    try {
+        stat = await fs.stat(worktreePath);
+    }
+    catch (error) {
+        throw new FlowError("INTERNAL_STATE", `contract ${contractId} worktree not found at ${worktreePath}`, { cause: error });
+    }
+    if (!stat.isDirectory()) {
+        throw new FlowError("INTERNAL_STATE", `contract ${contractId} worktree path is not a directory: ${worktreePath}`);
+    }
+    return worktreePath;
+}
+export async function readCallKeiyakuContext(executionCwd, input) {
+    const ledgerCandidate = input.repoCwd ?? executionCwd;
+    const isRepo = await isGitRepo(ledgerCandidate);
+    if (!isRepo) {
+        if (input.bare && input.contractId) {
+            const asTyped = input.contractAddressSource === "at-address"
+                ? `@${input.contractId}`
+                : `--contract ${input.contractId}`;
+            throw new AddressResolutionError("EMPTY_PARAM", `commission address ${asTyped} cannot be combined with --bare`, buildResolutionAttempt({
+                repo: { kind: "user" },
+                workdir: executionCwd,
+                spelling: {
+                    asTyped,
+                    source: input.contractAddressSource ?? "explicit-flag",
+                },
+            }));
+        }
+        if (input.contractId) {
+            const asTyped = input.contractAddressSource === "at-address"
+                ? `@${input.contractId}`
+                : `--contract ${input.contractId}`;
+            throw new AddressResolutionError("EMPTY_PARAM", `${asTyped} is a commission address, but ${ledgerCandidate} has no repository ledger; contract addressing requires a ledger`, buildResolutionAttempt({
+                repo: { kind: "user" },
+                workdir: executionCwd,
+                spelling: {
+                    asTyped,
+                    source: input.contractAddressSource ?? "explicit-flag",
+                },
+            }));
+        }
+        return {
+            activeKeiyaku: false,
+            effectiveCwd: executionCwd,
+            historyCwd: executionCwd,
+            profileCwd: executionCwd,
+            projectionCwd: executionCwd,
+            address: buildUncommissionedAddress({
+                repo: { kind: "user" },
+                workdir: executionCwd,
+                binding: "bare",
+            }),
+        };
+    }
+    const ledgerCwd = await stableRepoRoot(ledgerCandidate);
+    if (input.reviveBinding) {
+        if (input.reviveBinding.kind === "commission") {
+            input.contractId = input.reviveBinding.commissionId;
+            input.contractAddressSource = "artifact-provenance";
+        }
+        else {
+            return {
+                activeKeiyaku: false,
+                effectiveCwd: executionCwd,
+                historyCwd: ledgerCwd,
+                profileCwd: ledgerCwd,
+                projectionCwd: ledgerCwd,
+                address: buildUncommissionedRepositoryAddress({
+                    stableRoot: ledgerCwd,
+                    workdir: executionCwd,
+                    binding: input.reviveBinding.kind,
+                }),
+            };
+        }
+    }
+    if (input.bare && input.contractId) {
+        const repositoryAddress = buildUncommissionedRepositoryAddress({
+            stableRoot: ledgerCwd,
+            workdir: executionCwd,
+            binding: "bare",
+        });
+        const asTyped = input.contractAddressSource === "at-address"
+            ? `@${input.contractId}`
+            : `--contract ${input.contractId}`;
+        throw new AddressResolutionError("EMPTY_PARAM", `commission address ${asTyped} cannot be combined with --bare`, buildResolutionAttempt({
+            repo: repositoryAddress.repo,
+            workdir: repositoryAddress.workdir,
+            spelling: {
+                asTyped,
+                source: input.contractAddressSource ?? "explicit-flag",
+            },
+        }));
+    }
+    if (input.bare) {
+        return {
+            activeKeiyaku: false,
+            effectiveCwd: executionCwd,
+            historyCwd: ledgerCwd,
+            profileCwd: ledgerCwd,
+            projectionCwd: ledgerCwd,
+            address: buildUncommissionedRepositoryAddress({
+                stableRoot: ledgerCwd,
+                workdir: executionCwd,
+                binding: "bare",
+            }),
+        };
+    }
+    let address;
+    if (input.contractId) {
+        address = await resolveContractAddress(ledgerCwd, input.contractId, input.contractAddressSource);
+    }
+    else if (await isGitRepo(executionCwd)) {
+        const executionRepo = await stableRepoRoot(executionCwd);
+        if (input.repoCwd && executionRepo !== ledgerCwd) {
+            const presented = await contractPresentedByWorktree(executionCwd);
+            if (presented) {
+                throw new FlowError("EMPTY_PARAM", `cross-repository contract-worktree addressing is pending: -C presents @${presented} from ${executionRepo}, but --repo selects ${ledgerCwd}`);
+            }
+        }
+        else {
+            const presented = await contractPresentedByWorktree(executionCwd);
+            if (presented) {
+                address = await resolveContractAddress(ledgerCwd, presented, "worktree-presented");
+            }
+        }
+    }
+    if (!address) {
+        try {
+            address = await resolveContractAddress(ledgerCwd);
+        }
+        catch (error) {
+            if (error instanceof AddressResolutionError
+                && error.code === "EMPTY_PARAM"
+                && error.attempt.expected === "commission"
+                && error.attempt.candidates.length === 0) {
+                return {
+                    activeKeiyaku: false,
+                    effectiveCwd: executionCwd,
+                    historyCwd: ledgerCwd,
+                    profileCwd: ledgerCwd,
+                    projectionCwd: ledgerCwd,
+                    address: buildUncommissionedRepositoryAddress({
+                        stableRoot: ledgerCwd,
+                        workdir: executionCwd,
+                        binding: "unbound",
+                    }),
+                };
+            }
+            throw error;
+        }
+    }
+    return await withResolvedAddress(address, async () => {
+        const contractId = address.binding.commissionId;
+        const ledger = await readLedger(ledgerCwd, contractId);
+        if (!ledger) {
+            throw new FlowError("INTERNAL_STATE", `contract ${contractId} not found or not active`);
+        }
+        const state = deriveContractState(ledger.entries);
+        if (state.state === "corrupt") {
+            throw new FlowError("INTERNAL_STATE", `contract ${contractId} is corrupt at entry ${state.at}: ${state.reason}`);
+        }
+        if (isTerminalState(state)) {
+            throw new FlowError("EMPTY_PARAM", `commission ${contractId} is terminal and cannot launch an Akuma`);
+        }
+        const bind = ledger.entries.find((entry) => entry.kind === "bind");
+        if (!bind) {
+            throw new FlowError("INTERNAL_STATE", `contract ${contractId} active ledger is missing bind entry`);
+        }
+        const effectiveCwd = await resolveWorkspaceCwd(ledgerCwd, contractId, bind);
+        const executionAddress = { ...address, workdir: effectiveCwd };
+        const openArc = findOpenArcView(ledger.entries);
+        const currentIntent = openArc
+            ? {
+                source: "arc",
+                arc: openArc.arc,
+                title: openArc.title,
+                objective: openArc.objective,
+                brief: openArc.brief,
+            }
+            : ledger.entries.some((entry) => entry.kind === "arc")
+                ? undefined
+                : {
+                    source: "bind",
+                    arc: 0,
+                    name: bind.data.name,
+                    objective: bind.data.objective,
+                    scope: bind.data.scope,
+                    checks: bind.data.checks,
+                    extensions: bind.data.extensions,
+                };
+        return {
+            activeKeiyaku: true,
+            effectiveCwd,
+            historyCwd: ledgerCwd,
+            profileCwd: effectiveCwd,
+            projectionCwd: ledgerCwd,
+            currentIntent,
+            address: executionAddress,
+        };
+    });
+}

package/build/core/call/execution.js

@@ -0,0 +1,217 @@
+import { buildCallTerms } from "../../agents/call-terms.js";
+import { createAbortError, restoreOutcome, SubagentFailure, } from "../../agents/harness/index.js";
+import { resolveAkumaLaunchSnapshot } from "../../agents/launch-snapshot/resolve.js";
+import { selectSubagent } from "../../agents/selector.js";
+import { FlowError } from "../../flow-error.js";
+import { assertProjectionAlias, moveProjectionAlias } from "../projection-alias.js";
+import { projectionDir } from "../projection-core.js";
+import { createProjectionExecutionId } from "../projection-generation-identity.js";
+import { PROJECTION_ADOPTION_TIMEOUT_MS, startProjectionGeneration } from "../projection-generation-launcher.js";
+import { openProjectionGenerationStore, openProjectionGenerationStoreReadOnly, } from "../projection/generation/store.js";
+import { observeProjectionLife } from "../projection-life-observer.js";
+import { mintProjection, mintRepositoryProjection } from "../projection-mint.js";
+import { waitForProjection } from "../projection-wait.js";
+export function readCurrentGenerationOrThrow(projectionDirectory) {
+    const store = openProjectionGenerationStoreReadOnly(projectionDirectory);
+    try {
+        const current = store.readCurrentGeneration();
+        if (!current)
+            throw new FlowError("INTERNAL_STATE", "projection has no current generation");
+        return current;
+    }
+    finally {
+        store.close();
+    }
+}
+export function outcomeFromGeneration(current) {
+    const verdict = current.verdict;
+    if (!verdict)
+        throw new FlowError("INTERNAL_STATE", "projection generation has no terminal verdict");
+    const facts = verdict.facts;
+    const finalMessage = typeof facts.finalMessage === "string"
+        ? facts.finalMessage
+        : typeof facts.detail === "string"
+            ? facts.detail
+            : "";
+    if (facts.state === "failed" && typeof facts.detail === "string") {
+        throw new FlowError("SUBAGENT_EXEC_ERROR", facts.detail);
+    }
+    const session = facts.session;
+    if (session === null || typeof session !== "object" || Array.isArray(session)) {
+        throw new FlowError("INTERNAL_STATE", "projection verdict is missing its session envelope");
+    }
+    const record = {
+        status: facts.state === "completed"
+            ? "completed"
+            : facts.state === "dismissed"
+                ? "dismissed"
+                : "failed",
+        finalMessage,
+        output: typeof facts.output === "string" ? facts.output : "",
+        diagnostics: typeof facts.diagnostics === "string" ? facts.diagnostics : "",
+        session: session,
+        warnings: Array.isArray(facts.warnings)
+            ? facts.warnings
+            : [],
+        ...(facts.error && typeof facts.error === "object" && !Array.isArray(facts.error)
+            ? { error: facts.error }
+            : {}),
+    };
+    return restoreOutcome(record);
+}
+export async function executeSubagent(agentName, prompt, cwd, options) {
+    const { projection: projectionCoordinate, launchSnapshot } = await buildCallConfig(agentName, prompt, cwd, options);
+    if (!projectionCoordinate) {
+        throw new FlowError("INTERNAL_STATE", "durable execution requires a projection coordinate");
+    }
+    const launched = await startProjectionGeneration(projectionCoordinate.dir, projectionCoordinate.executionId);
+    if (launched.status === "failed") {
+        throw new FlowError("SUBAGENT_EXEC_ERROR", launched.detail);
+    }
+    const joined = await waitForProjection({
+        projectionDirectory: projectionCoordinate.dir,
+        signal: options.signal,
+    });
+    if (joined.state !== "terminal") {
+        throw new FlowError("INTERNAL_STATE", "durable execution ended without a terminal generation");
+    }
+    const current = readCurrentGenerationOrThrow(projectionCoordinate.dir);
+    const providerOutcome = outcomeFromGeneration(current);
+    const outcome = {
+        status: providerOutcome.status,
+        finalMessage: providerOutcome.finalMessage,
+        output: providerOutcome.output,
+        diagnostics: providerOutcome.diagnostics,
+        session: providerOutcome.session,
+        warnings: providerOutcome.warnings,
+        ...(providerOutcome.error ? { error: providerOutcome.error } : {}),
+        launchSnapshot,
+    };
+    const completionFacts = current.verdict?.facts;
+    switch (outcome.status) {
+        case "completed":
+            return { outcome, projection: projectionCoordinate, ...(completionFacts ? { completionFacts } : {}) };
+        case "dismissed":
+            throw createAbortError("subagent exec cancelled by client");
+        case "failed": {
+            const error = outcome.error;
+            if (!error) {
+                throw new FlowError("SUBAGENT_EXEC_ERROR", "Subagent exec failed without an error payload.");
+            }
+            throw new FlowError(error.code, error.message, {
+                cause: new SubagentFailure(error.code, error.message, {
+                    timeoutMs: error.timeoutMs,
+                    exitCode: error.exitCode,
+                    output: outcome.output,
+                    diagnostics: outcome.diagnostics,
+                }),
+            });
+        }
+    }
+    throw new FlowError("INTERNAL_STATE", "Unhandled subagent outcome state.");
+}
+export async function launchSubagentGeneration(agentName, prompt, cwd, options) {
+    const { projection, launchSnapshot } = await buildCallConfig(agentName, prompt, cwd, options);
+    if (!projection) {
+        throw new FlowError("INTERNAL_STATE", "durable launch requires a projection coordinate");
+    }
+    const launched = await startProjectionGeneration(projection.dir, projection.executionId);
+    if (launched.status === "failed") {
+        throw new FlowError("SUBAGENT_EXEC_ERROR", launched.detail);
+    }
+    return { projection, launchSnapshot };
+}
+export async function buildCallConfig(agentName, prompt, cwd, options) {
+    const launchSnapshot = options.launchSnapshot ?? resolveAkumaLaunchSnapshot(await selectSubagent(agentName, cwd), {
+        executionCwd: cwd,
+        projectRoot: cwd,
+        ...(options.model !== undefined ? { model: options.model } : {}),
+        ...(options.effort !== undefined ? { effort: options.effort } : {}),
+    });
+    const resolvedTerms = buildCallTerms(launchSnapshot, prompt, cwd, {
+        signal: options.signal,
+        idleTimeoutMs: options.idleTimeoutMs,
+    });
+    // Mint projection directory for supervisor pump.
+    const slug = launchSnapshot.akuma.name;
+    const publishProjection = async () => {
+        const mintInput = {
+            cwd: options.projectionCwd ?? cwd,
+            workspaceRoot: cwd,
+            slug,
+            pid: process.pid,
+            akuma: launchSnapshot.akuma.name,
+            provider: launchSnapshot.provider.kind,
+            binding: options.binding,
+            effectivePolicy: launchSnapshot.akuma.policy,
+            nowMs: Date.now(),
+        };
+        const minted = options.authority.kind === "repository"
+            ? await mintRepositoryProjection({ ...mintInput, authority: { kind: "repository" } })
+            : mintProjection({ ...mintInput, authority: { kind: "user" } });
+        const executionId = createProjectionExecutionId();
+        const launchFacts = JSON.parse(JSON.stringify({
+            executionId,
+            createdAt: new Date().toISOString(),
+            launchedBy: "call",
+            inputs: {
+                prompt,
+                task: options.task ?? prompt,
+                launchSnapshot,
+                idleTimeoutMs: resolvedTerms.idleTimeoutMs,
+                cwd,
+                historyCwd: options.historyStorageCwd ?? cwd,
+                ...(options.evidenceCwd !== undefined ? { evidenceCwd: options.evidenceCwd } : {}),
+                ...(options.title !== undefined ? { title: options.title } : {}),
+                ...(options.context !== undefined ? { context: options.context } : {}),
+                persistProjectionResponse: options.persistProjectionResponse ?? false,
+                ...(options.continuation ? {
+                    session: options.continuation.session,
+                    resumePath: options.continuation.resumePath,
+                    sourceArtifactId: options.continuation.sourceArtifactId,
+                } : {}),
+            },
+        }));
+        const store = openProjectionGenerationStore(minted.dir);
+        try {
+            const launch = store.launchIfSettled({ executionId, facts: launchFacts });
+            if (launch.status !== "committed") {
+                throw new FlowError("INTERNAL_STATE", `initial generation launch rejected: ${launch.reason}`);
+            }
+        }
+        finally {
+            store.close();
+        }
+        const previousAliasTarget = options.alias === undefined
+            ? undefined
+            : moveProjectionAlias(options.projectionCwd ?? cwd, assertProjectionAlias(options.alias), minted.id);
+        const previousAliasTargetStillRunning = previousAliasTarget === undefined
+            ? undefined
+            : (() => {
+                try {
+                    const phase = observeProjectionLife(projectionDir(options.projectionCwd ?? cwd, previousAliasTarget), { nowMs: Date.now(), startupTimeoutMs: PROJECTION_ADOPTION_TIMEOUT_MS }).phase;
+                    return phase === "minting" || phase === "active" || phase === "quiescent"
+                        ? previousAliasTarget
+                        : undefined;
+                }
+                catch {
+                    return undefined;
+                }
+            })();
+        return {
+            id: minted.id,
+            dir: minted.dir,
+            executionId,
+            ...(options.alias ? { alias: options.alias } : {}),
+            ...(previousAliasTargetStillRunning ? { previousAliasTarget: previousAliasTargetStillRunning } : {}),
+        };
+    };
+    // Every public launch has one durable projection object. Repository-free
+    // authority changes the storage owner, not whether the object exists; mint
+    // failure is therefore a launch failure rather than an in-process fallback.
+    const projectionCoordinate = await publishProjection();
+    return {
+        projection: projectionCoordinate,
+        launchSnapshot,
+    };
+}

package/build/core/call/prompt.js

@@ -0,0 +1,42 @@
+import { ACTOR_IDENTITY } from "../../keiyaku.js";
+export function buildCallPrompt(input) {
+    const references = [...new Set((input.referenceFiles ?? []).map((file) => file.trim()).filter(Boolean))];
+    if (input.currentIntent?.source === "arc") {
+        const arc = input.currentIntent;
+        return [
+            `You are a called ${ACTOR_IDENTITY} working inside open arc a${arc.arc}.`,
+            "Stay within the arc scope and do the requested work directly.",
+            `Title: ${arc.title}`,
+            `Objective: ${arc.objective}`,
+            `Brief:\n${arc.brief}`,
+            "",
+            `Task:\n${input.task}`,
+            `Context:\n${input.context?.trim() || "(none provided)"}`,
+            references.length > 0 ? `Reference files:\n${references.map((file) => `- ${file}`).join("\n")}` : "",
+            "Provide the final result for the caller/main agent.",
+        ].filter(Boolean).join("\n\n");
+    }
+    if (input.currentIntent?.source === "bind") {
+        const bind = input.currentIntent;
+        const trimmedContext = input.context?.trim() ?? "";
+        const extensionsBlock = bind.extensions.length > 0
+            ? `Extensions:\n${bind.extensions.map((extension) => `## ${extension.title}\n${extension.content}`).join("\n\n")}`
+            : "";
+        return [
+            `You are a called ${ACTOR_IDENTITY} working inside derived default arc a0.`,
+            "Stay within the contract scope and do the requested work directly.",
+            `Contract: ${bind.name}`,
+            `Objective:\n${bind.objective}`,
+            `Scope:\n${bind.scope.map((value) => `- ${value}`).join("\n")}`,
+            `Checks:\n${bind.checks.map((value) => `- ${value}`).join("\n")}`,
+            extensionsBlock,
+            `Task:\n${input.task}`,
+            trimmedContext ? `Context:\n${trimmedContext}` : "",
+            references.length > 0 ? `Reference files:\n${references.map((file) => `- ${file}`).join("\n")}` : "",
+            "Provide the final result for the caller/main agent.",
+        ].filter(Boolean).join("\n\n");
+    }
+    return [input.task, input.context?.trim() ?? "", references.length > 0 ? `Reference files:\n${references.map((file) => `- ${file}`).join("\n")}` : ""]
+        .filter(Boolean)
+        .join("\n\n");
+}

package/build/core/call/reference.js

@@ -0,0 +1,24 @@
+import * as fs from "fs/promises";
+import * as path from "path";
+import { isErrnoException } from "../../errno.js";
+import { BASE_RULES_FILE, KEIYAKU_FILE } from "../../keiyaku.js";
+async function fileExists(cwd, relativePath) {
+    try {
+        await fs.access(path.join(cwd, relativePath));
+        return true;
+    }
+    catch (error) {
+        if (isErrnoException(error) && error.code === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}
+export async function collectCallReferenceFiles(cwd, input) {
+    const candidates = [
+        ...(input.activeKeiyaku ? [KEIYAKU_FILE] : []),
+        BASE_RULES_FILE,
+    ];
+    const existing = await Promise.all(candidates.map(async (file) => ({ file, exists: await fileExists(cwd, file) })));
+    return existing.filter((entry) => entry.exists).map((entry) => entry.file);
+}

package/build/core/call-persist.js

@@ -1,6 +1,6 @@
 import { appendDebugLog } from "../telemetry/debug-log.js";
 import { logWarn } from "../telemetry/logger.js";
-import { runCall } from "./call.js";
+import { runCall } from "./call/call.js";
 import { persistResponseHistory } from "./transcripts.js";
 import { isGitRepo } from "../git/branches.js";
 import * as path from "node:path";