pi-auto-permissions 0.1.0

package/src/canonical.ts

@@ -0,0 +1,314 @@
+import { createHash } from "node:crypto";
+import type { EnforcementBackend } from "./domain.ts";
+import { assertRevision } from "./domain.ts";
+
+export const DEFAULT_CANONICAL_LIMITS: Readonly<CanonicalLimits> = Object.freeze({
+  maxBytes: 64 * 1024,
+  maxDepth: 32,
+  maxNodes: 10_000,
+});
+
+export interface CanonicalLimits {
+  maxBytes: number;
+  maxDepth: number;
+  maxNodes: number;
+}
+
+export type CanonicalErrorCode =
+  | "unsupported"
+  | "cycle"
+  | "depth"
+  | "nodes"
+  | "bytes"
+  | "invalid-limit";
+
+export class CanonicalizationError extends Error {
+  readonly code: CanonicalErrorCode;
+  readonly path: string;
+
+  constructor(code: CanonicalErrorCode, message: string, path = "$") {
+    super(`${message} at ${path}`);
+    this.name = "CanonicalizationError";
+    this.code = code;
+    this.path = path;
+  }
+}
+
+export interface CanonicalDocument {
+  json: string;
+  utf8Bytes: number;
+  sha256: string;
+}
+
+export interface ActionInput {
+  toolName: string;
+  arguments: unknown;
+  cwd: string;
+  toolMetadata: unknown;
+}
+
+export interface CanonicalAction extends CanonicalDocument {
+  readonly kind: "canonical-action";
+}
+
+export interface ReviewBindingInput {
+  action: CanonicalAction;
+  globalRevision: number;
+  sessionRevision: number;
+  backend: EnforcementBackend;
+  sessionId: string;
+}
+
+export interface ReviewBinding extends CanonicalDocument {
+  readonly kind: "review-binding";
+  readonly actionSha256: string;
+  readonly globalRevision: number;
+  readonly sessionRevision: number;
+  readonly backend: EnforcementBackend;
+  readonly sessionId: string;
+}
+
+export function canonicalJson(value: unknown, limits: Partial<CanonicalLimits> = {}): CanonicalDocument {
+  const resolvedLimits = normalizeLimits(limits);
+  const state: EncodingState = {
+    limits: resolvedLimits,
+    active: new WeakSet<object>(),
+    nodes: 0,
+    bytes: 0,
+    chunks: [],
+  };
+
+  encode(value, "$", 0, state);
+  const json = state.chunks.join("");
+  return {
+    json,
+    utf8Bytes: state.bytes,
+    sha256: createHash("sha256").update(json, "utf8").digest("hex"),
+  };
+}
+
+export function canonicalizeAction(
+  input: Readonly<ActionInput>,
+  limits: Partial<CanonicalLimits> = {},
+): CanonicalAction {
+  if (typeof input.toolName !== "string" || input.toolName.length === 0) {
+    throw new CanonicalizationError("unsupported", "toolName must be a non-empty string", "$.toolName");
+  }
+  if (typeof input.cwd !== "string" || input.cwd.length === 0) {
+    throw new CanonicalizationError("unsupported", "cwd must be a non-empty string", "$.cwd");
+  }
+
+  const document = canonicalJson(
+    {
+      arguments: input.arguments,
+      cwd: input.cwd,
+      toolMetadata: input.toolMetadata,
+      toolName: input.toolName,
+    },
+    limits,
+  );
+
+  return { kind: "canonical-action", ...document };
+}
+
+export function createReviewBinding(
+  input: Readonly<ReviewBindingInput>,
+  limits: Partial<CanonicalLimits> = {},
+): ReviewBinding {
+  assertRevision(input.globalRevision, "global revision");
+  assertRevision(input.sessionRevision, "session revision");
+  if (typeof input.sessionId !== "string" || input.sessionId.length === 0) {
+    throw new CanonicalizationError("unsupported", "sessionId must be a non-empty string", "$.sessionId");
+  }
+
+  const document = canonicalJson(
+    {
+      actionSha256: input.action.sha256,
+      backend: input.backend,
+      globalRevision: input.globalRevision,
+      sessionId: input.sessionId,
+      sessionRevision: input.sessionRevision,
+    },
+    limits,
+  );
+
+  return {
+    kind: "review-binding",
+    ...document,
+    actionSha256: input.action.sha256,
+    globalRevision: input.globalRevision,
+    sessionRevision: input.sessionRevision,
+    backend: input.backend,
+    sessionId: input.sessionId,
+  };
+}
+
+export function reviewBindingMatches(
+  binding: Readonly<ReviewBinding>,
+  current: Readonly<ReviewBindingInput>,
+): boolean {
+  return (
+    binding.actionSha256 === current.action.sha256 &&
+    binding.globalRevision === current.globalRevision &&
+    binding.sessionRevision === current.sessionRevision &&
+    binding.backend === current.backend &&
+    binding.sessionId === current.sessionId
+  );
+}
+
+interface EncodingState {
+  limits: CanonicalLimits;
+  active: WeakSet<object>;
+  nodes: number;
+  bytes: number;
+  chunks: string[];
+}
+
+function encode(value: unknown, path: string, depth: number, state: EncodingState): void {
+  if (depth > state.limits.maxDepth) {
+    throw new CanonicalizationError("depth", `canonical value exceeds depth ${state.limits.maxDepth}`, path);
+  }
+  state.nodes += 1;
+  if (state.nodes > state.limits.maxNodes) {
+    throw new CanonicalizationError("nodes", `canonical value exceeds ${state.limits.maxNodes} nodes`, path);
+  }
+
+  if (value === null) return append("null", path, state);
+  if (typeof value === "string") {
+    // JSON string bytes are never fewer than the source's UTF-16 code units
+    // plus its quotes. Reject impossible fits before JSON.stringify can copy
+    // an adversarially large tool argument.
+    if (value.length + 2 > state.limits.maxBytes - state.bytes) {
+      throw new CanonicalizationError(
+        "bytes",
+        `canonical value exceeds ${state.limits.maxBytes} UTF-8 bytes`,
+        path,
+      );
+    }
+    return append(JSON.stringify(value), path, state);
+  }
+  if (typeof value === "boolean") return append(value ? "true" : "false", path, state);
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) {
+      throw new CanonicalizationError("unsupported", "non-finite numbers are unsupported", path);
+    }
+    return append(JSON.stringify(value), path, state);
+  }
+  if (typeof value !== "object") {
+    throw new CanonicalizationError("unsupported", `${typeof value} values are unsupported`, path);
+  }
+
+  if (state.active.has(value)) {
+    throw new CanonicalizationError("cycle", "cyclic values are unsupported", path);
+  }
+
+  state.active.add(value);
+  try {
+    if (Array.isArray(value)) {
+      encodeArray(value, path, depth, state);
+    } else {
+      encodeObject(value, path, depth, state);
+    }
+  } finally {
+    state.active.delete(value);
+  }
+}
+
+function encodeArray(value: unknown[], path: string, depth: number, state: EncodingState): void {
+  if (value.length > state.limits.maxNodes - state.nodes) {
+    throw new CanonicalizationError("nodes", `canonical value exceeds ${state.limits.maxNodes} nodes`, path);
+  }
+  const ownKeys = Reflect.ownKeys(value);
+  for (let index = 0; index < value.length; index += 1) {
+    if (!Object.hasOwn(value, index)) {
+      throw new CanonicalizationError("unsupported", "sparse arrays are unsupported", `${path}[${index}]`);
+    }
+  }
+  for (const key of ownKeys) {
+    if (key === "length") continue;
+    if (typeof key === "symbol" || !isCanonicalArrayIndex(key, value.length)) {
+      throw new CanonicalizationError("unsupported", "arrays with custom properties are unsupported", path);
+    }
+  }
+
+  append("[", path, state);
+  for (let index = 0; index < value.length; index += 1) {
+    if (index > 0) append(",", path, state);
+    const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+    if (descriptor === undefined || !("value" in descriptor)) {
+      throw new CanonicalizationError("unsupported", "array accessors are unsupported", `${path}[${index}]`);
+    }
+    encode(descriptor.value, `${path}[${index}]`, depth + 1, state);
+  }
+  append("]", path, state);
+}
+
+function encodeObject(value: object, path: string, depth: number, state: EncodingState): void {
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw new CanonicalizationError("unsupported", "only plain objects are supported", path);
+  }
+  if (Object.getOwnPropertySymbols(value).length > 0) {
+    throw new CanonicalizationError("unsupported", "symbol keys are unsupported", path);
+  }
+
+  const keys = Object.keys(value);
+  if (keys.length > state.limits.maxNodes - state.nodes) {
+    throw new CanonicalizationError("nodes", `canonical value exceeds ${state.limits.maxNodes} nodes`, path);
+  }
+  // Bound total key material before sort/JSON escaping. Three is the minimum
+  // per-key structural cost for two quotes and a colon.
+  let minimumKeyBytes = 0;
+  for (const key of keys) {
+    minimumKeyBytes += key.length + 3;
+    if (minimumKeyBytes > state.limits.maxBytes - state.bytes) {
+      throw new CanonicalizationError(
+        "bytes",
+        `canonical value exceeds ${state.limits.maxBytes} UTF-8 bytes`,
+        path,
+      );
+    }
+  }
+  keys.sort();
+  append("{", path, state);
+  keys.forEach((key, index) => {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (descriptor === undefined || !("value" in descriptor)) {
+      throw new CanonicalizationError("unsupported", "object accessors are unsupported", childPath(path, key));
+    }
+    if (index > 0) append(",", path, state);
+    append(JSON.stringify(key), childPath(path, key), state);
+    append(":", path, state);
+    encode(descriptor.value, childPath(path, key), depth + 1, state);
+  });
+  append("}", path, state);
+}
+
+function append(chunk: string, path: string, state: EncodingState): void {
+  const bytes = Buffer.byteLength(chunk, "utf8");
+  if (state.bytes + bytes > state.limits.maxBytes) {
+    throw new CanonicalizationError("bytes", `canonical value exceeds ${state.limits.maxBytes} UTF-8 bytes`, path);
+  }
+  state.bytes += bytes;
+  state.chunks.push(chunk);
+}
+
+function normalizeLimits(limits: Partial<CanonicalLimits>): CanonicalLimits {
+  const resolved = { ...DEFAULT_CANONICAL_LIMITS, ...limits };
+  for (const [name, value] of Object.entries(resolved)) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+      throw new CanonicalizationError("invalid-limit", `${name} must be a positive safe integer`);
+    }
+  }
+  return resolved;
+}
+
+function isCanonicalArrayIndex(key: string, length: number): boolean {
+  if (!/^(0|[1-9]\d*)$/u.test(key)) return false;
+  const index = Number(key);
+  return Number.isSafeInteger(index) && index >= 0 && index < length && String(index) === key;
+}
+
+function childPath(parent: string, key: string): string {
+  return /^[A-Za-z_$][A-Za-z0-9_$]*$/u.test(key) ? `${parent}.${key}` : `${parent}[${JSON.stringify(key)}]`;
+}

package/src/commands/index.ts

@@ -0,0 +1,362 @@
+import { getSupportedThinkingLevels } from "@earendil-works/pi-ai";
+import type { Model, ModelThinkingLevel } from "@earendil-works/pi-ai";
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+
+import {
+  isModelThinkingLevel,
+  type PermissionMode,
+  type ReviewerSelection,
+} from "../domain.js";
+
+type MaybePromise<T> = T | Promise<T>;
+
+export type PermissionCommandSnapshot =
+  | { health: "healthy"; reviewer: ReviewerSelection | null }
+  | { health: "fault"; error: string };
+
+/**
+ * The command layer deliberately knows nothing about files, sessions, or the
+ * enforcement runtime. In particular, setReviewerAndAuto is one host-level
+ * semantic operation: the command layer never exposes a partially selected
+ * reviewer tuple and never switches the session before that tuple is durable.
+ */
+export interface PermissionCommandsHost {
+  readSnapshot(): MaybePromise<PermissionCommandSnapshot>;
+  setRequestedMode(mode: PermissionMode, ctx: ExtensionCommandContext): MaybePromise<void>;
+  /** Must repair faulted global state before committing the complete tuple. */
+  setReviewerAndAuto(selection: ReviewerSelection, ctx: ExtensionCommandContext): MaybePromise<void>;
+  /** Must remain callable in faulted global state so the command can repair it. */
+  setEnabled(enabled: boolean, ctx: ExtensionCommandContext): MaybePromise<void>;
+  updateStatus?(ctx: ExtensionCommandContext): MaybePromise<void>;
+}
+
+type CommandRegistrar = Pick<ExtensionAPI, "registerCommand">;
+
+const AUTO = "Auto";
+const UNRESTRICTED = "Unrestricted";
+const AUTO_UNCONFIGURED = "Auto (unavailable — select /perm-auto-model first)";
+const AUTO_FAULTED = "Auto (unavailable — repair permissions settings first)";
+
+const PERM_USAGE = "Usage: /perm auto|unrestricted";
+const MODEL_USAGE = "Usage: /perm-auto-model provider/model thinkingLevel";
+const ENABLED_USAGE = "Usage: /perm-enabled on|off";
+
+/** Register the complete, intentionally small user-facing command surface. */
+export function registerPermissionCommands(
+  pi: CommandRegistrar,
+  host: PermissionCommandsHost,
+): void {
+  pi.registerCommand("perm", {
+    description: "Set permission mode to Auto or Unrestricted",
+    getArgumentCompletions: (prefix) => completeValues(prefix, ["auto", "unrestricted"]),
+    handler: async (rawArgs, ctx) => {
+      const args = rawArgs.trim();
+      if (args.length > 0) {
+        if (args !== "auto" && args !== "unrestricted") {
+          ctx.ui.notify(PERM_USAGE, "warning");
+          return;
+        }
+
+        if (args === "auto" && !(await autoIsAvailable(host, ctx))) return;
+        await mutate(
+          ctx,
+          host,
+          () => host.setRequestedMode(args, ctx),
+          `Permissions: ${args === "auto" ? AUTO : UNRESTRICTED}.`,
+        );
+        return;
+      }
+
+      if (!ctx.hasUI) {
+        ctx.ui.notify(PERM_USAGE, "warning");
+        return;
+      }
+
+      const snapshot = await readSnapshot(host, ctx);
+      if (snapshot === undefined) return;
+      const autoLabel =
+        snapshot.health === "fault"
+          ? AUTO_FAULTED
+          : snapshot.reviewer === null
+            ? AUTO_UNCONFIGURED
+            : AUTO;
+      const selected = await selectOption(ctx, "Permission mode", [autoLabel, UNRESTRICTED]);
+      if (selected === undefined) return;
+
+      if (selected === autoLabel) {
+        if (autoLabel !== AUTO) {
+          notifyAutoUnavailable(ctx, snapshot);
+          return;
+        }
+        await mutate(ctx, host, () => host.setRequestedMode("auto", ctx), "Permissions: Auto.");
+        return;
+      }
+
+      if (selected === UNRESTRICTED) {
+        await mutate(
+          ctx,
+          host,
+          () => host.setRequestedMode("unrestricted", ctx),
+          "Permissions: Unrestricted.",
+        );
+      }
+    },
+  });
+
+  pi.registerCommand("perm-auto-model", {
+    description: "Select the Auto reviewer model and thinking level",
+    handler: async (rawArgs, ctx) => {
+      const args = rawArgs.trim();
+      let candidate: ReviewerCandidate | undefined;
+
+      if (args.length === 0) {
+        if (!ctx.hasUI) {
+          ctx.ui.notify(MODEL_USAGE, "warning");
+          return;
+        }
+        candidate = await selectReviewerInteractively(ctx);
+      } else {
+        const parsed = parseReviewerArgs(args);
+        if (parsed === undefined) {
+          ctx.ui.notify(MODEL_USAGE, "warning");
+          return;
+        }
+        candidate = parsed;
+      }
+
+      if (candidate === undefined) return;
+      const validated = await validateReviewer(candidate, ctx);
+      if (validated === undefined) return;
+
+      await mutate(
+        ctx,
+        host,
+        () => host.setReviewerAndAuto(validated, ctx),
+        `Auto reviewer: ${validated.provider}/${validated.modelId} (thinking: ${validated.thinkingLevel}). Permissions: Auto.`,
+      );
+    },
+  });
+
+  pi.registerCommand("perm-enabled", {
+    description: "Enable or disable permission enforcement globally",
+    getArgumentCompletions: (prefix) => completeValues(prefix, ["on", "off"]),
+    handler: async (rawArgs, ctx) => {
+      const args = rawArgs.trim();
+      if (args !== "on" && args !== "off") {
+        ctx.ui.notify(ENABLED_USAGE, "warning");
+        return;
+      }
+
+      const enabled = args === "on";
+      await mutate(
+        ctx,
+        host,
+        () => host.setEnabled(enabled, ctx),
+        `Permissions ${enabled ? "enabled" : "disabled"} globally.`,
+      );
+    },
+  });
+}
+
+interface ReviewerCandidate {
+  provider: string;
+  modelId: string;
+  thinkingLevel: ModelThinkingLevel;
+}
+
+function parseReviewerArgs(args: string): ReviewerCandidate | undefined {
+  const parts = args.split(/\s+/u);
+  if (parts.length !== 2) return undefined;
+  const modelSpec = parts[0];
+  const thinkingLevel = parts[1];
+  if (modelSpec === undefined || thinkingLevel === undefined || !isModelThinkingLevel(thinkingLevel)) {
+    return undefined;
+  }
+
+  const slash = modelSpec.indexOf("/");
+  if (slash <= 0 || slash === modelSpec.length - 1) return undefined;
+  return {
+    provider: modelSpec.slice(0, slash),
+    modelId: modelSpec.slice(slash + 1),
+    thinkingLevel,
+  };
+}
+
+async function selectReviewerInteractively(
+  ctx: ExtensionCommandContext,
+): Promise<ReviewerCandidate | undefined> {
+  let available: Model<string>[];
+  try {
+    available = ctx.modelRegistry.getAvailable();
+  } catch (error) {
+    notifyFailure(ctx, "Could not list available reviewer models", error);
+    return undefined;
+  }
+
+  const byLabel = new Map<string, Model<string>>();
+  for (const model of available) byLabel.set(`${model.provider}/${model.id}`, model);
+  const labels = [...byLabel.keys()].sort();
+  if (labels.length === 0) {
+    ctx.ui.notify("No available reviewer models were found.", "warning");
+    return undefined;
+  }
+
+  const modelLabel = await selectOption(ctx, "Auto reviewer model", labels);
+  if (modelLabel === undefined) return undefined;
+  const model = byLabel.get(modelLabel);
+  if (model === undefined) {
+    ctx.ui.notify("The selected reviewer model is no longer available.", "warning");
+    return undefined;
+  }
+
+  const levels = supportedThinkingLevels(model);
+  if (levels.length === 0) {
+    ctx.ui.notify(`Reviewer model ${modelLabel} has no supported thinking levels.`, "warning");
+    return undefined;
+  }
+  const thinkingLevel = await selectOption(ctx, "Auto reviewer thinking level", levels);
+  if (thinkingLevel === undefined) return undefined;
+  if (!isModelThinkingLevel(thinkingLevel) || !levels.includes(thinkingLevel)) {
+    ctx.ui.notify("The selected thinking level is no longer supported.", "warning");
+    return undefined;
+  }
+
+  return { provider: model.provider, modelId: model.id, thinkingLevel };
+}
+
+async function validateReviewer(
+  candidate: ReviewerCandidate,
+  ctx: ExtensionCommandContext,
+): Promise<ReviewerSelection | undefined> {
+  let model: Model<string> | undefined;
+  let available: Model<string>[];
+  try {
+    model = ctx.modelRegistry.find(candidate.provider, candidate.modelId);
+    available = ctx.modelRegistry.getAvailable();
+  } catch (error) {
+    notifyFailure(ctx, "Could not resolve the reviewer model", error);
+    return undefined;
+  }
+
+  const display = `${candidate.provider}/${candidate.modelId}`;
+  if (model === undefined) {
+    ctx.ui.notify(`Reviewer model ${display} does not exist.`, "warning");
+    return undefined;
+  }
+  if (!available.some((item) => item.provider === candidate.provider && item.id === candidate.modelId)) {
+    ctx.ui.notify(`Reviewer model ${display} is not available.`, "warning");
+    return undefined;
+  }
+
+  const levels = supportedThinkingLevels(model);
+  if (!levels.includes(candidate.thinkingLevel)) {
+    ctx.ui.notify(
+      `Thinking level ${candidate.thinkingLevel} is not supported by ${display}. Supported: ${levels.join(", ") || "none"}.`,
+      "warning",
+    );
+    return undefined;
+  }
+
+  try {
+    const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+    if (!auth.ok) {
+      ctx.ui.notify(`Reviewer model ${display} has no usable authentication: ${auth.error}`, "warning");
+      return undefined;
+    }
+  } catch (error) {
+    notifyFailure(ctx, `Could not resolve authentication for ${display}`, error);
+    return undefined;
+  }
+
+  return { ...candidate };
+}
+
+function supportedThinkingLevels(model: Model<string>): ModelThinkingLevel[] {
+  return [...new Set(getSupportedThinkingLevels(model).filter(isModelThinkingLevel))];
+}
+
+async function autoIsAvailable(
+  host: PermissionCommandsHost,
+  ctx: ExtensionCommandContext,
+): Promise<boolean> {
+  const snapshot = await readSnapshot(host, ctx);
+  if (snapshot === undefined) return false;
+  if (snapshot.health === "healthy" && snapshot.reviewer !== null) return true;
+  notifyAutoUnavailable(ctx, snapshot);
+  return false;
+}
+
+function notifyAutoUnavailable(
+  ctx: ExtensionCommandContext,
+  snapshot: PermissionCommandSnapshot,
+): void {
+  if (snapshot.health === "fault") {
+    ctx.ui.notify(`Auto is unavailable because permission settings are invalid: ${snapshot.error}`, "warning");
+  } else {
+    ctx.ui.notify("Auto is unavailable until /perm-auto-model selects a reviewer and thinking level.", "warning");
+  }
+}
+
+async function readSnapshot(
+  host: PermissionCommandsHost,
+  ctx: ExtensionCommandContext,
+): Promise<PermissionCommandSnapshot | undefined> {
+  try {
+    return await host.readSnapshot();
+  } catch (error) {
+    notifyFailure(ctx, "Could not read permission settings", error);
+    return undefined;
+  }
+}
+
+async function mutate(
+  ctx: ExtensionCommandContext,
+  host: PermissionCommandsHost,
+  operation: () => MaybePromise<void>,
+  successMessage: string,
+): Promise<void> {
+  try {
+    await operation();
+  } catch (error) {
+    notifyFailure(ctx, "Permission settings were not changed", error);
+    return;
+  }
+
+  if (host.updateStatus !== undefined) {
+    try {
+      await host.updateStatus(ctx);
+    } catch (error) {
+      notifyFailure(ctx, "Permission settings changed, but status could not be refreshed", error);
+    }
+  }
+  ctx.ui.notify(successMessage, "info");
+}
+
+function notifyFailure(ctx: ExtensionCommandContext, prefix: string, error: unknown): void {
+  const detail = error instanceof Error ? error.message : String(error);
+  ctx.ui.notify(`${prefix}: ${detail}`, "error");
+}
+
+async function selectOption(
+  ctx: ExtensionCommandContext,
+  title: string,
+  options: string[],
+): Promise<string | undefined> {
+  try {
+    return await ctx.ui.select(title, options);
+  } catch (error) {
+    notifyFailure(ctx, "Could not open permission selection", error);
+    return undefined;
+  }
+}
+
+function completeValues(prefix: string, values: readonly string[]) {
+  const normalized = prefix.trimStart();
+  const filtered = values.filter((value) => value.startsWith(normalized));
+  return filtered.length === 0
+    ? null
+    : filtered.map((value) => ({ value, label: value }));
+}