@astrosheep/keiyaku 4.6.19 → 4.6.20

package/README.md

@@ -212,7 +212,10 @@ lists every recognized namespace.
 npm install -g @astrosheep/keiyaku
 ```
 
-Pi loads the extension from the package source and invokes the `keiyaku` CLI from `PATH`, so Pi users must have that command installed and available in the host environment.
+Pi's shipped extension provides native `akuma_*` tools through the public SDK,
+plus the `/keiyaku` status overlay. The overlay still invokes `keiyaku` from
+`PATH`; native tools do not. See [`plugins/pi/README.md`](plugins/pi/README.md)
+for host lifetime, detached work, and request-permission scope.
 
 Node ≥ 22.19. Product law lives in [`docs/`](docs/README.md).
 
@@ -224,8 +227,9 @@ into each host package so native installations are self-contained. The separate
 `plugins/square` workspace is Keiyaku's internal Square observer, not a coding
 harness plugin. Installation recipes and harness package metadata select the built
 assets under `build/plugins` and `build/skills`, except the Pi package metadata,
-which selects the source extension and `skills/` so a source checkout is loadable
-without a build.
+which selects the TypeScript extension and `skills/`. Build a source checkout
+before loading that extension so its package-root SDK is available; published
+packages already include the SDK build.
 
 Building from source also builds the Windows launcher with Zig 0.14.1 or later. Install
 that system tool separately and make `zig` available on `PATH`, or set

package/build/plugins/pi/README.md

@@ -0,0 +1,111 @@
+# Keiyaku in Pi
+
+The existing Pi package entry `plugins/pi/keiyaku.ts` supplies `/keiyaku` (the
+status overlay) and ten native Akuma tools. It imports only the supported
+`@astrosheep/keiyaku` package root. Build the checkout before loading it locally;
+an installed npm package already carries its built SDK.
+
+```sh
+# Existing installation path; no separate experimental package
+keiyaku install pi
+# One-invocation local development, after npm run build
+pi --extension ./plugins/pi/keiyaku.ts
+```
+
+## Native tools
+
+All tools return the SDK result in `details`, `structuredContent`, and JSON
+text. Typed refusals and partial birth results remain data. An exceptional
+failure retaining a born Akuma also retains its identity in structured error
+data. No native tool shells out to the CLI.
+
+| Tool | Parameters |
+| --- | --- |
+| `akuma_call` | `akuma` definition name, `body`; optional `workdir`, `writableDirectories`, `detach`, `bare`, `wait`, `timeoutMs`, `schema` |
+| `akuma_status` | `akuma`; optional `repo` |
+| `akuma_list` | optional `archetype`, `limit` |
+| `akuma_definitions` | optional `limit` |
+| `akuma_tell` | `akuma`, `body`; optional `interrupt`, `detach`, `repo` |
+| `akuma_ask` | `akuma`, `body`; optional `interrupt`, `detach`, `schema`, `timeoutMs`, `repo` |
+| `akuma_wait` | `akuma` array; optional `completion` (`any` or `all`), `timeoutMs`, `repo` |
+| `akuma_history` | `akuma`; optional `id`, `last`, `before`, `since`, `limit`, `repo` |
+| `akuma_fork` | `akuma`, `at`; optional `detach`, `bare`, `repo` |
+| `akuma_kill` | `akuma` array; optional `repo` |
+
+`akuma_call` supports every configured provider, not only Pi. Default
+`detach: false` launches in the calling Pi session's in-process host scope.
+Default `wait: false` returns after birth and first-input admission; these are
+**independent choices**. `wait: true` observes the first answer for up to five
+minutes by default. `timeoutMs` on call requires `wait: true`.
+Call and Fork pass `bare` through to the SDK: it omits only Keiyaku runtime
+instructions and remains frozen through wake and inherited by forks. Providers
+without a verified runtime-instruction channel retain their explicit refusal
+unless the caller opts out.
+
+`writableDirectories` grants native tools access to additional existing canonical
+absolute directories at birth (currently Codex only). It preserves the native
+sandbox mode, network policy, and existing writable roots. Other providers
+refuse nonempty grants. These are explicit filesystem grants, not product-action
+permissions; nothing automatically exposes the repository or Home. Forks
+inherit the frozen native recipe; there is no live elevation option.
+
+```json
+{"akuma":"worker","body":"Inspect the parser without changing files."}
+{"akuma":"worker","body":"Run the checks.","detach":true,"wait":true,"timeoutMs":300000}
+```
+
+Tell, Ask and Fork explicitly select future launch hosting through their own
+`detach` option, also defaulting to false. A running Body never moves hosts. A
+sleeping Akuma can be woken in the current session even if another host created
+it. Ordinary CLI defaults and `--wait` semantics are unchanged.
+
+World resolves from Pi's `ctx.cwd`. Relative `workdir` and `repo` paths resolve
+there too; `repo` supplies Git association/selector context, not a different
+World. Caller attribution comes from the current Pi session manager, not ambient
+parent Akuma or harness environment declarations. Single targets accept IDs or
+World-local aliases; Wait/Kill also accept globs and Contract selectors (the
+latter need `repo`). History `id` and Fork `at` are exact returned `turn/n`
+identities. Exact history cannot combine with paging or `last`.
+
+Ask/Wait are unbounded unless `timeoutMs` is supplied. Deadline or tool abort
+ends observation, not admitted work. Optional `schema` supplies a provider JSON
+answer contract; the result is JSON-decoded, not locally validated against
+arbitrary JSON Schema. Schema input to busy work retains the SDK refusal.
+
+## Lifetime and permissions
+
+The extension owns one `AkumaHost.inProcess()` scope per Pi session. Orderly
+`session_shutdown` closes only that scope's exact in-process launches, including
+setup and automatic succession. It never kills by AkuId, so an older session
+cannot stop a foreign host's later wake of the same identity. Detached work
+survives. Reload and session replacement follow Pi's shutdown/start lifecycle.
+
+The Pi provider supplies the public SDK extension flag
+`keiyaku-request-only: true` to its own sessions. The extension reads that flag
+at native tool execution, before World establishment or SDK operations, and
+refuses local tools there (including nested tool calls). Those child Akumas use
+the existing CLI in their tool environment, with authenticated direct-parent
+routing and frozen permissions. There is no ambient identity guess or duplicate
+permission evaluator. If the optional extension is absent, Pi collects an
+unknown-option diagnostic without failing provider startup.
+
+In-process hosting is shared lifetime, not a sandbox: arbitrary extensions can
+block or terminate the runtime. A noncooperative tool/provider can remain
+physically live after the Body records hung and releases its leash. Scope close
+rejects with that exact launch's retained failure; it never reports physical
+retirement based on a later Body's status. Abrupt host death has no graceful
+cleanup guarantee, and no daemon or persisted host policy recovers live objects.
+Child model usage is not rolled into an already-returned parent tool result.
+
+## Verification
+
+```sh
+npm run build
+npm test -- tests/akuma-in-process.test.ts tests/pi-akuma-tools.test.ts tests/pi-extension.test.ts tests/package-consumers.test.ts
+```
+
+The native-tool tests load the built package's actual extension with Pi's public
+loader and execute a deterministic offline model through real Pi tool calls,
+SDK operations, Heart/leash, subprocess tools and detached launches. They do not
+replace the Body engine or depend on model credentials. These are not real-model
+quality or OS sandbox tests.

package/build/plugins/pi/akuma-tools.ts

@@ -0,0 +1,310 @@
+import { resolve } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  AkumaHost,
+  Akumas,
+  Repo,
+  Schema,
+  World,
+  listArchetypeDefinitions,
+  type CallResult,
+  type AkumaHostScope,
+  type AkumaCaller,
+  type AkumaAddressInput,
+  type AkumaAskInput,
+  type AkumaHistoryInput,
+  type AkumaKillInput,
+  type AkumaListInput,
+  type AkumaTellInput,
+  type AkumaWaitInput,
+  type ForkInput,
+  type JsonSchemaDocument,
+  type WorldRoot,
+} from "@astrosheep/keiyaku";
+
+const selector = { type: "string", minLength: 1, description: "Akuma ID or World-local alias" };
+const selectors = {
+  type: "array",
+  items: selector,
+  minItems: 1,
+  description: "IDs, aliases or glob selectors; Contract selectors require repo",
+};
+const repo = { type: "string", minLength: 1, description: "Optional Git worktree path, relative to session cwd" };
+const body = { type: "string", minLength: 1, description: "Input to admit; an observation deadline never retracts it" };
+const interrupt = {
+  type: "boolean",
+  description: "Admit input with a request for current work to yield; admission survives failed retirement",
+};
+const detach = {
+  type: "boolean",
+  description:
+    "Launch future work detached (default false: this Pi session's in-process scope). Never relocates an already running Body.",
+};
+const bare = {
+  type: "boolean",
+  description: "Omit Keiyaku runtime instructions only; preserved through wake and inherited by forks",
+};
+const timeoutMs = {
+  type: "integer",
+  minimum: 0,
+  description: "Observation limit in milliseconds; omitted is unbounded",
+};
+const limit = { type: "integer", minimum: 1 };
+
+type ToolAddress<Input> = Omit<Input, "repo" | "signal"> & { repo?: string };
+type LaunchChoice = { detach?: boolean };
+
+function caller(ctx: ExtensionContext): AkumaCaller {
+  return { kind: "external", integration: "pi", id: ctx.sessionManager.getSessionId() };
+}
+
+/** Native adaptation only. Addressing, admission, observation and lifecycle stay with Keiyaku. */
+export function registerAkumaTools(pi: ExtensionAPI): void {
+  pi.registerFlag("keiyaku-request-only", {
+    type: "boolean",
+    default: false,
+    description: "Disable local native Akuma tools in provider-owned Pi sessions; use the request-aware CLI",
+  });
+  type Session = { id: string; host?: AkumaHostScope; closed: boolean };
+  let current: Session | undefined;
+  const create = (ctx: ExtensionContext): Session => ({
+    id: ctx.sessionManager.getSessionId(),
+    ...(pi.getFlag("keiyaku-request-only") === true ? {} : { host: AkumaHost.inProcess() }),
+    closed: false,
+  });
+  function session(ctx: ExtensionContext): Session {
+    if (current === undefined) current = create(ctx);
+    if (current.id !== ctx.sessionManager.getSessionId())
+      throw new Error("Keiyaku Pi session has changed; wait for session_start");
+    if (current.closed) throw new Error("Keiyaku Pi session is shutting down");
+    if (current.host === undefined)
+      throw new Error(
+        "Native Akuma tools require an external Pi session. Inside an Akuma use the request-aware keiyaku CLI (direct-parent permissions apply).",
+      );
+    return current;
+  }
+  pi.on("session_start", (_event, ctx) => {
+    if (current?.id === ctx.sessionManager.getSessionId() && !current.closed) return;
+    if (current !== undefined && !current.closed) throw new Error("Previous Keiyaku Pi session has not shut down");
+    current = create(ctx);
+  });
+  pi.on("session_shutdown", async (_event, ctx) => {
+    const owned = current;
+    if (owned === undefined || owned.id !== ctx.sessionManager.getSessionId()) return;
+    owned.closed = true;
+    await owned.host?.close();
+  });
+  function register<Input>(
+    name: string,
+    description: string,
+    properties: Record<string, unknown>,
+    required: string[],
+    run: (
+      input: Input,
+      akumas: Akumas,
+      ctx: ExtensionContext,
+      signal: AbortSignal | undefined,
+      world: WorldRoot,
+    ) => Promise<object>,
+  ): void {
+    pi.registerTool({
+      name,
+      label: name,
+      description,
+      parameters: { type: "object", properties, required, additionalProperties: false },
+      outputSchema: { type: "object", additionalProperties: true },
+      async execute(_id, raw, signal, _update, ctx) {
+        // SDK flag injection happens after the factory. Read here, before World
+        // establishment, including when invoked as another tool's nested call.
+        if (pi.getFlag("keiyaku-request-only") === true)
+          throw new Error(
+            "Native Akuma tools require an external Pi session. Inside an Akuma use the request-aware keiyaku CLI (direct-parent permissions apply).",
+          );
+        const owned = session(ctx);
+        signal?.throwIfAborted();
+        const world = await (await World.resolve(ctx.cwd)).establish();
+        if (owned.closed) throw new Error("Keiyaku Pi session is shutting down");
+        const { detach: detached, ...input } = raw as Input & LaunchChoice;
+        let result: object;
+        try {
+          result = await run(
+            input as Input,
+            Akumas.of(world, detached ? { hosting: "detached" } : owned.host),
+            ctx,
+            signal,
+            world,
+          );
+        } catch (error) {
+          // SDK exceptions can retain a leading birth. Do not turn that known
+          // identity into a text-only error or pretend the birth was rolled back.
+          if (!(error instanceof Error) || !("akuma" in error) || typeof error.akuma !== "string") throw error;
+          result = { akuma: error.akuma, failure: { diagnostic: error.message } };
+          const text = JSON.stringify(result);
+          return {
+            content: [{ type: "text", text }],
+            details: result,
+            structuredContent: JSON.parse(text),
+            isError: true,
+          };
+        }
+        const text = JSON.stringify(result);
+        return {
+          content: [{ type: "text", text }],
+          details: result,
+          structuredContent: JSON.parse(text),
+        };
+      },
+    });
+  }
+
+  async function address<Input extends { repo?: string }>(input: Input, ctx: ExtensionContext) {
+    const { repo: path, ...rest } = input;
+    return { ...rest, ...(path === undefined ? {} : { repo: await Repo.at({ path: resolve(ctx.cwd, path) }) }) };
+  }
+
+  register<{
+    akuma: string;
+    body: string;
+    workdir?: string;
+    writableDirectories?: readonly string[];
+    bare?: boolean;
+    wait?: boolean;
+    timeoutMs?: number;
+    schema?: JsonSchemaDocument;
+  }>(
+    "akuma_call",
+    "Call any configured Akuma provider. By default launch in this Pi session and return birth plus first-Tell receipt immediately. detach selects detached hosting; wait separately observes the first answer (default five-minute bound). Deadlines/abort stop observation, not admitted execution. Session shutdown retires only this session's in-process launches.",
+    {
+      akuma: {
+        type: "string",
+        minLength: 1,
+        pattern: "\\S",
+        description: "Callable definition name (see akuma_definitions)",
+      },
+      body,
+      workdir: { type: "string", minLength: 1, description: "Execution directory relative to Pi cwd (default Pi cwd)" },
+      detach,
+      writableDirectories: {
+        type: "array",
+        items: { type: "string", minLength: 1 },
+        description:
+          "Additional existing canonical absolute writable directories (Codex only); preserves native sandbox/network policy. Separate from product actions.",
+      },
+      bare,
+      wait: { type: "boolean", description: "Observe first answer, independently of host choice (default false)" },
+      timeoutMs,
+      schema: { type: "object", additionalProperties: true },
+    },
+    ["akuma", "body"],
+    async (input, akumas, ctx, signal) => {
+      if (input.timeoutMs !== undefined && input.wait !== true) throw new TypeError("timeoutMs requires wait: true");
+      const result: CallResult = await akumas.call({
+        archetype: input.akuma,
+        body: input.body,
+        cwd: resolve(ctx.cwd, input.workdir ?? "."),
+        ...(input.writableDirectories === undefined ? {} : { writableDirectories: input.writableDirectories }),
+        mode: input.wait ? "wait" : "detach",
+        caller: caller(ctx),
+        ...(input.bare === undefined ? {} : { bare: input.bare }),
+        ...(input.timeoutMs === undefined ? {} : { timeoutMs: input.timeoutMs }),
+        ...(input.schema === undefined ? {} : { schema: Schema.json(input.schema, (value) => value) }),
+        ...(signal === undefined ? {} : { signal }),
+      });
+      return result;
+    },
+  );
+
+  register<ToolAddress<AkumaAddressInput>>(
+    "akuma_status",
+    "Observe one Akuma's lifecycle, current work and retained outcome. No mutation.",
+    { akuma: selector, repo },
+    ["akuma"],
+    async (input, akumas, ctx) => akumas.status(await address(input, ctx)),
+  );
+  register<AkumaListInput>(
+    "akuma_list",
+    "List a bounded recent-activity roster of Akuma instances, with aliases. Use akuma_definitions for callable names.",
+    { archetype: { type: "string", minLength: 1 }, limit },
+    [],
+    async (input, akumas) => akumas.list(input),
+  );
+  register<{ limit?: number }>(
+    "akuma_definitions",
+    "List visible callable Akuma definitions for all configured providers (not running instances).",
+    { limit },
+    [],
+    async (input, _akumas, _ctx, _signal, world) => listArchetypeDefinitions({ project: world, ...input }),
+  );
+  register<ToolAddress<AkumaTellInput> & LaunchChoice>(
+    "akuma_tell",
+    "Admit input without awaiting its answer. detach explicitly selects future wake hosting (default this Pi session); running work stays in its current host. Optional interrupt admits first, then requests current work to yield.",
+    { akuma: selector, body, interrupt, detach, repo },
+    ["akuma", "body"],
+    async (input, akumas, ctx, signal) =>
+      akumas.tell({ ...(await address(input, ctx)), ...(signal === undefined ? {} : { signal }) }),
+  );
+  register<ToolAddress<Omit<AkumaAskInput, "schema" | "observe">> & LaunchChoice & { schema?: JsonSchemaDocument }>(
+    "akuma_ask",
+    "Admit input and observe that exact answer. timeoutMs/abort stop observation, never admitted work. detach selects future wake hosting (default this Pi session), never relocates running work. Optional JSON Schema is a provider answer contract; parsed JSON is returned without arbitrary local schema validation.",
+    {
+      akuma: selector,
+      body,
+      interrupt,
+      detach,
+      timeoutMs,
+      schema: { type: "object", additionalProperties: true },
+      repo,
+    },
+    ["akuma", "body"],
+    async (input, akumas, ctx, signal) => {
+      const { schema, ...rest } = await address(input, ctx);
+      return akumas.ask({
+        ...rest,
+        ...(signal === undefined ? {} : { signal }),
+        ...(schema === undefined ? {} : { schema: Schema.json(schema, (value) => value) }),
+      });
+    },
+  );
+  register<ToolAddress<AkumaWaitInput>>(
+    "akuma_wait",
+    "Observe existing Akuma-wide work for a frozen selection. Defaults to any; all waits for every member. Completion is not proof of success. Deadline/cancellation does not stop workers.",
+    { akuma: selectors, completion: { type: "string", enum: ["any", "all"] }, timeoutMs, repo },
+    ["akuma"],
+    async (input, akumas, ctx, signal) =>
+      akumas.wait({ ...(await address(input, ctx)), ...(signal === undefined ? {} : { signal }) }),
+  );
+  register<ToolAddress<AkumaHistoryInput>>(
+    "akuma_history",
+    "Read retained execution history, the last answer, or one exact turn/n outcome. id cannot combine with paging or last. before/since are durable sequence cursors, not timestamps.",
+    {
+      akuma: selector,
+      id: { type: "string", pattern: "^turn/[1-9][0-9]*$" },
+      before: { type: "integer", minimum: 1 },
+      since: { type: "integer", minimum: 1 },
+      limit,
+      last: { type: "boolean" },
+      repo,
+    },
+    ["akuma"],
+    async (input, akumas, ctx) => akumas.history(await address(input, ctx)),
+  );
+  register<ToolAddress<ForkInput> & LaunchChoice>(
+    "akuma_fork",
+    "Fork one exact retained answered turn/n into a prompt-free Akuma. detach selects birth hosting (default this Pi session). Source is unchanged. Native refusal preserves unavailable history/provider capability; cancellation cannot undo birth.",
+    { akuma: selector, at: { type: "string", pattern: "^turn/[1-9][0-9]*$" }, detach, bare, repo },
+    ["akuma", "at"],
+    async (input, akumas, ctx) =>
+      akumas.fork({
+        ...(await address(input, ctx)),
+        caller: caller(ctx),
+      }),
+  );
+  register<ToolAddress<AkumaKillInput>>(
+    "akuma_kill",
+    "Stop current work for a frozen Akuma selection without admitting input or deleting history. Returns each owner's honest stop evidence; does not shut down this Pi host.",
+    { akuma: selectors, repo },
+    ["akuma"],
+    async (input, akumas, ctx, signal) =>
+      akumas.kill({ ...(await address(input, ctx)), ...(signal === undefined ? {} : { signal }) }),
+  );
+}

package/build/plugins/pi/keiyaku.ts

@@ -1,4 +1,5 @@
 import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
+import { registerAkumaTools } from "./akuma-tools.ts";
 
 type ExecResult = Readonly<{ stdout: string; stderr: string; code: number }>;
 
@@ -37,6 +38,7 @@ function overlay(lines: readonly string[], theme: Theme, done: () => void) {
 }
 
 export default function keiyakuExtension(pi: ExtensionAPI): void {
+  registerAkumaTools(pi);
   pi.registerCommand("keiyaku", {
     description: "Open the Kanshi world status",
     handler: async (_args, ctx) => {

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

@@ -2,6 +2,7 @@ import { type AkumaCaller } from "./caller.js";
 import type { Settings } from "../settings.js";
 import type { WorldRoot } from "../world.js";
 import { type AllowedAction } from "./allowed.js";
+import type { BodyLauncher } from "./body-launch.js";
 import { type TellResult } from "./body.js";
 import type { CallInitialTell } from "./call-initial-tell.js";
 import { type AllocatedAkuma } from "./identity.js";
@@ -16,6 +17,8 @@ export type AkumaCallInput = Readonly<{
     body?: string;
     cwd?: string;
     allowed?: readonly AllowedAction[];
+    writableDirectories?: readonly string[];
+    bare?: boolean;
     schema?: Schema<unknown>;
     initiator?: string;
     caller?: AkumaCaller;
@@ -51,5 +54,5 @@ type AkumaCallLaunchInput = Omit<AkumaCallInput, "body" | "schema"> & Readonly<{
  * standalone birth: load the caller Archetype/Settings, freeze allowed and cwd,
  * then invoke the P3 prepared-call executor under local or request custody.
  */
-export declare function admitAkumaCall(path: WorldRoot, configuration: AkumaConfiguration, input: AkumaCallLaunchInput, context: AkumaCallContext): Promise<AdmittedAkumaCall>;
+export declare function admitAkumaCall(path: WorldRoot, configuration: AkumaConfiguration, input: AkumaCallLaunchInput, context: AkumaCallContext, spawn: BodyLauncher): Promise<AdmittedAkumaCall>;
 export {};

package/build/src/akuma/akuma-call.js

@@ -5,8 +5,8 @@ import { readAkumaBirthCwd } from "./akuma-observe.js";
 import { AkumaOwner } from "./akuma-owner.js";
 import { decodeAllowedActions, unionAllowedActions } from "./allowed.js";
 import { AkumaArchetypeError, loadPreparedArchetype } from "./archetype.js";
-import { spawnAkumaBody } from "./body.js";
-import { canonicalBirthCwd } from "./call-input.js";
+import { tellWakeRuntime } from "./body.js";
+import { bareOption, canonicalBirthCwd, writableDirectoriesOption } from "./call-input.js";
 import { requestForwardedAkumaCall } from "./call-request.js";
 import { validateAkumaName } from "../identity/normalize.js";
 import { PreparedCallAdmissionError, executePreparedCall } from "./publication.js";
@@ -24,6 +24,7 @@ async function admitBodyRequest(input) {
         archetype: input.name,
         ...(input.call.initialTell === undefined ? {} : { initialTell: input.call.initialTell }),
         ...(cwd === undefined ? {} : { cwd }),
+        ...(input.call.writableDirectories === undefined ? {} : { writableDirectories: input.call.writableDirectories }),
         recipe: input.recipe,
         ...(input.call.initiator === undefined ? {} : { birthInitiator: input.call.initiator }),
         ...(input.call.contractId === undefined ? {} : { contractId: input.call.contractId }),
@@ -53,6 +54,7 @@ async function admitDirect(input) {
         result = await executePreparedCall({
             archetype: input.archetype.name,
             cwd,
+            ...(input.call.writableDirectories === undefined ? {} : { writableDirectories: input.call.writableDirectories }),
             ...(input.call.caller === undefined ? {} : { caller: input.call.caller }),
             ...(input.call.initialTell === undefined ? {} : { initialTell: input.call.initialTell }),
             ...(input.call.signal === undefined ? {} : { signal: input.call.signal }),
@@ -60,14 +62,25 @@ async function admitDirect(input) {
                 kind: "local",
                 world: input.path,
                 recipe: input.recipe,
-                spawn: async (launch) => await spawnAkumaBody({
-                    paths: launch.paths,
-                    seed: launch.seed,
+                spawn: async (launch) => await input.spawn({
+                    ...launch,
                     ...(input.call.initiator === undefined ? {} : { birthInitiator: input.call.initiator }),
                     ...(input.call.contractId === undefined ? {} : { completion: { contractId: input.call.contractId } }),
                 }),
                 admitInitialTell: async ({ id, initialTell, signal }) => await new AkumaOwner(id, input.path).admitInitialTell(initialTell, {
+                    runtime: tellWakeRuntime(input.spawn),
                     ...(signal === undefined ? {} : { signal }),
+                    ...(input.call.contractId === undefined
+                        ? {}
+                        : {
+                            runtime: {
+                                spawn: async (paths) => await input.spawn({
+                                    paths,
+                                    refuseIfHeld: true,
+                                    completion: { contractId: input.call.contractId },
+                                }),
+                            },
+                        }),
                 }),
             },
         });
@@ -97,7 +110,7 @@ async function admitDirect(input) {
  * standalone birth: load the caller Archetype/Settings, freeze allowed and cwd,
  * then invoke the P3 prepared-call executor under local or request custody.
  */
-export async function admitAkumaCall(path, configuration, input, context) {
+export async function admitAkumaCall(path, configuration, input, context, spawn) {
     decodeAkumaCaller(input.caller);
     const name = validateAkumaName(input.archetype);
     const home = configuration.home === undefined ? {} : { home: configuration.home };
@@ -106,14 +119,18 @@ export async function admitAkumaCall(path, configuration, input, context) {
     const allowed = input.allowed === undefined
         ? archetype.allowed
         : unionAllowedActions(archetype.allowed, decodeAllowedActions(input.allowed, "Akuma call allowed"));
+    const writableDirectories = await writableDirectoriesOption(input.writableDirectories);
+    if (writableDirectories.length > 0 && archetype.provider.kind !== "codex-app-server")
+        throw new TypeError(`writableDirectories is unsupported by provider ${archetype.provider.kind}`);
     const execution = executionChannel(configuration.execution);
     const requestRecipe = Object.freeze({
         ...(archetype.description === undefined ? {} : { description: archetype.description }),
         provider: archetype.provider,
         options: archetype.options,
         allowed,
+        bare: bareOption(input.bare) ?? false,
     });
     if (execution.kind === "body-request")
         return await admitBodyRequest({ call: input, context, path, name, recipe: requestRecipe, execution });
-    return await admitDirect({ call: input, context, path, archetype, recipe: requestRecipe });
+    return await admitDirect({ call: input, context, path, archetype, recipe: requestRecipe, spawn });
 }

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

@@ -6,6 +6,10 @@ import { type InterruptReceipt } from "./akuma-owner.js";
 import { type AkumaStatus } from "./akuma.js";
 import type { AllowedAction } from "./allowed.js";
 import { type KillEvidence } from "./heart/index.js";
+import type { ReportFact } from "./heart/facts.js";
+import { type AkumaHostOptions } from "../body-host.js";
+export type { AkumaHostOptions } from "../body-host.js";
+import type { BodyLauncher } from "./body-launch.js";
 import { type AkuId } from "./identity.js";
 import type { ActivityHistory } from "./projection.js";
 import { type Schema, type StandardSchemaV1 } from "./schema.js";
@@ -26,10 +30,6 @@ export type AkumaHistoryOptions = Readonly<{
 export type AkumaSignalOptions = Readonly<{
     signal?: AbortSignal;
 }>;
-/** Observes only plugin diagnostics produced in this host, never remote Body logs. */
-export type AkumaHostOptions = Readonly<{
-    reportDiagnostic?: (message: string) => void;
-}>;
 /** Capture the observer capability, not the caller's mutable options object. */
 export declare function captureAkumaHostDiagnostic(host: AkumaHostOptions | undefined): AkumaHostOptions["reportDiagnostic"];
 export type AkumaBirthInput = Readonly<{
@@ -38,10 +38,23 @@ export type AkumaBirthInput = Readonly<{
     home?: string;
     settings?: Settings;
     allowed?: readonly AllowedAction[];
+    writableDirectories?: readonly string[];
+    bare?: boolean;
     caller?: AkumaCaller;
     initiator?: string;
     host?: AkumaHostOptions;
 }>;
+export type AkumaReportOptions = AkumaSignalOptions & Readonly<{
+    bodySequence: number;
+    turnSequence: number;
+}>;
+export type AkumaReportResult = Readonly<{
+    kind: "recorded";
+    report: ReportFact;
+}> | Readonly<{
+    kind: "refused";
+    reason: "not-born" | "not-current-execution";
+}>;
 export type AkumaTellOptions = AkumaSignalOptions & Readonly<{
     interrupt?: boolean;
     initiator?: string;
@@ -51,22 +64,29 @@ export type AkumaAskOptions<T> = AkumaTellOptions & Readonly<{
     schema?: Schema<T> | StandardSchemaV1<T>;
 }>;
 export type { AkumaAskResult, AkumaTellResult, InterruptReceipt, KillEvidence };
-export declare class Akuma {
+declare class AkumaHandle {
     readonly id: AkuId;
     private readonly root;
     private readonly reportDiagnostic;
-    private constructor();
+    private readonly spawn;
+    constructor(id: AkuId, root: WorldRoot, reportDiagnostic: (message: string) => void, spawn: BodyLauncher);
     private owner;
-    static birth(archetype: string, input: AkumaBirthInput): Promise<Akuma>;
-    static select(root: WorldRoot, selector: string, host?: AkumaHostOptions): Akuma;
     tell(text: string, options?: AkumaTellOptions): Promise<AkumaTellResult>;
     ask(text: string, options?: AkumaAskOptions<string>): Promise<AkumaAskResult<string>>;
     ask<T>(text: string, options: AkumaAskOptions<T> & Readonly<{
         schema: Schema<T> | StandardSchemaV1<T>;
     }>): Promise<AkumaAskResult<T>>;
+    report(text: string, options: AkumaReportOptions): Promise<AkumaReportResult>;
     status(): Promise<AkumaStatus>;
     idle(options?: AkumaIdleOptions): Promise<AkumaIdleResult>;
     history(options?: AkumaHistoryOptions): Promise<ActivityHistory>;
     stream(options?: AkumaSignalOptions): AsyncIterable<AkumaStreamSnapshot>;
     kill(options?: AkumaSignalOptions): Promise<KillEvidence>;
 }
+export declare class Akuma extends AkumaHandle {
+    private constructor();
+    static birth(archetype: string, input: AkumaBirthInput): Promise<Akuma>;
+    static select(root: WorldRoot, selector: string, host?: AkumaHostOptions): Akuma;
+}
+/** Internal product composition; hosting is captured independently of public operation inputs. */
+export declare function akumaWithLauncher(root: WorldRoot, selector: string, spawn: BodyLauncher, host?: AkumaHostOptions): Akuma;