@akagilnc/pi-workflow-roles 0.1.2521 → 0.1.2653-next.71811ca

package/src/packaged-role-registry.ts

@@ -1,4 +1,4 @@
-/** The single package-owned source for role attendance and settlement metadata. */
+/** Composition-root unique authoritative public-role records (#509 / #524). */
 import { COLLECTOR_OUTPUT_TOOL } from "./package-contracts/collector-output.ts";
 import { JUDGE_OUTPUT_TOOL_NAME } from "./package-contracts/judge-output.ts";
 import { REVIEWER_OUTPUT_TOOL_NAME } from "./package-contracts/reviewer-output.ts";
@@ -7,20 +7,130 @@ import { DOCTOR_OUTPUT_TOOL_NAME } from "./doctor-contracts.ts";
 import { MERGER_OUTPUT_TOOL_NAME } from "./merger-contracts.ts";
 import { NOTARY_OUTPUT_TOOL_NAME } from "./notary-contracts.ts";
 
-export const PACKAGED_ROLE_REGISTRY = [
-  { role: "judge", phases: [null], outputTool: JUDGE_OUTPUT_TOOL_NAME, inputFlag: undefined, phaseFlag: undefined, activationStage: "load-and-install" },
-  { role: "fixer", phases: ["plan", "apply"], outputTool: FIXER_OUTPUT_TOOL_NAME, inputFlag: "ak-fix-packet", phaseFlag: "ak-fixer-phase", activationStage: "load-and-install" },
-  { role: "coder", phases: ["plan", "apply"], outputTool: CODER_OUTPUT_TOOL_NAME, inputFlag: "ak-coder-task", phaseFlag: "ak-coder-phase", activationStage: "load-and-install" },
-  { role: "reviewer", phases: [null], outputTool: REVIEWER_OUTPUT_TOOL_NAME, inputFlag: undefined, phaseFlag: undefined, activationStage: "load-and-install" },
+/** Shared by public notary and gatekeeper-province notary. */
+export const NOTARY_SESSION_MATERIALS = [
+  "CLAUDE.md",
+  "souls/notary.md",
+  "souls/gate-output-guide.md",
+] as const;
+
+/**
+ * One record per public callable role. Navigator is absent (name-only materials
+ * live on the session-opening projection).
+ */
+export const PUBLIC_ROLE_RECORDS = [
+  {
+    role: "judge",
+    phases: [null],
+    outputTool: JUDGE_OUTPUT_TOOL_NAME,
+    inputFlag: undefined,
+    phaseFlag: undefined,
+    activationStage: "load-and-install",
+    sessionMaterials: [
+      "CLAUDE.md",
+      "souls/judge.md",
+      "souls/audit-law.md",
+      "souls/quality-law.md",
+      "souls/judge-output-guide.md",
+    ],
+  },
+  {
+    role: "fixer",
+    phases: ["plan", "apply"],
+    outputTool: FIXER_OUTPUT_TOOL_NAME,
+    inputFlag: "ak-fix-packet",
+    phaseFlag: "ak-fixer-phase",
+    activationStage: "load-and-install",
+    sessionMaterials: [
+      "CLAUDE.md",
+      "souls/fixer.md",
+      "souls/quality-law.md",
+      "souls/fixer-output-guide.md",
+    ],
+  },
+  {
+    role: "coder",
+    phases: ["plan", "apply"],
+    outputTool: CODER_OUTPUT_TOOL_NAME,
+    inputFlag: "ak-coder-task",
+    phaseFlag: "ak-coder-phase",
+    activationStage: "load-and-install",
+    sessionMaterials: [
+      "CLAUDE.md",
+      "souls/coder.md",
+      "souls/quality-law.md",
+      "souls/coder-output-guide.md",
+    ],
+  },
+  {
+    role: "reviewer",
+    phases: [null],
+    outputTool: REVIEWER_OUTPUT_TOOL_NAME,
+    inputFlag: undefined,
+    phaseFlag: undefined,
+    activationStage: "load-and-install",
+    sessionMaterials: [
+      "CLAUDE.md",
+      "souls/reviewer.md",
+      "souls/audit-law.md",
+      "souls/quality-law.md",
+    ],
+  },
   // ak-collector-repo is GitHub owner/repo identity, not a local material path (#438).
-  { role: "collector", phases: [null], outputTool: COLLECTOR_OUTPUT_TOOL, inputFlag: undefined, phaseFlag: undefined, activationStage: "load-and-install" },
-  { role: "doctor", phases: [null], outputTool: DOCTOR_OUTPUT_TOOL_NAME, inputFlag: "ak-doctor-case", phaseFlag: undefined, activationStage: "load-and-install" },
-  { role: "merger", phases: [null], outputTool: MERGER_OUTPUT_TOOL_NAME, inputFlag: "ak-merger-input", phaseFlag: undefined, activationStage: "prepare-git-and-install" },
-  { role: "notary", phases: [null], outputTool: NOTARY_OUTPUT_TOOL_NAME, inputFlag: "ak-notary-source-run", phaseFlag: undefined, activationStage: "load-and-install" },
+  {
+    role: "collector",
+    phases: [null],
+    outputTool: COLLECTOR_OUTPUT_TOOL,
+    inputFlag: undefined,
+    phaseFlag: undefined,
+    activationStage: "load-and-install",
+    sessionMaterials: ["CLAUDE.md", "souls/collector.md"],
+  },
+  {
+    role: "doctor",
+    phases: [null],
+    outputTool: DOCTOR_OUTPUT_TOOL_NAME,
+    inputFlag: "ak-doctor-case",
+    phaseFlag: undefined,
+    activationStage: "load-and-install",
+    sessionMaterials: ["CLAUDE.md", "souls/doctor.md"],
+  },
+  {
+    role: "merger",
+    phases: [null],
+    outputTool: MERGER_OUTPUT_TOOL_NAME,
+    inputFlag: "ak-merger-input",
+    phaseFlag: undefined,
+    activationStage: "prepare-git-and-install",
+    sessionMaterials: ["CLAUDE.md", "souls/merger.md"],
+  },
+  {
+    role: "notary",
+    phases: [null],
+    outputTool: NOTARY_OUTPUT_TOOL_NAME,
+    inputFlag: "ak-notary-source-run",
+    phaseFlag: undefined,
+    activationStage: "load-and-install",
+    sessionMaterials: NOTARY_SESSION_MATERIALS,
+  },
 ] as const;
 
-export type PackagedRole = (typeof PACKAGED_ROLE_REGISTRY)[number]["role"];
-export type PackagedRoleMetadata = (typeof PACKAGED_ROLE_REGISTRY)[number];
+export type PublicRoleRecord = (typeof PUBLIC_ROLE_RECORDS)[number];
+export type PackagedRole = PublicRoleRecord["role"];
+
+/**
+ * Read-only metadata projection (no sessionMaterials).
+ * Distributed per PublicRoleRecord member so role↔field associations stay intact.
+ */
+export type PackagedRoleMetadata = PublicRoleRecord extends infer R
+  ? R extends PublicRoleRecord
+    ? Omit<R, "sessionMaterials">
+    : never
+  : never;
+
+/** Historical symbol — derived from PUBLIC_ROLE_RECORDS. */
+export const PACKAGED_ROLE_REGISTRY: readonly PackagedRoleMetadata[] =
+  PUBLIC_ROLE_RECORDS.map(({ sessionMaterials: _omit, ...metadata }) => metadata);
 
 export function packagedRoleMetadata(role: string): PackagedRoleMetadata | undefined {
   return PACKAGED_ROLE_REGISTRY.find((entry) => entry.role === role);

package/src/pi/adapter.ts

@@ -0,0 +1,192 @@
+import {
+  parseSkillBlock,
+  type ExtensionAPI,
+  type ExtensionContext,
+  type SessionManager,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import type { Static, TSchema } from "typebox";
+import { requireGatekeeperPass, type GatekeeperNonPassResult, type GatekeeperSubject } from "../gatekeeper-role.ts";
+import type {
+  HostContext,
+  HostEventRegistration,
+  HostGatekeeperActions,
+  HostToolDefinition,
+  HostToolResult,
+  RoleHost,
+} from "../host-contracts.ts";
+
+export type PiRoleHostAdapter = {
+  readonly host: RoleHost;
+};
+
+const piContexts = new WeakMap<HostContext, ExtensionContext>();
+
+/** Project Pi's activation context onto the package-owned host contract. */
+function projectPiContext(context: ExtensionContext, transcriptFromContext?: (context: ExtensionContext) => string): HostContext {
+  const sessionManager = context.sessionManager as SessionManager;
+  const host: HostContext = {
+    cwd: context.cwd,
+    mode: context.mode,
+    model: context.model === undefined ? undefined : { provider: context.model.provider },
+    sessionManager: {
+      getLeafEntry: () => context.sessionManager.getLeafEntry(),
+      getLeafId: () => context.sessionManager.getLeafId(),
+      getEntries: () => context.sessionManager.getEntries(),
+      getSessionDir: () => context.sessionManager.getSessionDir(),
+      getSessionFile: () => context.sessionManager.getSessionFile(),
+      getHeader: () => context.sessionManager.getHeader(),
+      setSessionFile: (path) => sessionManager.setSessionFile(path),
+      appendCustomEntry: (customType, data) => sessionManager.appendCustomEntry(customType, data),
+    },
+    ...(context.signal === undefined ? {} : { signal: context.signal }),
+    ...(context.ui === undefined ? {} : { ui: { notify: (message, type) => context.ui.notify(message, type) } }),
+    ...(transcriptFromContext === undefined ? {} : { transcript: () => transcriptFromContext(context) }),
+    abort: () => context.abort(),
+  };
+  piContexts.set(host, context);
+  return host;
+}
+
+/** Recover the Pi context only at the Pi composition boundary. */
+export function toPiContext(context: HostContext): ExtensionContext {
+  const piContext = piContexts.get(context);
+  if (piContext === undefined) throw new Error("Host context is not backed by the Pi adapter");
+  return piContext;
+}
+
+/** Gatekeeper receives HostContext directly (#518 §1③) without recovering raw ExtensionContext via WeakMap. */
+function requirePiGatekeeperPass(options: {
+  context: HostContext;
+  subject: GatekeeperSubject;
+  signal?: AbortSignal;
+  hostActions: HostGatekeeperActions;
+  toolCallId: string;
+}): Promise<void> {
+  return requireGatekeeperPass({
+    context: options.context,
+    subject: options.subject,
+    ...(options.signal === undefined ? {} : { signal: options.signal }),
+    hostActions: {
+      failInfrastructure(error, _context, toolCallId) {
+        options.hostActions.failInfrastructure(error, options.context, toolCallId);
+      },
+      bindSubmissionNonPass: options.hostActions.bindSubmissionNonPass,
+    },
+    toolCallId: options.toolCallId,
+  });
+}
+
+function toPiResult<D>(result: HostToolResult<D>): HostToolResult<D> {
+  return result;
+}
+
+function toPiToolDefinition<S extends TSchema, D>(
+  tool: HostToolDefinition<S, D>,
+  projectContext: (context: ExtensionContext) => HostContext,
+): ToolDefinition<S, D> {
+  return {
+    name: tool.name,
+    label: tool.label,
+    description: tool.description,
+    ...(tool.promptSnippet === undefined ? {} : { promptSnippet: tool.promptSnippet }),
+    parameters: tool.parameters,
+    execute: async (toolCallId, params, signal, update, context) =>
+      toPiResult(await tool.execute(
+        toolCallId,
+        params as Static<S>,
+        signal,
+        update === undefined ? undefined : (result) => update(toPiResult(result)),
+        projectContext(context),
+      )),
+  };
+}
+
+/** Pi composition boundary. Each consumed capability is adapted explicitly. */
+export function createPiRoleHostAdapter(
+  pi: ExtensionAPI,
+  options: { transcriptFromContext?: (context: ExtensionContext) => string } = {},
+): PiRoleHostAdapter {
+  const host: RoleHost = {
+    capabilities: {
+      skillExpansion(prompt) {
+        const parsed = parseSkillBlock(prompt);
+        if (parsed == null) return undefined;
+        const userMessage = parsed.userMessage ?? "";
+        return Object.freeze({
+          name: parsed.name,
+          location: parsed.location,
+          content: parsed.content,
+          userMessage,
+        });
+      },
+    },
+    registerFlag: (name, definition) => pi.registerFlag(name, definition),
+    getFlag: (name) => pi.getFlag(name),
+    registerTool: (tool) => pi.registerTool(toPiToolDefinition(
+      tool,
+      (context) => projectPiContext(context, options.transcriptFromContext),
+    )),
+    getAllTools: () => pi.getAllTools().map(({ name, sourceInfo }) => ({
+      name,
+      ...(sourceInfo?.path === undefined ? {} : { sourceInfo: { path: sourceInfo.path } }),
+    })),
+    setActiveTools: (names) => pi.setActiveTools(names),
+    getActiveTools: () => pi.getActiveTools(),
+    requireGatekeeperPass: requirePiGatekeeperPass,
+    on(...registration: HostEventRegistration) {
+      const context = (value: ExtensionContext) => projectPiContext(value, options.transcriptFromContext);
+      if (registration[0] === "before_agent_start") {
+        const [, handler] = registration;
+        pi.on("before_agent_start", (value, ctx) => handler({ prompt: value.prompt, systemPrompt: value.systemPrompt, systemPromptOptions: value.systemPromptOptions }, context(ctx)));
+      } else if (registration[0] === "input") {
+        const [, handler] = registration;
+        pi.on("input", (value, ctx) => handler({ text: value.text, ...(value.images === undefined ? {} : { images: value.images }), source: value.source }, context(ctx)));
+      } else if (registration[0] === "tool_call") {
+        const [, handler] = registration;
+        pi.on("tool_call", (value, ctx) => handler({ toolName: value.toolName, toolCallId: value.toolCallId, input: value.input }, context(ctx)));
+      } else if (registration[0] === "tool_result") {
+        const [, handler] = registration;
+        pi.on("tool_result", (value, ctx) => handler({ toolName: value.toolName, toolCallId: value.toolCallId, isError: value.isError, content: (value.content ?? []).map((part) => part.type === "text" ? { type: "text", text: part.text } : { type: "image", data: part.data, mimeType: part.mimeType }), details: value.details }, context(ctx)));
+      } else if (registration[0] === "session_start") {
+        const [, handler] = registration;
+        pi.on("session_start", (value, ctx) => handler({ reason: value.reason }, context(ctx)));
+      } else if (registration[0] === "session_shutdown") {
+        const [, handler] = registration;
+        pi.on("session_shutdown", (_value, ctx) => handler({}, context(ctx)));
+      } else if (registration[0] === "after_provider_response") {
+        const [, handler] = registration;
+        pi.on("after_provider_response", (value, ctx) => handler({ status: value.status }, context(ctx)));
+      } else if (registration[0] === "agent_end") {
+        const [, handler] = registration;
+        pi.on("agent_end", (value, ctx) => handler({
+        messages: value.messages.map((message) => ({
+          role: message.role,
+          content: "content" in message && Array.isArray(message.content) ? message.content.map((part) => part.type === "text"
+            ? { type: "text", text: part.text }
+            : part.type === "toolCall"
+              ? { type: "toolCall", id: part.id, name: part.name, arguments: part.arguments }
+              : { type: part.type }) : [],
+          ...("toolName" in message && typeof message.toolName === "string" ? { toolName: message.toolName } : {}),
+          ...("isError" in message && typeof message.isError === "boolean" ? { isError: message.isError } : {}),
+          ...("stopReason" in message && typeof message.stopReason === "string" ? { stopReason: message.stopReason } : {}),
+        })),
+      }, context(ctx)));
+      } else if (registration[0] === "agent_settled") {
+        const [, handler] = registration;
+        pi.on("agent_settled", (_value, ctx) => handler({}, context(ctx)));
+      } else if (registration[0] === "tool_execution_start") {
+        const [, handler] = registration;
+        pi.on("tool_execution_start", (value, ctx) => handler({ toolName: value.toolName, toolCallId: value.toolCallId }, context(ctx)));
+      } else if (registration[0] === "tool_execution_update") {
+        const [, handler] = registration;
+        pi.on("tool_execution_update", (value, ctx) => handler({ toolName: value.toolName, toolCallId: value.toolCallId, partialResult: value.partialResult }, context(ctx)));
+      } else {
+        const [, handler] = registration;
+        pi.on("tool_execution_end", (value, ctx) => handler({ toolName: value.toolName, toolCallId: value.toolCallId, isError: value.isError }, context(ctx)));
+      }
+    },
+    ...(typeof pi.getCommands === "function" ? { getCommands: () => pi.getCommands().map(({ name }) => ({ name })) } : {}),
+  };
+  return { host };
+}

package/src/pi/durable-principal.ts

@@ -0,0 +1,98 @@
+import { lstat } from "node:fs/promises";
+import { join } from "node:path";
+
+import type {
+  DurablePrincipal,
+  DurablePrincipalAuthority,
+  DurablePrincipalCoordinates,
+  NewDurablePrincipalRequest,
+} from "../host-contracts.ts";
+import { resolveBookKeyFromGit } from "../activation-ledger-git.ts";
+import {
+  activationBookDirectory,
+  resolveActivationLedgerHome,
+} from "../activation-ledger-topology.ts";
+
+type PiDurablePrincipal = DurablePrincipal & {
+  readonly sessionDirectory: string;
+  readonly sessionFile: string;
+};
+
+function encode(coordinates: DurablePrincipalCoordinates): PiDurablePrincipal {
+  return coordinates as PiDurablePrincipal;
+}
+
+export function issuePiDurablePrincipalCoordinates(
+  request: NewDurablePrincipalRequest,
+): DurablePrincipalCoordinates & {
+  readonly ledgerHome: string;
+  readonly bookKey: string;
+  readonly runDirectory: string;
+} {
+  const ledgerHome = resolveActivationLedgerHome(
+    request.home === undefined ? undefined : () => request.home!,
+  );
+  const bookKey = resolveBookKeyFromGit(request.cwd);
+  const runDirectory = join(
+    activationBookDirectory(ledgerHome, bookKey),
+    "runs",
+    `${request.runId}@${request.role}`,
+  );
+  const sessionDirectory = join(runDirectory, "session");
+  return {
+    ledgerHome,
+    bookKey,
+    runDirectory,
+    sessionDirectory,
+    sessionFile: join(sessionDirectory, "session.jsonl"),
+  };
+}
+
+/** Pi's durable-principal codec and availability authority. */
+export const piDurablePrincipalAuthority: DurablePrincipalAuthority = {
+  issue(request: NewDurablePrincipalRequest): DurablePrincipal {
+    const coordinates = issuePiDurablePrincipalCoordinates(request);
+    return encode({
+      sessionDirectory: coordinates.sessionDirectory,
+      sessionFile: coordinates.sessionFile,
+    });
+  },
+  decode(value: unknown): DurablePrincipalCoordinates {
+    const record = value as Partial<DurablePrincipalCoordinates> | null;
+    if (record === null || typeof record !== "object") {
+      throw new Error("durable principal payload is missing");
+    }
+    if (typeof record.sessionDirectory !== "string" || record.sessionDirectory.trim() === "") {
+      throw new Error("durable principal session directory is missing");
+    }
+    return {
+      sessionDirectory: record.sessionDirectory,
+      sessionFile:
+        typeof record.sessionFile === "string" && record.sessionFile.trim() !== ""
+          ? record.sessionFile
+          : join(record.sessionDirectory, "session.jsonl"),
+    };
+  },
+  async isAvailable(principal: DurablePrincipal): Promise<boolean> {
+    const { sessionFile } = this.decode(principal);
+    try {
+      const stat = await lstat(sessionFile);
+      return stat.isFile() && !stat.isSymbolicLink();
+    } catch {
+      return false;
+    }
+  },
+};
+
+/**
+ * Transitional coordinate accessor.
+ * S1b-2 (#526) removed 13 per-role builder accessors and auto-resume decode
+ * consumption. Remaining consumers: admission persistence projection and
+ * settlement/inspect (S4 #519 retires this seam).
+ */
+export function decodePiDurablePrincipal(
+  authority: DurablePrincipalAuthority,
+  principal: DurablePrincipal,
+): DurablePrincipalCoordinates {
+  return authority.decode(principal);
+}