@akagilnc/pi-workflow-roles 0.1.2020 → 0.1.2033

package/src/package-owned-tool-idle.ts

@@ -5,12 +5,18 @@
  * Real producing onUpdate resets; final resolve/reject clears; timeout throws so
  * Pi settles the current call as an LLM-visible isError tool result. No retry,
  * role failure, process termination, signal abort, config, or Pi built-in coverage.
+ *
+ * #339: do not name-exempt whole terminating tools. Outer idle stays armed for
+ * pre/post-audit work. Only the real compliance-audit await suspends this single
+ * layer (ADR 0059 owns that interval); resume re-arms the same outer backstop.
  */
+import { AsyncLocalStorage } from "node:async_hooks";
 import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
 
 import {
   DEFAULT_STREAM_IDLE_TIMEOUT_MS,
   createStreamIdleGuard,
+  type StreamIdleGuard,
 } from "./stream-idle-guard.ts";
 import { isProducingToolUpdate } from "./tool-execution-observation.ts";
 
@@ -19,6 +25,17 @@ export const PACKAGE_OWNED_TOOL_IDLE_TIMEOUT_CODE = "AK_PACKAGE_OWNED_TOOL_IDLE_
 
 const WRAPPED = Symbol.for("ak.packageOwnedToolIdleWrapped");
 
+type PackageOwnedToolIdleSuspension = {
+  suspend(): void;
+  resume(): void;
+};
+
+/**
+ * Active outer package-owned execute idle, if any. Nested tool executes install
+ * their own store; compliance audit only suspends the store visible at await time.
+ */
+const packageOwnedToolIdleScope = new AsyncLocalStorage<PackageOwnedToolIdleSuspension>();
+
 export class PackageOwnedToolIdleTimeoutError extends Error {
   readonly code = PACKAGE_OWNED_TOOL_IDLE_TIMEOUT_CODE;
   readonly idleTimeoutMs = PACKAGE_OWNED_TOOL_IDLE_TIMEOUT_MS;
@@ -52,6 +69,24 @@ function isPackageOwnedToolActivityUpdate(partialResult: unknown): boolean {
   return true;
 }
 
+/**
+ * #339: suspend the active package-owned execute idle for one real compliance
+ * audit await. Single-layer only — production has one runComplianceAudit seam.
+ * No-op outside a wrapped package-owned execute. No second timeout or retry.
+ */
+export async function withPackageOwnedToolIdleSuspended<T>(
+  run: () => Promise<T>,
+): Promise<T> {
+  const scope = packageOwnedToolIdleScope.getStore();
+  if (scope === undefined) return run();
+  scope.suspend();
+  try {
+    return await run();
+  } finally {
+    scope.resume();
+  }
+}
+
 /**
  * Single shared execute wrapper for package-owned tool definitions.
  * Idempotent: wrapping twice returns the same protected definition.
@@ -72,7 +107,8 @@ export function wrapPackageOwnedToolDefinition<T extends PackageOwnedToolLike>(t
     const onUpdate = args[3] as ((partialResult: unknown) => void) | undefined;
     return new Promise((resolve, reject) => {
       let settled = false;
-      const idle = createStreamIdleGuard({
+      let suspended = false;
+      let idle: StreamIdleGuard = createStreamIdleGuard({
         idleTimeoutMs: PACKAGE_OWNED_TOOL_IDLE_TIMEOUT_MS,
       });
 
@@ -88,6 +124,25 @@ export function wrapPackageOwnedToolDefinition<T extends PackageOwnedToolLike>(t
       };
       idle.signal.addEventListener("abort", onIdle, { once: true });
 
+      const suspension: PackageOwnedToolIdleSuspension = {
+        suspend(): void {
+          if (settled || suspended) return;
+          suspended = true;
+          // ADR 0059 owns the audit interval — drop this layer until audit returns.
+          idle.signal.removeEventListener("abort", onIdle);
+          idle.dispose();
+        },
+        resume(): void {
+          if (settled || !suspended) return;
+          suspended = false;
+          // Fresh single-layer silence window for post-audit work (e.g. cleanup).
+          idle = createStreamIdleGuard({
+            idleTimeoutMs: PACKAGE_OWNED_TOOL_IDLE_TIMEOUT_MS,
+          });
+          idle.signal.addEventListener("abort", onIdle, { once: true });
+        },
+      };
+
       const guardedOnUpdate = onUpdate === undefined
         ? undefined
         : (partialResult: unknown) => {
@@ -101,12 +156,14 @@ export function wrapPackageOwnedToolDefinition<T extends PackageOwnedToolLike>(t
       callArgs[2] = signal;
       callArgs[3] = guardedOnUpdate;
 
-      void Promise.resolve()
-        .then(() => originalExecute(...callArgs))
-        .then(
-          (result) => settle(() => resolve(result)),
-          (error: unknown) => settle(() => reject(error)),
-        );
+      void packageOwnedToolIdleScope.run(suspension, async () => {
+        try {
+          const result = await originalExecute(...callArgs);
+          settle(() => resolve(result));
+        } catch (error) {
+          settle(() => reject(error));
+        }
+      });
     });
   };
   (wrappedExecute as { [WRAPPED]?: boolean })[WRAPPED] = true;

package/src/public-cli/cli.ts

@@ -10,7 +10,7 @@ import {
   formatModelSpec,
   loadCredentialProviders,
   loadPublicCliConfig,
-  parseModelSpec,
+  parsePersistentModelSpec,
   resolveEffectiveSeat,
   savePublicCliConfig,
   setPersistentSeatConfig,
@@ -402,7 +402,7 @@ async function runConfigCommand(
       if (!isPublicConfigurableSeat(seat)) {
         throw new CliUsageError(`unknown configurable seat: ${seat}`);
       }
-      config = setPersistentSeatConfig(config, seat, parseModelSpec(spec));
+      config = setPersistentSeatConfig(config, seat, parsePersistentModelSpec(spec));
     }
     await savePublicCliConfig(config, home);
     io.stdout(renderConfig(config));

package/src/public-cli/coder-run.ts

@@ -24,6 +24,7 @@ import {
   type AdmittedCoderInvocation,
 } from "./invocation.ts";
 import {
+  buildSeatModelCliArgs,
   type CredentialProviders,
   type SeatModelConfig,
 } from "./config.ts";
@@ -84,17 +85,6 @@ export type CoderRunEnv = {
   timeoutMs?: number;
 };
 
-function buildModelArgs(model: SeatModelConfig | undefined): string[] {
-  if (model === undefined) return [];
-  return [
-    "--provider",
-    model.provider,
-    "--model",
-    model.model,
-    "--thinking",
-    model.thinking,
-  ];
-}
 
 /**
  * Build Internal activation extra-args for an admitted Coder run.
@@ -136,7 +126,7 @@ export function buildCoderActivationExtraArgs(
     admitted.taskPath,
     "--mode",
     "json",
-    ...buildModelArgs(options.model),
+    ...buildSeatModelCliArgs(options.model),
     prompt,
   ];
 }
@@ -179,7 +169,7 @@ export function buildCoderResumeActivationExtraArgs(
     admitted.taskPath,
     "--mode",
     "json",
-    ...buildModelArgs(options.model),
+    ...buildSeatModelCliArgs(options.model),
     RESUME_TRANSPORT_ENVELOPE,
   ];
 }
@@ -304,7 +294,7 @@ async function dispatchAdmittedCoder(input: {
         io,
       );
     }
-    await markRunRunning(admitted.runDirectory);
+    await markRunRunning(admitted.runDirectory, env.model);
     await clearTypedProviderHttpObservation(admitted.runDirectory);
 
     const childEnv: NodeJS.ProcessEnv = {
@@ -434,6 +424,7 @@ export async function runPublicCoder(
       attachmentPaths: parsed.attachmentPaths,
       ...(parsed.project === undefined ? {} : { project: parsed.project }),
       ...(env.createRunId === undefined ? {} : { createRunId: env.createRunId }),
+      ...(env.model === undefined ? {} : { model: env.model }),
     });
   } catch (error) {
     if (error instanceof CliUsageError) {

package/src/public-cli/collector-run.ts

@@ -20,6 +20,7 @@ import {
   type ParseCollectorArgvResult,
 } from "./invocation.ts";
 import {
+  buildSeatModelCliArgs,
   type CredentialProviders,
   type SeatModelConfig,
 } from "./config.ts";
@@ -69,17 +70,6 @@ export type CollectorRunEnv = {
   timeoutMs?: number;
 };
 
-function buildModelArgs(model: SeatModelConfig | undefined): string[] {
-  if (model === undefined) return [];
-  return [
-    "--provider",
-    model.provider,
-    "--model",
-    model.model,
-    "--thinking",
-    model.thinking,
-  ];
-}
 
 /**
  * Build Internal activation extra-args for an admitted Collector run.
@@ -114,7 +104,7 @@ export function buildCollectorActivationExtraArgs(
       : ["--ak-collector-request-manifest", admitted.requestManifestPath]),
     "--mode",
     "json",
-    ...buildModelArgs(options.model),
+    ...buildSeatModelCliArgs(options.model),
     prompt,
   ];
 }
@@ -202,7 +192,7 @@ async function dispatchAdmittedCollector(input: {
         io,
       );
     }
-    await markRunRunning(admitted.runDirectory);
+    await markRunRunning(admitted.runDirectory, env.model);
     await clearTypedProviderHttpObservation(admitted.runDirectory);
 
     const childEnv: NodeJS.ProcessEnv = {
@@ -340,6 +330,7 @@ export async function runPublicCollector(
       ...(parsed.repo === undefined ? {} : { repo: parsed.repo }),
       ...(parsed.requestManifestPath === undefined ? {} : { requestManifestPath: parsed.requestManifestPath }),
       ...(env.createRunId === undefined ? {} : { createRunId: env.createRunId }),
+      ...(env.model === undefined ? {} : { model: env.model }),
     });
   } catch (error) {
     if (error instanceof CliUsageError) {

package/src/public-cli/config.ts

@@ -108,12 +108,18 @@ export function parseModelSpec(
   const thinkingSplit = trimmed.lastIndexOf(":");
   let modelPart = trimmed;
   let thinking: PublicThinkingLevel | undefined = fallbackThinking;
-  if (thinkingSplit > 0) {
+  // #346: no colon → bare provider/model is legal. Colon present (any index,
+  // including 0) → suffix must be a typed PublicThinkingLevel (empty/unknown
+  // stay format rejects; never swallow ":…" into the model name).
+  if (thinkingSplit !== -1) {
     const maybeThinking = trimmed.slice(thinkingSplit + 1);
-    if (THINKING_LEVELS.has(maybeThinking as PublicThinkingLevel)) {
-      thinking = maybeThinking as PublicThinkingLevel;
-      modelPart = trimmed.slice(0, thinkingSplit);
+    if (!THINKING_LEVELS.has(maybeThinking as PublicThinkingLevel)) {
+      throw new Error(
+        `model specification must be provider/model[:thinking], got ${spec}`,
+      );
     }
+    thinking = maybeThinking as PublicThinkingLevel;
+    modelPart = trimmed.slice(0, thinkingSplit);
   }
   const slash = modelPart.indexOf("/");
   if (slash <= 0 || slash === modelPart.length - 1) {
@@ -123,16 +129,48 @@ export function parseModelSpec(
   }
   const provider = modelPart.slice(0, slash);
   const model = modelPart.slice(slash + 1);
-  if (!thinking) {
+  // #346: bare provider/model is legal on invocation — do not invent thinking.
+  // Persistent config set still requires thinking via parsePersistentModelSpec.
+  return thinking === undefined
+    ? { provider, model }
+    : { provider, model, thinking };
+}
+
+/** Persistent seat config keeps the three-part provider/model:thinking grammar. */
+export function parsePersistentModelSpec(spec: string): SeatModelConfig & {
+  thinking: PublicThinkingLevel;
+} {
+  const parsed = parseModelSpec(spec);
+  if (parsed.thinking === undefined) {
     throw new Error(
       `model specification requires a thinking level (provider/model:thinking), got ${spec}`,
     );
   }
-  return { provider, model, thinking };
+  return {
+    provider: parsed.provider,
+    model: parsed.model,
+    thinking: parsed.thinking,
+  };
 }
 
 export function formatModelSpec(selection: SeatModelConfig): string {
-  return `${selection.provider}/${selection.model}:${selection.thinking}`;
+  const base = `${selection.provider}/${selection.model}`;
+  return selection.thinking === undefined ? base : `${base}:${selection.thinking}`;
+}
+
+/**
+ * Single source: seat model selection → Pi argv at the public CLI execution seam.
+ * Bare provider/model omits --thinking so pi/model defaults apply; suffix passes through.
+ */
+export function buildSeatModelCliArgs(model: SeatModelConfig | undefined): string[] {
+  if (model === undefined) return [];
+  return [
+    "--provider",
+    model.provider,
+    "--model",
+    model.model,
+    ...(model.thinking === undefined ? [] : ["--thinking", model.thinking]),
+  ];
 }
 
 function parsePublicCliConfig(value: unknown): PublicCliConfig {

package/src/public-cli/doctor-run.ts

@@ -20,6 +20,7 @@ import {
   type ParseDoctorArgvResult,
 } from "./invocation.ts";
 import {
+  buildSeatModelCliArgs,
   type CredentialProviders,
   type SeatModelConfig,
 } from "./config.ts";
@@ -70,17 +71,6 @@ export type DoctorRunEnv = {
   timeoutMs?: number;
 };
 
-function buildModelArgs(model: SeatModelConfig | undefined): string[] {
-  if (model === undefined) return [];
-  return [
-    "--provider",
-    model.provider,
-    "--model",
-    model.model,
-    "--thinking",
-    model.thinking,
-  ];
-}
 
 /**
  * Build Internal activation extra-args for an admitted Doctor run.
@@ -111,7 +101,7 @@ export function buildDoctorActivationExtraArgs(
     admitted.caseRunsPath,
     "--mode",
     "json",
-    ...buildModelArgs(options.model),
+    ...buildSeatModelCliArgs(options.model),
     prompt,
   ];
 }
@@ -183,7 +173,7 @@ async function dispatchAdmittedDoctor(input: {
         io,
       );
     }
-    await markRunRunning(admitted.runDirectory);
+    await markRunRunning(admitted.runDirectory, env.model);
     await clearTypedProviderHttpObservation(admitted.runDirectory);
 
     const childEnv: NodeJS.ProcessEnv = {
@@ -319,6 +309,7 @@ export async function runPublicDoctor(
       ...(parsed.project === undefined ? {} : { project: parsed.project }),
       ...(parsed.runs === undefined ? {} : { runs: parsed.runs }),
       ...(env.createRunId === undefined ? {} : { createRunId: env.createRunId }),
+      ...(env.model === undefined ? {} : { model: env.model }),
     });
   } catch (error) {
     if (error instanceof CliUsageError) {

package/src/public-cli/fixer-run.ts

@@ -26,6 +26,7 @@ import {
   type AdmittedFixerInvocation,
 } from "./invocation.ts";
 import {
+  buildSeatModelCliArgs,
   type CredentialProviders,
   type SeatModelConfig,
 } from "./config.ts";
@@ -87,17 +88,6 @@ export type FixerRunEnv = {
   timeoutMs?: number;
 };
 
-function buildModelArgs(model: SeatModelConfig | undefined): string[] {
-  if (model === undefined) return [];
-  return [
-    "--provider",
-    model.provider,
-    "--model",
-    model.model,
-    "--thinking",
-    model.thinking,
-  ];
-}
 
 /**
  * Build Internal activation extra-args for an admitted Fixer run.
@@ -145,7 +135,7 @@ export function buildFixerActivationExtraArgs(
     ...prerequisiteArgs,
     "--mode",
     "json",
-    ...buildModelArgs(options.model),
+    ...buildSeatModelCliArgs(options.model),
     prompt,
   ];
 }
@@ -194,7 +184,7 @@ export function buildFixerResumeActivationExtraArgs(
     ...prerequisiteArgs,
     "--mode",
     "json",
-    ...buildModelArgs(options.model),
+    ...buildSeatModelCliArgs(options.model),
     RESUME_TRANSPORT_ENVELOPE,
   ];
 }
@@ -303,7 +293,7 @@ async function dispatchAdmittedFixer(input: {
         io,
       );
     }
-    await markRunRunning(admitted.runDirectory);
+    await markRunRunning(admitted.runDirectory, env.model);
     await clearTypedProviderHttpObservation(admitted.runDirectory);
 
     const childEnv: NodeJS.ProcessEnv = {
@@ -461,6 +451,7 @@ export async function runPublicFixer(
         : { prerequisitesPath: parsed.prerequisitesPath }),
       ...(parsed.project === undefined ? {} : { project: parsed.project }),
       ...(env.createRunId === undefined ? {} : { createRunId: env.createRunId }),
+      ...(env.model === undefined ? {} : { model: env.model }),
     });
   } catch (error) {
     if (error instanceof CliUsageError) {

package/src/public-cli/invocation.ts

@@ -172,14 +172,39 @@ type RoleInvocationLedgerSource = Pick<
   "runId" | "bookKey" | "projectRoot" | "runDirectory" | "sessionDirectory" | "sessionFile" | "correlationId" | "ticketNumber"
 >;
 
+/**
+ * Effective provider/model selection recorded on the invocation identity page.
+ * thinking is present only when the caller/seat supplied it — bare model omits it.
+ */
+export type InvocationEffectiveModel = {
+  readonly provider: string;
+  readonly model: string;
+  readonly thinking?: string;
+};
+
+/** Project effective model onto ledger fields; absent thinking stays absent. */
+function effectiveModelLedgerFields(
+  model: InvocationEffectiveModel | undefined,
+): Record<string, string> {
+  if (model === undefined) return {};
+  return {
+    provider: model.provider,
+    model: model.model,
+    ...(model.thinking === undefined ? {} : { thinking: model.thinking }),
+  };
+}
+
 /**
  * Persist one `invocation.json` identity page for the public run.
  * Admission is the sole source for every field; this is the only identity
  * projection and callers never provide an independent ledger shape.
+ * When an effective model is known at admission, provider/model (and thinking
+ * only when supplied) are written onto the same page.
  */
 async function writeRoleInvocationLedger(
   source: RoleInvocationLedgerSource,
   role: AdmittedRoleInvocation["role"],
+  effectiveModel?: InvocationEffectiveModel,
 ): Promise<void> {
   const identity = {
     role,
@@ -191,6 +216,7 @@ async function writeRoleInvocationLedger(
     sessionFile: source.sessionFile,
     ...(source.correlationId === undefined ? {} : { correlationId: source.correlationId }),
     ...(source.ticketNumber === undefined ? {} : { ticketNumber: source.ticketNumber }),
+    ...effectiveModelLedgerFields(effectiveModel),
   };
   await writeFile(
     join(source.runDirectory, "invocation.json"),
@@ -199,6 +225,37 @@ async function writeRoleInvocationLedger(
   );
 }
 
+/**
+ * Merge the effective launch model onto the existing invocation identity page
+ * (resume / temporary override path — same field shape as admission write).
+ * Bare model clears any prior thinking key so absence stays honest.
+ */
+export async function recordEffectiveInvocationModel(
+  runDirectory: string,
+  model: InvocationEffectiveModel,
+): Promise<void> {
+  const ledgerPath = join(runDirectory, "invocation.json");
+  const current = JSON.parse(await readFile(ledgerPath, "utf8")) as Record<
+    string,
+    unknown
+  >;
+  const next: Record<string, unknown> = {
+    ...current,
+    provider: model.provider,
+    model: model.model,
+  };
+  if (model.thinking === undefined) {
+    delete next.thinking;
+  } else {
+    next.thinking = model.thinking;
+  }
+  await writeFile(
+    ledgerPath,
+    `${JSON.stringify(next, null, 2)}\n`,
+    "utf8",
+  );
+}
+
 /** Merge observed launch-time fields into the single existing invocation.json identity page. */
 async function mergeInvocationIdentityPage(
   runDirectory: string,
@@ -686,6 +743,8 @@ export type AdmitJudgeInvocationOptions = {
   project?: string;
   /** Injectable clock/id for tests. */
   createRunId?: () => string;
+  /** Effective model for this invocation — written onto invocation.json. */
+  model?: InvocationEffectiveModel;
 };
 
 /**
@@ -736,7 +795,7 @@ export async function admitJudgeInvocation(
   };
   const admittedRequestPath = join(runDirectory, "admitted-request.json");
   await writeFile(admittedRequestPath, `${JSON.stringify(admitted, null, 2)}\n`, "utf8");
-  await writeRoleInvocationLedger(admitted, admitted.role);
+  await writeRoleInvocationLedger(admitted, admitted.role, options.model);
 
   return {
     role: "judge",
@@ -811,6 +870,8 @@ export type AdmitCoderInvocationOptions = {
   attachmentPaths: readonly string[];
   project?: string;
   createRunId?: () => string;
+  /** Effective model for this invocation — written onto invocation.json. */
+  model?: InvocationEffectiveModel;
 };
 
 /**
@@ -874,7 +935,7 @@ export async function admitCoderInvocation(
   };
   const admittedRequestPath = join(runDirectory, "admitted-request.json");
   await writeFile(admittedRequestPath, `${JSON.stringify(admitted, null, 2)}\n`, "utf8");
-  await writeRoleInvocationLedger(admitted, admitted.role);
+  await writeRoleInvocationLedger(admitted, admitted.role, options.model);
 
   return {
     role: "coder",
@@ -923,6 +984,8 @@ export type AdmitFixerInvocationOptions = {
   prerequisitesPath?: string;
   project?: string;
   createRunId?: () => string;
+  /** Effective model for this invocation — written onto invocation.json. */
+  model?: InvocationEffectiveModel;
 };
 
 /**
@@ -1026,7 +1089,7 @@ export async function admitFixerInvocation(
   };
   const admittedRequestPath = join(runDirectory, "admitted-request.json");
   await writeFile(admittedRequestPath, `${JSON.stringify(admitted, null, 2)}\n`, "utf8");
-  await writeRoleInvocationLedger(admitted, admitted.role);
+  await writeRoleInvocationLedger(admitted, admitted.role, options.model);
 
   return {
     role: "fixer",
@@ -1188,6 +1251,8 @@ export type AdmitCollectorInvocationOptions = {
   /** Optional public request configuration; copied into the admitted run. */
   requestManifestPath?: string;
   createRunId?: () => string;
+  /** Effective model for this invocation — written onto invocation.json. */
+  model?: InvocationEffectiveModel;
 };
 
 /**
@@ -1286,7 +1351,7 @@ export async function admitCollectorInvocation(
     `${JSON.stringify(admitted, null, 2)}\n`,
     "utf8",
   );
-  await writeRoleInvocationLedger(admitted, admitted.role);
+  await writeRoleInvocationLedger(admitted, admitted.role, options.model);
 
   return {
     role: "collector",
@@ -1440,6 +1505,8 @@ export type AdmitDoctorInvocationOptions = {
   attachmentPaths?: readonly string[];
   project?: string;
   createRunId?: () => string;
+  /** Effective model for this invocation — written onto invocation.json. */
+  model?: InvocationEffectiveModel;
 };
 
 /**
@@ -1619,7 +1686,7 @@ export async function admitDoctorInvocation(
     `${JSON.stringify(admitted, null, 2)}\n`,
     "utf8",
   );
-  await writeRoleInvocationLedger(admitted, admitted.role);
+  await writeRoleInvocationLedger(admitted, admitted.role, options.model);
 
   return {
     role: "doctor",
@@ -1730,6 +1797,8 @@ export type AdmitReviewerInvocationOptions = {
   authorityRefs?: readonly string[];
   project?: string;
   createRunId?: () => string;
+  /** Effective model for this invocation — written onto invocation.json. */
+  model?: InvocationEffectiveModel;
 };
 
 /**
@@ -1794,7 +1863,7 @@ export async function admitReviewerInvocation(
     `${JSON.stringify(admitted, null, 2)}\n`,
     "utf8",
   );
-  await writeRoleInvocationLedger(admitted, admitted.role);
+  await writeRoleInvocationLedger(admitted, admitted.role, options.model);
 
   return {
     role: "reviewer",
@@ -1945,6 +2014,8 @@ export type AdmitMergerInvocationOptions = {
   createRunId?: () => string;
   /** Test seam; production binds createProductionMergerGitState(projectRoot). */
   gitState?: MergerGitState;
+  /** Effective model for this invocation — written onto invocation.json. */
+  model?: InvocationEffectiveModel;
 };
 
 /**
@@ -2052,7 +2123,7 @@ export async function admitMergerInvocation(
     `${JSON.stringify(admitted, null, 2)}\n`,
     "utf8",
   );
-  await writeRoleInvocationLedger(admitted, admitted.role);
+  await writeRoleInvocationLedger(admitted, admitted.role, options.model);
 
   return {
     role: "merger",