pi-sage 0.2.0

package/.pi/extensions/sage/policy.ts

@@ -0,0 +1,114 @@
+import type { BlockCode, CallerContext, CallerDecision, SageBudgetState, SageMode, SageToolResult } from "./types.js";
+import type { SageSettings } from "./settings.js";
+
+export function isEligibleCaller(ctx: CallerContext | null | undefined): CallerDecision {
+  if (!ctx || !ctx.session || !ctx.agent || !ctx.runtime) {
+    return { ok: false, blockCode: "unknown-context", reason: "Missing caller context" };
+  }
+
+  if (ctx.session.interactive !== true) {
+    return { ok: false, blockCode: "non-interactive", reason: "Sage allowed only in interactive sessions" };
+  }
+
+  if (ctx.runtime.mode === "ci") {
+    return { ok: false, blockCode: "ci-mode", reason: "Sage disabled in CI mode" };
+  }
+
+  if (ctx.agent.isRpcOrchestrated === true || ctx.runtime.mode === "rpc") {
+    return { ok: false, blockCode: "rpc-role", reason: "Sage disabled for RPC-orchestrated agents" };
+  }
+
+  if (ctx.agent.isSubagent === true) {
+    return { ok: false, blockCode: "subagent", reason: "Sage disabled for subagents" };
+  }
+
+  if (ctx.agent.role !== "primary") {
+    return { ok: false, blockCode: "ineligible-caller", reason: "Only primary agent may invoke Sage" };
+  }
+
+  return { ok: true, reason: "eligible" };
+}
+
+export function isHardCostCapExceeded(settings: SageSettings, budgetState: SageBudgetState): boolean {
+  if (settings.maxEstimatedCostPerSession === undefined) return false;
+  return budgetState.sessionCostTotal >= settings.maxEstimatedCostPerSession;
+}
+
+export function evaluateSoftBudget(input: {
+  settings: SageSettings;
+  budgetState: SageBudgetState;
+  mode: SageMode;
+  force: boolean;
+  questionLength: number;
+  contextLength: number;
+}): { ok: boolean; reason: string } {
+  const { settings, budgetState, mode, force, questionLength, contextLength } = input;
+
+  const forceBypassesSoftLimits = mode === "user-requested" && force === true && settings.explicitRequestAlwaysAllowed;
+  if (forceBypassesSoftLimits) {
+    return { ok: true, reason: "force=true bypassed soft limits" };
+  }
+
+  if (mode === "autonomous" && settings.autonomousEnabled === false) {
+    return { ok: false, reason: "Autonomous Sage calls are disabled" };
+  }
+
+  if (questionLength > settings.maxQuestionChars) {
+    return { ok: false, reason: `Question exceeds soft limit (${settings.maxQuestionChars} chars)` };
+  }
+
+  if (contextLength > settings.maxContextChars) {
+    return { ok: false, reason: `Context exceeds soft limit (${settings.maxContextChars} chars)` };
+  }
+
+  if (mode === "autonomous") {
+    if (budgetState.callsThisTurn >= settings.maxCallsPerTurn) {
+      return { ok: false, reason: "Per-turn Sage call soft limit reached" };
+    }
+
+    if (budgetState.sessionCalls >= settings.maxCallsPerSession) {
+      return { ok: false, reason: "Per-session Sage call soft limit reached" };
+    }
+
+    if (budgetState.lastAutoTurn !== undefined) {
+      const turnsSinceLastAuto = budgetState.currentTurn - budgetState.lastAutoTurn;
+      if (turnsSinceLastAuto <= settings.cooldownTurnsBetweenAutoCalls) {
+        return {
+          ok: false,
+          reason: `Autonomous cooldown active (${settings.cooldownTurnsBetweenAutoCalls} turns required)`
+        };
+      }
+    }
+  }
+
+  return { ok: true, reason: "within soft limits" };
+}
+
+export function makeBlockedResult(input: {
+  mode: SageMode;
+  model?: string;
+  reasoningLevel?: "minimal" | "low" | "medium" | "high" | "xhigh";
+  blockCode: BlockCode;
+  reason: string;
+  allowedByContext: boolean;
+  allowedByBudget: boolean;
+}): SageToolResult {
+  return {
+    content: [{ type: "text", text: `Sage blocked: ${input.reason}` }],
+    details: {
+      model: input.model ?? "unavailable",
+      reasoningLevel: input.reasoningLevel ?? "minimal",
+      latencyMs: 0,
+      stopReason: "blocked",
+      policy: {
+        mode: input.mode,
+        allowedByContext: input.allowedByContext,
+        contextReason: input.allowedByContext ? "eligible" : input.reason,
+        blockCode: input.blockCode,
+        allowedByBudget: input.allowedByBudget,
+        budgetReason: input.allowedByBudget ? "within limits" : input.reason
+      }
+    },
+    isError: false
+  };
+}

package/.pi/extensions/sage/runner.ts

@@ -0,0 +1,461 @@
+import { spawn } from "node:child_process";
+import { EOL } from "node:os";
+import { isAbsolute, resolve } from "node:path";
+import { isPathAllowed, resolveToolPolicy, validateBashCommandForProfile } from "./tool-policy.js";
+import type { ToolPolicySettings } from "./settings.js";
+import type {
+  BlockCode,
+  Objective,
+  ReasoningLevel,
+  ToolUsage,
+  Urgency,
+  UsageBreakdown
+} from "./types.js";
+
+export interface SageRunnerInput {
+  cwd: string;
+  model: string;
+  reasoningLevel: ReasoningLevel;
+  timeoutMs: number;
+  question: string;
+  context?: string;
+  files?: string[];
+  evidence?: string[];
+  objective?: Objective;
+  urgency?: Urgency;
+  toolPolicy: ToolPolicySettings;
+  signal?: AbortSignal;
+}
+
+export interface SageRunnerOutput {
+  text: string;
+  latencyMs: number;
+  stopReason: string;
+  usage?: UsageBreakdown;
+  toolUsage: ToolUsage;
+}
+
+interface JsonEvent {
+  type?: string;
+  toolName?: string;
+  args?: unknown;
+  result?: {
+    content?: Array<{ type?: string; text?: string }>;
+  };
+  message?: {
+    role?: string;
+    content?: Array<{ type?: string; text?: string }>;
+    stopReason?: string;
+    usage?: {
+      input?: number;
+      output?: number;
+      cacheRead?: number;
+      cacheWrite?: number;
+      totalTokens?: number;
+      cost?: { total?: number };
+    };
+  };
+}
+
+export class SageRunnerPolicyError extends Error {
+  constructor(
+    readonly blockCode: BlockCode,
+    message: string
+  ) {
+    super(message);
+    this.name = "SageRunnerPolicyError";
+  }
+}
+
+export function isSageRunnerPolicyError(error: unknown): error is SageRunnerPolicyError {
+  return error instanceof SageRunnerPolicyError;
+}
+
+export async function runSageSingleShot(input: SageRunnerInput): Promise<SageRunnerOutput> {
+  const policy = resolveToolPolicy(input.toolPolicy);
+  const startedAt = Date.now();
+
+  const invocation = resolvePiInvocation();
+  const args = [...invocation.prefixArgs, ...buildPiArgs(input.model, input.reasoningLevel, policy.cliTools)];
+  const prompt = buildSagePrompt(input);
+
+  const child = spawn(invocation.command, args, {
+    cwd: input.cwd,
+    env: {
+      ...process.env,
+      PI_SAGE_SUBAGENT: "1"
+    },
+    shell: invocation.shell,
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+
+  let stdoutBuffer = "";
+  let stderrBuffer = "";
+  let assistantText = "";
+  let stopReason = "unknown";
+  let usage: UsageBreakdown | undefined;
+  let policyViolation: SageRunnerPolicyError | undefined;
+
+  const toolUsage: ToolUsage = {
+    profile: policy.profile,
+    callsUsed: 0,
+    filesRead: 0,
+    bytesRead: 0
+  };
+
+  const failPolicy = (blockCode: BlockCode, reason: string): void => {
+    if (policyViolation) return;
+    policyViolation = new SageRunnerPolicyError(blockCode, reason);
+    child.kill("SIGTERM");
+  };
+
+  child.stdout.setEncoding("utf8");
+  child.stderr.setEncoding("utf8");
+
+  if (child.stdin) {
+    child.stdin.setDefaultEncoding("utf8");
+    child.stdin.write(prompt);
+    child.stdin.end();
+  }
+
+  child.stdout.on("data", (chunk: string) => {
+    stdoutBuffer += chunk;
+    const lines = stdoutBuffer.split(/\r?\n/);
+    stdoutBuffer = lines.pop() ?? "";
+
+    for (const line of lines) {
+      const parsed = parseJsonLine(line);
+      if (!parsed) continue;
+
+      if (parsed.type === "tool_execution_start") {
+        const toolName = parsed.toolName ?? "unknown";
+
+        if (!isToolAllowed(toolName, policy.allowedTools)) {
+          failPolicy("tool-disallowed", `Tool not allowed by Sage policy: ${toolName}`);
+          continue;
+        }
+
+        if (toolName === "bash") {
+          const command = extractBashCommand(parsed.args);
+          const decision = validateBashCommandForProfile(policy.profile, command ?? "");
+          if (!decision.ok) {
+            failPolicy(decision.blockCode ?? "tool-disallowed", decision.reason);
+            continue;
+          }
+        }
+
+        toolUsage.callsUsed += 1;
+        if (toolUsage.callsUsed > policy.maxToolCalls) {
+          failPolicy("volume-cap", "Exceeded max tool calls");
+          continue;
+        }
+
+        const candidatePaths = extractCandidatePaths(parsed.args);
+        for (const candidatePath of candidatePaths) {
+          const normalizedPath = isAbsolute(candidatePath) ? candidatePath : resolve(input.cwd, candidatePath);
+          const pathDecision = isPathAllowed(normalizedPath, [input.cwd], policy.sensitivePathDenylist);
+          if (!pathDecision.ok) {
+            failPolicy(pathDecision.blockCode ?? "path-denied", pathDecision.reason);
+            break;
+          }
+        }
+      }
+
+      if (parsed.type === "tool_execution_end") {
+        const chunkBytes = estimateContentBytes(parsed.result?.content);
+        toolUsage.bytesRead += chunkBytes;
+
+        if (chunkBytes > policy.maxBytesPerFile) {
+          failPolicy("volume-cap", "Exceeded max bytes per file");
+          continue;
+        }
+
+        if (toolUsage.bytesRead > policy.maxTotalBytesRead) {
+          failPolicy("volume-cap", "Exceeded max total bytes read");
+          continue;
+        }
+
+        if (parsed.toolName === "read") {
+          toolUsage.filesRead += 1;
+          if (toolUsage.filesRead > policy.maxFilesRead) {
+            failPolicy("volume-cap", "Exceeded max files read");
+            continue;
+          }
+        }
+      }
+
+      if (parsed.type === "message_end" && parsed.message?.role === "assistant") {
+        const text = extractAssistantText(parsed.message.content);
+        if (text.trim().length > 0) assistantText = text;
+        if (typeof parsed.message.stopReason === "string") stopReason = parsed.message.stopReason;
+        const parsedUsage = parseUsage(parsed.message.usage);
+        if (parsedUsage) usage = parsedUsage;
+      }
+    }
+  });
+
+  child.stderr.on("data", (chunk: string) => {
+    stderrBuffer += chunk;
+  });
+
+  let timedOut = false;
+  let escalationTimer: NodeJS.Timeout | undefined;
+
+  const timeout = setTimeout(() => {
+    timedOut = true;
+    try {
+      child.kill("SIGTERM");
+    } catch {
+      // Ignore kill errors
+    }
+
+    escalationTimer = setTimeout(() => {
+      try {
+        child.kill("SIGKILL");
+      } catch {
+        // Ignore kill errors
+      }
+    }, 2000);
+  }, input.timeoutMs);
+
+  if (input.signal) {
+    const onAbort = () => child.kill("SIGTERM");
+    input.signal.addEventListener("abort", onAbort, { once: true });
+    child.once("close", () => input.signal?.removeEventListener("abort", onAbort));
+  }
+
+  const exit = await new Promise<{ code: number | null; signal: NodeJS.Signals | null }>((resolve, reject) => {
+    child.once("error", (error) => reject(error));
+    child.once("close", (code, signal) => resolve({ code, signal }));
+  });
+
+  clearTimeout(timeout);
+  if (escalationTimer) clearTimeout(escalationTimer);
+
+  if (policyViolation) {
+    throw policyViolation;
+  }
+
+  if (stdoutBuffer.trim()) {
+    const parsed = parseJsonLine(stdoutBuffer.trim());
+    if (parsed?.type === "message_end" && parsed.message?.role === "assistant") {
+      const text = extractAssistantText(parsed.message.content);
+      if (text.trim().length > 0) assistantText = text;
+      if (typeof parsed.message.stopReason === "string") stopReason = parsed.message.stopReason;
+      const parsedUsage = parseUsage(parsed.message.usage);
+      if (parsedUsage) usage = parsedUsage;
+    }
+  }
+
+  const latencyMs = Date.now() - startedAt;
+
+  if (timedOut || (exit.signal === "SIGTERM" && latencyMs >= input.timeoutMs)) {
+    throw new Error("Sage subprocess timed out");
+  }
+
+  if (exit.code !== 0 && assistantText.trim().length === 0) {
+    throw new Error(`Sage subprocess failed (code ${String(exit.code)}): ${stderrBuffer.trim() || "no stderr"}`);
+  }
+
+  return {
+    text: assistantText.trim().length > 0 ? assistantText : `Sage returned no assistant text.${EOL}${stderrBuffer.trim()}`,
+    latencyMs,
+    stopReason,
+    usage,
+    toolUsage
+  };
+}
+
+function resolvePiInvocation(): { command: string; prefixArgs: string[]; shell: boolean } {
+  const envOverride = process.env.PI_BIN?.trim();
+
+  if (envOverride) {
+    const tokens = tokenizeCommand(envOverride);
+    const command = tokens.at(0);
+    if (command) {
+      return {
+        command,
+        prefixArgs: tokens.slice(1),
+        shell: false
+      };
+    }
+  }
+
+  if (process.platform === "win32") {
+    return {
+      command: "pi",
+      prefixArgs: [],
+      shell: true
+    };
+  }
+
+  return { command: "pi", prefixArgs: [], shell: false };
+}
+
+function tokenizeCommand(command: string): string[] {
+  const regex = /"([^"]*)"|'([^']*)'|(\S+)/g;
+  const tokens: string[] = [];
+
+  for (const match of command.matchAll(regex)) {
+    const token = match[1] ?? match[2] ?? match[3];
+    if (token) tokens.push(token);
+  }
+
+  return tokens;
+}
+
+function buildPiArgs(model: string, reasoningLevel: ReasoningLevel, cliTools: string[]): string[] {
+  const args = [
+    "--mode",
+    "json",
+    "-p",
+    "--no-session",
+    "--no-extensions",
+    "--model",
+    model,
+    "--thinking",
+    reasoningLevel
+  ];
+
+  if (cliTools.length === 0) {
+    args.push("--no-tools");
+  } else {
+    args.push("--tools", cliTools.join(","));
+  }
+
+  return args;
+}
+
+function buildSagePrompt(input: SageRunnerInput): string {
+  const lines: string[] = [];
+  lines.push("You are Sage, an advisory reasoning subagent.");
+  lines.push("Provide analysis and recommendations only. Do not claim to have applied changes.");
+  lines.push("Keep your response concise and actionable.");
+  lines.push("");
+  lines.push(`Question: ${input.question}`);
+
+  if (input.objective) lines.push(`Objective: ${input.objective}`);
+  if (input.urgency) lines.push(`Urgency: ${input.urgency}`);
+
+  if (input.context && input.context.trim()) {
+    lines.push("");
+    lines.push("Context:");
+    lines.push(input.context.trim());
+  }
+
+  if (input.files && input.files.length > 0) {
+    lines.push("");
+    lines.push("Relevant files:");
+    for (const file of input.files) lines.push(`- ${file}`);
+  }
+
+  if (input.evidence && input.evidence.length > 0) {
+    lines.push("");
+    lines.push("Evidence:");
+    for (const item of input.evidence) lines.push(`- ${item}`);
+  }
+
+  lines.push("");
+  lines.push("Required response format:");
+  lines.push("1) Assessment");
+  lines.push("2) Recommended next steps");
+  lines.push("3) Risks and confidence");
+
+  return lines.join(EOL);
+}
+
+function parseJsonLine(line: string): JsonEvent | undefined {
+  const trimmed = line.trim();
+  if (trimmed.length === 0) return undefined;
+  try {
+    const parsed = JSON.parse(trimmed) as unknown;
+    if (typeof parsed !== "object" || parsed === null) return undefined;
+    return parsed as JsonEvent;
+  } catch {
+    return undefined;
+  }
+}
+
+function extractAssistantText(content: Array<{ type?: string; text?: string }> | undefined): string {
+  if (!content) return "";
+  const parts = content
+    .filter((item) => item.type === "text" && typeof item.text === "string")
+    .map((item) => item.text ?? "");
+  return parts.join("").trim();
+}
+
+function parseUsage(usage: unknown): UsageBreakdown | undefined {
+  if (typeof usage !== "object" || usage === null) return undefined;
+
+  const usageRecord = usage as {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    totalTokens?: number;
+    cost?: { total?: number };
+  };
+
+  const input = usageRecord.input ?? 0;
+  const output = usageRecord.output ?? 0;
+  const cacheRead = usageRecord.cacheRead ?? 0;
+  const cacheWrite = usageRecord.cacheWrite ?? 0;
+  const totalTokens = usageRecord.totalTokens ?? input + output + cacheRead + cacheWrite;
+  const costTotal = usageRecord.cost?.total;
+
+  return {
+    input,
+    output,
+    cacheRead,
+    cacheWrite,
+    totalTokens,
+    costTotal
+  };
+}
+
+function estimateContentBytes(content: Array<{ type?: string; text?: string }> | undefined): number {
+  if (!content) return 0;
+  let total = 0;
+  for (const item of content) {
+    if (item.type === "text" && typeof item.text === "string") {
+      total += Buffer.byteLength(item.text, "utf8");
+    }
+  }
+  return total;
+}
+
+function extractCandidatePaths(args: unknown): string[] {
+  if (typeof args !== "object" || args === null) return [];
+
+  const obj = args as Record<string, unknown>;
+  const paths: string[] = [];
+
+  if (typeof obj.path === "string") paths.push(obj.path);
+  if (typeof obj.root === "string") paths.push(obj.root);
+  if (typeof obj.cwd === "string") paths.push(obj.cwd);
+
+  if (Array.isArray(obj.paths)) {
+    for (const value of obj.paths) {
+      if (typeof value === "string") paths.push(value);
+    }
+  }
+
+  return paths;
+}
+
+function extractBashCommand(args: unknown): string | undefined {
+  if (typeof args !== "object" || args === null) return undefined;
+  const obj = args as Record<string, unknown>;
+  return typeof obj.command === "string" ? obj.command : undefined;
+}
+
+function isToolAllowed(toolName: string, allowedTools: string[]): boolean {
+  const allowed = new Set(allowedTools);
+  if (allowed.has(toolName)) return true;
+
+  if (toolName === "find" && allowed.has("glob")) {
+    return true;
+  }
+
+  return false;
+}