@akagilnc/pi-workflow-roles 0.1.4802 → 0.1.4874

package/src/public-cli/turn-request.ts

@@ -7,11 +7,20 @@ import type {
   DurablePrincipal,
   MethodBinding,
   RoleTurnActivation,
-  RoleTurnModelConfig,
   RoleTurnRequest,
 } from "../host-contracts.ts";
 import { pickEngineAxis } from "../package-resources/engine-material.ts";
+import {
+  resolvePackagedMethodSkillPath,
+  type PackagedMethodSkillName,
+} from "../package-resources/method-skill.ts";
+import {
+  packagedRoleActivationFlags,
+  packagedRoleMetadata,
+} from "../packaged-role-registry.ts";
 import type { SeatModelConfig } from "./config.ts";
+import type { AdmittedRoleInvocation } from "./invocation.ts";
+import { parentRunPathFromGatePointerInstruction } from "./run-lifecycle.ts";
 import type { PublicThinkingLevel } from "./registry.ts";
 
 /** Structural model shape shared by the seam so seat/env sources fit. */
@@ -93,3 +102,85 @@ export function projectRoleTurnRequest(
     ...(options.stationChild === undefined ? {} : { stationChild: options.stationChild }),
   };
 }
+
+/**
+ * Packaged method this admitted run settles with.
+ * Coder carries one only on apply. Other seats read `settleMethod`.
+ */
+export function packagedSettleSkill(
+  admitted: AdmittedRoleInvocation,
+): PackagedMethodSkillName | undefined {
+  const record = packagedRoleMetadata(admitted.role);
+  if (record === undefined) return undefined;
+  if ("applyMethod" in record && record.applyMethod !== undefined) {
+    return "phase" in admitted && admitted.phase === "apply" ? record.applyMethod : undefined;
+  }
+  if ("settleMethod" in record && record.settleMethod !== undefined) return record.settleMethod;
+  return undefined;
+}
+
+function readAdmittedPath(admitted: AdmittedRoleInvocation, path: string): unknown {
+  let current: unknown = admitted;
+  for (const key of path.split(".")) {
+    if (current === null || typeof current !== "object") return undefined;
+    current = (current as Record<string, unknown>)[key];
+  }
+  return current;
+}
+
+/** Activation object for one admitted run. Field copies come from the composition-root record. */
+function activationForAdmitted(admitted: AdmittedRoleInvocation): RoleTurnActivation {
+  if (packagedRoleMetadata(admitted.role) === undefined) {
+    throw new Error(`no turn projection for ${admitted.role}`);
+  }
+  const activation: Record<string, unknown> = { role: admitted.role };
+  for (const spec of packagedRoleActivationFlags(admitted.role)) {
+    let value = readAdmittedPath(admitted, spec.from ?? spec.field);
+    if (spec.fallback === "gate-pointer") {
+      const trimmed = typeof value === "string" ? value.trim() : "";
+      value = trimmed !== ""
+        ? trimmed
+        : parentRunPathFromGatePointerInstruction(admitted.instruction);
+      if (typeof value !== "string" || value === "") continue;
+    }
+    if (value === undefined) continue;
+    if (spec.text === true) {
+      if (typeof value !== "number") continue;
+      value = String(value);
+    }
+    activation[spec.field] = value;
+  }
+  return activation as RoleTurnActivation;
+}
+
+/** Skill bindings declared on the composition-root record for this admitted run. */
+function methodBindings(
+  admitted: AdmittedRoleInvocation,
+  packageRoot: string,
+): readonly MethodBinding[] {
+  const record = packagedRoleMetadata(admitted.role);
+  const names: PackagedMethodSkillName[] = [];
+  if (record !== undefined && "methodSkills" in record && record.methodSkills !== undefined) {
+    names.push(...record.methodSkills);
+  }
+  const apply = packagedSettleSkill(admitted);
+  if (apply !== undefined && !names.includes(apply)) names.push(apply);
+  return names.map((name) => ({
+    kind: "skill" as const,
+    path: resolvePackagedMethodSkillPath(packageRoot, name),
+  }));
+}
+
+/** Registry activation and method bindings for one admitted public seat. */
+export function admittedSeatTurnDetails(
+  admitted: AdmittedRoleInvocation,
+  packageRoot: string,
+): {
+  readonly activation: RoleTurnActivation;
+  readonly methods: readonly MethodBinding[];
+} {
+  return {
+    activation: activationForAdmitted(admitted),
+    methods: methodBindings(admitted, packageRoot),
+  };
+}

package/src/public-role-summons.ts

@@ -498,132 +498,45 @@ export async function summonPublicRole(
     return { ok: await run(prepared.env, () => parsedArgv) };
   }
 
+  const [{ runPublicInstructionSeat, runPublicInstructionSeatResume }, { PUBLIC_ROLE_ARGV }] = await Promise.all([
+    import("./public-cli/instruction-seat-run.ts"),
+    import("./public-cli/cli.ts"),
+  ]);
+  const { packagedRoleMetadata } = await import("./packaged-role-registry.ts");
+  const record = packagedRoleMetadata(options.role);
+  const parse = ((args: readonly string[]) =>
+    PUBLIC_ROLE_ARGV[options.role].parse(args)) as (args: readonly string[]) => import("./public-cli/invocation.ts").PublicSeatParse;
+  const resumeRunId = record?.summonResume === true
+    && typeof options.resumeRunId === "string"
+    && options.resumeRunId.trim() !== ""
+    ? options.resumeRunId.trim()
+    : undefined;
   let result: {
     exitCode: number;
     terminal?: TerminalResult;
     admitted?: { readonly runDirectory?: string };
   };
-  switch (options.role) {
-    case "notary": {
-      const [{ runPublicNotary }, { parseNotaryArgv }] = await Promise.all([
-        import("./public-cli/notary-run.ts"),
-        import("./public-cli/invocation.ts"),
-      ]);
-      const stepped = await runPrepared(parseNotaryArgv, (env, once) =>
-        runPublicNotary(options.argv, env as never, io, once));
-      if ("fail" in stepped) return stepped.fail;
-      result = stepped.ok;
-      break;
-    }
-    case "inspector": {
-      const [{ runPublicInspector }, { parseInspectorArgv }] = await Promise.all([
-        import("./public-cli/inspector-run.ts"),
-        import("./public-cli/invocation.ts"),
-      ]);
-      const stepped = await runPrepared(parseInspectorArgv, (env, once) =>
-        runPublicInspector(options.argv, env as never, io, once));
-      if ("fail" in stepped) return stepped.fail;
-      result = stepped.ok;
-      break;
-    }
-    case "auditor":
-    case "navigator":
-    case "gatekeeper": {
-      const seat = options.role;
-      const [{ runPublicInstructionSeat, runPublicInstructionSeatResume }, invocation] = await Promise.all([
-        import("./public-cli/instruction-seat-run.ts"),
-        import("./public-cli/invocation.ts"),
-      ]);
-      const parse =
-        seat === "auditor"
-          ? invocation.parseAuditorArgv
-          : seat === "navigator"
-            ? invocation.parseNavigatorArgv
-            : invocation.parseGatekeeperArgv;
-      const resumeRunId = typeof options.resumeRunId === "string" && options.resumeRunId.trim() !== ""
-        ? options.resumeRunId.trim()
-        : undefined;
-      if (resumeRunId !== undefined) {
-        // Host CLI resume — same face as `ak-role resume <runId> [message]`.
-        // Instruction/materials ride summons.instruction (not package memory).
-        const instruction = options.argv[0] ?? "";
-        const stepped = await runPrepared(parse, (env) =>
-          runPublicInstructionSeatResume(
-            {
-              runId: resumeRunId,
-              summons: {
-                instruction,
-                instructionEmpty: instruction.trim() === "",
-              },
-            },
-            env as never,
-            io,
-          ));
-        if ("fail" in stepped) return stepped.fail;
-        result = stepped.ok;
-      } else {
-        const stepped = await runPrepared(parse, (env, once) =>
-          runPublicInstructionSeat(options.argv, env as never, io, seat, once));
-        if ("fail" in stepped) return stepped.fail;
-        result = stepped.ok;
-      }
-      break;
-    }
-    case "judge": {
-      const [{ runPublicJudge }, { parseJudgeArgv }] = await Promise.all([
-        import("./public-cli/judge-run.ts"),
-        import("./public-cli/invocation.ts"),
-      ]);
-      const stepped = await runPrepared(parseJudgeArgv, (env, once) =>
-        runPublicJudge(options.argv, env as never, io, once));
-      if ("fail" in stepped) return stepped.fail;
-      result = stepped.ok;
-      break;
-    }
-    case "doctor": {
-      const [{ runPublicDoctor }, { parseDoctorArgv }] = await Promise.all([
-        import("./public-cli/doctor-run.ts"),
-        import("./public-cli/invocation.ts"),
-      ]);
-      const stepped = await runPrepared(parseDoctorArgv, (env, once) =>
-        runPublicDoctor(options.argv, env as never, io, once));
-      if ("fail" in stepped) return stepped.fail;
-      result = stepped.ok;
-      break;
-    }
-    case "diarist": {
-      const [{ runPublicDiarist }, { parseDiaristArgv }] = await Promise.all([
-        import("./public-cli/diarist-run.ts"),
-        import("./public-cli/invocation.ts"),
-      ]);
-      const stepped = await runPrepared(parseDiaristArgv, (env, once) =>
-        runPublicDiarist(options.argv, env as never, io, once));
-      if ("fail" in stepped) return stepped.fail;
-      result = stepped.ok;
-      break;
-    }
-    case "countersign": {
-      const [{ runPublicCountersign }, { parseCountersignArgv }] = await Promise.all([
-        import("./public-cli/countersign-run.ts"),
-        import("./public-cli/invocation.ts"),
-      ]);
-      const stepped = await runPrepared(parseCountersignArgv, (env, once) =>
-        runPublicCountersign(options.argv, env as never, io, once));
-      if ("fail" in stepped) return stepped.fail;
-      result = stepped.ok;
-      break;
-    }
-    case "reviewer": {
-      const [{ runPublicReviewer }, { parseReviewerArgv }] = await Promise.all([
-        import("./public-cli/reviewer-run.ts"),
-        import("./public-cli/invocation.ts"),
-      ]);
-      const stepped = await runPrepared(parseReviewerArgv, (env, once) =>
-        runPublicReviewer(options.argv, env as never, io, once));
-      if ("fail" in stepped) return stepped.fail;
-      result = stepped.ok;
-      break;
-    }
+  if (resumeRunId !== undefined) {
+    const instruction = options.argv[0] ?? "";
+    const stepped = await runPrepared(parse, (env) =>
+      runPublicInstructionSeatResume(
+        {
+          runId: resumeRunId,
+          summons: {
+            instruction,
+            instructionEmpty: instruction.trim() === "",
+          },
+        },
+        env as never,
+        io,
+      ));
+    if ("fail" in stepped) return stepped.fail;
+    result = stepped.ok;
+  } else {
+    const stepped = await runPrepared(parse, (env, once) =>
+      runPublicInstructionSeat(options.argv, env as never, io, options.role, once));
+    if ("fail" in stepped) return stepped.fail;
+    result = stepped.ok;
   }
 
   const stderr = captured?.stderrText();
@@ -1105,20 +1018,22 @@ export async function summonGateOfficer(options: {
     ...(options.hostAdapters === undefined ? {} : { hostAdapters: options.hostAdapters }),
     ...(options.createRunId === undefined ? {} : { createRunId: options.createRunId }),
   } as const;
-  if (options.officer === "notary") {
+  const { packagedGateSummon } = await import("./packaged-role-registry.ts");
+  const gateSummon = packagedGateSummon(options.officer);
+  if (gateSummon === "source-run") {
     // #753/#879: reask or verbatim body rides summons.instruction / first-mint prompt.
     // Binding stays --source-run (never folded into content).
     return summonPublicRole({
-      role: "notary",
+      role: options.officer,
       argv: ["--source-run", options.sourceRunDirectory, "--project", options.cwd],
       ...common,
     });
   }
-  if (options.officer === "auditor") {
+  if (gateSummon === "subject-source") {
     // #756: judge compliance path — same queue law as notary/inspector.
     // Binding pointer on argv; dialogue content rides gateReviewInstruction.
     return summonPublicRole({
-      role: "auditor",
+      role: options.officer,
       argv: [
         "--subject",
         "judge",
@@ -1129,13 +1044,14 @@ export async function summonGateOfficer(options: {
       ...common,
     });
   }
-  if (options.officer === "countersign") {
+  if (gateSummon === "parent-instruction") {
     // #969 / #987: Secretariat submission gate → 给事中.
     // Dialogue / identity instruction = parent typed payload 原话 (ADR 0079) or reask;
     // no code-authored summons prose (#924). Gate resume key = parentRunPath
     // (sourceRunDirectory); board ticket handoff is bind-only, never a resume
     // lookup (#987 Result 7). Receipt ticketNumber stays payload content.
     // correlationId only on this officer — notary/auditor/inspector stay untouched.
+    // Gate resume key is the parent run directory. The board ticket only binds.
     const { runIdFromRunDirectory } = await import("./run-terminal-artifacts.ts");
     const correlationId = runIdFromRunDirectory(options.sourceRunDirectory);
     if (correlationId === undefined || correlationId.trim() === "") {
@@ -1148,7 +1064,7 @@ export async function summonGateOfficer(options: {
     // Argv instruction = reask or parent payload bytes only (never a fabricated line).
     const instruction = options.reask ?? gateReviewInstruction ?? "";
     return summonPublicRole({
-      role: "countersign",
+      role: options.officer,
       argv: ["--project", options.cwd, "--", instruction],
       ...common,
       correlationId,
@@ -1159,7 +1075,7 @@ export async function summonGateOfficer(options: {
   // Inspector: argv stays pure 卷宗指针 (#747 parentRunPath lookup key).
   // Content (body/reask) rides env → summons.instruction / first-mint prompt.
   return summonPublicRole({
-    role: "inspector",
+    role: options.officer,
     argv: [`卷宗指针：${options.sourceRunDirectory}`],
     ...common,
   });

package/src/reviewer-role.ts

@@ -5,7 +5,8 @@ import { withTerminatingOutputDeclarations } from "./package-contracts/terminati
 
 import type { AnyCanonicalSkillBinding, CanonicalSkillBinding } from "./canonical-skill-binding.ts";
 export type { CanonicalSkillBinding };
-import { REVIEWER_ACCEPTED_TEXT, REVIEWER_OUTPUT_TOOL_NAME, type ReviewerIntent } from "./package-contracts/reviewer-output.ts";
+import { packagedRoleAcceptedText } from "./packaged-role-registry.ts";
+import { REVIEWER_OUTPUT_TOOL_NAME, type ReviewerIntent } from "./package-contracts/reviewer-output.ts";
 
 export { REVIEWER_OUTPUT_TOOL_NAME };
 export type { ReviewerIntent };
@@ -103,7 +104,7 @@ export function createReviewerRoleRuntime(
           async execute(_id: string, parameters: unknown): Promise<HostToolResult<unknown>> {
             if (!soul || !binding) throw new Error("御史台输入未装载");
             return {
-              content: [{ type: "text" as const, text: REVIEWER_ACCEPTED_TEXT }],
+              content: [{ type: "text" as const, text: packagedRoleAcceptedText("reviewer") }],
               details: parameters,
               terminate: true as const,
             };

package/src/role-activation-flags.ts

@@ -4,54 +4,33 @@
  * Host adapters only deliver these flags (ACP/headless getFlag map; pi argv pairs).
  */
 import type { RoleTurnRequest } from "./host-contracts.ts";
-import { packagedRoleInputFlag, packagedRolePhaseFlag } from "./packaged-role-registry.ts";
+import { packagedRoleActivationFlags } from "./packaged-role-registry.ts";
 
-/** Project closed RoleTurnActivation onto the shared host flag map. */
+/**
+ * Project closed RoleTurnActivation onto the shared host flag map.
+ * Seat flag names and fields come from the composition-root record.
+ * countersign ticketNumber stays off this map (no private transport flag, #632).
+ */
 export function projectActivationFlags(request: RoleTurnRequest): Map<string, boolean | string> {
   const activation = request.activation;
   const flags = new Map<string, boolean | string>([["ak-role", activation.role]]);
   if (request.stationChild === true) {
     flags.set("ak-station-child", true);
   }
-  const inputFlag = packagedRoleInputFlag(activation.role);
-  const phaseFlag = packagedRolePhaseFlag(activation.role);
-  if ("phase" in activation && phaseFlag !== undefined) flags.set(phaseFlag, activation.phase);
-  if (inputFlag !== undefined) {
-    const path = "taskPath" in activation ? activation.taskPath
-      : "packetPath" in activation ? activation.packetPath
-        : "casePath" in activation ? activation.casePath
-          : "inputPath" in activation ? activation.inputPath
-            : "sourceRun" in activation ? activation.sourceRun
-              : undefined;
-    if (path !== undefined) flags.set(inputFlag, path);
-  }
-  if (activation.role === "fixer" && activation.prerequisitesPath !== undefined) {
-    flags.set("ak-fixer-prerequisites", activation.prerequisitesPath);
-  }
-  if (activation.role === "reviewer") {
-    flags.set("ak-review-base", activation.baseRevision);
-    flags.set("ak-review-lens", activation.lens);
-    flags.set("ak-review-authority-refs", JSON.stringify(activation.authorityRefs));
-    if (activation.ticketNumber !== undefined) {
-      flags.set("ak-review-ticket-number", String(activation.ticketNumber));
-    }
-  }
-  // countersign ticketNumber stays on activation/admission/invocation only —
-  // no private transport flag (inner-gate material path deleted in #632).
-  if (activation.role === "notary" && activation.ticketNumber !== undefined) {
-    flags.set("ak-notary-ticket-number", String(activation.ticketNumber));
-  }
-  if (activation.role === "gleaner-left") {
-    flags.set("ak-gleaner-left-base", activation.baseRevision);
-  }
-  if (activation.role === "collector") {
-    flags.set("ak-collector-repo", activation.repo);
-    // #676 D1: pr optional at admission; omit flag when role binds from materials.
-    if (activation.pr !== undefined) flags.set("ak-collector-pr", activation.pr);
-    if (activation.requestManifestPath !== undefined) {
-      flags.set("ak-collector-request-manifest", activation.requestManifestPath);
-    }
-    if (activation.waitMs !== undefined) flags.set("ak-collector-wait-ms", activation.waitMs);
+  const values = activation as Record<string, unknown>;
+  for (const spec of packagedRoleActivationFlags(activation.role)) {
+    if (spec.flag === undefined) continue;
+    const text = activationFlagText(values[spec.field]);
+    if (text !== undefined) flags.set(spec.flag, text);
   }
   return flags;
 }
+
+function activationFlagText(value: unknown): string | undefined {
+  if (typeof value === "string") return value;
+  if (typeof value === "number") return String(value);
+  if (Array.isArray(value) && value.every((item) => typeof item === "string")) {
+    return JSON.stringify(value);
+  }
+  return undefined;
+}

package/src/role-runtime-dependencies.ts

@@ -1,7 +1,6 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 
-import { loadCanonicalSkillBinding as loadHomeCanonicalSkillBinding } from "./canonical-skill-binding.ts";
 import { createGhCollectorGitHubTransport } from "./collector-github.ts";
 import { createPiDoctorAuditor } from "./doctor-auditor.ts";
 import { loadDoctorCase } from "./doctor-evidence.ts";
@@ -14,19 +13,31 @@ import {
   loadAuditorReferenceMaterialsFromSubjectInput,
   loadAuditorSoulFromSubjectInput,
 } from "./auditor-soul.ts";
+import { packagedRoleMetadata, type PackagedRole } from "./packaged-role-registry.ts";
 import {
-  loadGatekeeperSessionMaterials,
   loadMainRoleReferenceMaterials,
   loadMainRoleSessionMaterials,
 } from "./session-opening-materials.ts";
 
+function usesSubjectSoul(role: string): boolean {
+  const record = packagedRoleMetadata(role);
+  return record !== undefined && "soulSource" in record && record.soulSource === "subject";
+}
+
 /** Single packaged source for reference materials across production composition roots. */
 export function loadPackagedRoleReferenceMaterials(role: Parameters<NonNullable<RoleRuntimeDependencies["loadRoleReferenceMaterials"]>>[0]): Promise<string> {
-  return role === "auditor"
+  return usesSubjectSoul(role)
     ? loadAuditorReferenceMaterialsFromSubjectInput()
     : loadMainRoleReferenceMaterials(role);
 }
 
+/** One production soul loader. Subject seats read the subject input; every other seat reads its record. */
+export function loadRegisteredRoleSoul(role: PackagedRole): Promise<string> {
+  return usesSubjectSoul(role)
+    ? loadAuditorSoulFromSubjectInput()
+    : loadMainRoleSessionMaterials(role);
+}
+
 /** Host-neutral packaged role runtime deps for the parent-process envelope. */
 export function createRoleRuntimeDependencies(packageRoot: string): RoleRuntimeDependencies {
   // packageRoot is the install root (resources/ lives there). Never resolve via
@@ -39,37 +50,25 @@ export function createRoleRuntimeDependencies(packageRoot: string): RoleRuntimeD
   return {
     packageRoot,
     loadRoleReferenceMaterials: loadPackagedRoleReferenceMaterials,
-    loadJudgeSoul: () => loadMainRoleSessionMaterials("judge"),
-    loadFixerSoul: () => loadMainRoleSessionMaterials("fixer"),
+    loadRoleSoul: loadRegisteredRoleSoul,
     loadFixPacket: (path) => readFile(path, "utf8"),
-    loadCoderSoul: () => loadMainRoleSessionMaterials("coder"),
     loadCoderTask: (path) => readFile(path, "utf8"),
-    loadReviewerSoul: () => loadMainRoleSessionMaterials("reviewer"),
-    loadCollectorSoul: () => loadMainRoleSessionMaterials("collector"),
     loadCollectorHandbookSeed: () => readFile(collectorHandbookSeedPath, "utf8"),
     createCollectorTransport: () => createGhCollectorGitHubTransport(),
-    loadDoctorSoul: () => loadMainRoleSessionMaterials("doctor"),
     loadDoctorCase,
-    loadInspectorSoul: () => loadMainRoleSessionMaterials("inspector"),
-    loadGatekeeperSoul: () => loadGatekeeperSessionMaterials("gatekeeper"),
-    loadNavigatorSoul: () => loadMainRoleSessionMaterials("navigator"),
-    loadAuditorSoul: () => loadAuditorSoulFromSubjectInput(),
-    loadNotarySoul: () => loadMainRoleSessionMaterials("notary"),
-    loadCountersignSoul: () => loadMainRoleSessionMaterials("countersign"),
-    loadGleanerLeftSoul: () => loadMainRoleSessionMaterials("gleaner-left"),
-    loadDiaristSoul: () => loadMainRoleSessionMaterials("diarist"),
-    loadSecretariatSoul: () => loadMainRoleSessionMaterials("secretariat"),
     loadNotarySourceRun: loadNotarySourceRunLocator,
-    loadMergerSoul: () => loadMainRoleSessionMaterials("merger"),
     loadMergerInput: async (path) => JSON.parse(await readFile(path, "utf8")),
     async loadCanonicalSkillBinding(name) {
-      if (name === "tdd") {
-        return loadPackagedCanonicalSkillBinding(packageRoot, "tdd");
-      }
-      if (name === "ak-cross-m-review") {
-        return loadPackagedCanonicalSkillBinding(packageRoot, "ak-cross-m-review");
+      switch (name) {
+        case "tdd":
+          return loadPackagedCanonicalSkillBinding(packageRoot, name);
+        case "ak-cross-m-review":
+          return loadPackagedCanonicalSkillBinding(packageRoot, name);
+        default: {
+          const unexpected: never = name;
+          throw new Error(`Canonical skill is not packaged: ${String(unexpected)}`);
+        }
       }
-      return loadHomeCanonicalSkillBinding(name);
     },
     // #590: doctor compliance still on disposeCompliance path; judge→auditor is gate queue (#756).
     auditDoctorCompliance: (options) => doctorAuditor(options),
@@ -86,7 +85,7 @@ export function createRoleRuntimeDependencies(packageRoot: string): RoleRuntimeD
       subject: options.subject,
       authority: options.authority,
       invocationId: options.invocationId,
-      loadSoul: () => loadMainRoleSessionMaterials("navigator"),
+      loadSoul: () => loadRegisteredRoleSoul("navigator"),
       loadRoutePlaybook: () => readFile(navigatorRoutePlaybookPath, "utf8"),
       loadRoleHelp: async (role) => formatNavigatorRoleHelp(role),
       createSession: navigatorSessionFactory,