@akagilnc/pi-workflow-roles 0.1.2043 → 0.1.2052

package/extensions/role-runtime.ts

@@ -33,6 +33,7 @@ import {
 import { loadCanonicalSkillBinding as loadHomeCanonicalSkillBinding } from "../src/canonical-skill-binding.ts";
 import { loadPackagedCanonicalSkillBinding } from "../src/package-resources/method-skill-binding.ts";
 import { JUDGE_OUTPUT_TOOL_NAME } from "../src/package-contracts/judge-output.ts";
+import { readOAuthKeepaliveProviders } from "../src/oauth-keepalive.ts";
 import {
   createProductionMergerGitState,
   createRoleRuntimeExtension,
@@ -244,7 +245,11 @@ export default function roleRuntime(pi: ExtensionAPI): void {
   const reviewerAgent = createReviewerAgentRunner();
   registerNavigatorModelCommand(pi);
   const navigatorSessionFactory = createNativeNavigatorSessionFactory();
+  // #351: static provider list from extension setting (default ["kimi-coding"]).
+  // Production root is the sole reader; keepalive never auto-detects providers.
+  const oauthKeepaliveProviders = readOAuthKeepaliveProviders();
   createRoleRuntimeExtension({
+    oauthKeepalive: { providers: oauthKeepaliveProviders },
     loadJudgeSoul: () => readFile(judgeSoulPath, "utf8"),
     loadFixerSoul: () => readFile(fixerSoulPath, "utf8"),
     loadFixPacket: (path) => readFile(path, "utf8"),

package/package.json

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

package/resources/engines/codex.md

@@ -0,0 +1,32 @@
+# codex engine method material
+
+This file is packaged method material for the optional `codex` labor engine.
+When a role run selects this engine, read these bytes and follow the local CLI's
+actual interface for the labor detour. Return the labor result to the same role
+session so typed submission stays on the existing in-session path.
+
+Material is data for the model, not a code contract. Do not invent package flags.
+
+## Invocation examples (local Codex CLI)
+
+Non-interactive labor prompt (working root = role project):
+
+```bash
+codex exec -C "$PROJECT_ROOT" "YOUR_LABOR_PROMPT"
+```
+
+Write the last agent message to a file, then bring that text back into the role
+session:
+
+```bash
+codex exec -C "$PROJECT_ROOT" -o /tmp/codex-labor-last.txt "YOUR_LABOR_PROMPT"
+```
+
+JSON event stream when the host needs machine-readable progress:
+
+```bash
+codex exec --json -C "$PROJECT_ROOT" "YOUR_LABOR_PROMPT"
+```
+
+Prefer the installed `codex` binary's own `--help` / `codex exec --help` over
+any remembered flag set. Do not wrap this engine behind `ak-role` flags.

package/resources/engines/cursor.md

@@ -0,0 +1,32 @@
+# cursor engine method material
+
+This file is packaged method material for the optional `cursor` labor engine.
+When a role run selects this engine, read these bytes and follow the local CLI's
+actual interface for the labor detour. Return the labor result to the same role
+session so typed submission stays on the existing in-session path.
+
+Material is data for the model, not a code contract. Do not invent package flags.
+
+## Invocation examples (local Cursor Agent CLI)
+
+The machine entrypoint is `agent` (also exposed as `cursor-agent`). Run from the
+role project root. Non-interactive print mode:
+
+```bash
+agent -p --force --output-format text "YOUR_LABOR_PROMPT"
+```
+
+Choose a model explicitly when the seat needs a known Cursor model id:
+
+```bash
+agent -p --force --model grok-4.5 --output-format text "YOUR_LABOR_PROMPT"
+```
+
+Stream JSON events for long labor:
+
+```bash
+agent -p --force --output-format stream-json "YOUR_LABOR_PROMPT"
+```
+
+Prefer `agent --help` on the host over any remembered flag set. Do not wrap this
+engine behind `ak-role` flags.

package/resources/engines/kimi.md

@@ -0,0 +1,31 @@
+# kimi engine method material
+
+This file is packaged method material for the optional `kimi` labor engine.
+When a role run selects this engine, read these bytes and follow the local CLI's
+actual interface for the labor detour. Return the labor result to the same role
+session so typed submission stays on the existing in-session path.
+
+Material is data for the model, not a code contract. Do not invent package flags.
+
+## Invocation examples (local Kimi Code CLI)
+
+One-shot non-interactive prompt from the role project root:
+
+```bash
+kimi --yolo -p "YOUR_LABOR_PROMPT"
+```
+
+Pin a model alias when needed:
+
+```bash
+kimi --yolo -m <model-alias> -p "YOUR_LABOR_PROMPT"
+```
+
+Machine-readable prompt mode:
+
+```bash
+kimi --yolo --output-format text -p "YOUR_LABOR_PROMPT"
+```
+
+Prefer `kimi --help` on the host over any remembered flag set. Do not wrap this
+engine behind `ak-role` flags.

package/src/oauth-keepalive.ts

@@ -0,0 +1,216 @@
+/**
+ * Extension-side OAuth credential keepalive (#351).
+ *
+ * Periodically calls the public `ctx.modelRegistry.refresh` facade so expired
+ * OAuth tokens (e.g. kimi-coding 900s TTL) are renewed during long sessions.
+ * Does not read auth.json, touch pi-ai private APIs, or reuse the 183s idle gate.
+ */
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const DEFAULT_OAUTH_KEEPALIVE_PROVIDERS = ["kimi-coding"] as const;
+
+export const OAUTH_KEEPALIVE_INTERVAL_MS = 60_000;
+
+/** Persistent extension setting filename under PI_CODING_AGENT_DIR / ~/.pi/agent. */
+export const OAUTH_KEEPALIVE_SETTING_FILENAME = "oauth-keepalive.json";
+
+/** Path to the static provider-list extension setting (default ["kimi-coding"]). */
+export function oauthKeepaliveSettingPath(): string {
+  return join(
+    process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent"),
+    OAUTH_KEEPALIVE_SETTING_FILENAME,
+  );
+}
+
+function isExactRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Read the static keepalive provider list from the extension setting file.
+ * Missing file → default ["kimi-coding"]. Malformed content fails closed.
+ * Production extension root is the sole caller that feeds this into keepalive.
+ */
+export function readOAuthKeepaliveProviders(
+  path = oauthKeepaliveSettingPath(),
+): readonly string[] {
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf8")) as unknown;
+    if (!isExactRecord(raw) || !Array.isArray(raw.providers)) {
+      throw new Error(
+        "OAuth keepalive setting is malformed: expected { providers: string[] }",
+      );
+    }
+    const providers = raw.providers.map((id, index) => {
+      if (typeof id !== "string" || id.trim() === "") {
+        throw new Error(
+          `OAuth keepalive setting providers[${index}] must be a non-empty string`,
+        );
+      }
+      // Accept via trim-non-empty; return the normalized id so refresh can hit real providers.
+      return id.trim();
+    });
+    return Object.freeze(providers);
+  } catch (error) {
+    // Absent optional setting uses the documented default; all other causes propagate.
+    if (
+      error instanceof Error &&
+      "code" in error &&
+      (error as NodeJS.ErrnoException).code === "ENOENT"
+    ) {
+      return DEFAULT_OAUTH_KEEPALIVE_PROVIDERS;
+    }
+    throw error;
+  }
+}
+
+/** Injected interval scheduler (same shape as TrajectoryScheduler). */
+export type OAuthKeepaliveScheduler = {
+  /** Schedule `tick` every `ms` milliseconds; return a cancel function. */
+  every: (ms: number, tick: () => void) => () => void;
+};
+
+export type OAuthKeepaliveOptions = {
+  /** Static provider id list; frozen at construction. Default: ["kimi-coding"]. */
+  providers?: readonly string[];
+  /** Interval between ticks in ms. Default: 60_000. First tick is after one interval. */
+  intervalMs?: number;
+  /** Injectable scheduler for tests. Default: setInterval + unref. */
+  scheduler?: OAuthKeepaliveScheduler;
+};
+
+/** Minimal context surface used by keepalive (public extension facade only). */
+export type OAuthKeepaliveContext = {
+  modelRegistry: {
+    refresh: (options?: {
+      allowNetwork?: boolean;
+      providers?: readonly string[];
+      force?: boolean;
+      signal?: AbortSignal;
+    }) => Promise<{
+      aborted: boolean;
+      errors: ReadonlyMap<string, Error>;
+    }>;
+  };
+  ui?: {
+    notify?: (message: string, type?: "info" | "warning" | "error") => void;
+  };
+};
+
+export type OAuthKeepalive = {
+  start(ctx: OAuthKeepaliveContext): void;
+  stop(): void;
+};
+
+const defaultScheduler: OAuthKeepaliveScheduler = {
+  every(ms, tick) {
+    const timer = setInterval(tick, ms);
+    // Allow the process to exit if a caller forgets stop (same discipline as trajectory).
+    timer.unref?.();
+    return () => clearInterval(timer);
+  },
+};
+
+function errorClassName(error: unknown): string {
+  if (error instanceof Error && error.name.trim() !== "") return error.name;
+  if (error !== null && typeof error === "object" && "name" in error) {
+    const name = (error as { name?: unknown }).name;
+    if (typeof name === "string" && name.trim() !== "") return name;
+  }
+  return "Error";
+}
+
+function formatWarning(providerId: string, error: unknown): string {
+  const cls = errorClassName(error);
+  const detail =
+    error instanceof Error
+      ? error.message
+      : typeof error === "string"
+        ? error
+        : String(error);
+  return `oauth-keepalive: refresh failed for provider ${providerId} (${cls}): ${detail}`;
+}
+
+function emitWarning(ctx: OAuthKeepaliveContext, providerId: string, error: unknown): void {
+  const text = formatWarning(providerId, error);
+  // Exactly one visible surface per failure: prefer ui.notify when present;
+  // console.warn only when notify is unavailable (print/json / headless)
+  // or when notify itself throws (still one surface; carry the notify cause).
+  const notify = ctx.ui?.notify;
+  if (typeof notify === "function") {
+    try {
+      notify(text, "warning");
+    } catch (notifyError) {
+      // Notify threw: fall back once so refresh failure stays visible.
+      console.warn(text, notifyError);
+    }
+    return;
+  }
+  console.warn(text);
+}
+
+/**
+ * Session-lifecycle owner for periodic OAuth refresh via the public modelRegistry facade.
+ * Single-flight: overlapping ticks are skipped. stop() cancels the interval and aborts in-flight work.
+ */
+export function createOAuthKeepalive(options: OAuthKeepaliveOptions = {}): OAuthKeepalive {
+  const providers = Object.freeze(
+    (options.providers ?? DEFAULT_OAUTH_KEEPALIVE_PROVIDERS).map((id) => id),
+  ) as readonly string[];
+  const intervalMs = options.intervalMs ?? OAUTH_KEEPALIVE_INTERVAL_MS;
+  const scheduler = options.scheduler ?? defaultScheduler;
+
+  let cancel: (() => void) | undefined;
+  let abortController: AbortController | undefined;
+  /** Bare single-flight gate; survives stop/start until the in-flight call settles. */
+  let inFlight = false;
+
+  const stop = (): void => {
+    cancel?.();
+    cancel = undefined;
+    abortController?.abort();
+    abortController = undefined;
+    // Do not clear unsettled inFlight — single-flight is continuous across stop/start.
+  };
+
+  const runTick = async (ctx: OAuthKeepaliveContext): Promise<void> => {
+    if (inFlight) return;
+    const ac = abortController;
+    if (ac === undefined || ac.signal.aborted) return;
+    inFlight = true;
+    try {
+      const result = await ctx.modelRegistry.refresh({
+        providers: [...providers],
+        allowNetwork: true,
+        signal: ac.signal,
+      });
+      if (ac.signal.aborted || result.aborted) return;
+      for (const [providerId, error] of result.errors) {
+        emitWarning(ctx, providerId, error);
+      }
+    } catch (error) {
+      if (ac.signal.aborted) return;
+      // Whole-call failure: one warning per configured provider (ticket error surface).
+      for (const providerId of providers) {
+        emitWarning(ctx, providerId, error);
+      }
+    } finally {
+      inFlight = false;
+    }
+  };
+
+  return {
+    start(ctx) {
+      // Reload / re-start: tear down any prior interval before hanging a new one.
+      stop();
+      abortController = new AbortController();
+      cancel = scheduler.every(intervalMs, () => {
+        void runTick(ctx);
+      });
+    },
+    stop,
+  };
+}

package/src/package-resources/engine-material.ts

@@ -0,0 +1,111 @@
+/**
+ * Packaged engine method-material seam (#356 T1 / ADR 0069).
+ * Legal engine names = directory stems under resources/engines/ — no code whitelist.
+ * Material body is data for the LLM, not a code contract.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+
+const ENGINE_MATERIAL_RELATIVE_ROOT = "resources/engines" as const;
+
+export type EngineSessionMaterial = Readonly<{
+  name: string;
+  materialPath: string;
+}>;
+
+/** Non-empty, trimmed, no path separators or traversal. */
+export function isEngineNameSyntax(name: string): boolean {
+  if (typeof name !== "string") return false;
+  if (name.length === 0 || name.trim() !== name) return false;
+  if (name === "." || name === "..") return false;
+  if (name.includes("/") || name.includes("\\") || name.includes("\0")) return false;
+  if (name.includes("..")) return false;
+  return true;
+}
+
+export function engineMaterialRelativeDirectory(): string {
+  return ENGINE_MATERIAL_RELATIVE_ROOT;
+}
+
+export function resolveEngineMaterialDirectory(packageRoot: string): string {
+  return join(packageRoot, ENGINE_MATERIAL_RELATIVE_ROOT);
+}
+
+/**
+ * Enumerate legal engine names from packaged material files.
+ * Only `*.md` stems that pass name syntax are legal.
+ */
+export function listEngineMaterialNames(packageRoot: string): readonly string[] {
+  const dir = resolveEngineMaterialDirectory(packageRoot);
+  if (!existsSync(dir)) return Object.freeze([]);
+  const names = readdirSync(dir)
+    .filter((entry) => entry.endsWith(".md"))
+    .map((entry) => entry.slice(0, -".md".length))
+    .filter((stem) => isEngineNameSyntax(stem))
+    .sort();
+  return Object.freeze([...names]);
+}
+
+export function resolveEngineMaterialPath(
+  packageRoot: string,
+  name: string,
+): string {
+  const legal = assertLegalEngineName(packageRoot, name);
+  return join(resolveEngineMaterialDirectory(packageRoot), `${legal}.md`);
+}
+
+/**
+ * Assert `name` is a legal engine material stem under packageRoot.
+ * Returns the canonical name on success; throws Error on illegal.
+ */
+export function assertLegalEngineName(packageRoot: string, name: string): string {
+  if (!isEngineNameSyntax(name)) {
+    throw new Error(`illegal engine name: ${name}`);
+  }
+  const legal = listEngineMaterialNames(packageRoot);
+  if (!legal.includes(name)) {
+    throw new Error(
+      `unknown engine: ${name} (known: ${legal.length === 0 ? "(none)" : legal.join(", ")})`,
+    );
+  }
+  return name;
+}
+
+/**
+ * Resolve optional engine options into session material coordinates.
+ * No engine → undefined (caller keeps default prompt bytes).
+ */
+export function engineSessionMaterialFromOptions(options: {
+  engine?: string;
+  packageRoot?: string;
+}): EngineSessionMaterial | undefined {
+  if (options.engine === undefined) return undefined;
+  if (options.packageRoot === undefined || options.packageRoot.trim() === "") {
+    throw new Error("packageRoot is required when engine is configured");
+  }
+  const name = assertLegalEngineName(options.packageRoot, options.engine);
+  return Object.freeze({
+    name,
+    materialPath: resolveEngineMaterialPath(options.packageRoot, name),
+  });
+}
+
+/**
+ * Append engine method-material path delivery to session initial material lines.
+ * No material → identity copy (byte-stable when joined the same way).
+ * Delivers engine name + absolute material path only — never material body.
+ */
+export function appendEngineSessionMaterial(
+  lines: readonly string[],
+  engineMaterial?: EngineSessionMaterial,
+): string[] {
+  if (engineMaterial === undefined) {
+    return [...lines];
+  }
+  const out = [...lines];
+  out.push("");
+  out.push("Engine method material (read these bytes and follow them):");
+  out.push(`- engine: ${engineMaterial.name}`);
+  out.push(`- ${engineMaterial.materialPath}`);
+  return out;
+}