@astrosheep/keiyaku 4.0.6 → 4.1.1

package/README.md

@@ -94,7 +94,7 @@ did not land until the gates had current evidence.
 kanshi ─ 7 keiyaku · 18 akuma · 286 task ─ /Users/astrosheep/Developer/keiyaku-v4 main 9cfdca6017633e51827b9b2eba3c76a7fe08e05f
 
 keiyaku 7
-⧗ kei/add-acp-provider-and-grok-build-profile pending-delivery
+⧗ kei/add-acp-provider-and-grok-build-profile tendered
   worktree · integration c5cafef6 · -> refs/heads/main
   ! reviewed
 ⧗ kei/align-task-cli-truth-promises waiting

package/build/integrations/marketplace/plugins/keiyaku/skills/keiyaku/SKILL.md

@@ -39,4 +39,7 @@ keiyaku -C <repo> tell <aku/...|@alias> (<prompt> | -)
 `-C` is the invocation and Akuma execution cwd. Add `--repo <path>` only when
 a Contract or Dispatch reader must use a different Git repository.
 
+Repeated `--allowed` values add actions to the Archetype defaults. Restriction
+comes from the Archetype base and, for nested calls, the direct parent Soul.
+
 Use text by default; add `--json` when a script needs structured output.

package/build/integrations/marketplace/plugins/keiyaku/skills/keiyaku-akuma/SKILL.md

@@ -29,6 +29,9 @@ exclusive. Decide up front whether you will stay:
 Alias already points elsewhere, it moves to the born Akuma. The worker's
 execution cwd is exactly `-C <path>`, or your own cwd when `-C` is omitted.
 
+Repeated `--allowed` values add actions to the Archetype defaults. Restriction
+comes from the Archetype base and, for nested calls, the direct parent Soul.
+
 ## Archetypes
 
 An Archetype is a Markdown file at `~/.keiyaku/akuma/<name>.md`. Its

package/build/integrations/marketplace/plugins/keiyaku/skills/keiyaku-workflow/SKILL.md

@@ -17,7 +17,7 @@ contract document -> bind -> work -> audit -> deliver -> review gates
                                                                 \-> abandoned
 ```
 
-The lifecycle is `waiting -> bound -> pending-delivery -> claimed | abandoned`;
+The lifecycle is `waiting -> bound -> tendered -> claimed | abandoned`;
 the last two are terminal. Reserve `--after` for true logical ordering: one
 Contract's result must ultimately build on another's settled outcome, or their
 intended work has a large or irreconcilable interaction that should be
@@ -219,7 +219,7 @@ included. Read the receipt:
   delivery is done.
 - When a gate is not current, the receipt shows the recorded candidate and the
   placement stop. This is not a failed delivery. The Contract stays
-  `pending-delivery` while you complete the gates.
+  `tendered` while you complete the gates.
 - A lag row reports an accepted physical effect that has not finished. The
   delivery stands; `reconcile` completes the effect later. It never changes
   the verdict.
@@ -283,10 +283,7 @@ Placement follows the Git mental model you already have:
   The deliver or review you just ran still counts: the recorded candidate and
   any `✓ reviewed` verdict are kept, but nothing claims and nothing moves.
   The target ref, its checkout, and your bytes stay exactly where they were,
-  and the Contract stays `pending-delivery`.
-- A `--here` Contract behaves like a commit with gates: it lands on the current
-  branch and cannot deliver to a foreign checked-out target.
-
+  and the Contract stays `tendered`.
 After a refusal, handle the listed paths, then `deliver` again or record a
 satisfied review; either command requests placement again.
 

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

@@ -1,5 +1,6 @@
+import { type TellResult, type TellWakeRuntime } from "./body.js";
 import { type AkumaLife, type KillEvidence, type ResumeCoordinate, type Soul } from "./heart/index.js";
-import { type AkuId } from "./identity.js";
+import { type AkuId, type AkumaPaths } from "./identity.js";
 import { type ActivityHistory, type ActivitySnapshot } from "./projection.js";
 import { type Settings } from "../settings.js";
 import type { WorldRoot } from "../world.js";
@@ -20,6 +21,8 @@ export type AkumaStatus = Readonly<{
     timeline: ActivitySnapshot;
     strandedReason?: "resume-unsupported";
 }>;
+/** The default completion judgment over one complete status snapshot. */
+export declare function defaultWaitComplete(status: AkumaStatus): boolean;
 export type { ReadonlyRestraint } from "./provider-recipe.js";
 export type * from "./projection.js";
 export type UnbornAkumaListRow = Readonly<{
@@ -54,16 +57,7 @@ type AkumaCallContext = Readonly<{
     initiatorCwd?: string;
     cwdCanonical?: true;
 }>;
-export type TellResult = Readonly<{
-    admission: Readonly<{
-        tellId: string;
-        fact: "recorded";
-    }>;
-    wake: "spawned" | Readonly<{
-        kind: "failed";
-        diagnostic: string;
-    }>;
-}>;
+export type { TellResult, TellWake } from "./body.js";
 export type InterruptReceipt = Readonly<{
     kind: "unavailable";
     evidence: "hung" | "untidy" | "unavailable";
@@ -94,14 +88,23 @@ export declare class AkumaNotBornError extends Error {
     readonly kind = "akuma-not-born";
     constructor(id: AkuId);
 }
-export declare function tellAkumaWithId(worldPath: WorldRoot, id: AkuId, body: string, tellId: string, recordedAt?: string): Promise<TellResult>;
+export declare function tellAkumaWithId(input: Readonly<{
+    worldPath: WorldRoot;
+    id: AkuId;
+    body: string;
+    tellId: string;
+    recordedAt?: string;
+    runtime?: TellWakeRuntime;
+}>): Promise<TellResult>;
+export declare function killAkumaWithRecovery(paths: AkumaPaths, recover?: (paths: AkumaPaths) => Promise<void>): Promise<KillEvidence>;
 export type BudgetedStatusObservation = Readonly<{
     status: AkumaStatus;
     ordinarySelected: number;
 }>;
-/** Package-internal budgeted observation; Fleet allocates, Akuma still selects. */
+/** Package-internal observation; Fleet chooses the aperture and ordinary budget. */
 export declare function readBudgetedStatus(worldPath: WorldRoot, id: AkuId, input: Readonly<{
-    ordinaryBudget: number;
+    aperture: "monitoring" | "receipt";
+    ordinaryBudget?: number;
 }>): Promise<BudgetedStatusObservation>;
 /** Package-internal birth projection used by the composed Library call result. */
 export declare function readAkumaBirthCwd(worldPath: WorldRoot, id: AkuId): Promise<string>;

package/build/src/akuma/akuma.js

@@ -1,17 +1,17 @@
 import { randomUUID } from "node:crypto";
 import { readdir, realpath, stat } from "node:fs/promises";
 import { resolve } from "node:path";
-import { CONTROL_RESPONSE_MS, spawnAkumaBody } from "./body.js";
+import { CONTROL_RESPONSE_MS, handoffPendingTells, spawnAkumaBody, wakeRecordedTell, } from "./body.js";
 import { HeldAkumaLeash, activitySlice, isHeartAbsent, life, lifeAt, probeLeash, readHeart, readLastAnsweredTurn, readForkPoint, readKill, readSeal, readSoul, recordTell, requestPause, requestStop, } from "./heart/index.js";
 import { akuIdFromDirectoryName, akumaPaths, akumaRunRoot, parseAkuId, pathsForAkuId, archetypeName, } from "./identity.js";
-import { ordinarySelectedCount, ordinarySnapshotBudget, projectTurns, selectActivitySnapshot, selectHistory, selectSnapshot, } from "./projection.js";
+import { ordinarySnapshotBudget, projectTurns, selectHistory, selectSnapshot, } from "./projection.js";
 import { listArchetypes as readArchetypes, loadArchetype } from "./archetype.js";
 import { publishAkuma } from "./publication.js";
 import { resolveProviderExecution } from "./providers/index.js";
 import { injectedBodyRequests, requestBodyCall } from "./requests.js";
 import { settings as readSettings } from "../settings.js";
-import { decodeAllowedActions, } from "./allowed.js";
-const POLL_MS = 25;
+import { decodeAllowedActions, unionAllowedActions } from "./allowed.js";
+const POLL_MS = 100;
 async function canonicalBirthCwd(input) {
     const selected = resolve(input);
     try {
@@ -31,6 +31,11 @@ function callReadonly(value) {
         throw new TypeError("Akuma call readonly must be true");
     return { readonly: true };
 }
+/** The default completion judgment over one complete status snapshot. */
+export function defaultWaitComplete(status) {
+    return (status.life !== "running" &&
+        !status.timeline.entries.some((entry) => entry.kind === "row" && entry.row.kind === "tell" && entry.row.state === "pending"));
+}
 const CALL_EXECUTION = Symbol("akuma-call-execution");
 const CALL_WITH_CONTEXT = Symbol("akuma-call-with-context");
 export class AkumaNotBornError extends Error {
@@ -52,7 +57,7 @@ async function takeLeashUntil(paths, deadline) {
             return leash;
         if (performance.now() >= deadline)
             return null;
-        await wait(POLL_MS);
+        await wait(Math.min(POLL_MS, Math.max(0, deadline - performance.now())));
     }
 }
 async function recordTellBody(paths, akuma, body, id = randomUUID(), recordedAt = new Date().toISOString()) {
@@ -61,32 +66,56 @@ async function recordTellBody(paths, akuma, body, id = randomUUID(), recordedAt
         throw new AkumaNotBornError(akuma);
     return { kind: "recorded", tellId: admitted.tell.id };
 }
-async function wakeTell(paths, tellId) {
-    try {
-        await spawnAkumaBody({ paths });
-        return { admission: { tellId, fact: "recorded" }, wake: "spawned" };
-    }
-    catch (error) {
-        return {
-            admission: { tellId, fact: "recorded" },
-            wake: { kind: "failed", diagnostic: diagnostic(error) },
-        };
-    }
-}
-export async function tellAkumaWithId(worldPath, id, body, tellId, recordedAt = new Date().toISOString()) {
-    const paths = pathsForAkuId(worldPath, id);
-    const recorded = await recordTellBody(paths, id, body, tellId, recordedAt);
-    return await wakeTell(paths, recorded.tellId);
+export async function tellAkumaWithId(input) {
+    const paths = pathsForAkuId(input.worldPath, input.id);
+    const recorded = await recordTellBody(paths, input.id, input.body, input.tellId, input.recordedAt);
+    return await wakeRecordedTell(paths, recorded.tellId, input.runtime);
 }
 function diagnostic(error) {
     return error instanceof Error ? error.message : String(error);
 }
+export async function killAkumaWithRecovery(paths, recover = handoffPendingTells) {
+    try {
+        const request = await requestStop(paths, new Date().toISOString());
+        if (request.kind !== "requested")
+            return request.kind;
+        const target = request.body;
+        const leash = await takeLeashUntil(paths, performance.now() + CONTROL_RESPONSE_MS);
+        if ((await readKill(paths, target.sequence)) !== null) {
+            leash?.release();
+            return "killed";
+        }
+        if (leash === null) {
+            if ((await readKill(paths, target.sequence)) !== null)
+                return "killed";
+            const body = (await readHeart(paths)).latestBody;
+            return body?.sequence === target.sequence && body.hung !== undefined ? "hung" : "unavailable";
+        }
+        try {
+            const settledBody = (await readHeart(paths)).latestBody;
+            if (settledBody?.sequence !== target.sequence)
+                return (await readKill(paths, target.sequence)) === null ? "unavailable" : "killed";
+            if (settledBody.end !== "put-down") {
+                await leash.clearStop(paths);
+                return "untidy";
+            }
+            const settled = await leash.settleStop(paths, target.sequence);
+            return settled === null ? "unavailable" : "killed";
+        }
+        finally {
+            leash.release();
+        }
+    }
+    finally {
+        void recover(paths).catch(() => undefined);
+    }
+}
 async function fleetListRow(paths, expected) {
     const snapshot = await readHeart(paths);
     if (snapshot.soul !== null)
         return await bornListRow(paths, expected, snapshot);
     try {
-        if (await probeLeash(paths) === "held")
+        if ((await probeLeash(paths)) === "held")
             return { id: expected, life: "unborn" };
         const seal = await readSeal(paths);
         return seal === null ? { id: expected, life: "unborn" } : { id: expected, life: "stillborn", seal };
@@ -118,32 +147,36 @@ async function bornListRow(paths, expected, snapshot) {
         pending: snapshot.pending.map((tell) => tell.id),
     };
 }
-async function bornStatus(paths, expected, budget) {
+async function bornStatus(paths, expected, input) {
+    if (input.ordinaryBudget !== undefined && (!Number.isSafeInteger(input.ordinaryBudget) || input.ordinaryBudget < 0)) {
+        throw new TypeError("ordinary budget must be a nonnegative safe integer");
+    }
     const snapshot = await readHeart(paths);
     if (snapshot.soul === null)
         throw new AkumaNotBornError(expected);
     const current = await bornListRow(paths, expected, snapshot);
-    const resumeUnsupported = current.life === "stranded"
-        && snapshot.latestSession?.provider === snapshot.soul.provider.name
-        && (await resolveProviderExecution(snapshot.soul.provider)).adapter.resume === undefined;
+    const resumeUnsupported = current.life === "stranded" &&
+        snapshot.latestSession?.provider === snapshot.soul.provider.name &&
+        (await resolveProviderExecution(snapshot.soul.provider)).adapter.resume === undefined;
     const slice = await activitySlice(paths);
+    const selected = selectSnapshot(projectTurns(slice.rows), {
+        aperture: input.aperture,
+        budget: ordinarySnapshotBudget(input.ordinaryBudget),
+    });
     return {
-        id: current.id,
-        life: current.life,
-        ...(snapshot.soul.readonly === undefined ? {} : { readonly: snapshot.soul.readonly }),
-        ...(resumeUnsupported ? { strandedReason: "resume-unsupported" } : {}),
-        timeline: budget === undefined
-            ? selectActivitySnapshot(slice.rows)
-            : selectSnapshot(projectTurns(slice.rows), budget),
+        status: {
+            id: current.id,
+            life: current.life,
+            ...(snapshot.soul.readonly === undefined ? {} : { readonly: snapshot.soul.readonly }),
+            ...(resumeUnsupported ? { strandedReason: "resume-unsupported" } : {}),
+            timeline: selected.snapshot,
+        },
+        ordinarySelected: selected.ordinaryCount,
     };
 }
-/** Package-internal budgeted observation; Fleet allocates, Akuma still selects. */
+/** Package-internal observation; Fleet chooses the aperture and ordinary budget. */
 export async function readBudgetedStatus(worldPath, id, input) {
-    if (!Number.isSafeInteger(input.ordinaryBudget) || input.ordinaryBudget < 0) {
-        throw new TypeError("ordinary budget must be a nonnegative safe integer");
-    }
-    const status = await bornStatus(pathsForAkuId(worldPath, id), id, ordinarySnapshotBudget(input.ordinaryBudget));
-    return { status, ordinarySelected: ordinarySelectedCount(status.timeline) };
+    return await bornStatus(pathsForAkuId(worldPath, id), id, input);
 }
 /** Package-internal birth projection used by the composed Library call result. */
 export async function readAkumaBirthCwd(worldPath, id) {
@@ -166,13 +199,16 @@ export class AkumaHandle {
         return pathsForAkuId(this.worldPath, this.id);
     }
     async status() {
-        return await bornStatus(this.paths, this.id);
+        return (await bornStatus(this.paths, this.id, { aperture: "monitoring" })).status;
     }
     async history(input = {}) {
         if (input.before !== undefined && input.since !== undefined) {
             throw new TypeError("Akuma history before and since are mutually exclusive");
         }
-        for (const [name, value] of [["before", input.before], ["since", input.since]]) {
+        for (const [name, value] of [
+            ["before", input.before],
+            ["since", input.since],
+        ]) {
             if (value !== undefined && (!Number.isSafeInteger(value) || value <= 0)) {
                 throw new TypeError(`Akuma history ${name} must be a positive safe integer`);
             }
@@ -191,9 +227,8 @@ export class AkumaHandle {
             limit,
         });
     }
-    async wait(predicate = (status) => status.life !== "running", options = {}) {
-        if (options.timeoutMs !== undefined
-            && (!Number.isFinite(options.timeoutMs) || options.timeoutMs < 0)) {
+    async wait(predicate = defaultWaitComplete, options = {}) {
+        if (options.timeoutMs !== undefined && (!Number.isFinite(options.timeoutMs) || options.timeoutMs < 0)) {
             throw new TypeError("Akuma wait timeoutMs must be a nonnegative finite millisecond duration");
         }
         const deadline = options.timeoutMs === undefined ? undefined : performance.now() + options.timeoutMs;
@@ -206,7 +241,7 @@ export class AkumaHandle {
     }
     async tell(body) {
         const recorded = await recordTellBody(this.paths, this.id, body);
-        return await wakeTell(this.paths, recorded.tellId);
+        return await wakeRecordedTell(this.paths, recorded.tellId);
     }
     async interrupt(body) {
         const request = await requestPause(this.paths, new Date().toISOString());
@@ -221,9 +256,10 @@ export class AkumaHandle {
         }
         if (leash === null) {
             const body = (await readHeart(this.paths)).latestBody;
-            return { kind: "unavailable", evidence: body?.sequence === request.body.sequence && body.hung !== undefined
-                    ? "hung"
-                    : "unavailable" };
+            return {
+                kind: "unavailable",
+                evidence: body?.sequence === request.body.sequence && body.hung !== undefined ? "hung" : "unavailable",
+            };
         }
         const settledBody = (await readHeart(this.paths)).latestBody;
         if (settledBody?.sequence === request.body.sequence && settledBody.hung !== undefined) {
@@ -262,7 +298,7 @@ export class AkumaHandle {
         finally {
             leash.release();
         }
-        return { kind: "interrupted", putDown, tell: await wakeTell(this.paths, recorded.tellId) };
+        return { kind: "interrupted", putDown, tell: await wakeRecordedTell(this.paths, recorded.tellId) };
     }
     async fork(input) {
         const source = await readSoul(this.paths);
@@ -298,21 +334,23 @@ export class AkumaHandle {
                 worldPath: this.worldPath,
                 archetype: source.archetype,
                 awaitAsleep: true,
-                launch: async (allocated) => await spawnAkumaBody({
-                    paths: allocated.paths,
-                    seed: {
-                        id: allocated.id,
-                        archetype: source.archetype,
-                        ...(source.description === undefined ? {} : { description: source.description }),
-                        provider: source.provider,
-                        options: source.options,
-                        ...(source.readonly === undefined ? {} : { readonly: source.readonly }),
-                        allowed: source.allowed,
-                        cwd: source.cwd,
-                        origin: { kind: "fork", parent: this.id, at: input.at },
-                    },
-                    birthSession,
-                }),
+                launch: async (allocated) => {
+                    (await spawnAkumaBody({
+                        paths: allocated.paths,
+                        seed: {
+                            id: allocated.id,
+                            archetype: source.archetype,
+                            ...(source.description === undefined ? {} : { description: source.description }),
+                            provider: source.provider,
+                            options: source.options,
+                            ...(source.readonly === undefined ? {} : { readonly: source.readonly }),
+                            allowed: source.allowed,
+                            cwd: source.cwd,
+                            origin: { kind: "fork", parent: this.id, at: input.at },
+                        },
+                        birthSession,
+                    })).release();
+                },
             });
             return { kind: "forked", child: child.id };
         }
@@ -325,39 +363,7 @@ export class AkumaHandle {
         }
     }
     async kill() {
-        const at = new Date().toISOString();
-        const request = await requestStop(this.paths, at);
-        if (request.kind !== "requested")
-            return request.kind;
-        const target = request.body;
-        const graceDeadline = performance.now() + CONTROL_RESPONSE_MS;
-        const leash = await takeLeashUntil(this.paths, graceDeadline);
-        if (await readKill(this.paths, target.sequence) !== null) {
-            leash?.release();
-            return "killed";
-        }
-        if (leash === null) {
-            if (await readKill(this.paths, target.sequence) !== null)
-                return "killed";
-            const body = (await readHeart(this.paths)).latestBody;
-            return body?.sequence === target.sequence && body.hung !== undefined ? "hung" : "unavailable";
-        }
-        try {
-            const settledBody = (await readHeart(this.paths)).latestBody;
-            if (settledBody?.sequence !== target.sequence)
-                return await readKill(this.paths, target.sequence) === null ? "unavailable" : "killed";
-            if (settledBody.end !== "put-down") {
-                await leash.clearStop(this.paths);
-                return "untidy";
-            }
-            const settled = await leash.settleStop(this.paths, target.sequence);
-            if (settled === null)
-                return "unavailable";
-            return "killed";
-        }
-        finally {
-            leash.release();
-        }
+        return await killAkumaWithRecovery(this.paths);
     }
     async lastAnswer() {
         const turn = await readLastAnsweredTurn(this.paths);
@@ -395,7 +401,7 @@ export class Akuma {
         const readonly = callReadonly(input.readonly);
         const name = archetypeName(input.archetype);
         const home = this.configuration.home === undefined ? {} : { home: this.configuration.home };
-        const settings = this.configuration.settings ?? await readSettings({ root: this.path, ...home });
+        const settings = this.configuration.settings ?? (await readSettings({ root: this.path, ...home }));
         const archetype = await loadArchetype({
             name,
             ...home,
@@ -404,7 +410,7 @@ export class Akuma {
         });
         const allowed = input.allowed === undefined
             ? archetype.allowed
-            : decodeAllowedActions(input.allowed, "Akuma call allowed");
+            : unionAllowedActions(archetype.allowed, decodeAllowedActions(input.allowed, "Akuma call allowed"));
         const requests = injectedBodyRequests();
         const requestRecipe = Object.freeze({
             ...(archetype.description === undefined ? {} : { description: archetype.description }),
@@ -416,7 +422,9 @@ export class Akuma {
         if (requests !== null) {
             const cwd = input.cwd === undefined
                 ? undefined
-                : context?.cwdCanonical === true ? input.cwd : await canonicalBirthCwd(input.cwd);
+                : context?.cwdCanonical === true
+                    ? input.cwd
+                    : await canonicalBirthCwd(input.cwd);
             const child = await requestBodyCall({
                 directory: requests,
                 id: randomUUID(),
@@ -434,24 +442,24 @@ export class Akuma {
         }
         const initiatorCwd = context.initiatorCwd;
         const selectedCwd = input.cwd ?? initiatorCwd ?? this.path;
-        const cwd = input.cwd !== undefined && context?.cwdCanonical === true
-            ? input.cwd
-            : await canonicalBirthCwd(selectedCwd);
+        const cwd = input.cwd !== undefined && context?.cwdCanonical === true ? input.cwd : await canonicalBirthCwd(selectedCwd);
         const recipe = requestRecipe;
         const published = await publishAkuma({
             worldPath: this.path,
             archetype: archetype.name,
-            launch: async (allocated) => await spawnAkumaBody({
-                paths: allocated.paths,
-                seed: {
-                    id: allocated.id,
-                    archetype: allocated.archetype,
-                    ...recipe,
-                    cwd,
-                    origin: { kind: "direct" },
-                },
-                initialBody: input.body,
-            }),
+            launch: async (allocated) => {
+                (await spawnAkumaBody({
+                    paths: allocated.paths,
+                    seed: {
+                        id: allocated.id,
+                        archetype: allocated.archetype,
+                        ...recipe,
+                        cwd,
+                        origin: { kind: "direct" },
+                    },
+                    initialBody: input.body,
+                })).release();
+            },
         });
         return new AkumaHandle(published.id, this.path, {
             cwd,

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

@@ -4,4 +4,5 @@ export type AllowedActions = readonly AllowedAction[];
 export declare function isAllowedAction(value: unknown): value is AllowedAction;
 export declare function decodeAllowedActions(value: unknown, label?: string): AllowedActions;
 export declare function effectiveAllowedActions(value: unknown): AllowedActions;
+export declare function unionAllowedActions(base: AllowedActions, additions: AllowedActions): AllowedActions;
 export declare function clipAllowedActions(requested: AllowedActions, parent: AllowedActions): AllowedActions;

package/build/src/akuma/allowed.js

@@ -27,6 +27,12 @@ export function decodeAllowedActions(value, label = "allowed") {
 export function effectiveAllowedActions(value) {
     return value === undefined ? ALLOWED_ACTIONS : decodeAllowedActions(value);
 }
+export function unionAllowedActions(base, additions) {
+    const merged = new Set(base);
+    for (const action of additions)
+        merged.add(action);
+    return Object.freeze([...merged].sort());
+}
 export function clipAllowedActions(requested, parent) {
     const ceiling = new Set(parent);
     return Object.freeze(requested.filter((action) => ceiling.has(action)));

package/build/src/akuma/archetype.js

@@ -96,7 +96,11 @@ function decodeArchetype(name, path, markdown) {
     const network = archetypeEnum(values, "network", ["disabled", "enabled"]);
     const description = archetypeField(values, "description");
     const allowed = effectiveAllowedActions(values.allowed);
+    const systemPromptMode = archetypeEnum(values, "systemPromptMode", ["append", "replace"]);
     const systemPrompt = lines.slice(closing + 1).join("\n");
+    if (systemPromptMode !== undefined && systemPrompt.length === 0) {
+        throw new TypeError("Akuma systemPromptMode requires a nonempty Markdown body");
+    }
     return Object.freeze({
         name,
         path,
@@ -106,7 +110,12 @@ function decodeArchetype(name, path, markdown) {
             ...(model === undefined ? {} : { model }),
             ...(effort === undefined ? {} : { effort }),
             ...(network === undefined ? {} : { network }),
-            ...(systemPrompt.length === 0 ? {} : { systemPrompt }),
+            ...(systemPrompt.length === 0
+                ? {}
+                : {
+                    systemPrompt,
+                    systemPromptMode: systemPromptMode ?? "append",
+                }),
         }),
         ...(readonly === undefined ? {} : { readonly }),
         allowed,
@@ -135,7 +144,8 @@ export async function listArchetypeDefinitions(input = {}) {
 }
 function record(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value)
-        ? value : null;
+        ? value
+        : null;
 }
 function optionalProviderText(value, name, field) {
     const selected = value[field];