@signalridge/pi-goal 0.49.7

package/src/settings.ts

@@ -0,0 +1,200 @@
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export const GOAL_SETTINGS_FILE = "pi-goal.json";
+export const GOAL_TOOL_VISIBILITIES = ["always", "after-first-goal"] as const;
+
+export type GoalToolVisibility = (typeof GOAL_TOOL_VISIBILITIES)[number];
+export type ContinuationLimit = number | null;
+
+export interface GoalSettings {
+  toolVisibility: GoalToolVisibility;
+  experimental: {
+    goals: boolean;
+  };
+  rpc: {
+    enabled: boolean;
+  };
+  continuationLimits: {
+    automaticTurns: ContinuationLimit;
+    noProgressTurns: ContinuationLimit;
+  };
+}
+
+export const DEFAULT_GOAL_SETTINGS: GoalSettings = {
+  toolVisibility: "always",
+  experimental: { goals: false },
+  rpc: { enabled: false },
+  continuationLimits: { automaticTurns: 25, noProgressTurns: 3 },
+};
+
+export type GoalSettingsLoadResult =
+  | { kind: "missing" }
+  | { kind: "invalid"; reason: string }
+  | { kind: "loaded"; settings: GoalSettings };
+
+export type GoalSettingsLoadIssue = Extract<GoalSettingsLoadResult, { kind: "invalid" }>;
+
+interface GoalSettingsSaveFileSystem {
+  mkdirSync: typeof mkdirSync;
+  writeFileSync: typeof writeFileSync;
+  renameSync: typeof renameSync;
+  rmSync: typeof rmSync;
+}
+
+export function normalizeGoalSettings(value: unknown): GoalSettings | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+  const toolVisibility = Object.hasOwn(value, "toolVisibility")
+    ? Reflect.get(value, "toolVisibility")
+    : DEFAULT_GOAL_SETTINGS.toolVisibility;
+  if (!GOAL_TOOL_VISIBILITIES.includes(toolVisibility as GoalToolVisibility)) return undefined;
+
+  const experimentalValue = Object.hasOwn(value, "experimental") ? Reflect.get(value, "experimental") : undefined;
+  if (
+    experimentalValue !== undefined &&
+    (typeof experimentalValue !== "object" || experimentalValue === null || Array.isArray(experimentalValue))
+  ) {
+    return undefined;
+  }
+  const goals =
+    experimentalValue && Object.hasOwn(experimentalValue, "goals")
+      ? Reflect.get(experimentalValue, "goals")
+      : DEFAULT_GOAL_SETTINGS.experimental.goals;
+  if (typeof goals !== "boolean") return undefined;
+
+  const rpcValue = Object.hasOwn(value, "rpc") ? Reflect.get(value, "rpc") : undefined;
+  if (rpcValue !== undefined && (typeof rpcValue !== "object" || rpcValue === null || Array.isArray(rpcValue))) {
+    return undefined;
+  }
+  const rpcEnabled =
+    rpcValue && Object.hasOwn(rpcValue, "enabled")
+      ? Reflect.get(rpcValue, "enabled")
+      : DEFAULT_GOAL_SETTINGS.rpc.enabled;
+  if (typeof rpcEnabled !== "boolean") return undefined;
+
+  const continuationLimitsValue = Object.hasOwn(value, "continuationLimits")
+    ? Reflect.get(value, "continuationLimits")
+    : undefined;
+  if (
+    continuationLimitsValue !== undefined &&
+    (typeof continuationLimitsValue !== "object" ||
+      continuationLimitsValue === null ||
+      Array.isArray(continuationLimitsValue))
+  ) {
+    return undefined;
+  }
+  const automaticTurns = continuationLimitsValue
+    ? normalizeContinuationLimit(
+        Reflect.get(continuationLimitsValue, "automaticTurns"),
+        DEFAULT_GOAL_SETTINGS.continuationLimits.automaticTurns,
+      )
+    : DEFAULT_GOAL_SETTINGS.continuationLimits.automaticTurns;
+  const noProgressTurns = continuationLimitsValue
+    ? normalizeContinuationLimit(
+        Reflect.get(continuationLimitsValue, "noProgressTurns"),
+        DEFAULT_GOAL_SETTINGS.continuationLimits.noProgressTurns,
+      )
+    : DEFAULT_GOAL_SETTINGS.continuationLimits.noProgressTurns;
+  if (automaticTurns === undefined || noProgressTurns === undefined) return undefined;
+
+  return {
+    toolVisibility: toolVisibility as GoalToolVisibility,
+    experimental: { goals },
+    rpc: { enabled: rpcEnabled },
+    continuationLimits: { automaticTurns, noProgressTurns },
+  };
+}
+
+function normalizeContinuationLimit(value: unknown, fallback: ContinuationLimit): ContinuationLimit | undefined {
+  if (value === undefined) return fallback;
+  if (value === null) return null;
+  return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}
+
+export function saveGoalSettings(
+  settings: GoalSettings,
+  settingsPath = join(getAgentDir(), GOAL_SETTINGS_FILE),
+  overrides: Partial<GoalSettingsSaveFileSystem> = {},
+) {
+  const normalized = normalizeGoalSettings(settings);
+  if (!normalized) throw new Error("Refusing to save invalid pi-goal settings.");
+
+  let raw: Record<string, unknown> = {};
+  try {
+    const contents = readFileSync(settingsPath, "utf8");
+    const parsed = JSON.parse(contents) as unknown;
+    if (!normalizeGoalSettings(parsed)) {
+      throw new Error(`${settingsPath}: invalid settings shape`);
+    }
+    raw = ownRecord(parsed) ?? {};
+  } catch (error) {
+    if (!isNodeError(error) || error.code !== "ENOENT") {
+      throw new Error(`Cannot save invalid settings file: ${formatError(error)}`);
+    }
+  }
+
+  const experimental = ownRecord(raw.experimental) ?? {};
+  const rpc = ownRecord(raw.rpc) ?? {};
+  const continuationLimits = ownRecord(raw.continuationLimits) ?? {};
+  const document = `${JSON.stringify(
+    {
+      ...raw,
+      toolVisibility: normalized.toolVisibility,
+      experimental: { ...experimental, goals: normalized.experimental.goals },
+      rpc: { ...rpc, enabled: normalized.rpc.enabled },
+      continuationLimits: {
+        ...continuationLimits,
+        automaticTurns: normalized.continuationLimits.automaticTurns,
+        noProgressTurns: normalized.continuationLimits.noProgressTurns,
+      },
+    },
+    null,
+    2,
+  )}\n`;
+  const fs = { mkdirSync, writeFileSync, renameSync, rmSync, ...overrides };
+  const temporaryPath = join(dirname(settingsPath), `.${basename(settingsPath)}.${randomUUID()}.tmp`);
+  try {
+    fs.mkdirSync(dirname(settingsPath), { recursive: true });
+    fs.writeFileSync(temporaryPath, document, { encoding: "utf8", flag: "wx" });
+    fs.renameSync(temporaryPath, settingsPath);
+  } finally {
+    try {
+      fs.rmSync(temporaryPath, { force: true });
+    } catch {
+      // Best-effort cleanup must not replace the save result.
+    }
+  }
+}
+
+export function readGoalSettings(settingsPath = join(getAgentDir(), GOAL_SETTINGS_FILE)): GoalSettingsLoadResult {
+  let contents: string;
+  try {
+    contents = readFileSync(settingsPath, "utf8");
+  } catch (error: unknown) {
+    if (isNodeError(error) && error.code === "ENOENT") return { kind: "missing" };
+    return { kind: "invalid", reason: `${settingsPath}: ${formatError(error)}` };
+  }
+
+  try {
+    const settings = normalizeGoalSettings(JSON.parse(contents) as unknown);
+    return settings
+      ? { kind: "loaded", settings }
+      : { kind: "invalid", reason: `${settingsPath}: invalid settings shape` };
+  } catch (error: unknown) {
+    return { kind: "invalid", reason: `${settingsPath}: ${formatError(error)}` };
+  }
+}
+
+function ownRecord(value: unknown): Record<string, unknown> | undefined {
+  return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && "code" in error;
+}
+
+function formatError(error: unknown) {
+  return error instanceof Error ? error.message : String(error);
+}

package/src/tool-policy.ts

@@ -0,0 +1,178 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { GoalToolVisibility } from "./settings.js";
+
+export const GOAL_COMPLETE_TOOL = "goal_complete";
+export const GOAL_BLOCKED_TOOL = "goal_blocked";
+export const GOAL_TOOL_NAMES = [GOAL_COMPLETE_TOOL, GOAL_BLOCKED_TOOL] as const;
+
+export interface GoalToolVisibilitySnapshot {
+  activeTools: string[];
+  goalToolsUnlocked: boolean;
+  goalToolsHiddenByPolicy: string[];
+}
+
+interface ToolPolicyContext {
+  isIdle?: () => boolean;
+}
+
+export class GoalToolPolicy {
+  private unlocked = false;
+  private readonly hiddenByPolicy = new Set<string>();
+  private readonly pi: ExtensionAPI;
+
+  constructor(pi: ExtensionAPI) {
+    this.pi = pi;
+  }
+
+  isUnlocked() {
+    return this.unlocked;
+  }
+
+  hasHiddenTools() {
+    return this.hiddenByPolicy.size > 0;
+  }
+
+  isGoalToolName(name: string) {
+    return (GOAL_TOOL_NAMES as readonly string[]).includes(name);
+  }
+
+  toolsAvailable() {
+    const active = new Set(this.pi.getActiveTools());
+    return GOAL_TOOL_NAMES.every((name) => active.has(name));
+  }
+
+  lock() {
+    this.unlocked = false;
+  }
+
+  unlock() {
+    this.unlocked = true;
+  }
+
+  unlockAndForgetHidden() {
+    this.unlocked = true;
+    this.hiddenByPolicy.clear();
+  }
+
+  hideIfLocked() {
+    if (this.unlocked) return;
+    const active = this.pi.getActiveTools();
+    const hidden = active.filter((name) => this.isGoalToolName(name));
+    if (hidden.length === 0) return;
+    this.pi.setActiveTools(active.filter((name) => !this.isGoalToolName(name)));
+    for (const name of hidden) this.hiddenByPolicy.add(name);
+  }
+
+  restoreHidden() {
+    const activeBeforeRestore = this.pi.getActiveTools();
+    const activeSet = new Set(activeBeforeRestore);
+    const missingOwnedTools = [...this.hiddenByPolicy].filter((name) => !activeSet.has(name));
+    if (missingOwnedTools.length === 0) {
+      this.hiddenByPolicy.clear();
+      return;
+    }
+    try {
+      this.pi.setActiveTools([...activeBeforeRestore, ...missingOwnedTools]);
+      const restored = new Set(this.pi.getActiveTools());
+      if (missingOwnedTools.some((name) => !restored.has(name))) {
+        throw new Error("the active tool policy rejected a previously hidden goal tool");
+      }
+      this.hiddenByPolicy.clear();
+    } catch (error) {
+      this.pi.setActiveTools(activeBeforeRestore);
+      throw error;
+    }
+  }
+
+  prepareActivation(visibility: GoalToolVisibility, ctx: ToolPolicyContext) {
+    if (visibility === "after-first-goal") {
+      if (!this.toolsAvailable() && ctx.isIdle?.() !== true) {
+        throw new Error("wait until Pi is idle before revealing the goal tools");
+      }
+      this.reveal();
+      return;
+    }
+    this.assertAvailable();
+  }
+
+  prepareSessionStart(visibility: GoalToolVisibility, previous: GoalToolVisibility) {
+    if (visibility === "after-first-goal" && previous === "always") this.lock();
+    if (visibility !== "always") return;
+    try {
+      if (this.hasHiddenTools()) this.restoreHidden();
+    } finally {
+      // Always mode remains unlocked even when an external restrictive policy
+      // prevents restoration; retained ownership lets a later session retry.
+      this.unlock();
+    }
+  }
+
+  reconcileRestoredState(visibility: GoalToolVisibility, hasUnfinishedGoal: boolean) {
+    if (visibility !== "after-first-goal") return;
+    if (hasUnfinishedGoal) this.unlockAndForgetHidden();
+    else if (!this.unlocked) this.hideIfLocked();
+  }
+
+  applyVisibilityChange(
+    previous: GoalToolVisibility,
+    next: GoalToolVisibility,
+    hasUnfinishedGoal: boolean,
+    ctx: ToolPolicyContext,
+  ) {
+    if (previous === next) return;
+    if (next === "always") {
+      if (this.hasHiddenTools() && ctx.isIdle?.() !== true) {
+        throw new Error("Wait for Pi to become idle before revealing Goal tools.");
+      }
+      this.restoreHidden();
+      this.unlock();
+      return;
+    }
+    if (hasUnfinishedGoal) {
+      this.unlockAndForgetHidden();
+      return;
+    }
+    if (ctx.isIdle?.() !== true) {
+      throw new Error("Wait for Pi to become idle before hiding Goal tools.");
+    }
+    this.lock();
+    this.hideIfLocked();
+  }
+
+  snapshot(): GoalToolVisibilitySnapshot {
+    return {
+      activeTools: this.pi.getActiveTools(),
+      goalToolsUnlocked: this.unlocked,
+      goalToolsHiddenByPolicy: [...this.hiddenByPolicy],
+    };
+  }
+
+  restore(snapshot: GoalToolVisibilitySnapshot) {
+    this.pi.setActiveTools(snapshot.activeTools);
+    this.unlocked = snapshot.goalToolsUnlocked;
+    this.hiddenByPolicy.clear();
+    for (const name of snapshot.goalToolsHiddenByPolicy) this.hiddenByPolicy.add(name);
+  }
+
+  private reveal() {
+    const snapshot = this.snapshot();
+    try {
+      const active = this.pi.getActiveTools();
+      const activeSet = new Set(active);
+      const missing = GOAL_TOOL_NAMES.filter((name) => !activeSet.has(name));
+      if (missing.length > 0) this.pi.setActiveTools([...active, ...missing]);
+      this.assertAvailable();
+      this.unlockAndForgetHidden();
+    } catch (error) {
+      this.restore(snapshot);
+      throw error;
+    }
+  }
+
+  private assertAvailable() {
+    if (this.toolsAvailable()) return;
+    throw new Error(
+      "goal_complete and goal_blocked are unavailable; include them in the active tool allowlist or leave the restrictive tool mode first.",
+    );
+  }
+}