@cr1ms0n/pi-subagent 0.8.8 → 0.9.0

package/src/context-policy.ts

@@ -1,169 +0,0 @@
-/**
- * Remote Context eligibility boundary for the four Pi context-management tools.
- *
- * `pi-subagent` does not own the Remote Context model list: the operator-owned
- * `pi-openai-toolkit` configuration owns it. This module reads that file once
- * per dispatch and fails closed to an empty allowlist whenever the file is
- * missing, unreadable, malformed, or not in `contextManagement: "remote"` mode.
- *
- * Matching is exact and case-sensitive on the complete `provider/model` string:
- * entries are never trimmed, prefix-matched, or inferred from a bare model id.
- * The toolkit's separate native `openai-codex` provider rule is intentionally
- * not mirrored here — only configured `gatewayContextModels` entries are
- * eligible, because the boundary is "models outside the allowlist receive no
- * context-manager tools".
- *
- * Nothing in this module writes to stdout: that channel is the child RPC
- * protocol and the parent TUI.
- */
-
-import * as fs from "node:fs/promises";
-import * as path from "node:path";
-import { piAgentDir } from "./agents.js";
-
-/**
- * Pi context-management tools are control-plane capabilities: they may update
- * continuity notes or the remote context window, but they cannot modify the
- * child checkout. Keep them separate from ordinary source-inspection tools so
- * the read-only profile's exception remains explicit.
- */
-export const CONTEXT_MANAGEMENT_TOOLS: ReadonlySet<string> = new Set([
-  "new_context",
-  "get_context_remaining",
-  "history",
-  "notes",
-]);
-
-/** Canonical enumeration order when appending context tools to a child allowlist. */
-export const CONTEXT_MANAGEMENT_TOOL_NAMES: readonly string[] = Object.freeze([
-  ...CONTEXT_MANAGEMENT_TOOLS,
-]);
-
-/** Toolkit config path relative to the Pi agent directory. */
-export const TOOLKIT_CONFIG_PATH_PARTS: readonly string[] = Object.freeze([
-  "extensions",
-  "pi-openai-toolkit",
-  "config.json",
-]);
-
-/** Immutable per-dispatch snapshot of the operator-owned Remote Context allowlist. */
-export interface ContextManagementPolicy {
-  /** Exact `provider/model` strings eligible for Remote Context. */
-  readonly gatewayModels: readonly string[];
-}
-
-/** Fail-closed policy used for missing/unreadable/invalid/disabled configuration. */
-export const EMPTY_CONTEXT_MANAGEMENT_POLICY: ContextManagementPolicy = Object.freeze({
-  gatewayModels: Object.freeze([]),
-});
-
-function asRecord(value: unknown): Record<string, unknown> | undefined {
-  return value !== null && typeof value === "object" && !Array.isArray(value)
-    ? (value as Record<string, unknown>)
-    : undefined;
-}
-
-/**
- * Pure parser over the toolkit config JSON.
- *
- * Returns the exact gateway model set only when `compaction.contextManagement`
- * is `"remote"` and every `compaction.gatewayContextModels` entry is a non-empty
- * string. Any other shape — including a partly malformed list — yields the
- * empty policy so a compromised/edited file cannot widen the boundary.
- */
-export function parseContextManagementPolicy(raw: unknown): ContextManagementPolicy {
-  const compaction = asRecord(asRecord(raw)?.compaction);
-  if (!compaction || compaction.contextManagement !== "remote") return EMPTY_CONTEXT_MANAGEMENT_POLICY;
-  const listed = compaction.gatewayContextModels;
-  if (!Array.isArray(listed)) return EMPTY_CONTEXT_MANAGEMENT_POLICY;
-  const gatewayModels: string[] = [];
-  for (const entry of listed) {
-    if (typeof entry !== "string" || entry.trim() === "") return EMPTY_CONTEXT_MANAGEMENT_POLICY;
-    if (!gatewayModels.includes(entry)) gatewayModels.push(entry);
-  }
-  return Object.freeze({ gatewayModels: Object.freeze(gatewayModels) });
-}
-
-/** Default toolkit config path, using the shared Pi agent-directory precedence. */
-export function contextManagementConfigPath(agentDir = piAgentDir()): string {
-  return path.join(agentDir, ...TOOLKIT_CONFIG_PATH_PARTS);
-}
-
-/**
- * Read one Remote Context snapshot. The injectable path keeps checks offline.
- * Every failure mode (missing, unreadable, invalid JSON, wrong shape) returns
- * the empty policy, so an ineligible target never inherits context tools.
- */
-export async function readContextManagementPolicy(
-  file = contextManagementConfigPath(),
-): Promise<ContextManagementPolicy> {
-  try {
-    return parseContextManagementPolicy(JSON.parse(await fs.readFile(file, "utf8")));
-  } catch {
-    return EMPTY_CONTEXT_MANAGEMENT_POLICY; // fail closed; stdout is the RPC channel
-  }
-}
-
-/** True when `model` exactly equals a configured `gatewayContextModels` entry. */
-export function isGatewayContextModel(
-  policy: ContextManagementPolicy | undefined,
-  model: string | undefined,
-): boolean {
-  if (!policy || !model) return false;
-  return policy.gatewayModels.includes(model);
-}
-
-/**
- * Context-tool names a target model may receive: the parent-exposed subset,
- * and only for an exact allowlisted model. Empty for every other target.
- */
-export function contextToolsForModel(
-  policy: ContextManagementPolicy | undefined,
-  model: string | undefined,
-  parentExposed: readonly string[],
-): string[] {
-  if (!isGatewayContextModel(policy, model)) return [];
-  const exposed = new Set(parentExposed);
-  return CONTEXT_MANAGEMENT_TOOL_NAMES.filter((tool) => exposed.has(tool));
-}
-
-/** Tool list for the internally constructed read-only synthesis child. */
-export function synthesisToolsForModel(
-  policy: ContextManagementPolicy | undefined,
-  model: string | undefined,
-  parentExposed: readonly string[],
-): string[] {
-  return ["read", ...contextToolsForModel(policy, model, parentExposed)];
-}
-
-/**
- * Re-derive a child tool allowlist for one target model (primary request or a
- * fallback attempt). Non-context names keep their existing order/deduplication;
- * all four context names are removed first and re-appended only when the
- * effective backend is Pi and the attempt model is exactly allowlisted.
- *
- * Non-Pi backends are returned unchanged. Absent a dispatch policy, a Pi list
- * loses every context name (fail closed) — low-level `runTasks` callers that
- * provide a validated `TaskSpec` but no snapshot cannot reintroduce them. A Pi
- * task with no explicit list becomes `--no-tools` at the backend boundary
- * rather than silently falling back to Pi's unrestricted default tool set.
- */
-export function filterContextToolsForModel(
-  tools: readonly string[] | undefined,
-  options: {
-    backend: string;
-    model?: string;
-    policy?: ContextManagementPolicy;
-    parentExposed?: readonly string[];
-  },
-): string[] | undefined {
-  if (tools === undefined) return options.backend === "pi" ? [] : undefined;
-  if (options.backend !== "pi") return [...tools];
-  const kept = tools.filter((tool) => !CONTEXT_MANAGEMENT_TOOLS.has(tool));
-  return [
-    ...new Set([
-      ...kept,
-      ...contextToolsForModel(options.policy, options.model, options.parentExposed ?? []),
-    ]),
-  ];
-}

package/src/model-policy.ts

@@ -1,169 +0,0 @@
-import * as fs from "node:fs/promises";
-import * as os from "node:os";
-import * as path from "node:path";
-import { isThinkingLevel, type ThinkingLevel } from "./thinking.js";
-
-export const MODEL_POLICY_CONFIG_FILE = path.join(os.homedir(), ".pi", "subagent.json");
-
-export interface ModelRoute {
-  model: string;
-  /** Immutable order owned by the user configuration. */
-  fallbackModels: readonly string[];
-  /** Optional route default; callers may override it with task/agent/profile settings. */
-  thinking?: ThinkingLevel;
-}
-
-export interface ModelPolicySnapshot {
-  default: ModelRoute;
-  agents: ReadonlyMap<string, ModelRoute>;
-  source: string;
-}
-
-export interface ModelPolicyValidation {
-  route?: ModelRoute;
-  error?: string;
-}
-
-const AGENT_NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/i;
-
-function invalid(source: string, message: string): never {
-  throw new Error(`Invalid modelPolicy in ${source}: ${message}`);
-}
-
-function modelId(value: unknown, pathName: string, source: string): string {
-  if (typeof value !== "string") invalid(source, `${pathName}.model must be a string in provider/model-id form`);
-  const model = value.trim();
-  const slash = model.indexOf("/");
-  if (!model || slash <= 0 || slash === model.length - 1 || /[\x00-\x1f\s]/.test(model)) {
-    invalid(source, `${pathName}.model must be a non-empty provider/model-id without whitespace`);
-  }
-  return model;
-}
-
-function route(value: unknown, pathName: string, source: string): ModelRoute {
-  if (!value || typeof value !== "object" || Array.isArray(value)) {
-    invalid(source, `${pathName} must be an object`);
-  }
-  const record = value as Record<string, unknown>;
-  const unknown = Object.keys(record).filter((key) => key !== "model" && key !== "fallbackModels" && key !== "thinking");
-  if (unknown.length) invalid(source, `${pathName} has unknown field(s): ${unknown.join(", ")}`);
-  const model = modelId(record.model, pathName, source);
-  const rawFallbacks = record.fallbackModels === undefined ? [] : record.fallbackModels;
-  if (!Array.isArray(rawFallbacks)) invalid(source, `${pathName}.fallbackModels must be an array`);
-  const fallbackModels = rawFallbacks.map((value, index) => modelId(value, `${pathName}.fallbackModels[${index}]`, source));
-  if (new Set(fallbackModels).size !== fallbackModels.length) invalid(source, `${pathName}.fallbackModels must not contain duplicates`);
-  if (fallbackModels.includes(model)) invalid(source, `${pathName}.fallbackModels must not repeat the primary model`);
-  const thinking = record.thinking;
-  if (thinking !== undefined && !isThinkingLevel(thinking)) {
-    invalid(source, `${pathName}.thinking must be a non-empty Pi thinking level string without whitespace or control characters`);
-  }
-  return Object.freeze({
-    model,
-    fallbackModels: Object.freeze([...fallbackModels]),
-    ...(thinking === undefined ? {} : { thinking }),
-  });
-}
-
-/** Parse only the modelPolicy subtree; no provider catalog or credentials are read. */
-export function parseModelPolicy(raw: unknown, source = MODEL_POLICY_CONFIG_FILE): ModelPolicySnapshot {
-  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
-    invalid(source, "modelPolicy must be an object");
-  }
-  const record = raw as Record<string, unknown>;
-  const unknown = Object.keys(record).filter((key) => key !== "default" && key !== "agents");
-  if (unknown.length) invalid(source, `modelPolicy has unknown field(s): ${unknown.join(", ")}`);
-  if (!("default" in record)) invalid(source, "modelPolicy.default is required");
-  const defaultRoute = route(record.default, "modelPolicy.default", source);
-  const agents = new Map<string, ModelRoute>();
-  const rawAgents = record.agents === undefined ? {} : record.agents;
-  if (!rawAgents || typeof rawAgents !== "object" || Array.isArray(rawAgents)) {
-    invalid(source, "modelPolicy.agents must be an object");
-  }
-  for (const [name, value] of Object.entries(rawAgents as Record<string, unknown>)) {
-    const normalized = name.trim().toLowerCase();
-    if (!AGENT_NAME.test(normalized)) invalid(source, `modelPolicy.agents key ${JSON.stringify(name)} is not a valid agent name`);
-    if (agents.has(normalized)) invalid(source, `modelPolicy.agents contains duplicate agent ${normalized}`);
-    agents.set(normalized, route(value, `modelPolicy.agents.${normalized}`, source));
-  }
-  return Object.freeze({ default: defaultRoute, agents, source });
-}
-
-/** Read the raw config only far enough to validate modelPolicy. */
-export async function readModelPolicyFile(file = MODEL_POLICY_CONFIG_FILE): Promise<ModelPolicySnapshot> {
-  let raw: unknown;
-  try {
-    raw = JSON.parse(await fs.readFile(file, "utf8"));
-  } catch (error: any) {
-    if (error?.code === "ENOENT") throw new Error(`Model policy is not configured. Create ${file} using the model policy template.`);
-    throw new Error(`Could not read ${file} as JSON; model policy was not loaded.`);
-  }
-  if (!raw || typeof raw !== "object" || Array.isArray(raw) || !("modelPolicy" in (raw as Record<string, unknown>))) {
-    throw new Error(`Model policy is missing from ${file}. Add modelPolicy.default using the model policy template.`);
-  }
-  return parseModelPolicy((raw as Record<string, unknown>).modelPolicy, file);
-}
-
-export function resolveModelRoute(policy: ModelPolicySnapshot, agent?: string): ModelRoute {
-  const name = agent?.trim().toLowerCase();
-  return (name && policy.agents.get(name)) || policy.default;
-}
-
-/** Validate the caller-owned fields against the immutable configured route. */
-export function validateModelRequest(
-  policy: ModelPolicySnapshot,
-  options: { agent?: string; model?: string; fallbackModels?: string[]; fallbackModelsProvided?: boolean },
-): ModelPolicyValidation {
-  const route = resolveModelRoute(policy, options.agent);
-  const actualModel = options.model?.trim();
-  if (!actualModel) return { error: `model is required; expected configured model ${route.model}` };
-  if (actualModel !== route.model) {
-    return { error: `model ${JSON.stringify(actualModel)} does not match the configured model ${JSON.stringify(route.model)}${options.agent ? ` for agent ${options.agent}` : ""}` };
-  }
-  if (options.fallbackModelsProvided) {
-    const requested = (options.fallbackModels ?? []).map((model) => model.trim());
-    if (requested.length !== route.fallbackModels.length || requested.some((model, index) => model !== route.fallbackModels[index])) {
-      return {
-        error: `fallback_models must exactly match the configured order for ${actualModel}: [${route.fallbackModels.join(", ")}]`,
-      };
-    }
-  }
-  return { route };
-}
-
-export function formatModelPolicyPrompt(policy: ModelPolicySnapshot | undefined, error?: string): string {
-  if (!policy) {
-    return [
-      "## Subagent model policy",
-      error || `No valid model policy is configured at ${MODEL_POLICY_CONFIG_FILE}.`,
-      "Management actions (status/wait/cancel/steer/diff/apply/discard) remain available, but every new task/tasks[] spawn and plan request is rejected until modelPolicy is configured.",
-      "Use the package model-policy template; do not invent model IDs or fallback models.",
-    ].join("\n");
-  }
-  const lines = [
-    "## Subagent model policy",
-    "Every new task/tasks[] spawn must pass model explicitly and it must exactly match this mapping. Management actions do not need model.",
-    `default (agentless and unmapped agents): model=${policy.default.model}; fallback_models=[${policy.default.fallbackModels.join(", ")}]; thinking=${policy.default.thinking ?? "(unset)"}`,
-  ];
-  for (const [agent, route] of [...policy.agents.entries()].sort(([a], [b]) => a.localeCompare(b))) {
-    lines.push(`agent:${agent}: model=${route.model}; fallback_models=[${route.fallbackModels.join(", ")}]; thinking=${route.thinking ?? "(unset)"}`);
-  }
-  lines.push(
-    "If fallback_models is omitted, the configured list is used. If it is supplied, it must match the configured list exactly, including order.",
-    "thinking is a route default: explicit task thinking, agent thinking, and profile taskDefaults.thinking override it; parent thinking is used only when the route is unset.",
-    "Do not use model/fallback_models from agent frontmatter, taskDefaults, or the parent session; those legacy model fields are ignored.",
-  );
-  return lines.join("\n");
-}
-
-export function modelPolicyTemplate(): string {
-  return JSON.stringify({
-    modelPolicy: {
-      default: { model: "<provider/model-id>", fallbackModels: [], thinking: "medium" },
-      agents: { "<agent-name>": { model: "<provider/model-id>", fallbackModels: [], thinking: "high" } },
-    },
-  }, null, 2);
-}
-
-export function modelPolicySource(file = MODEL_POLICY_CONFIG_FILE): string {
-  return path.normalize(file);
-}