pi-t3-pstack 0.0.0-stage → 0.1.0

package/src/state.ts

@@ -0,0 +1,124 @@
+import {
+  appendFileSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+
+import { Type } from "@earendil-works/pi-ai";
+import type { Static } from "@earendil-works/pi-ai";
+import { Value } from "typebox/value";
+
+// Machine-wide pstack state, shared by every Pi session: which model families
+// are out of usage, and one ledger line per delegated brief.
+
+const stateDir = (): string => {
+  const stateHome = process.env.XDG_STATE_HOME?.trim();
+
+  return path.join(
+    stateHome || path.join(homedir(), ".local", "state"),
+    "t3-pstack"
+  );
+};
+
+const FamilyRecordSchema = Type.Union([
+  Type.Object({
+    reason: Type.Union([Type.Literal("exhausted"), Type.Literal("unhealthy")]),
+    resetAt: Type.Optional(Type.String()),
+    since: Type.String(),
+    source: Type.Union([Type.Literal("delegate"), Type.Literal("user")]),
+    state: Type.Literal("exhausted"),
+  }),
+  Type.Object({
+    childThreadId: Type.String(),
+    since: Type.String(),
+    state: Type.Literal("probing"),
+  }),
+]);
+
+const AccountsFileSchema = Type.Object({
+  families: Type.Record(Type.String(), FamilyRecordSchema),
+});
+
+export type FamilyRecord = Static<typeof FamilyRecordSchema>;
+
+type AccountsFile = Static<typeof AccountsFileSchema>;
+
+const accountsPath = (): string => path.join(stateDir(), "accounts.json");
+
+export const readFamilies = (): AccountsFile["families"] => {
+  try {
+    const parsed: unknown = JSON.parse(readFileSync(accountsPath(), "utf-8"));
+
+    return Value.Check(AccountsFileSchema, parsed) ? parsed.families : {};
+  } catch {
+    return {};
+  }
+};
+
+// Write to a temporary file and rename it over the old one, so a session
+// reading at the same time sees the old state or the new one, never half.
+export const updateFamily = (family: string, record?: FamilyRecord): void => {
+  const families = Object.fromEntries(
+    Object.entries(readFamilies()).filter(([name]) => name !== family)
+  );
+
+  if (record !== undefined) {
+    families[family] = record;
+  }
+
+  mkdirSync(stateDir(), { recursive: true });
+
+  const target = accountsPath();
+  const temporary = `${target}.${process.pid}.tmp`;
+
+  writeFileSync(temporary, `${JSON.stringify({ families }, null, 2)}\n`);
+  renameSync(temporary, target);
+};
+
+export const appendLedger = (
+  line: Record<string, string | number | null>
+): void => {
+  mkdirSync(stateDir(), { recursive: true });
+  appendFileSync(
+    path.join(stateDir(), "ledger.jsonl"),
+    `${JSON.stringify(line)}\n`
+  );
+};
+
+const LedgerLineSchema = Type.Object({
+  cacheRead: Type.Optional(Type.Number()),
+  cacheWrite: Type.Optional(Type.Number()),
+  cost: Type.Optional(Type.Number()),
+  input: Type.Optional(Type.Number()),
+  job: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  minutes: Type.Optional(Type.Number()),
+  model: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  report: Type.Optional(Type.String()),
+  status: Type.Optional(Type.String()),
+  threadId: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  tokens: Type.Optional(Type.Number()),
+});
+
+export type LedgerLine = Static<typeof LedgerLineSchema>;
+
+export const readLedger = (): LedgerLine[] => {
+  try {
+    return readFileSync(path.join(stateDir(), "ledger.jsonl"), "utf-8")
+      .split("\n")
+      .flatMap((line) => {
+        try {
+          const parsed: unknown = JSON.parse(line);
+
+          return Value.Check(LedgerLineSchema, parsed) ? [parsed] : [];
+        } catch {
+          return [];
+        }
+      });
+  } catch {
+    return [];
+  }
+};

package/src/t3-http.ts

@@ -0,0 +1,140 @@
+// Calls one tool on T3's MCP endpoint directly, with the thread's own token.
+// Lifecycle handlers such as agent_end get no ctx.executeTool, and the
+// orchestrator has to schedule its resume exactly when its own model failed.
+
+const TIMEOUT_MS = 15_000;
+
+const PROTOCOL_VERSION = "2025-06-18";
+
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | readonly JsonValue[]
+  | { readonly [key: string]: JsonValue };
+
+interface JsonRpcReply {
+  readonly error?: { readonly message?: string };
+  readonly result?: {
+    readonly content?: readonly { readonly text?: string }[];
+    readonly isError?: boolean;
+    readonly structuredContent?: JsonValue;
+  };
+}
+
+export const insideT3 = (): boolean => Boolean(process.env.T3_MCP_URL?.trim());
+
+const parseReply = (contentType: string, body: string): JsonRpcReply => {
+  if (!contentType.includes("text/event-stream")) {
+    // SAFETY: T3's MCP endpoint answers with a JSON-RPC reply; every field is read optionally.
+    return JSON.parse(body) as JsonRpcReply;
+  }
+
+  const data = body
+    .split("\n")
+    .filter((line) => line.startsWith("data:"))
+    .map((line) => line.slice(5).trim())
+    .findLast((line) => line.startsWith("{"));
+
+  // SAFETY: same JSON-RPC reply shape as above, carried in an event-stream data line.
+  return JSON.parse(data ?? "{}") as JsonRpcReply;
+};
+
+const post = async (
+  url: string,
+  headers: Headers,
+  message: Readonly<Record<string, JsonValue>>
+): Promise<{ body: string; response: Response }> => {
+  const response = await fetch(url, {
+    body: JSON.stringify({ jsonrpc: "2.0", ...message }),
+    headers,
+    method: "POST",
+    signal: AbortSignal.timeout(TIMEOUT_MS),
+  });
+
+  const body = await response.text();
+
+  if (!response.ok) {
+    throw new Error(`T3 MCP answered ${response.status}`);
+  }
+
+  return { body, response };
+};
+
+const replyResult = (name: string, reply: JsonRpcReply): JsonValue => {
+  if (reply.error !== undefined || reply.result?.isError === true) {
+    throw new Error(
+      `${name} failed: ${reply.error?.message ?? reply.result?.content?.[0]?.text ?? "unknown error"}`
+    );
+  }
+
+  return (
+    reply.result?.structuredContent ??
+    JSON.parse(reply.result?.content?.[0]?.text ?? "null")
+  );
+};
+
+// T3 holds an open session until it expires, so each call closes its own.
+const closeSession = async (url: string, headers: Headers): Promise<void> => {
+  try {
+    const response = await fetch(url, {
+      headers,
+      method: "DELETE",
+      signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+
+    await response.body?.cancel();
+  } catch {
+    // T3 expires a session it never got to close.
+  }
+};
+
+export const callT3Tool = async (
+  name: string,
+  args: Readonly<Record<string, JsonValue>>
+): Promise<JsonValue> => {
+  const url = process.env.T3_MCP_URL?.trim() ?? "";
+
+  const headers = new Headers({
+    accept: "application/json, text/event-stream",
+    authorization: `Bearer ${process.env.T3_MCP_BEARER_TOKEN ?? ""}`,
+    "content-type": "application/json",
+    "mcp-protocol-version": PROTOCOL_VERSION,
+  });
+
+  const init = await post(url, headers, {
+    id: 1,
+    method: "initialize",
+    params: {
+      capabilities: {},
+      clientInfo: { name: "t3-pstack", version: "0" },
+      protocolVersion: PROTOCOL_VERSION,
+    },
+  });
+
+  const session = init.response.headers.get("mcp-session-id");
+
+  if (session !== null) {
+    headers.set("mcp-session-id", session);
+  }
+
+  try {
+    await post(url, headers, { method: "notifications/initialized" });
+
+    const call = await post(url, headers, {
+      id: 2,
+      method: "tools/call",
+      params: { arguments: args, name },
+    });
+
+    return replyResult(
+      name,
+      parseReply(call.response.headers.get("content-type") ?? "", call.body)
+    );
+  } finally {
+    if (session !== null) {
+      await closeSession(url, headers);
+    }
+  }
+};

package/src/t3-json.ts

@@ -0,0 +1,50 @@
+import { Type } from "@earendil-works/pi-ai";
+import type { Static, TSchema } from "@earendil-works/pi-ai";
+import { Value } from "typebox/value";
+
+const ResultEnvelopeSchema = Type.Object({
+  structuredContent: Type.Unknown(),
+});
+
+const TextPartSchema = Type.Object({ text: Type.String() });
+
+export interface ToolOutput {
+  readonly content: readonly unknown[];
+  readonly structuredContent?: unknown;
+}
+
+const textOf = (content: readonly unknown[]): string =>
+  content
+    .map((part) => (Value.Check(TextPartSchema, part) ? part.text : ""))
+    .join("");
+
+// T3's in-thread bridge passes the whole MCP result as structuredContent,
+// a direct MCP client passes the server's structuredContent itself, and
+// some results carry their data only as JSON text.
+export const t3Json = <S extends TSchema>(
+  schema: S,
+  output: ToolOutput
+): Static<S> | undefined => {
+  const structured = output.structuredContent;
+
+  const fromStructured = [
+    Value.Check(ResultEnvelopeSchema, structured)
+      ? structured.structuredContent
+      : undefined,
+    structured,
+  ].find((candidate) => Value.Check(schema, candidate));
+
+  if (Value.Check(schema, fromStructured)) {
+    return fromStructured;
+  }
+
+  try {
+    const parsed = JSON.parse(textOf(output.content));
+
+    return Value.Check(schema, parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+export const t3Text = (output: ToolOutput): string => textOf(output.content);

package/src/t3-mcp.ts

@@ -0,0 +1,188 @@
+import type { ImageContent, TextContent } from "@earendil-works/pi-ai";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+
+import { insideT3 } from "./t3-http.ts";
+
+const SERVER_NAME = "t3";
+const TOOL_PREFIX = `mcp__${SERVER_NAME}__`;
+const STATUS_KEY = "t3-mcp";
+const DEFAULT_URL = "http://127.0.0.1:3773/mcp";
+const PROBE_TIMEOUT_MS = 1500;
+const REFRESH_INTERVAL_MS = 3000;
+const AUTH_FAILURE = /sign.?in|unauthori[sz]ed|\b401\b|authoriz/iu;
+
+// T3 refuses these outside a T3 thread because they act as the calling thread.
+// Hiding them keeps the model from choosing a tool that cannot work here.
+const THREAD_ONLY_TOOLS = [
+  "create_threads",
+  "delegate_task",
+  "device_*",
+  "html_*",
+  "preview_*",
+  "request_secret",
+  "t3_preview_*",
+  "t3_worktree_handoff",
+  "t3_worktree_status",
+  "task_cancel",
+  "task_status",
+] as const;
+
+const hiddenThreadOnlyTools = Object.fromEntries(
+  THREAD_ONLY_TOOLS.map((pattern) => [pattern, "hidden" as const])
+);
+
+type T3McpState =
+  | { readonly kind: "connecting" }
+  | { readonly kind: "offline" }
+  | { readonly kind: "sign-in" }
+  | { readonly kind: "connected"; readonly tools: number };
+
+interface T3McpObservation {
+  readonly authFailed: boolean;
+  readonly firstCheck: boolean;
+  readonly liveTools: number;
+  readonly reachable: boolean;
+}
+
+const deriveState = (observation: T3McpObservation): T3McpState => {
+  if (!observation.reachable) {
+    return { kind: "offline" };
+  }
+
+  if (observation.liveTools === 0 && observation.firstCheck) {
+    return { kind: "connecting" };
+  }
+
+  if (observation.authFailed || observation.liveTools === 0) {
+    return { kind: "sign-in" };
+  }
+
+  return { kind: "connected", tools: observation.liveTools };
+};
+
+const statusText = (state: T3McpState): string => {
+  switch (state.kind) {
+    case "connected": {
+      return `T3 MCP ● connected, ${state.tools} ${state.tools === 1 ? "tool" : "tools"}`;
+    }
+
+    case "connecting": {
+      return "T3 MCP ○ connecting";
+    }
+
+    case "offline": {
+      return "T3 MCP ○ offline, start T3 Code";
+    }
+
+    default: {
+      return `T3 MCP ○ not signed in, run /mcp login ${SERVER_NAME}`;
+    }
+  }
+};
+
+const serverUrl = (): string =>
+  process.env.T3_PSTACK_MCP_URL?.trim() || DEFAULT_URL;
+
+const metadataUrl = (url: string): string =>
+  new URL("/.well-known/oauth-protected-resource", url).href;
+
+const probeReachable = async (url: string): Promise<boolean> => {
+  try {
+    const response = await fetch(metadataUrl(url), {
+      signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+    });
+
+    await response.body?.cancel();
+
+    return response.ok;
+  } catch {
+    return false;
+  }
+};
+
+const textOf = (content: readonly (TextContent | ImageContent)[]): string =>
+  content.map((part) => (part.type === "text" ? part.text : "")).join("\n");
+
+export const registerT3Mcp = (pi: ExtensionAPI): void => {
+  if (insideT3()) {
+    return;
+  }
+
+  const url = serverUrl();
+
+  pi.registerMcpServer(SERVER_NAME, {
+    description:
+      "T3 Code app tools: launch, steer, and wait on T3 threads (t3_thread_launch, t3_thread_send, t3_thread_wait), schedules, projects, queues, and pull request watching. Outside a T3 thread, list tools need a projectId from t3_project_list.",
+    toolExposure: hiddenThreadOnlyTools,
+    url,
+  });
+
+  let authFailed = false;
+  let firstCheck = true;
+  let timer: ReturnType<typeof setInterval> | undefined;
+
+  const liveTools = (): number =>
+    pi
+      .getAllTools()
+      .filter(
+        (tool) =>
+          tool.name.startsWith(TOOL_PREFIX) && tool.exposure !== "hidden"
+      ).length;
+
+  const refresh = async (ctx: ExtensionContext): Promise<void> => {
+    if (!ctx.hasUI) {
+      return;
+    }
+
+    const reachable = await probeReachable(url);
+
+    const state = deriveState({
+      authFailed,
+      firstCheck,
+      liveTools: liveTools(),
+      reachable,
+    });
+
+    firstCheck = false;
+
+    ctx.ui.setStatus(STATUS_KEY, statusText(state));
+  };
+
+  const stopTimer = (): void => {
+    if (timer !== undefined) {
+      clearInterval(timer);
+      timer = undefined;
+    }
+  };
+
+  pi.on("session_start", async (_event, ctx) => {
+    stopTimer();
+    firstCheck = true;
+    await refresh(ctx);
+
+    if (ctx.mode === "tui") {
+      timer = setInterval(async () => {
+        try {
+          await refresh(ctx);
+        } catch {
+          stopTimer();
+        }
+      }, REFRESH_INTERVAL_MS);
+      timer.unref();
+    }
+  });
+
+  pi.on("tool_result", async (event, ctx) => {
+    if (!event.toolName.startsWith(TOOL_PREFIX)) {
+      return;
+    }
+
+    authFailed = event.isError && AUTH_FAILURE.test(textOf(event.content));
+    await refresh(ctx);
+  });
+
+  pi.on("session_shutdown", stopTimer);
+};

package/src/tasks.ts

@@ -0,0 +1,163 @@
+import { Type } from "@earendil-works/pi-ai";
+import type { Static } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+
+import {
+  escapeHtml,
+  frameHeight,
+  pageHtml,
+  renderInlineCard,
+  wrappedLines,
+} from "./cards.ts";
+
+const TaskStatusSchema = Type.Union([
+  Type.Literal("pending"),
+  Type.Literal("in_progress"),
+  Type.Literal("completed"),
+]);
+
+const TaskStepSchema = Type.Object({
+  id: Type.String({
+    description: "Stable ID for this step. Keep it the same across updates.",
+    minLength: 1,
+  }),
+  status: TaskStatusSchema,
+  text: Type.String({ description: "What the step does.", minLength: 1 }),
+});
+
+const TaskSnapshotSchema = Type.Object({
+  explanation: Type.Optional(
+    Type.String({ description: "Optional note about why the list changed." })
+  ),
+  steps: Type.Array(TaskStepSchema, {
+    description:
+      "The complete task list. Each call replaces the previous list.",
+    minItems: 1,
+  }),
+});
+
+type TaskStatus = Static<typeof TaskStatusSchema>;
+
+type TaskSnapshot = Static<typeof TaskSnapshotSchema>;
+
+interface TaskProgress {
+  readonly completed: number;
+  readonly total: number;
+}
+
+interface StatusPresentation {
+  readonly label: string;
+  readonly mark: string;
+  readonly word: string;
+}
+
+const STATUS_PRESENTATION: Readonly<Record<TaskStatus, StatusPresentation>> = {
+  completed: { label: "Completed", mark: "✓", word: "done" },
+  in_progress: { label: "In progress", mark: "●", word: "doing" },
+  pending: { label: "Pending", mark: "○", word: "todo" },
+};
+
+const checkSnapshot = (snapshot: TaskSnapshot): void => {
+  const ids = new Set(snapshot.steps.map((step) => step.id));
+
+  if (ids.size !== snapshot.steps.length) {
+    throw new Error("Each task step needs a unique id.");
+  }
+
+  const running = snapshot.steps.filter(
+    (step) => step.status === "in_progress"
+  );
+
+  if (running.length > 1) {
+    throw new Error("Only one task step can be in_progress at a time.");
+  }
+};
+
+const taskProgress = (snapshot: TaskSnapshot): TaskProgress => ({
+  completed: snapshot.steps.filter((step) => step.status === "completed")
+    .length,
+  total: snapshot.steps.length,
+});
+
+const taskSummary = (snapshot: TaskSnapshot): string => {
+  const progress = taskProgress(snapshot);
+
+  const lines = snapshot.steps.map(
+    (step) => `[${STATUS_PRESENTATION[step.status].word}] ${step.text}`
+  );
+
+  return [
+    `Tasks: ${progress.completed} of ${progress.total} complete`,
+    ...lines,
+  ].join("\n");
+};
+
+const taskCardHtml = (snapshot: TaskSnapshot): string => {
+  const progress = taskProgress(snapshot);
+
+  const note =
+    snapshot.explanation === undefined
+      ? ""
+      : `<p class="note">${escapeHtml(snapshot.explanation)}</p>`;
+
+  const items = snapshot.steps
+    .map(
+      (step) =>
+        `<li class="${step.status}"><span class="dot" aria-hidden="true">${STATUS_PRESENTATION[step.status].mark}</span><span class="text"><span class="sr-only">${STATUS_PRESENTATION[step.status].label}: </span>${escapeHtml(step.text)}</span></li>`
+    )
+    .join("");
+
+  return pageHtml(
+    "Tasks",
+    `<main class="card"><div class="head"><h1>Tasks</h1><span class="muted">${progress.completed} of ${progress.total} complete</span></div>${note}<ol>${items}</ol></main>`
+  );
+};
+
+const taskCardHeight = (snapshot: TaskSnapshot): number => {
+  let height = 75;
+
+  if (snapshot.explanation !== undefined) {
+    height += wrappedLines(snapshot.explanation, 38) * 21 + 10;
+  }
+
+  for (const step of snapshot.steps) {
+    height += wrappedLines(step.text, 38) * 21 + 8;
+  }
+
+  return height;
+};
+
+const TaskToolDetailsSchema = Type.Object({
+  rendered: Type.Boolean(),
+  snapshot: TaskSnapshotSchema,
+});
+
+type TaskToolDetails = Static<typeof TaskToolDetailsSchema>;
+
+export const tasksTool = defineTool({
+  annotations: { readOnlyHint: true },
+  description:
+    "Publish the current task list for this run. Send the complete list every time, with stable step ids and at most one step in_progress. T3 shows the list as a task card in the chat.",
+  execute: async (_toolCallId, params, _signal, _onUpdate, ctx) => {
+    checkSnapshot(params);
+
+    const rendered = await renderInlineCard(ctx, {
+      height: frameHeight(taskCardHeight(params)),
+      html: taskCardHtml(params),
+      title: "Tasks",
+    });
+
+    const details: TaskToolDetails = { rendered, snapshot: params };
+
+    return {
+      content: [{ text: taskSummary(params), type: "text" }],
+      details,
+      structuredContent: details,
+    };
+  },
+  label: "Pstack tasks",
+  name: "pstack_tasks",
+  outputSchema: TaskToolDetailsSchema,
+  parameters: TaskSnapshotSchema,
+  promptSnippet: "Publish the current task list as a card in the chat.",
+});

package/src/transcript.ts

@@ -0,0 +1,17 @@
+import { Type } from "@earendil-works/pi-ai";
+import type { Static } from "@earendil-works/pi-ai";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export const PstackTranscriptSchema = Type.Object({
+  branchEntryIds: Type.Array(Type.String()),
+  sessionFile: Type.Optional(Type.String()),
+  sessionId: Type.String(),
+});
+
+export type PstackTranscript = Static<typeof PstackTranscriptSchema>;
+
+export const transcriptRef = (ctx: ExtensionContext): PstackTranscript => ({
+  branchEntryIds: ctx.sessionManager.getBranch().map((entry) => entry.id),
+  sessionFile: ctx.sessionManager.getSessionFile(),
+  sessionId: ctx.sessionManager.getSessionId(),
+});