pi-t3-pstack 0.0.0-stage → 0.1.0

package/src/plan.ts

@@ -0,0 +1,252 @@
+import { Type } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+
+import {
+  escapeHtml,
+  frameHeight,
+  pageHtml,
+  renderInlineCard,
+  wrappedLines,
+} from "./cards.ts";
+
+const PLAN_GATE_ENTRY = "t3-pstack-plan-gate";
+
+const PLAN_CHOICES = ["Approve", "Revise", "Cancel"] as const;
+
+type PlanChoice = (typeof PLAN_CHOICES)[number];
+
+type PlanGate =
+  | { readonly state: "open" }
+  | { readonly state: "planning" }
+  | { readonly planId: string; readonly state: "awaiting" }
+  | { readonly planId: string; readonly state: "revising" }
+  | { readonly planId: string; readonly state: "approved" }
+  | { readonly planId: string; readonly state: "cancelled" };
+
+const OPEN_GATE: PlanGate = { state: "open" };
+
+const BLOCK_REASONS: Readonly<Partial<Record<PlanGate["state"], string>>> = {
+  awaiting:
+    "A proposed plan is waiting for the user's approval. Only read-only tools run until the user approves it.",
+  cancelled:
+    "The user cancelled the plan. Only read-only tools run until the user sends a new message.",
+  planning:
+    "T3 is in Plan mode. Only read-only tools run. Propose the plan with pstack_plan; the user approves it from the plan card.",
+  revising:
+    "The user asked for a revised plan. Only read-only tools run until the user approves a plan through pstack_plan.",
+};
+
+// Codemode runs each nested tool call through tool_call handlers, so the
+// calls it makes are checked one by one.
+const ALWAYS_ALLOWED_TOOLS: ReadonlySet<string> = new Set([
+  "codemode",
+  "find",
+  "grep",
+  "ls",
+  "mcp__t3-code__html_preview",
+  "mcp__t3-code__html_render",
+  "mcp__t3-code__orchestrator_capabilities",
+  "mcp__t3-code__t3_thread_read",
+  "mcp__t3__orchestrator_capabilities",
+  "mcp__t3__t3_thread_read",
+  "read",
+  "tool_search",
+]);
+
+const isPlanGate = (data: unknown): data is PlanGate => {
+  if (data === null || typeof data !== "object" || !("state" in data)) {
+    return false;
+  }
+
+  return [
+    "open",
+    "planning",
+    "awaiting",
+    "revising",
+    "approved",
+    "cancelled",
+  ].includes(String(data.state));
+};
+
+const currentGate = (ctx: ExtensionContext): PlanGate => {
+  const entries = ctx.sessionManager.getBranch();
+
+  for (let index = entries.length - 1; index >= 0; index -= 1) {
+    const entry = entries[index];
+
+    if (
+      entry?.type === "custom" &&
+      entry.customType === PLAN_GATE_ENTRY &&
+      isPlanGate(entry.data)
+    ) {
+      return entry.data;
+    }
+  }
+
+  return OPEN_GATE;
+};
+
+const isPlanChoice = (value: string | undefined): value is PlanChoice =>
+  PLAN_CHOICES.some((choice) => choice === value);
+
+const planCardHtml = (title: string, plan: string): string =>
+  pageHtml(
+    title,
+    `<main class="card"><div class="head"><h1>${escapeHtml(title)}</h1></div><pre>${escapeHtml(plan)}</pre></main>`
+  );
+
+const planCardHeight = (title: string, plan: string): number =>
+  70 + wrappedLines(title, 40) * 21 + wrappedLines(plan, 30) * 21;
+
+const PlanSchema = Type.Object({
+  plan: Type.String({
+    description: "The plan in Markdown, as numbered steps.",
+    minLength: 1,
+  }),
+  title: Type.Optional(
+    Type.String({ description: "Short plan title.", minLength: 1 })
+  ),
+});
+
+interface PlanToolDetails {
+  readonly choice: PlanChoice | "dismissed";
+  readonly feedback?: string;
+  readonly planId: string;
+}
+
+export const registerPlanGate = (pi: ExtensionAPI): void => {
+  const setGate = (gate: PlanGate): void => {
+    pi.appendEntry(PLAN_GATE_ENTRY, gate);
+  };
+
+  const readOnly = (toolName: string): boolean =>
+    ALWAYS_ALLOWED_TOOLS.has(toolName) ||
+    pi
+      .getAllTools()
+      .some(
+        (tool) =>
+          tool.name === toolName && tool.annotations?.readOnlyHint === true
+      );
+
+  pi.on("tool_call", (event, ctx) => {
+    const reason = BLOCK_REASONS[currentGate(ctx).state];
+
+    if (reason === undefined || readOnly(event.toolName)) {
+      return;
+    }
+
+    return { block: true, reason };
+  });
+
+  pi.on("before_agent_start", (event, ctx) => {
+    if (currentGate(ctx).state === "planning") {
+      event.systemPromptOptions.sections.t3_plan_mode =
+        "T3 Code is in Plan mode for this message. Investigate with read-only tools only; writes, shell commands and delegation are blocked. When the plan is decision complete, call pstack_plan with it and stop. The user approves it from the plan card.";
+    }
+
+    if (
+      event.messageType === "user" &&
+      currentGate(ctx).state === "cancelled"
+    ) {
+      setGate(OPEN_GATE);
+    }
+  });
+
+  pi.registerTool(
+    defineTool({
+      annotations: { readOnlyHint: true },
+      description:
+        "Ask the user to approve a plan before any file changes. Until the user approves, only read-only tools run. On Revise, change the plan and call this tool again. On Cancel, stop: only read-only tools run until the user's next message.",
+      execute: async (toolCallId, params, _signal, _onUpdate, ctx) => {
+        if (!ctx.hasUI) {
+          throw new Error(
+            "Plan approval needs an interactive client, such as T3 Code or the Pi terminal."
+          );
+        }
+
+        const title = params.title ?? "Proposed plan";
+
+        setGate({ planId: toolCallId, state: "awaiting" });
+
+        const rendered = await renderInlineCard(ctx, {
+          height: frameHeight(planCardHeight(title, params.plan)),
+          html: planCardHtml(title, params.plan),
+          title,
+        });
+
+        const question = rendered
+          ? `Approve "${title}" shown above?`
+          : `Approve this plan?\n\n${params.plan}`;
+
+        const answer = await ctx.ui.select(question, [...PLAN_CHOICES]);
+        const choice = isPlanChoice(answer) ? answer : "Cancel";
+
+        if (choice === "Approve") {
+          setGate({ planId: toolCallId, state: "approved" });
+
+          const details: PlanToolDetails = { choice, planId: toolCallId };
+
+          return {
+            content: [
+              {
+                text: "The user approved the plan. Carry it out now.",
+                type: "text",
+              },
+            ],
+            details,
+          };
+        }
+
+        if (choice === "Revise") {
+          const feedback =
+            (await ctx.ui.input("What should change in the plan?")) ?? "";
+
+          setGate({ planId: toolCallId, state: "revising" });
+
+          const details: PlanToolDetails = {
+            choice,
+            feedback,
+            planId: toolCallId,
+          };
+
+          return {
+            content: [
+              {
+                text: `The user asked for a revised plan. Feedback: ${feedback.length > 0 ? feedback : "none given"}. Revise the plan and call pstack_plan again. Only read-only tools run until the user approves.`,
+                type: "text",
+              },
+            ],
+            details,
+          };
+        }
+
+        setGate({ planId: toolCallId, state: "cancelled" });
+
+        const details: PlanToolDetails = {
+          choice: answer === undefined ? "dismissed" : choice,
+          planId: toolCallId,
+        };
+
+        return {
+          content: [
+            {
+              text: "The user cancelled the plan. Stop and wait for the user's next message.",
+              type: "text",
+            },
+          ],
+          details,
+          terminate: true,
+        };
+      },
+      executionMode: "sequential",
+      label: "Pstack plan",
+      name: "pstack_plan",
+      parameters: PlanSchema,
+      promptSnippet: "Ask the user to approve a plan before changing files.",
+    })
+  );
+};

package/src/resources.ts

@@ -0,0 +1,30 @@
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+export interface PstackPaths {
+  readonly extensionDir: string;
+  readonly pstackRoot: string;
+  readonly skillsDir: string;
+}
+
+export const pstackPaths = (): PstackPaths => {
+  const extensionDir = path.dirname(import.meta.dirname);
+  const pstackRoot = path.join(extensionDir, "pstack");
+
+  return {
+    extensionDir,
+    pstackRoot,
+    skillsDir: path.join(pstackRoot, "skills"),
+  };
+};
+
+export const policyPath = (): string =>
+  path.join(pstackPaths().pstackRoot, "models.json");
+
+export const skillPaths = (paths: PstackPaths): string[] => {
+  if (!existsSync(paths.skillsDir)) {
+    return [];
+  }
+
+  return [paths.skillsDir];
+};

package/src/results.ts

@@ -0,0 +1,92 @@
+import { Type } from "@earendil-works/pi-ai";
+import type { Static } from "@earendil-works/pi-ai";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { Value } from "typebox/value";
+
+import {
+  httpReader,
+  readAccounts,
+  settleChild,
+  TERMINAL_STATUSES,
+} from "./accounts.ts";
+import { readLedger } from "./state.ts";
+import { insideT3 } from "./t3-http.ts";
+import { t3Json } from "./t3-json.ts";
+
+// T3 builds a delegated task's result from the child's streamed text, so the
+// block the child's extension writes after its last message never reaches the
+// parent through T3. The child also records that block in the ledger with its
+// own thread ID, and this adds it to the parent's task_status result.
+
+const STATUS_TOOLS: ReadonlySet<string> = new Set([
+  "mcp__t3-code__task_status",
+  "mcp__t3__task_status",
+]);
+
+const StatusSchema = Type.Object({
+  childThreadId: Type.String(),
+  status: Type.Optional(Type.String()),
+  workState: Type.Optional(Type.String()),
+});
+
+type Status = Static<typeof StatusSchema>;
+
+const finished = (status: Status): boolean =>
+  (status.status !== undefined && TERMINAL_STATUSES.has(status.status)) ||
+  status.workState === "result_available";
+
+// A child that hit a usage limit marks its family out as soon as the parent
+// reads its status, not only at the parent's next pstack_model call.
+const settleEarly = async (
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  status: Status
+): Promise<void> => {
+  const childFamily = readAccounts(ctx).watching.get(status.childThreadId);
+
+  if (!insideT3() || childFamily === undefined || !finished(status)) {
+    return;
+  }
+
+  try {
+    await settleChild(pi, httpReader, status.childThreadId, childFamily);
+  } catch {
+    // pstack_model settles this child later through T3's bridge.
+  }
+};
+
+export const registerResults = (pi: ExtensionAPI): void => {
+  pi.on("tool_result", async (event, ctx) => {
+    if (!STATUS_TOOLS.has(event.toolName) || event.isError) {
+      return;
+    }
+
+    const status = t3Json(StatusSchema, event);
+
+    if (status === undefined) {
+      return;
+    }
+
+    await settleEarly(pi, ctx, status);
+
+    const line = readLedger().findLast(
+      (entry) => entry.threadId === status.childThreadId && entry.report
+    );
+
+    if (line?.report === undefined) {
+      return;
+    }
+
+    const content = [
+      ...event.content,
+      { text: line.report, type: "text" as const },
+    ];
+
+    return Value.Check(Type.Undefined(), event.structuredContent)
+      ? { content }
+      : { content, structuredContent: event.structuredContent };
+  });
+};

package/src/resume.ts

@@ -0,0 +1,143 @@
+import { Type } from "@earendil-works/pi-ai";
+import type { Static } from "@earendil-works/pi-ai";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { Value } from "typebox/value";
+
+import type { Classified } from "./failures.ts";
+import { callT3Tool, insideT3 } from "./t3-http.ts";
+
+// When the orchestrator's own account runs out, nothing is left to call a
+// tool, so the extension asks T3 to post a resume prompt into this thread
+// after the reset, and deletes that schedule when the prompt arrives. T3
+// schedules recur, so the delete is what makes it run once.
+
+const RESUME_ENTRY = "t3-pstack-resume";
+
+// With no reset time in the error, try again after this long.
+const UNKNOWN_RESET_MS = 60 * 60_000;
+
+// Start a little after the reset, so the account is open when the turn starts.
+const AFTER_RESET_MS = 2 * 60_000;
+
+const MARKER = /\[pstack-resume (?<marker>[\w-]+)\]/u;
+
+const ResumeSchema = Type.Object({
+  marker: Type.String(),
+  scheduledTaskId: Type.Optional(Type.String()),
+  state: Type.Union([Type.Literal("scheduled"), Type.Literal("done")]),
+});
+
+const ScheduledSchema = Type.Object({ scheduledTaskId: Type.String() });
+
+const resumes = (ctx: ExtensionContext) =>
+  ctx.sessionManager
+    .getBranch()
+    .flatMap((entry) =>
+      entry.type === "custom" &&
+      entry.customType === RESUME_ENTRY &&
+      Value.Check(ResumeSchema, entry.data)
+        ? [entry.data]
+        : []
+    );
+
+const pending = (ctx: ExtensionContext) => {
+  const all = resumes(ctx);
+
+  const done = new Set(
+    all.filter((entry) => entry.state === "done").map((entry) => entry.marker)
+  );
+
+  return all.filter(
+    (entry) => entry.state === "scheduled" && !done.has(entry.marker)
+  );
+};
+
+const twoDigits = (value: number): string => String(value).padStart(2, "0");
+
+export const scheduleResume = async (
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  modelFamily: string,
+  failure: Classified
+): Promise<void> => {
+  if (!insideT3() || pending(ctx).length > 0) {
+    return;
+  }
+
+  const resetAt =
+    failure.resetAt === undefined
+      ? Date.now() + UNKNOWN_RESET_MS
+      : Date.parse(failure.resetAt);
+
+  const at = new Date(Math.max(resetAt, Date.now()) + AFTER_RESET_MS);
+  const marker = `${Date.now().toString(36)}`;
+
+  const prompt = `[pstack-resume ${marker}] The previous turn stopped because the ${modelFamily} account ran out of usage or had no working connection. Its reset time has passed. Continue the work from where it stopped: read the task list, check what the last steps left, and go on.`;
+
+  try {
+    const result = await callT3Tool("schedule_task", {
+      bindToCurrentThread: true,
+      prompt,
+      schedule: {
+        timeOfDay: `${twoDigits(at.getHours())}:${twoDigits(at.getMinutes())}`,
+        type: "fixed_time",
+        weekdays: [at.getDay()],
+      },
+      title: `pstack resume after ${modelFamily} reset`,
+    });
+
+    const scheduled: Static<typeof ResumeSchema> = {
+      marker,
+      state: "scheduled",
+    };
+
+    if (Value.Check(ScheduledSchema, result)) {
+      scheduled.scheduledTaskId = result.scheduledTaskId;
+    }
+
+    pi.appendEntry(RESUME_ENTRY, scheduled);
+
+    if (ctx.hasUI) {
+      ctx.ui.notify(
+        `${modelFamily} is out. This chat resumes at ${at.toLocaleString()}.`,
+        "warning"
+      );
+    }
+  } catch (error) {
+    if (ctx.hasUI) {
+      ctx.ui.notify(
+        `${modelFamily} is out, and scheduling a resume failed: ${String(error)}`,
+        "error"
+      );
+    }
+  }
+};
+
+export const registerResume = (pi: ExtensionAPI): void => {
+  pi.on("before_agent_start", async (event, ctx) => {
+    const marker = MARKER.exec(
+      event.messageType === "user" ? event.prompt : ""
+    )?.[1];
+
+    if (marker === undefined) {
+      return;
+    }
+
+    const entry = pending(ctx).find((candidate) => candidate.marker === marker);
+
+    if (entry === undefined) {
+      return;
+    }
+
+    pi.appendEntry(RESUME_ENTRY, { marker, state: "done" });
+
+    if (entry.scheduledTaskId !== undefined) {
+      await callT3Tool("delete_scheduled_task", {
+        scheduledTaskId: entry.scheduledTaskId,
+      }).catch(() => null);
+    }
+  });
+};

package/src/session.ts

@@ -0,0 +1,70 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+import type { PstackPaths } from "./resources.ts";
+
+const SESSION_HOOK_OFF = /^session hook:\s*off\s*$/mu;
+
+export const modelSheetPath = (): string => {
+  const configHome = process.env.XDG_CONFIG_HOME?.trim();
+
+  if (configHome) {
+    return path.join(configHome, "t3-pstack", "models.md");
+  }
+
+  return path.join(homedir(), ".config", "t3-pstack", "models.md");
+};
+
+export const sessionHookEnabled = (): boolean => {
+  const sheetPath = modelSheetPath();
+
+  if (!existsSync(sheetPath)) {
+    return true;
+  }
+
+  return !SESSION_HOOK_OFF.test(readFileSync(sheetPath, "utf-8"));
+};
+
+// Upstream's hook text is written for Claude Code and Codex. Each pair
+// rewrites a part that reads differently on Pi, where pstack_model reads the
+// model sheet and no shell output budget cuts a SKILL.md.
+const PI_REWRITES: readonly (readonly [string, string])[] = [
+  ["t3-pstack:poteto-mode", "/skill:poteto-mode"],
+  [
+    " On Codex, open its SKILL.md whole, in a shell call of its own with `max_output_tokens: 10000`, since a smaller budget cuts out its middle.",
+    " Read its SKILL.md in full before you act.",
+  ],
+  [
+    "This runs on T3: before the first subagent or panel in a session, read the model sheet, `~/.config/t3-pstack/models.md` (`$XDG_CONFIG_HOME/t3-pstack/models.md` when that is set), or `t3-pstack-models.md` in this host's config directory when that file is missing. This chat runs the playbook itself. A step it says to delegate goes through `delegate_task` to that role's sheet entry,",
+    "This chat runs the playbook itself. A step it says to delegate goes through `delegate_task` with a target from `pstack_model`,",
+  ],
+];
+
+export const sessionGuidance = (paths: PstackPaths): string => {
+  const contextPath = path.join(
+    paths.pstackRoot,
+    "hooks",
+    "session-start-context.md"
+  );
+
+  const upstreamGuidance = existsSync(contextPath)
+    ? readFileSync(contextPath, "utf-8").trim()
+    : "You have t3-pstack, pstack for T3 Code.";
+
+  let piGuidance = upstreamGuidance;
+
+  for (const [from, to] of PI_REWRITES) {
+    piGuidance = piGuidance.replaceAll(from, to);
+  }
+
+  return [
+    piGuidance,
+    "",
+    "Pi notes:",
+    `- The pstack root is ${paths.pstackRoot}. Read skill and agent files there when a skill names a plugin root.`,
+    "- The session task tool is pstack_tasks. Keep the playbook todolist there and send the complete list on every change, with stable step ids and at most one step in_progress.",
+    "- When a workflow needs the transcript, use pstack_transcript, not the Claude Code or Codex finders.",
+    "- When a plan needs the user's approval before edits, call pstack_plan.",
+  ].join("\n");
+};