@akagilnc/pi-workflow-roles 0.1.3771 → 0.1.3789

package/src/host-descriptions.ts

@@ -1,10 +1,13 @@
 /**
- * Packaged host description table (#729 / #731).
- * Key = seat-table `host` value; the row is the generic ACP factory's input.
+ * Packaged host description tables (#729 / #731 / #645).
+ * Key = seat-table `host` value.
+ * - ACP family rows feed the generic ACP factory.
+ * - Headless CLI family rows feed the generic headless factory (#645; #646 codex next).
  * pi is the in-process default, not a row.
- * Unregistered names fail closed (#510); this table does not fallback.
+ * Unregistered names fail closed (#510); these tables do not fallback.
  */
 import type { AcpHostDescription } from "./acp-host/description.ts";
+import type { HeadlessHostDescription } from "./headless-host/description.ts";
 
 /** Grok CLI reads vendor-private compat surfaces unless each is disabled by name. */
 const PRIVATE_COMPAT_ENV = Object.fromEntries(
@@ -15,6 +18,8 @@ const PRIVATE_COMPAT_ENV = Object.fromEntries(
 
 export const DEFAULT_ROLE_TURN_HOST = "pi" as const;
 
+export type HostFamily = "acp" | "headless";
+
 export const HOST_DESCRIPTIONS: Readonly<Record<string, AcpHostDescription>> = Object.freeze({
   /** Operator home `~/.grok`, native session/load resume, `agent [--model X] stdio`. */
   "grok-build": Object.freeze({
@@ -60,17 +65,59 @@ export const HOST_DESCRIPTIONS: Readonly<Record<string, AcpHostDescription>> = O
   }),
 });
 
+/**
+ * Headless CLI family (#645). Claude is the first row; codex (#646) adds another.
+ * fixedArgs: print mode, isolation without `--bare` (OAuth stays), full permissions.
+ * `--setting-sources` empty = load no user/project/local CLAUDE.md/hooks/skills
+ * (role envelope is delivered via `--system-prompt` wholesale replace).
+ * `--strict-mcp-config` with no `--mcp-config` drops operator MCP + claude.ai connectors.
+ */
+export const HEADLESS_HOST_DESCRIPTIONS: Readonly<Record<string, HeadlessHostDescription>> = Object.freeze({
+  "claude": Object.freeze({
+    binaryFromHome: Object.freeze([".local", "bin", "claude"]),
+    sessionBindingFile: "claude-headless-session.json",
+    fixedArgs: Object.freeze([
+      // One result envelope (not stream-json): typed receipt only; no event-stream copy.
+      "--output-format", "json",
+      "--permission-mode", "bypassPermissions",
+      // Empty sources: no user/project/local operator surface (envelope owns materials).
+      "--setting-sources", "",
+      // With adapter-supplied --mcp-config only (AK relay); drops operator + claude.ai MCP.
+      "--strict-mcp-config",
+    ]),
+    promptFlag: "-p",
+    modelFlag: "--model",
+    effortFlag: "--effort",
+    // File path keeps large role envelopes off ARG_MAX.
+    systemPromptFlag: "--system-prompt-file",
+    jsonSchemaFlag: "--json-schema",
+    mcpConfigFlag: "--mcp-config",
+    sessionIdFlag: "--session-id",
+    resumeFlag: "--resume",
+  }),
+});
+
 export function lookupHostDescription(host: string): AcpHostDescription | undefined {
   return Object.hasOwn(HOST_DESCRIPTIONS, host) ? HOST_DESCRIPTIONS[host] : undefined;
 }
 
+export function lookupHeadlessHostDescription(host: string): HeadlessHostDescription | undefined {
+  return Object.hasOwn(HEADLESS_HOST_DESCRIPTIONS, host) ? HEADLESS_HOST_DESCRIPTIONS[host] : undefined;
+}
+
+export function lookupHostFamily(host: string): HostFamily | undefined {
+  if (lookupHostDescription(host) !== undefined) return "acp";
+  if (lookupHeadlessHostDescription(host) !== undefined) return "headless";
+  return undefined;
+}
+
 export function packagedExternalHostNames(): readonly string[] {
-  return Object.keys(HOST_DESCRIPTIONS);
+  return [...Object.keys(HOST_DESCRIPTIONS), ...Object.keys(HEADLESS_HOST_DESCRIPTIONS)];
 }
 
-/** Legal persistent/invocation host: default pi, or a table key. */
+/** Legal persistent/invocation host: default pi, or a table key (any family). */
 export function assertRegisteredHostName(host: string): string {
-  if (host === DEFAULT_ROLE_TURN_HOST || lookupHostDescription(host) !== undefined) {
+  if (host === DEFAULT_ROLE_TURN_HOST || lookupHostFamily(host) !== undefined) {
     return host;
   }
   throw new Error(`unregistered host: ${host}`);

package/src/public-cli/cli.ts

@@ -45,7 +45,7 @@ import type { CliIo } from "./cli-io.ts";
 import type { PostAdmissionEnv } from "./post-admission.ts";
 import type { RoleTurnHost, RoleTurnRequest } from "../host-contracts.ts";
 import { packagedExternalHostNames } from "../host-descriptions.ts";
-import { loadProductionAcpHostFactory } from "./load-production-acp-host.ts";
+import { loadProductionExternalHostFactory } from "./load-production-external-host.ts";
 import {
   createPiRoleTurnHost,
   appendPiSessionCustomEntry,
@@ -347,7 +347,7 @@ function resolveRoleTurnHost(
           ok: true as const,
           host: {
             executeTurn: async (request: RoleTurnRequest) => {
-              hostPromise ??= loadProductionAcpHostFactory(env.packageRoot, name).then((create) =>
+              hostPromise ??= loadProductionExternalHostFactory(env.packageRoot, name).then((create) =>
                 create({
                   packageRoot: env.packageRoot,
                   principalAuthority: options.principalAuthority,

package/src/public-cli/load-production-external-host.ts

@@ -0,0 +1,29 @@
+/**
+ * Family-dispatch loader for packaged external RoleTurnHost factories (#645).
+ * ACP rows → production ACP host; headless rows → production headless host.
+ * Unregistered names fail closed before any import.
+ */
+import { lookupHostFamily } from "../host-descriptions.ts";
+import type { DurablePrincipalAuthority, RoleTurnHost } from "../host-contracts.ts";
+import { loadProductionAcpHostFactory } from "./load-production-acp-host.ts";
+import { loadProductionHeadlessHostFactory } from "./load-production-headless-host.ts";
+
+export type ProductionExternalHostFactory = (options: {
+  packageRoot: string;
+  principalAuthority: DurablePrincipalAuthority;
+}) => RoleTurnHost;
+
+/** Resolve the production host factory for one registered external host key. */
+export async function loadProductionExternalHostFactory(
+  packageRoot: string,
+  host: string,
+): Promise<ProductionExternalHostFactory> {
+  const family = lookupHostFamily(host);
+  if (family === "acp") {
+    return loadProductionAcpHostFactory(packageRoot, host);
+  }
+  if (family === "headless") {
+    return loadProductionHeadlessHostFactory(packageRoot, host);
+  }
+  throw new Error(`unregistered host: ${host}`);
+}

package/src/public-cli/load-production-headless-host.ts

@@ -0,0 +1,48 @@
+/**
+ * Deferred loader for the packaged generic headless RoleTurnHost factory (#645).
+ *
+ * Public ak-role bin must not statically value-import the production host (or its
+ * role-runtime edges). Specifier is runtime-constructed so esbuild leaves this
+ * import external (ADR 0052 discovery stays peer-free).
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import type { HeadlessHostDescription } from "../headless-host/description.ts";
+import { lookupHeadlessHostDescription } from "../host-descriptions.ts";
+import type { DurablePrincipalAuthority, RoleTurnHost } from "../host-contracts.ts";
+
+export type ProductionHeadlessHostFactory = (options: {
+  packageRoot: string;
+  principalAuthority: DurablePrincipalAuthority;
+}) => RoleTurnHost;
+
+type GenericHeadlessHostFactory = (options: {
+  packageRoot: string;
+  principalAuthority: DurablePrincipalAuthority;
+  description: HeadlessHostDescription;
+}) => RoleTurnHost;
+
+/**
+ * Resolve the production headless host factory for one registered headless host
+ * key without a static graph edge into the public CLI bundle.
+ */
+export async function loadProductionHeadlessHostFactory(
+  packageRoot: string,
+  host: string,
+): Promise<ProductionHeadlessHostFactory> {
+  const description = lookupHeadlessHostDescription(host);
+  if (description === undefined) {
+    throw new Error(`unregistered headless host: ${host}`);
+  }
+  const built = join(packageRoot, "dist/headless-host/production-host.js");
+  const source = join(packageRoot, "src/headless-host/production-host.ts");
+  const target = existsSync(built) ? built : source;
+  const href = pathToFileURL(target).href;
+  const mod = (await import(href)) as {
+    createProductionHeadlessRoleTurnHost: GenericHeadlessHostFactory;
+  };
+  const create = mod.createProductionHeadlessRoleTurnHost;
+  return (options) => create({ ...options, description });
+}

package/src/public-cli/main.ts

@@ -26,6 +26,11 @@ function resolvePackageRoot(binDir: string): string {
 
 const packageRoot = resolvePackageRoot(here);
 
+// Nested institutional summons resolve package root from this env (#675 / #645).
+// Pin to the running bin's package so a stale outer install pin cannot load a
+// host family this tree owns but the older install lacks.
+process.env.AK_ROLE_PACKAGE_ROOT = packageRoot;
+
 // The host-provided runtime must be resolvable before the CLI module graph loads it.
 ensureHostPiRuntimeResolvable(packageRoot);
 

package/src/public-cli/option-definitions.ts

@@ -598,8 +598,8 @@ const COLLECTOR_OPTIONS = [
     repeatable: false,
     form: "option",
     description: {
-      en: "Optional request manifest JSON path ({requests:[{id,body}]}).",
-      zh: "可选 request manifest JSON 路径（{requests:[{id,body}]}）。",
+      en: "Optional request manifest JSON path ({requests:[{id,body}]}). Role may also decide request bodies from handbook/field activity without this file.",
+      zh: "可选 request manifest JSON 路径（{requests:[{id,body}]}）。角色亦可依手册/现场自行判定请求正文，不必依赖本文件。",
     },
   },
 ] as const satisfies readonly PublicOptionDefinition[];

package/src/public-role-summons.ts

@@ -65,6 +65,12 @@ export type PublicSummonRequest = {
    * Never folded into argv / parent-run lookup keys (ADR 0079 卷宗指针 stays pure).
    */
   readonly gateReviewInstruction?: string;
+  /**
+   * Parent-invocation host axis (#617 / #645). Nested institutional legs inherit
+   * the live parent `--host` so a single public entry does not require mutating
+   * persistent seat host. Seat model/thinking stay on the officer seat table.
+   */
+  readonly host?: string;
   /**
    * Offline test inject — same face as public CLI env.roleTurnHost. Production
    * summons leave this unset and use the seat-resolved host.
@@ -211,14 +217,13 @@ async function createSummonEnv(options: {
   const hostName = options.seat.host ?? "pi";
   let roleTurnHost = piHost;
   if (hostName !== "pi") {
-    const { lookupHostDescription } = await import("./host-descriptions.ts");
-    const { loadProductionAcpHostFactory } = await import(
-      "./public-cli/load-production-acp-host.ts"
+    const { lookupHostFamily } = await import("./host-descriptions.ts");
+    const { loadProductionExternalHostFactory } = await import(
+      "./public-cli/load-production-external-host.ts"
     );
-    // #729: the description table is the sole host authority — every registered
-    // key loads the same generic ACP factory (no per-host fork). Unregistered
-    // keys fail closed before any turn (#510), as the pre-merge fork did.
-    if (lookupHostDescription(hostName) === undefined) {
+    // #729 / #645: description tables are the sole host authority — family
+    // dispatch (ACP vs headless) is data-driven. Unregistered keys fail closed.
+    if (lookupHostFamily(hostName) === undefined) {
       throw new Error(
         `public role summons host unregistered: host=${hostName} seat=${options.role}`,
       );
@@ -226,7 +231,7 @@ async function createSummonEnv(options: {
     let hostPromise: Promise<RoleTurnHost> | undefined;
     roleTurnHost = {
       executeTurn: async (request) => {
-        hostPromise ??= loadProductionAcpHostFactory(options.packageRoot, hostName).then(
+        hostPromise ??= loadProductionExternalHostFactory(options.packageRoot, hostName).then(
           (create) =>
             create({
               packageRoot: options.packageRoot,
@@ -286,7 +291,10 @@ export async function summonPublicRole(
   const credentials =
     options.credentials ?? (await loadCredentialProviders(agentDir));
   const config = await loadPublicCliConfig(home);
-  const seat = resolveEffectiveSeat(config, options.role, credentials);
+  // Nested legs inherit parent invocation host when provided (#645 review path).
+  // Model/thinking stay on the officer seat — host-only inherit (seat-table law).
+  const invocation = options.host === undefined ? undefined : { host: options.host };
+  const seat = resolveEffectiveSeat(config, options.role, credentials, invocation);
   const env = {
     ...(await createSummonEnv({
       role: options.role,
@@ -412,6 +420,47 @@ export async function summonPublicRole(
 }
 
 /** Gate officer summons: notary/auditor via --source-run; inspector via pointer instruction. */
+/**
+ * Read parent invocation host so nested officers inherit live --host only (#645).
+ * Gate source runs necessarily own invocation.json — missing page, bad JSON, or
+ * bad shape stay loud (failure-honesty). Absent host field is lawful (seat default).
+ */
+async function parentInvocationHost(sourceRunDirectory: string): Promise<string | undefined> {
+  const { readFile } = await import("node:fs/promises");
+  const path = join(sourceRunDirectory, "invocation.json");
+  let text: string;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    const code =
+      error instanceof Error && "code" in error
+        ? (error as NodeJS.ErrnoException).code
+        : undefined;
+    throw new Error(
+      `parent invocation.json required for gate source run at ${path}: ${code ?? (error instanceof Error ? error.message : String(error))}`,
+      { cause: error },
+    );
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text) as unknown;
+  } catch (error) {
+    throw new Error(
+      `parent invocation.json unreadable at ${path}: ${error instanceof Error ? error.message : String(error)}`,
+      { cause: error },
+    );
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new Error(`parent invocation.json has non-object shape at ${path}`);
+  }
+  const host = (raw as Record<string, unknown>).host;
+  if (host === undefined) return undefined;
+  if (typeof host !== "string" || host.trim() === "") {
+    throw new Error(`parent invocation.json host must be a non-empty string at ${path}`);
+  }
+  return host;
+}
+
 export async function summonGateOfficer(options: {
   readonly officer: "inspector" | "notary" | "auditor";
   readonly sourceRunDirectory: string;
@@ -452,6 +501,9 @@ export async function summonGateOfficer(options: {
       submission: options.submission,
     });
   }
+  // Inherit parent live --host only so review roundtrip stays on one host without
+  // mutating persistent seat tables (#645). Officer model/thinking stay seat-owned.
+  const parentHost = await parentInvocationHost(options.sourceRunDirectory);
   const common = {
     cwd: options.cwd,
     ...(home === undefined ? {} : { home }),
@@ -462,6 +514,7 @@ export async function summonGateOfficer(options: {
     ...(gateReviewInstruction === undefined
       ? {}
       : { gateReviewInstruction }),
+    ...(parentHost === undefined ? {} : { host: parentHost }),
     ...(options.roleTurnHost === undefined ? {} : { roleTurnHost: options.roleTurnHost }),
     ...(options.createRunId === undefined ? {} : { createRunId: options.createRunId }),
   } as const;

package/src/role-runtime.ts

@@ -611,6 +611,8 @@ export type RoleRuntimeDependencies = {
   /** Shared-seam issue-fetch capability for Reviewer Spec self-fetch (#343). */
   createReviewerIssueFetcher?(): ReviewerIssueFetcher;
   loadCollectorSoul?(): Promise<string>;
+  /** #677: optional packaged seed for first-use general bot handbook. */
+  loadCollectorHandbookSeed?(): Promise<string>;
   createCollectorTransport?(): CollectorGitHubTransport;
   loadDoctorSoul?(): Promise<string>;
   loadNotarySoul?(): Promise<string>;
@@ -1717,6 +1719,9 @@ export function createRoleRuntimeExtension(
         ...(dependencies.createCollectorClock === undefined
           ? {}
           : { createClock: dependencies.createCollectorClock }),
+        ...(dependencies.loadCollectorHandbookSeed === undefined
+          ? {}
+          : { loadHandbookSeed: dependencies.loadCollectorHandbookSeed }),
       },
       hostActions,
     );