@mgiles/perk 3.2.0 → 3.3.0

package/extension/worker/readOnlySession.ts

@@ -1,294 +0,0 @@
-// The perk-owned, in-process read-only child session (context-isolation primitive #1).
-//
-// A deterministic, fully-isolated read-only child spun at the SDK level via `createAgentSession`,
-// plus the handoff contract both context-isolation primitives honor (the in-process one here; the
-// spawned shape later): cap the model-visible output, keep the FULL result in a verified scratch
-// file + a structured block, and return DOUBLE-DELIVERY (compact prose for the human + a structured
-// block for the orchestrator). Route-don't-relay is enforced structurally — the raw child output
-// never enters the parent; only a path/summary does. This is substrate only; its consumer is the
-// read-only CI executor. No registry stage, no door change, no cross-CLI behavior.
-//
-// Relationship to the in-session gate (extension/substrate/toolGating.ts): its READ_ONLY_TOOLS is the *in-session* allowlist
-// and includes a sub-allowlisted `bash`. This SDK-level set is the STRICTER ["read","grep","find",
-// "ls"] (no bash) — a separate constant, not a reuse. The CI executor composes its own allowlist when it needs a
-// gated test-runner command; that is not authored here.
-//
-// Isolation comes from the DefaultResourceLoader `no*` flags + the tools allowlist — NOT from
-// `extensionFactories: []` (which is already the default and controls only inline factories; it
-// does not stop `loader.reload()` from resolving the project's `.pi/settings.json` packages and
-// loading perk's own extension into the child). The `no*` flags keep perk's machinery out of the
-// child and keep the path offline/deterministic. A custom loader is reloaded by the caller.
-
-import { existsSync, mkdirSync, mkdtempSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { join } from "node:path";
-import type { Api, Model } from "@earendil-works/pi-ai";
-import {
-  type AgentSession,
-  createAgentSession,
-  DefaultResourceLoader,
-  SessionManager,
-  SettingsManager,
-} from "@earendil-works/pi-coding-agent";
-import { atomicWriteFileSync, ensureRunScratch, scratchDir } from "../substrate/cache.ts";
-
-/**
- * The SDK-level read-only allowlist (no `bash`; stricter than the in-session READ_ONLY_TOOLS).
- * Mirrors pi's read-only recipe (examples/sdk/05-tools.ts).
- */
-export const SDK_READ_ONLY_TOOLS = ["read", "grep", "find", "ls"];
-
-/** The model-visible byte cap (matches subagent's PER_TASK_OUTPUT_CAP); overridable per call. */
-export const DEFAULT_MODEL_VISIBLE_CAP = 50 * 1024;
-
-/** Minimal structural shape of a session message (we only read assistant text parts). */
-interface MessageLike {
-  role?: string;
-  content?: unknown;
-}
-
-/**
- * Scan messages newest-first for the last assistant message's first text part; "" if none.
- * Pure — mirrors subagent's getFinalOutput.
- */
-export function extractFinalAssistantText(messages: readonly MessageLike[]): string {
-  for (let i = messages.length - 1; i >= 0; i--) {
-    const msg = messages[i];
-    if (msg?.role !== "assistant") continue;
-    const content = msg.content;
-    if (typeof content === "string") return content;
-    if (Array.isArray(content)) {
-      for (const part of content) {
-        const p = part as { type?: string; text?: string };
-        if (p.type === "text" && typeof p.text === "string") return p.text;
-      }
-    }
-  }
-  return "";
-}
-
-export interface CapResult {
-  /** The (possibly truncated) text safe to show the model. */
-  shown: string;
-  /** Total UTF-8 byte length of the original text. */
-  bytesTotal: number;
-  /** UTF-8 byte length of `shown` (before the truncation notice). */
-  bytesShown: number;
-  /** Whether truncation occurred. */
-  truncated: boolean;
-}
-
-/**
- * UTF-8-byte-safe truncation (subagent's byte-trim loop). Under cap ⇒ unchanged, truncated:false.
- * When truncated, a notice points at the scratch file holding the full result; the notice sits at
- * the cut edge (appended in head mode, prepended in tail mode) so a top-down reader immediately
- * knows which side is missing.
- *
- * `keep` mirrors the SDK's truncateHead/truncateTail guidance: "head" (default) for
- * model-authored summaries/handoffs where the beginning matters; "tail" for command/CI logs where
- * failure summaries live at the end. Deliberately perk's own byte-only util (not the SDK's
- * line-count-aware `truncateTail`): `CapResult`'s byte fields and the scratch-pointing notice are
- * load-bearing in `ChildStructured`/`CiCheckResult`. Pure.
- */
-export function capForModel(
-  text: string,
-  cap: number = DEFAULT_MODEL_VISIBLE_CAP,
-  scratchPath: string | null = null,
-  keep: "head" | "tail" = "head",
-): CapResult {
-  const bytesTotal = Buffer.byteLength(text, "utf8");
-  if (bytesTotal <= cap) {
-    return { shown: text, bytesTotal, bytesShown: bytesTotal, truncated: false };
-  }
-  let trimmed = keep === "head" ? text.slice(0, cap) : text.slice(-cap);
-  while (Buffer.byteLength(trimmed, "utf8") > cap) {
-    trimmed = keep === "head" ? trimmed.slice(0, -1) : trimmed.slice(1);
-  }
-  const bytesShown = Buffer.byteLength(trimmed, "utf8");
-  const omitted = bytesTotal - bytesShown;
-  const where = scratchPath ? ` Full output preserved at ${scratchPath}.` : "";
-  const shown =
-    keep === "head"
-      ? `${trimmed}\n\n[Output truncated: ${omitted} bytes omitted.${where}]`
-      : `[Output truncated: ${omitted} bytes omitted.${where}]\n\n${trimmed}`;
-  return { shown, bytesTotal, bytesShown, truncated: true };
-}
-
-/**
- * The structured half of the double-delivery handoff — the block the orchestrator parses (and the
- * CI executor will place in a tool's forking-safe `details`).
- */
-export interface ChildStructured {
-  success: boolean;
-  summary: string;
-  scratchPath: string | null;
-  bytesTotal: number;
-  bytesShown: number;
-  truncated: boolean;
-  error?: string;
-}
-
-/**
- * The full double-delivery handoff: `prose` is the capped human-facing summary; `structured` is the
- * orchestrator-facing block; `scratchPath` is the verified path to the full result
- * (route-don't-relay — the raw output never enters the parent beyond the cap).
- */
-export interface ChildHandoff {
-  success: boolean;
-  prose: string;
-  structured: ChildStructured;
-  scratchPath: string | null;
-}
-
-/**
- * Create a locked-down, SDK-level read-only child session. Isolation = the DefaultResourceLoader
- * `no*` flags + the tools allowlist; a throwaway temp `agentDir` (a locked-down child loads nothing
- * from it, and there is no production ctx.agentDir). Creating the session is OFFLINE; only
- * `prompt()` requires a key. The caller must `dispose()` the returned session.
- */
-export async function createReadOnlySession(opts: {
-  cwd: string;
-  model?: Model<Api>;
-  tools?: string[];
-}): Promise<{ session: AgentSession }> {
-  // A throwaway temp agentDir — a locked-down child loads nothing from it (no production
-  // ctx.agentDir exists), exactly as the offline harness does.
-  const agentDir = mkdtempSync(join(tmpdir(), "perk-ro-agent-"));
-  const loader = new DefaultResourceLoader({
-    cwd: opts.cwd,
-    agentDir,
-    noExtensions: true,
-    noSkills: true,
-    noPromptTemplates: true,
-    noThemes: true,
-    noContextFiles: true,
-  });
-  // A custom loader is NOT auto-reloaded by createAgentSession — reload it ourselves.
-  await loader.reload();
-  const { session } = await createAgentSession({
-    cwd: opts.cwd,
-    model: opts.model,
-    resourceLoader: loader,
-    tools: opts.tools ?? SDK_READ_ONLY_TOOLS,
-    sessionManager: SessionManager.inMemory(opts.cwd),
-    settingsManager: SettingsManager.inMemory({
-      compaction: { enabled: false },
-      retry: { enabled: false },
-    }),
-  });
-  return { session };
-}
-
-export interface RunReadOnlyChildOpts {
-  cwd: string;
-  task: string;
-  model?: Model<Api>;
-  tools?: string[];
-  runId?: string;
-  step?: string;
-  modelVisibleCap?: number;
-  signal?: AbortSignal;
-}
-
-export interface RunReadOnlyChildDeps {
-  createSession?: (opts: {
-    cwd: string;
-    model?: Model<Api>;
-    tools?: string[];
-  }) => Promise<{ session: AgentSession }>;
-  runTask?: (session: AgentSession, task: string, signal?: AbortSignal) => Promise<string>;
-}
-
-/** Default production runTask: prompt the child, then extract its final assistant text. */
-async function defaultRunTask(
-  session: AgentSession,
-  task: string,
-  _signal?: AbortSignal,
-): Promise<string> {
-  await session.prompt(task);
-  return extractFinalAssistantText(session.messages as unknown as MessageLike[]);
-}
-
-/** Resolve the scratch file path for a child's full output (run-scoped when a runId is given). */
-function resolveScratchPath(cwd: string, runId?: string, step?: string): string {
-  if (runId) {
-    const dir = ensureRunScratch(cwd, runId);
-    return join(dir, `${step ?? "child"}.md`);
-  }
-  const base = scratchDir(cwd);
-  mkdirSync(base, { recursive: true });
-  const dir = mkdtempSync(join(base, "child-"));
-  return join(dir, `${step ?? "child"}.md`);
-}
-
-function failure(prose: string, error: string): ChildHandoff {
-  return {
-    success: false,
-    prose,
-    scratchPath: null,
-    structured: {
-      success: false,
-      summary: prose,
-      scratchPath: null,
-      bytesTotal: 0,
-      bytesShown: 0,
-      truncated: false,
-      error,
-    },
-  };
-}
-
-/**
- * One-shot read-only child orchestrator implementing the handoff contract: create the read-only
- * session, run the task, write the full raw output to a scratch file and VERIFY it
- * (write→verify→pass-path), cap the model-visible output into prose, and return
- * double-delivery. Fail loud + fail closed: NEVER throws to the parent — on any error it returns
- * `{ success:false, scratchPath:null }` with the error in both `prose` and `structured.error`.
- */
-export async function runReadOnlyChild(
-  opts: RunReadOnlyChildOpts,
-  deps: RunReadOnlyChildDeps = {},
-): Promise<ChildHandoff> {
-  const createSession = deps.createSession ?? createReadOnlySession;
-  const runTask = deps.runTask ?? defaultRunTask;
-  const cap = opts.modelVisibleCap ?? DEFAULT_MODEL_VISIBLE_CAP;
-
-  if (opts.signal?.aborted) return failure("read-only child aborted before start.", "aborted");
-
-  let session: AgentSession | null = null;
-  try {
-    const created = await createSession({ cwd: opts.cwd, model: opts.model, tools: opts.tools });
-    session = created.session;
-
-    const output = await runTask(session, opts.task, opts.signal);
-
-    if (opts.signal?.aborted) return failure("read-only child aborted.", "aborted");
-
-    // write → verify → pass-path: persist the full result, then confirm it landed.
-    const scratchPath = resolveScratchPath(opts.cwd, opts.runId, opts.step);
-    atomicWriteFileSync(scratchPath, output);
-    if (!existsSync(scratchPath)) {
-      return failure("read-only child: scratch write could not be verified.", "scratch-verify");
-    }
-
-    const capped = capForModel(output, cap, scratchPath);
-    return {
-      success: true,
-      prose: capped.shown,
-      scratchPath,
-      structured: {
-        success: true,
-        summary: capped.shown,
-        scratchPath,
-        bytesTotal: capped.bytesTotal,
-        bytesShown: capped.bytesShown,
-        truncated: capped.truncated,
-      },
-    };
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    return failure(`read-only child failed: ${message}`, message);
-  } finally {
-    session?.dispose();
-  }
-}