@akagilnc/pi-workflow-roles 0.1.4444 → 0.1.4503

package/dist/session-opening-materials.js

@@ -25,18 +25,29 @@ async function readPackageMaterial(relativePath) {
 }
 async function joinPackageMaterials(relativePaths) {
   const chunks = [];
-  for (const relativePath of relativePaths) {
-    chunks.push(await readPackageMaterial(relativePath));
-  }
+  for (const relativePath of relativePaths) chunks.push(await readPackageMaterial(relativePath));
   return chunks.join("\n\n");
 }
+function roleSoulPath(role, materials) {
+  const suffix = `/souls/${role}.md`;
+  const path = materials.find((candidate) => `/${candidate}`.endsWith(suffix));
+  if (path === void 0) throw new Error(`session materials omit the ${role} Soul`);
+  return path;
+}
+async function loadSeparatedSessionPart(role, materials, part) {
+  const soul = roleSoulPath(role, materials);
+  return part === "soul" ? readPackageMaterial(soul) : joinPackageMaterials(materials.filter((path) => path !== soul));
+}
 const MAIN_ROLE_SESSION_MATERIALS = {
   ...Object.fromEntries(
     PUBLIC_ROLE_RECORDS.map((record) => [record.role, record.sessionMaterials])
   )
 };
 function loadMainRoleSessionMaterials(role) {
-  return joinPackageMaterials(MAIN_ROLE_SESSION_MATERIALS[role]);
+  return loadSeparatedSessionPart(role, MAIN_ROLE_SESSION_MATERIALS[role], "soul");
+}
+function loadMainRoleReferenceMaterials(role) {
+  return loadSeparatedSessionPart(role, MAIN_ROLE_SESSION_MATERIALS[role], "references");
 }
 const GATEKEEPER_SESSION_MATERIALS = {
   // #639: single authority — the public gatekeeper record owns the province list.
@@ -45,13 +56,14 @@ const GATEKEEPER_SESSION_MATERIALS = {
   notary: NOTARY_SESSION_MATERIALS
 };
 function loadGatekeeperSessionMaterials(role) {
-  return joinPackageMaterials(GATEKEEPER_SESSION_MATERIALS[role]);
+  return loadSeparatedSessionPart(role, GATEKEEPER_SESSION_MATERIALS[role], "soul");
 }
 export {
   GATEKEEPER_SESSION_MATERIALS,
   MAIN_ROLE_SESSION_MATERIALS,
   joinPackageMaterials,
   loadGatekeeperSessionMaterials,
+  loadMainRoleReferenceMaterials,
   loadMainRoleSessionMaterials,
   readPackageMaterial,
   resolvePackageRootDir

package/extensions/role-runtime.ts

@@ -31,9 +31,14 @@ import { JUDGE_OUTPUT_TOOL_NAME } from "../src/package-contracts/judge-output.ts
 import { readOAuthKeepaliveProviders } from "../src/oauth-keepalive.ts";
 import {
   formatNavigatorRoleHelp,
+  type RoleRuntimeDependencies,
 } from "../src/role-runtime.ts";
 import { loadAuditorSoulFromSubjectInput } from "../src/auditor-soul.ts";
-import { loadGatekeeperSessionMaterials, loadMainRoleSessionMaterials } from "../src/session-opening-materials.ts";
+import { loadPackagedRoleReferenceMaterials } from "../src/role-runtime-dependencies.ts";
+import {
+  loadGatekeeperSessionMaterials,
+  loadMainRoleSessionMaterials,
+} from "../src/session-opening-materials.ts";
 const extensionPath = fileURLToPath(import.meta.url);
 const packageRoot = fileURLToPath(new URL("..", import.meta.url));
 const navigatorRoutePlaybookPath = fileURLToPath(new URL("../resources/navigator-route-playbook.md", import.meta.url));
@@ -105,12 +110,11 @@ export async function loadNavigatorWorkContext(
   });
 }
 
-export default function roleRuntime(pi: ExtensionAPI): void {
-  const oauthKeepaliveProviders = readOAuthKeepaliveProviders();
-  registerNavigatorModelCommand(pi);
+export function createPiRoleRuntimeDependencies(pi: ExtensionAPI): RoleRuntimeDependencies {
   const navigatorSessionFactory = createNativeNavigatorSessionFactory();
-  createPiRoleRuntimeExtension({
+  return {
     packageRoot,
+    loadRoleReferenceMaterials: loadPackagedRoleReferenceMaterials,
     loadJudgeSoul: () => loadMainRoleSessionMaterials("judge"),
     loadFixerSoul: () => loadMainRoleSessionMaterials("fixer"),
     loadFixPacket: (path) => readFile(path, "utf8"),
@@ -167,7 +171,13 @@ export default function roleRuntime(pi: ExtensionAPI): void {
       }
       return loadHomeCanonicalSkillBinding(name);
     },
-  }, {
+  };
+}
+
+export default function roleRuntime(pi: ExtensionAPI): void {
+  const oauthKeepaliveProviders = readOAuthKeepaliveProviders();
+  registerNavigatorModelCommand(pi);
+  createPiRoleRuntimeExtension(createPiRoleRuntimeDependencies(pi), {
     transcriptFromContext,
     oauthKeepalive: { providers: oauthKeepaliveProviders },
   })(pi);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akagilnc/pi-workflow-roles",
-  "version": "0.1.4444",
+  "version": "0.1.4503",
   "description": "Soul-bound workflow roles for Pi",
   "type": "module",
   "license": "Apache-2.0",

package/resources/method-host-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "ak-methods",
+  "version": "0.0.0",
+  "description": "ak-roles packaged role method skills"
+}

package/scripts/build-package.mjs

@@ -1,4 +1,4 @@
-import { chmod, copyFile, mkdir, readFile, writeFile } from "node:fs/promises";
+import { chmod, copyFile, cp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { build } from "esbuild";
@@ -200,6 +200,11 @@ export async function buildPackageArtifacts() {
   await buildAcpProductionHost();
   await buildHeadlessProductionHost();
   await buildMigrateBookTopology();
+  const pluginDir = join("dist", "method-host-plugin");
+  await rm(pluginDir, { recursive: true, force: true });
+  await mkdir(pluginDir, { recursive: true });
+  await cp("resources/method-host-plugin/.claude-plugin", join(pluginDir, ".claude-plugin"), { recursive: true });
+  await cp("resources/methods", join(pluginDir, "skills"), { recursive: true });
 }
 
 const isMain =

package/src/acp-host/description.ts

@@ -1,6 +1,6 @@
 /**
  * One ACP host description. Every host-specific value the generic ACP adapter
- * needs — binary location, argv shape, resume verb, binding filename, child env,
+ * needs — binary location, argv shape, resume verb, binding filename,
  * optional seat-profile soul — is data here; the lifecycle in role-turn-host.ts
  * stays one copy (#732).
  */
@@ -30,7 +30,6 @@ export type AcpHostDescription = Readonly<{
   boundResume: "session/load" | "session/new";
   /** Durable ACP binding filename written beside the session principal. */
   sessionBindingFile: string;
-  childEnv: Readonly<Record<string, string>>;
   /**
    * When set, the production factory ensures a seat profile whose SOUL.md is a
    * symlink to the packaged role soul, and prefixes argv with `flag <name>`.
@@ -44,8 +43,7 @@ export function resolveAcpBinary(description: AcpHostDescription, operatorHome:
   return join(operatorHome, ...description.binaryFromHome);
 }
 
-/** Stdio argv: optional profile flag, thinking flag (before the subcommand),
- * prefix, optional model flag pair, suffix. */
+/** Stdio argv: optional profile flag, thinking flag, prefix, model, suffix. */
 export function acpStdioArgs(
   description: AcpHostDescription,
   model?: { readonly model?: string; readonly thinking?: string },

package/src/acp-host/production-host.ts

@@ -55,7 +55,6 @@ export function createProductionAcpRoleTurnHost(options: ProductionAcpHostOption
   const { packageRoot, principalAuthority, description, hostName } = options;
   const env: NodeJS.ProcessEnv = {
     ...process.env,
-    ...description.childEnv,
     AK_PACKAGE_ROOT: packageRoot,
   };
 

package/src/auditor-soul.ts

@@ -85,10 +85,19 @@ export async function loadAuditorSoul(role: AuditorSoulRole): Promise<string> {
   if (soul.trim().length === 0) {
     throw new Error(`The ${role} auditor Soul is blank`);
   }
-  return joinPackageMaterials(materials);
+  return soul;
+}
+
+export function loadAuditorReferenceMaterials(role: AuditorSoulRole): Promise<string> {
+  const soulPath = auditorSoulRelativePath(role);
+  return joinPackageMaterials(AUDITOR_SESSION_MATERIALS[role].filter((path) => path !== soulPath));
 }
 
 /** Runtime loader: subject input decides which soul file to assemble. */
 export async function loadAuditorSoulFromSubjectInput(raw?: string): Promise<string> {
   return loadAuditorSoul(resolveAuditorSubject(raw));
 }
+
+export function loadAuditorReferenceMaterialsFromSubjectInput(raw?: string): Promise<string> {
+  return loadAuditorReferenceMaterials(resolveAuditorSubject(raw));
+}

package/src/headless-host/description.ts

@@ -90,6 +90,8 @@ export function headlessTurnArgs(options: {
   readonly effort?: string;
   /** Fresh session: pass as session id. Resume: pass as resume id. */
   readonly session: { readonly kind: "new"; readonly id: string } | { readonly kind: "resume"; readonly id: string };
+  /** Packaged method plugin dir (`--plugin-dir`). */
+  readonly pluginDir?: string;
 }): string[] {
   const { description } = options;
   const args: string[] = [
@@ -100,6 +102,7 @@ export function headlessTurnArgs(options: {
     description.jsonSchemaFlag,
     JSON.stringify(options.jsonSchema),
   ];
+  if (options.pluginDir) args.push("--plugin-dir", options.pluginDir);
   if (options.mcpConfigPath !== undefined && options.mcpConfigPath !== "") {
     args.push(description.mcpConfigFlag, options.mcpConfigPath);
   }
@@ -422,9 +425,7 @@ export function codexTurnArgs(options: {
 
   // JSONL event stream: thread_id + final agent_message + turn.completed/failed.
   args.push("--json");
-  // Operator config/MCP off; auth still uses CODEX_HOME (official).
-  // Project/system config and AGENTS.md have no official suppression switch.
-  args.push("--ignore-user-config", "--ignore-rules");
+  // Operator config/skills stay open (#922 host-native-loader). Auth uses CODEX_HOME.
   const roots = (options.writableRoots ?? []).filter((root) => root !== "");
   if (roots.length > 0) {
     // Resume has no --add-dir; the config key keeps extra roots available on both paths.

package/src/headless-host/role-turn-host.ts

@@ -23,6 +23,12 @@ import {
 } from "../prepared-role-turn.ts";
 
 import { reportHostSessionEvent } from "../host-session-record.ts";
+import {
+  applyClaudeSkillInvocation,
+  applyCodexSkillInvocation,
+  hostMethodSkills,
+  packagedMethodPluginDir,
+} from "../host-native-method.ts";
 import {
   closeJsonSchemaForCodex,
   codexTurnArgs,
@@ -410,6 +416,7 @@ function buildTurnArgs(options: {
   readonly sessionKind: "new" | "resume";
   readonly cwd: string;
   readonly writableRoots?: readonly string[];
+  readonly pluginDir?: string;
 }): readonly string[] {
   if (isCodexExecDescription(options.description)) {
     if (options.sessionKind === "resume" && !options.sessionId) {
@@ -441,6 +448,7 @@ function buildTurnArgs(options: {
     ...(options.model === undefined ? {} : { model: options.model }),
     ...(options.effort === undefined ? {} : { effort: options.effort }),
     session: { kind: options.sessionKind, id: options.sessionId },
+    ...(options.pluginDir === undefined ? {} : { pluginDir: options.pluginDir }),
   });
 }
 
@@ -469,11 +477,17 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
       await writeFile(systemPromptPath, systemPrompt, "utf8");
       let mcpConfigPath: string | undefined;
       let outputSchemaPath: string | undefined;
+      let pluginDir: string | undefined;
+      let applyMethodPrompt: (prompt: string) => string = codex
+        ? (prompt) => applyCodexSkillInvocation(request.methods, prompt)
+        : (prompt) => prompt;
       if (codex) {
-        // Codex --output-schema needs a closed transport projection on disk.
         outputSchemaPath = join(request.runDirectory, "headless-output-schema.json");
-        const closed = closeJsonSchemaForCodex(prepared.jsonSchema);
-        await writeFile(outputSchemaPath, `${JSON.stringify(closed, null, 2)}\n`, "utf8");
+        await writeFile(
+          outputSchemaPath,
+          `${JSON.stringify(closeJsonSchemaForCodex(prepared.jsonSchema), null, 2)}\n`,
+          "utf8",
+        );
       } else {
         mcpConfigPath = join(request.runDirectory, "headless-mcp-config.json");
         await writeFile(
@@ -481,6 +495,14 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
           `${JSON.stringify(headlessMcpConfigDocument(prepared.mcpServers), null, 2)}\n`,
           "utf8",
         );
+        if (hostMethodSkills(request.methods).length > 0) {
+          const packageRoot = env.AK_PACKAGE_ROOT ?? process.env.AK_PACKAGE_ROOT;
+          if (typeof packageRoot !== "string" || packageRoot === "") {
+            throw new Error("claude method plugin-dir requires AK_PACKAGE_ROOT");
+          }
+          pluginDir = packagedMethodPluginDir(packageRoot);
+          applyMethodPrompt = (prompt) => applyClaudeSkillInvocation(request.methods, prompt);
+        }
       }
 
       const sessionParent = config.sessionIdentity.resolveSessionFile(request.principal);
@@ -505,6 +527,7 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
               sessionKind,
               cwd: request.cwd,
               ...(gitCommonDir === undefined ? {} : { writableRoots: [gitCommonDir] }),
+              ...(pluginDir === undefined ? {} : { pluginDir }),
             });
           } catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -522,7 +545,7 @@ export function createHeadlessRoleTurnHost(config: HeadlessRoleTurnHostConfig):
               args,
               cwd: request.cwd,
               env,
-              stdin: prompt,
+              stdin: applyMethodPrompt(prompt),
               ...(abortSignal === undefined ? {} : { signal: abortSignal }),
               ...(request.timeoutMs === undefined ? {} : { timeoutMs: request.timeoutMs }),
               onStdoutLine(line) {

package/src/host-descriptions.ts

@@ -9,13 +9,6 @@
 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(
-  ["CLAUDE", "CURSOR", "CODEX"].flatMap((vendor) =>
-    ["SKILLS", "RULES", "AGENTS", "MCPS", "HOOKS", "SESSIONS"].map((kind) =>
-      [`GROK_${vendor}_${kind}_ENABLED`, "false"] as const)),
-);
-
 export const DEFAULT_ROLE_TURN_HOST = "pi" as const;
 
 export type HostFamily = "acp" | "headless";
@@ -32,11 +25,6 @@ export const HOST_DESCRIPTIONS: Readonly<Record<string, AcpHostDescription>> = O
     modelPassing: "argv",
     boundResume: "session/load",
     sessionBindingFile: "grok-acp-session.json",
-    childEnv: Object.freeze({
-      ...PRIVATE_COMPAT_ENV,
-      GROK_MEMORY: "0",
-      GROK_SUBAGENTS: "0",
-    }),
   }),
   /**
    * Operator home `~/.hermes`, native session/load resume, `acp` subcommand.
@@ -55,7 +43,6 @@ export const HOST_DESCRIPTIONS: Readonly<Record<string, AcpHostDescription>> = O
     modelPassing: "set_model",
     boundResume: "session/load",
     sessionBindingFile: "hermes-acp-session.json",
-    childEnv: Object.freeze({}),
     seatProfileSoul: Object.freeze({
       flag: "-p",
       namePrefix: "ak-",
@@ -69,12 +56,9 @@ export const HOST_DESCRIPTIONS: Readonly<Record<string, AcpHostDescription>> = O
  * Headless CLI family (#645 / #646). Claude print-mode is the first row;
  * codex exec (#646) adds another. Protocol-specific argv/parse live in
  * headless-host helpers (#752 per-host impl).
- * Claude fixedArgs: print mode, isolation without `--bare` (OAuth stays), full
- * permissions. stream-json + verbose: live host events for sitian records
- * (#811); result is last line. `--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.
+ * Claude fixedArgs: print mode, full permissions. stream-json + verbose: live
+ * host events for sitian records (#811); result is last line. Forced methods
+ * ride `--plugin-dir` (#922); operator skill/setting surfaces stay open.
  */
 export const HEADLESS_HOST_DESCRIPTIONS: Readonly<Record<string, HeadlessHostDescription>> = Object.freeze({
   "claude": Object.freeze({
@@ -87,10 +71,6 @@ export const HEADLESS_HOST_DESCRIPTIONS: Readonly<Record<string, HeadlessHostDes
       // Intermediate assistant/tool/system events require verbose with stream-json.
       "--verbose",
       "--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",

package/src/host-native-method.ts

@@ -0,0 +1,67 @@
+/** #922 host-native packaged method delivery. */
+import { lstat, mkdir, readlink, realpath, symlink } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+import type { MethodBinding } from "./host-contracts.ts";
+
+type HostMethodSkill = Readonly<{ name: string }>;
+export const HOST_METHOD_PLUGIN_NAME = "ak-methods" as const;
+export const packagedMethodsDir = (root: string) => join(root, "resources", "methods");
+export const packagedMethodPluginDir = (root: string) => join(root, "dist", "method-host-plugin");
+
+export function hostMethodSkills(methods: readonly MethodBinding[]): readonly HostMethodSkill[] {
+  return Object.freeze(methods.flatMap((method) => {
+    if (method.kind !== "skill") return [];
+    const name = basename(dirname(method.path));
+    return name ? [Object.freeze({ name })] : [];
+  }));
+}
+
+const alreadyPrefixed = (prompt: string, token: string) => {
+  const text = prompt.trimStart();
+  return text === token || text.startsWith(`${token} `) || text.startsWith(`${token}\n`);
+};
+
+function prefixMethodInvocation(token: string, prompt: string): string {
+  if (alreadyPrefixed(prompt, token)) return prompt;
+  return prompt ? `${token} ${prompt}` : token;
+}
+
+/** Claude's documented plugin Skill invocation syntax. */
+export function applyClaudeSkillInvocation(methods: readonly MethodBinding[], prompt: string): string {
+  const skills = hostMethodSkills(methods);
+  if (skills.length !== 1) return prompt;
+  return prefixMethodInvocation(`/${HOST_METHOD_PLUGIN_NAME}:${skills[0]!.name}`, prompt);
+}
+
+/** Codex's documented explicit Skill invocation syntax. */
+export function applyCodexSkillInvocation(methods: readonly MethodBinding[], prompt: string): string {
+  return hostMethodSkills(methods).reduceRight(
+    (invocation, skill) => prefixMethodInvocation(`$${skill.name}`, invocation),
+    prompt,
+  );
+}
+
+/** Install the documented project Skill catalog once and leave it in place. */
+export async function installWorkspaceMethodSkills(cwd: string, packageRoot: string): Promise<void> {
+  const target = await realpath(packagedMethodsDir(packageRoot));
+  const link = join(cwd, ".agents", "skills");
+  try {
+    const stat = await lstat(link);
+    if (!stat.isSymbolicLink() || await realpath(link) !== target) {
+      const detail = stat.isSymbolicLink() ? `symlink to ${await readlink(link)}` : "non-symlink entry";
+      throw new Error(`workspace method catalog conflict at ${link}: ${detail}`);
+    }
+    return;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+  await mkdir(dirname(link), { recursive: true });
+  try {
+    await symlink(target, link);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    if ((await realpath(link).catch(() => "")) !== target) {
+      throw new Error(`workspace method catalog conflict at ${link}`);
+    }
+  }
+}