@xingular/harness 0.1.6 → 2.0.0

package/dist/terminal-pi.js

@@ -6,10 +6,11 @@ import { createConnection } from "node:net";
 var SOCKET_ENV = "XINGULAR_HARNESS_SOCKET";
 var TOKEN_ENV = "XINGULAR_HARNESS_TOKEN";
 var SocketError = class extends Error {
-  constructor(code, message) {
-    super(message);
+  constructor(code, message2) {
+    super(message2);
     this.code = code;
   }
+  code;
 };
 function connectionFromEnv(env = process.env) {
   const socket = env[SOCKET_ENV];
@@ -60,6 +61,322 @@ function terminalCall(event, data = {}, timeoutMs = 6e5) {
   return request(connectionFromEnv(), { event, data }, event, timeoutMs);
 }
 
+// src/terminal/accountsMenu.ts
+var HEALTH = {
+  ok: "Ready",
+  limited: "Limit reached",
+  auth_expired: "Sign in again",
+  signed_out: "Signed out",
+  error: "Needs attention",
+  unknown: "Not checked"
+};
+var ADD = "Add account";
+var POOLS = "Pools";
+var CHECK_ALL = "Check all accounts";
+var DONE = "Done";
+var BACK = "Back";
+var USE_HERE = "Use for this session (restarts it)";
+var MAKE_DEFAULT = "Make default for new sessions";
+var RENAME = "Rename";
+var CHECK = "Check";
+var DETAILS = "Details";
+var ACTIVITY = "Activity";
+var SIGN_IN = "Sign in";
+var REMOVE_PROVIDER = "Remove a provider";
+var SIGN_OUT = "Sign out";
+var REMOVE = "Remove account";
+var NEW_POOL = "New pool";
+var EDIT = "Edit";
+var DELETE = "Delete";
+var SAVE_POOL = "Save pool";
+var CANCEL = "Cancel";
+var START_OVER = "Start over";
+var REMOVE_LAST = "Remove the last one";
+var CANCEL_SIGN_IN = "Cancel sign-in";
+var CHECK_STATUS = "Check status";
+var LOGIN_TIMEOUT_MS = 10 * 6e4;
+var POLL_MS = 1e3;
+var message = (error) => error instanceof Error ? error.message : String(error);
+async function attempt(ui, action) {
+  try {
+    await action();
+    return true;
+  } catch (error) {
+    ui.notify(message(error), "error");
+    return false;
+  }
+}
+function resetIn(resetsAt, now2 = Date.now()) {
+  const minutes = Math.round((Date.parse(resetsAt) - now2) / 6e4);
+  if (Number.isNaN(minutes)) return resetsAt;
+  if (minutes <= 0) return "now";
+  if (minutes < 60) return `in ${minutes}m`;
+  if (minutes < 60 * 24) return `in ${Math.floor(minutes / 60)}h ${minutes % 60}m`;
+  return `in ${Math.floor(minutes / (60 * 24))}d`;
+}
+function accountRows(overview, session) {
+  return overview.accounts.map((account, index) => {
+    const mark2 = account.isDefault ? "\u25CF" : "\u25CB";
+    const here2 = session?.accountId === account.id ? " \xB7 this session" : "";
+    return { account, label: `${index + 1}. ${mark2} ${account.label} \xB7 ${HEALTH[account.state.health] ?? HEALTH.unknown}${here2}` };
+  });
+}
+var limitLine = (limit) => `${limit.label}: ${limit.usedPercent ?? "?"}% used${limit.resetsAt ? `, resets ${resetIn(limit.resetsAt)}` : ""}`;
+function accountDetails(account) {
+  const state = account.state;
+  const lines2 = [
+    account.label,
+    `Health: ${HEALTH[state.health] ?? HEALTH.unknown}`,
+    `Default for new sessions: ${account.isDefault ? "yes" : "no"}`,
+    `Signed in: ${state.signedIn === null ? "not checked" : state.signedIn ? "yes" : "no"}`,
+    `Providers: ${state.piProviders.length ? state.piProviders.join(", ") : "none"}`,
+    state.plan ? `Plan: ${state.plan}` : null,
+    state.identity ? `Identity: ${state.identity}` : null,
+    `Last checked: ${state.lastCheckedAt ? new Date(state.lastCheckedAt).toLocaleString() : "never"}`,
+    state.lastError ? `Last error: ${state.lastError.message}${state.lastError.resetsAt ? ` (resets ${resetIn(state.lastError.resetsAt)})` : ""}` : null,
+    ...state.limits.map(limitLine),
+    state.limits.length ? null : "Usage limits: Pi providers do not report them.",
+    state.capabilities.length ? `Detected: ${state.capabilities.join(", ")}` : null
+  ];
+  return lines2.filter((line) => line !== null).join("\n");
+}
+function loginStep(step) {
+  if (step.type === "auth_url" && typeof step.url === "string") return `Open this link to sign in:
+${step.url}${typeof step.instructions === "string" ? `
+${step.instructions}` : ""}`;
+  if (step.type === "device_code" && typeof step.userCode === "string") return `Enter the code ${step.userCode} at ${String(step.verificationUri ?? "")}`;
+  return null;
+}
+async function runAccountsMenu(ui, call, session) {
+  for (; ; ) {
+    const overview = await call("accounts.list");
+    const rows = accountRows(overview, session);
+    const options = [...rows.map((row2) => row2.label), ADD, POOLS, CHECK_ALL, DONE];
+    const picked = await ui.select("Accounts", options);
+    if (!picked || picked === DONE) return;
+    if (picked === ADD) {
+      await addAccount(ui, call);
+      continue;
+    }
+    if (picked === POOLS) {
+      await poolsMenu(ui, call);
+      continue;
+    }
+    if (picked === CHECK_ALL) {
+      await attempt(ui, () => call("accounts.refresh"));
+      continue;
+    }
+    const row = rows[options.indexOf(picked)];
+    if (!row) continue;
+    if (await accountMenu(ui, call, session, row.account.id) === "relaunch") return "relaunch";
+  }
+}
+async function addAccount(ui, call) {
+  const label = await ui.input("Name for the new account", "Work, Personal, \u2026");
+  if (!label?.trim()) return;
+  if (await attempt(ui, () => call("accounts.create", { label: label.trim(), authKind: "subscription" }))) ui.notify("Account added. Sign in to use it.", "info");
+}
+async function accountMenu(ui, call, session, accountId) {
+  const isSession = session.accountId === accountId;
+  for (; ; ) {
+    const overview = await call("accounts.list");
+    const account = overview.accounts.find((candidate) => candidate.id === accountId);
+    if (!account) return;
+    const actions = [
+      ...isSession ? [] : [USE_HERE],
+      ...account.isDefault ? [] : [MAKE_DEFAULT],
+      RENAME,
+      CHECK,
+      DETAILS,
+      ACTIVITY,
+      SIGN_IN,
+      ...account.state.piProviders.length ? [REMOVE_PROVIDER] : [],
+      SIGN_OUT,
+      // The session's own account is in use, so it cannot be removed from inside the session.
+      ...isSession ? [] : [REMOVE],
+      BACK
+    ];
+    const action = await ui.select(`${account.label} \xB7 ${HEALTH[account.state.health] ?? HEALTH.unknown}`, actions);
+    if (!action || action === BACK) return;
+    if (action === USE_HERE) {
+      if (!await ui.confirm("Switch this session?", `This ends the terminal's Pi process and resumes the conversation on ${account.label}. Work in progress stops.`)) continue;
+      if (await attempt(ui, () => call("accounts.relaunch", { accountId }))) {
+        ui.notify(`Switching to ${account.label}.`, "info");
+        return "relaunch";
+      }
+    } else if (action === MAKE_DEFAULT) {
+      if (await attempt(ui, () => call("accounts.setDefault", { accountId }))) ui.notify(`${account.label} is the default for new sessions.`, "info");
+    } else if (action === RENAME) {
+      const label = await ui.input("New name", account.label);
+      if (label?.trim()) await attempt(ui, () => call("accounts.rename", { accountId, label: label.trim() }));
+    } else if (action === CHECK) {
+      if (await attempt(ui, () => call("accounts.refresh", { accountId }))) ui.notify("Checked.", "info");
+    } else if (action === DETAILS) {
+      await ui.select(accountDetails(account), [BACK]);
+    } else if (action === ACTIVITY) {
+      await showActivity(ui, call, accountId, account.label);
+    } else if (action === SIGN_IN) {
+      await signIn(ui, call, account);
+    } else if (action === REMOVE_PROVIDER) {
+      const provider = await ui.select("Remove which provider?", [...account.state.piProviders, BACK]);
+      if (!provider || provider === BACK) continue;
+      if (await ui.confirm(`Remove ${provider}?`, `The stored ${provider} sign-in for ${account.label} is deleted from this device.`)) await attempt(ui, () => call("accounts.removeProvider", { accountId, provider }));
+    } else if (action === SIGN_OUT) {
+      if (await ui.confirm(`Sign out of ${account.label}?`, "Stored sign-ins are deleted. The account stays, so you can sign in again.")) await attempt(ui, () => call("accounts.signOut", { accountId }));
+    } else if (action === REMOVE) {
+      const last = overview.accounts.length === 1;
+      const consequence = last ? "This is the only account. New sessions will ask you to add one." : account.isDefault ? "New sessions will use another account." : "Sessions pinned to it will ask for another account next time they start.";
+      if (!await ui.confirm(`Remove ${account.label}?`, `Its stored sign-in and its runtime folder are deleted. ${consequence}`)) continue;
+      if (await attempt(ui, () => call("accounts.remove", { accountId }))) ui.notify(`${account.label} was removed.`, "info");
+      return;
+    }
+  }
+}
+async function showActivity(ui, call, accountId, label) {
+  const entries = await call("accounts.audit", { accountId, limit: 30 });
+  const lines2 = entries.map((entry) => `${new Date(entry.at).toLocaleString()} \xB7 ${entry.action} \xB7 ${entry.detail}`);
+  await ui.select(`${label}: activity
+${lines2.join("\n") || "Nothing has happened here yet."}`, [BACK]);
+}
+async function signIn(ui, call, account) {
+  const providers = await call("accounts.providers");
+  if (!providers.length) {
+    ui.notify("No provider here can be signed in to.", "warning");
+    return;
+  }
+  const labels = providers.map((provider2, index2) => `${index2 + 1}. ${provider2.name}${account.state.piProviders.includes(provider2.id) ? " \xB7 signed in" : ""}`);
+  const pickedLabel = await ui.select(`Sign in ${account.label} to which provider?`, [...labels, BACK]);
+  const index = labels.indexOf(pickedLabel ?? "");
+  const provider = providers[index];
+  if (!provider) return;
+  const methods = [...provider.oauth ? [provider.oauthLabel ?? "Sign in with the browser"] : [], ...provider.apiKey ? ["Enter an API key"] : []];
+  if (!methods.length) {
+    ui.notify(`${provider.name} has no sign-in from a terminal.`, "warning");
+    return;
+  }
+  const method = methods.length === 1 ? methods[0] : await ui.select(`${provider.name}: how to sign in`, [...methods, BACK]);
+  if (!method || method === BACK) return;
+  if (method === "Enter an API key") {
+    const key = await ui.input(`API key for ${provider.name}`, "Paste the key");
+    if (!key?.trim()) return;
+    if (await attempt(ui, () => call("accounts.setApiKey", { accountId: account.id, provider: provider.id, key: key.trim() }))) ui.notify(`Key saved for ${provider.name}.`, "info");
+    return;
+  }
+  await runLogin(ui, call, account.id, provider.id);
+}
+async function runLogin(ui, call, accountId, provider) {
+  let loginId;
+  try {
+    loginId = (await call("accounts.loginStart", { accountId, provider })).loginId;
+  } catch (error) {
+    ui.notify(message(error), "error");
+    return;
+  }
+  return followLogin(ui, call, accountId, loginId);
+}
+async function followLogin(ui, call, accountId, loginId) {
+  const deadline = Date.now() + LOGIN_TIMEOUT_MS;
+  let shownRevision = -1;
+  for (; ; ) {
+    const snapshot = await call("accounts.loginStatus", { accountId });
+    if (!snapshot || snapshot.loginId !== loginId) return;
+    if (snapshot.status !== "running") return reportLogin(ui, snapshot);
+    if (snapshot.prompt) {
+      await answerPrompt(ui, call, loginId, snapshot.prompt);
+      continue;
+    }
+    const step = [...snapshot.events].reverse().map(loginStep).find((text3) => text3 !== null);
+    if (step && snapshot.revision !== shownRevision) {
+      shownRevision = snapshot.revision;
+      const choice = await ui.select(`${step}
+
+Finish in your browser, then choose Check status.`, [CHECK_STATUS, CANCEL_SIGN_IN]);
+      if (choice === CANCEL_SIGN_IN) {
+        await call("accounts.loginCancel", { accountId, loginId });
+        ui.notify("Sign-in cancelled.", "warning");
+        return;
+      }
+      continue;
+    }
+    if (Date.now() > deadline) {
+      await call("accounts.loginCancel", { accountId, loginId });
+      ui.notify("Sign-in timed out and was cancelled.", "error");
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, POLL_MS));
+  }
+}
+function reportLogin(ui, snapshot) {
+  if (snapshot.status === "completed") ui.notify("Signed in.", "info");
+  else if (snapshot.status === "cancelled") ui.notify("Sign-in was cancelled.", "warning");
+  else ui.notify(snapshot.error ?? "Sign-in failed.", "error");
+}
+async function answerPrompt(ui, call, loginId, prompt) {
+  const promptId = String(prompt.promptId ?? "");
+  const detail = prompt.prompt ?? {};
+  const text3 = detail.message ?? "Sign-in needs an answer.";
+  let value;
+  if (detail.type === "select" && Array.isArray(detail.options)) {
+    if (detail.options.every((option) => typeof option === "string")) {
+      value = await ui.select(text3, detail.options);
+    } else if (detail.options.every((option) => typeof option === "object" && option !== null && "id" in option && typeof option.id === "string" && "label" in option && typeof option.label === "string")) {
+      const options = detail.options;
+      const selected = await ui.select(text3, options.map((option) => option.label));
+      value = options.find((option) => option.label === selected)?.id;
+    }
+  } else {
+    value = await ui.input(text3, detail.placeholder ?? void 0);
+  }
+  await call("accounts.loginRespond", { loginId, promptId, value: value ?? null });
+}
+async function poolsMenu(ui, call) {
+  for (; ; ) {
+    const overview = await call("accounts.list");
+    const names = new Map(overview.accounts.map((account) => [account.id, account.label]));
+    const labels = overview.pools.map((pool2, index) => `${index + 1}. ${pool2.label} \xB7 ${pool2.accountIds.map((id) => names.get(id) ?? "removed account").join(" \u2192 ")}`);
+    const options = [NEW_POOL, ...labels, BACK];
+    const picked = await ui.select("Pools: new sessions use the first ready account in a pool, in this order", options);
+    if (!picked || picked === BACK) return;
+    if (picked === NEW_POOL) {
+      await editPool(ui, call, overview, null);
+      continue;
+    }
+    const pool = overview.pools[options.indexOf(picked) - 1];
+    if (!pool) continue;
+    const action = await ui.select(pool.label, [EDIT, DELETE, BACK]);
+    if (action === EDIT) await editPool(ui, call, overview, pool);
+    else if (action === DELETE && await ui.confirm(`Delete ${pool.label}?`, "The accounts stay. Only the pool is removed.")) await attempt(ui, () => call("accounts.removePool", { poolId: pool.id }));
+  }
+}
+async function editPool(ui, call, overview, pool) {
+  const label = await ui.input("Pool name", pool?.label);
+  if (!label?.trim()) return;
+  const names = new Map(overview.accounts.map((account) => [account.id, account.label]));
+  const order = [...pool?.accountIds ?? []];
+  for (; ; ) {
+    const ordered = order.map((id, index) => `${index + 1}. ${names.get(id) ?? "removed account"}`).join("  ");
+    const free = overview.accounts.filter((account) => !order.includes(account.id));
+    const addOptions = free.map((account) => `Add ${account.label}`);
+    const options = [...addOptions, ...order.length ? [REMOVE_LAST, START_OVER] : [], SAVE_POOL, CANCEL];
+    const picked = await ui.select(`${label.trim()}: ${ordered || "no accounts yet"}`, options);
+    if (!picked || picked === CANCEL) return;
+    if (picked === SAVE_POOL) {
+      if (!order.length) {
+        ui.notify("A pool needs at least one account.", "error");
+        continue;
+      }
+      if (await attempt(ui, () => call("accounts.savePool", { pool: { id: pool?.id, label: label.trim(), accountIds: order } }))) ui.notify("Pool saved.", "info");
+      return;
+    }
+    if (picked === START_OVER) order.length = 0;
+    else if (picked === REMOVE_LAST) order.pop();
+    else {
+      const account = free[addOptions.indexOf(picked)];
+      if (account) order.push(account.id);
+    }
+  }
+}
+
 // src/terminal/pluginMenu.ts
 var here = (attachment, projectId) => {
   if (projectId && attachment.on.projectIds.includes(projectId)) return true;
@@ -90,8 +407,8 @@ var SWITCH_OFF_EVERYWHERE = "Switch off everywhere";
 var SWITCH_ON_EVERYWHERE = "Switch on everywhere";
 var TRUST = "Trust its code";
 var UNTRUST = "Stop trusting its code";
-var BACK = "Back";
-var DONE = "Done";
+var BACK2 = "Back";
+var DONE2 = "Done";
 function rowActions(row, projectId) {
   const switchable = row.whole ? row.plugin.attachment !== null : true;
   const actions = [];
@@ -100,7 +417,7 @@ function rowActions(row, projectId) {
     actions.push(row.on ? SWITCH_OFF_EVERYWHERE : SWITCH_ON_EVERYWHERE);
   }
   if (row.whole && row.plugin.code) actions.push(row.plugin.trust === "untrusted" ? TRUST : UNTRUST);
-  return [...actions, BACK];
+  return [...actions, BACK2];
 }
 async function runPluginsMenu(ui, call, projectId) {
   let changed = false;
@@ -110,11 +427,11 @@ async function runPluginsMenu(ui, call, projectId) {
       ui.notify("There is nothing to switch or trust here yet.", "info");
       return;
     }
-    const picked = await ui.select(`Plugins${changed ? " (changes apply when this session restarts)" : ""}`, [...rows.map((row2) => row2.label), DONE]);
+    const picked = await ui.select(`Plugins${changed ? " (changes apply when this session restarts)" : ""}`, [...rows.map((row2) => row2.label), DONE2]);
     const row = rows.find((candidate) => candidate.label === picked);
     if (!row) break;
     const action = await ui.select(`${row.plugin.title}: ${row.plugin.description || "No description."}`, rowActions(row, projectId));
-    if (!action || action === BACK) continue;
+    if (!action || action === BACK2) continue;
     try {
       if (action === TRUST || action === UNTRUST) {
         const code = row.plugin.code;
@@ -137,15 +454,414 @@ Fingerprint ${code.hash.slice(0, 12)}. It runs inside the session and can do any
   if (changed) ui.notify("Saved. It applies when this session restarts.", "info");
 }
 
+// src/terminal/hubMenu.ts
+async function runHubMenu(ui, call) {
+  for (; ; ) {
+    const catalog = await call("hub.list");
+    const labels = catalog.entries.map((entry2) => `${entry2.title} \xB7 ${entry2.category} \xB7 ${entry2.id}@${entry2.version}`);
+    const picked = await ui.select("Hub", [...labels, "Refresh catalog", "Done"]);
+    if (picked === "Refresh catalog") {
+      const refreshed = await call("hub.list", { refresh: true });
+      if (refreshed.error) ui.notify(`${refreshed.error} Using ${refreshed.origin} content.`, "warning");
+      continue;
+    }
+    const entry = catalog.entries[labels.indexOf(picked ?? "")];
+    if (!entry) return;
+    const summary = `${entry.description}
+
+Publisher: ${entry.publisher}
+License: ${entry.license}
+Source: ${entry.sourceUrl}
+
+${entry.delivery.kind === "document" ? "Saved as data for a compatible application. Nothing is created or enabled." : "Installed switched off. Code remains untrusted and approvals remain unchanged."}`;
+    if (!await ui.confirm(`Install ${entry.title} ${entry.version}?`, summary)) continue;
+    try {
+      const receipt = await call("hub.install", { id: entry.id, version: entry.version });
+      ui.notify(receipt.document ? "Saved in this library for a compatible application." : "Installed, switched off. Use /plugins to review and attach it. Changes apply after restarting the session.", "info");
+    } catch (error) {
+      ui.notify(error instanceof Error ? error.message : String(error), "error");
+    }
+  }
+}
+
+// src/terminal/control.ts
+var claims = /* @__PURE__ */ new Map();
+function claimTerminalControl(connection = connectionFromEnv()) {
+  const identity = JSON.stringify([connection.socket, connection.token]);
+  let claim = claims.get(identity);
+  if (!claim) {
+    claim = socketCall(connection, "control.claim", {}, 15e3).then(({ key }) => {
+      if (!key) throw new Error("The terminal controller returned no control key.");
+      return key;
+    });
+    claims.set(identity, claim);
+  }
+  return claim;
+}
+async function controlCall(call, params = {}, timeoutMs = 12e4) {
+  const connection = connectionFromEnv();
+  const control = await claimTerminalControl(connection);
+  return socketCall(connection, call, params, timeoutMs, control);
+}
+
+// src/sessions/contracts.ts
+import { z } from "zod";
+var runStatusSchema = z.enum(["queued", "running", "waiting_for_approval", "waiting_for_input", "interrupted", "completed", "failed"]);
+var runEventTypeSchema = z.enum([
+  "started",
+  "context.snapshot",
+  "message.delta",
+  "message.completed",
+  "message.steered",
+  "tool.started",
+  "tool.completed",
+  "retry.started",
+  "retry.ended",
+  "compaction.started",
+  "compaction.ended",
+  "approval.requested",
+  "approval.resolved",
+  "question.requested",
+  "question.answered",
+  "extension.notice",
+  "reaction.added",
+  "agent.message",
+  "artifact.added",
+  "file.changed",
+  "usage.updated",
+  "account.status",
+  "status.changed",
+  "failed",
+  "completed"
+]);
+var messageDeltaPayload = z.object({ messageId: z.string(), text: z.string() });
+var messageCompletedPayload = z.object({ messageId: z.string(), role: z.enum(["user", "assistant"]), text: z.string() });
+var messageSteeredPayload = z.object({ text: z.string() });
+var contextSnapshotPayload = z.object({
+  systemPrompt: z.string().max(1e5),
+  contextUpdate: z.string().max(1e5).optional(),
+  tools: z.array(z.object({ name: z.string(), description: z.string().max(2e3), parameters: z.unknown() })).max(120),
+  systemPromptTruncated: z.boolean().optional(),
+  contextUpdateTruncated: z.boolean().optional(),
+  toolsTruncated: z.boolean().optional()
+});
+var toolAttachmentRefSchema = z.object({
+  id: z.string().min(1).max(300),
+  name: z.string().min(1).max(500),
+  mimeType: z.string().min(1).max(100)
+}).strict();
+var toolAttachmentRefsSchema = z.array(toolAttachmentRefSchema).max(16);
+var toolPayload = z.object({
+  toolCallId: z.string(),
+  name: z.string(),
+  summary: z.string().max(200).optional(),
+  input: z.string().max(24e3).optional(),
+  inputTruncated: z.boolean().optional(),
+  output: z.string().max(24e3).optional(),
+  outputTruncated: z.boolean().optional(),
+  ok: z.boolean().optional(),
+  /** On `tool.completed`: how long the call ran, and the size of what it returned to the model. */
+  durationMs: z.number().optional(),
+  resultChars: z.number().optional(),
+  /** Opaque attachment references. Content stays outside the run event stream. */
+  attachments: toolAttachmentRefsSchema.optional()
+});
+var retryStartedPayload = z.object({ attempt: z.number(), maxAttempts: z.number(), delayMs: z.number(), error: z.string().max(1e3).optional() });
+var retryEndedPayload = z.object({ attempt: z.number(), success: z.boolean(), error: z.string().max(1e3).optional() });
+var compactionStartedPayload = z.object({ reason: z.string() });
+var compactionEndedPayload = z.object({
+  reason: z.string(),
+  aborted: z.boolean(),
+  willRetry: z.boolean().optional(),
+  error: z.string().max(1e3).optional(),
+  tokensBefore: z.number().optional(),
+  tokensAfter: z.number().optional(),
+  summary: z.string().max(24e3).optional(),
+  summaryTruncated: z.boolean().optional()
+});
+var approvalAutomaticSchema = z.enum(["always", "remembered", "scope"]);
+var approvalRequestedPayload = z.object({
+  approvalId: z.string(),
+  target: z.string(),
+  action: z.string(),
+  screenshotRef: z.string().optional(),
+  operation: z.object({ tool: z.string(), args: z.unknown() }).optional(),
+  /** A tool the user may choose to always allow for this session. */
+  rememberable: z.boolean().optional(),
+  /** Set when the request was granted as it was made, so nobody is waiting on it. */
+  automatic: approvalAutomaticSchema.optional()
+});
+var approvalResolvedPayload = z.object({ approvalId: z.string(), decision: z.enum(["approved", "denied", "native"]), automatic: approvalAutomaticSchema.optional() });
+var questionOptionSchema = z.object({ label: z.string().min(1), description: z.string().optional() });
+var questionBatchFields = {
+  batchId: z.string().min(1).optional(),
+  batchIndex: z.number().int().min(1).max(5).optional(),
+  batchCount: z.number().int().min(1).max(5).optional()
+};
+var questionBatchRefinement = (value, context) => {
+  const fields = [value.batchId, value.batchIndex, value.batchCount];
+  if (fields.some((field) => field !== void 0) && fields.some((field) => field === void 0)) {
+    context.addIssue({ code: z.ZodIssueCode.custom, message: "Question batch fields must be supplied together." });
+  }
+  if (value.batchIndex !== void 0 && value.batchCount !== void 0 && value.batchIndex > value.batchCount) {
+    context.addIssue({ code: z.ZodIssueCode.custom, message: "Question batch index cannot exceed its count." });
+  }
+};
+var questionRequestedPayload = z.object({
+  questionId: z.string(),
+  question: z.string().min(1),
+  summary: z.string().min(1).max(100).optional(),
+  options: z.array(questionOptionSchema),
+  multiSelect: z.boolean(),
+  allowText: z.boolean(),
+  userOnly: z.boolean().optional(),
+  ...questionBatchFields
+}).superRefine(questionBatchRefinement);
+var questionAnsweredPayload = z.object({
+  questionId: z.string(),
+  selected: z.array(z.string()),
+  text: z.string().optional(),
+  notes: z.record(z.string(), z.string().max(1e4)).optional(),
+  ...questionBatchFields
+}).superRefine(questionBatchRefinement);
+var reactionAddedPayload = z.object({ emoji: z.string().min(1).refine((text3) => Buffer.byteLength(text3) <= 16 && !/[A-Za-z0-9\s]/.test(text3)) });
+var agentMessagePayload = z.object({ direction: z.enum(["to", "from"]), agentId: z.string(), agentName: z.string(), text: z.string() });
+var extensionNoticePayload = z.object({
+  kind: z.enum(["notify", "status", "widget", "title", "error"]),
+  level: z.enum(["info", "warning", "error"]).optional(),
+  key: z.string().optional(),
+  text: z.string(),
+  extension: z.string().optional()
+});
+var artifactPayload = z.object({ artifactId: z.string(), name: z.string(), file: z.unknown().optional() });
+var fileChangedPayload = z.object({ path: z.string(), change: z.enum(["added", "modified", "deleted"]) });
+var costSourceSchema = z.enum(["harness", "estimate", "mixed"]);
+var usageRequestSchema = z.object({
+  /** Position in the run, from 1. */
+  index: z.number(),
+  responseId: z.string().optional(),
+  model: z.string().optional(),
+  provider: z.string().optional(),
+  inputTokens: z.number().optional(),
+  cacheReadTokens: z.number().optional(),
+  cacheWriteTokens: z.number().optional(),
+  outputTokens: z.number().optional(),
+  reasoningTokens: z.number().optional(),
+  costUsd: z.number().optional(),
+  costSource: z.enum(["harness", "estimate"]).optional(),
+  /** Separate provider-supplied summary; never generic private thinking content. */
+  reasoningSummary: z.string().max(4e3).optional(),
+  /** From sending the request to the end of the response, and to its first output. */
+  durationMs: z.number().optional(),
+  ttftMs: z.number().optional(),
+  stopReason: z.string().optional()
+});
+var usagePayloadSchema = z.object({
+  /** Input tokens that were not read from the provider's cache. */
+  inputTokens: z.number().optional(),
+  /** Includes reasoning tokens. */
+  outputTokens: z.number().optional(),
+  cacheReadTokens: z.number().optional(),
+  cacheWriteTokens: z.number().optional(),
+  reasoningTokens: z.number().optional(),
+  costUsd: z.number().optional(),
+  costSource: costSourceSchema.optional(),
+  /** Model requests made so far. */
+  requests: z.number().optional(),
+  /** Size of the latest request (not cumulative), and the model's limit. */
+  contextTokens: z.number().optional(),
+  contextWindow: z.number().optional(),
+  model: z.string().optional(),
+  provider: z.string().optional(),
+  /** The request this update reports. */
+  request: usageRequestSchema.optional()
+});
+var accountIssueCategorySchema = z.enum(["auth_expired", "rate_limited", "quota", "network", "unknown"]);
+var accountLimitSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  usedPercent: z.number().nullable().optional(),
+  resetsAt: z.string().nullable().optional(),
+  windowMinutes: z.number().nullable().optional(),
+  status: z.string().nullable().optional()
+});
+var accountStatusPayload = z.object({
+  accountId: z.string(),
+  category: accountIssueCategorySchema.optional(),
+  message: z.string().optional(),
+  resetsAt: z.string().optional(),
+  plan: z.string().optional(),
+  limits: z.array(accountLimitSchema).optional()
+});
+var statusPayload = z.object({ status: runStatusSchema, reason: z.string().optional() });
+var failedPayload = z.object({ code: z.string(), message: z.string() });
+var emptyPayload = z.object({}).passthrough();
+var runEventPayloadSchemas = {
+  started: emptyPayload,
+  "context.snapshot": contextSnapshotPayload,
+  "message.delta": messageDeltaPayload,
+  "message.completed": messageCompletedPayload,
+  "message.steered": messageSteeredPayload,
+  "tool.started": toolPayload,
+  "tool.completed": toolPayload,
+  "retry.started": retryStartedPayload,
+  "retry.ended": retryEndedPayload,
+  "compaction.started": compactionStartedPayload,
+  "compaction.ended": compactionEndedPayload,
+  "approval.requested": approvalRequestedPayload,
+  "approval.resolved": approvalResolvedPayload,
+  "question.requested": questionRequestedPayload,
+  "question.answered": questionAnsweredPayload,
+  "extension.notice": extensionNoticePayload,
+  "reaction.added": reactionAddedPayload,
+  "agent.message": agentMessagePayload,
+  "artifact.added": artifactPayload,
+  "file.changed": fileChangedPayload,
+  "usage.updated": usagePayloadSchema,
+  "account.status": accountStatusPayload,
+  "status.changed": statusPayload,
+  failed: failedPayload,
+  completed: emptyPayload
+};
+var runEventSchema = z.object({
+  id: z.string(),
+  runId: z.string(),
+  sessionId: z.string(),
+  sequence: z.number().int().nonnegative(),
+  timestamp: z.string(),
+  type: runEventTypeSchema,
+  payload: z.unknown(),
+  /** The native event this one was derived from, kept as evidence. */
+  native: z.unknown().optional(),
+  /** Set when consecutive text deltas were merged for relay; covers sequences coalescedFrom..sequence. */
+  coalescedFrom: z.number().int().nonnegative().optional()
+}).superRefine((event, context) => {
+  if (!runEventPayloadSchemas[event.type].safeParse(event.payload).success) {
+    context.addIssue({ code: "custom", path: ["payload"], message: `Invalid payload for ${event.type}` });
+  }
+});
+var text = z.string().nullish().transform((value) => value ?? null);
+var runRecordSchema = z.object({
+  resumedFromRunId: text,
+  parentRunId: text,
+  relation: text,
+  terminalReason: text,
+  id: z.string(),
+  projectId: text,
+  mode: z.string(),
+  harness: z.string(),
+  sessionType: z.string(),
+  sessionId: z.string(),
+  nativeSessionId: text,
+  workingDirectory: text,
+  worktreeId: text,
+  goal: text,
+  attachmentCount: z.number().int().nonnegative().default(0),
+  startedAt: z.string(),
+  endedAt: text,
+  status: z.string(),
+  exitCode: z.number().int().nullish().transform((value) => value ?? null),
+  handoffId: text,
+  accountId: text,
+  agentId: text,
+  trigger: text
+});
+
+// src/core/index.ts
+import { DatabaseSync } from "node:sqlite";
+
+// src/sessions/subagents.ts
+var SUBAGENT_RECEIPT = "xingularSubagents";
+var SUBAGENT_OWNER = "xingular-subagent-owner";
+var SUBAGENT_RESULTS = "xingular-subagent-results";
+function subagentHistory(entries) {
+  const owners = [];
+  const receipts = [];
+  for (const raw of entries) {
+    if (!raw || typeof raw !== "object") continue;
+    const entry = raw;
+    if (entry.type === "custom" && entry.customType === SUBAGENT_OWNER && typeof entry.data?.runId === "string") owners.push(entry.data.runId);
+    const message2 = entry.type === "message" ? entry.message : entry;
+    const receipt = message2?.details?.[SUBAGENT_RECEIPT];
+    if (!receipt || receipt.version !== 1 || typeof receipt.ownerRunId !== "string") continue;
+    const strings = (value) => Array.isArray(value) && value.every((id) => typeof id === "string");
+    if (receipt.spawned !== void 0 && !strings(receipt.spawned) || receipt.delivered !== void 0 && !strings(receipt.delivered)) continue;
+    receipts.push(receipt);
+  }
+  return { owners, receipts };
+}
+
+// src/tools/askUser.ts
+var ASK_USER = "ask_user";
+var MAX_OPTIONS = 6;
+var text2 = (value) => typeof value === "string" ? value.trim() : "";
+function describeAnswer(answer) {
+  const parts = [];
+  if (answer.selected.length) parts.push(`The user chose: ${answer.selected.join(", ")}.`);
+  if (answer.text) parts.push(answer.selected.length ? `They added: ${answer.text}` : `The user answered: ${answer.text}`);
+  for (const [choice, note] of Object.entries(answer.notes ?? {})) parts.push(`Their note for ${choice}: ${note}`);
+  return parts.join(" ") || "The user did not answer.";
+}
+function askUserTool(run2) {
+  return {
+    name: ASK_USER,
+    label: "Ask the user",
+    description: "Ask the user one to five related questions in one request and wait until they answer the batch. Give each question a concise 2\u20133 word summary and aim to keep each question to 25 words or fewer. Offer up to 6 short options when the choices are clear; every option must include a helpful description of 25 words or fewer. Every question includes a free-text \u201CSomething else\u201D answer. Set multiSelect when several can apply. Use it when you need a decision, not for small talk.",
+    parameters: (Type2) => Type2.Object({
+      questions: Type2.Array(Type2.Object({
+        summary: Type2.String({ description: "A concise 2\u20133 word summary label" }),
+        question: Type2.String({ description: "A clear, standalone question; aim for 25 words or fewer" }),
+        options: Type2.Optional(
+          Type2.Array(Type2.Object({
+            label: Type2.String({ description: "A short choice" }),
+            description: Type2.String({ description: "Required. Briefly explain this choice in 25 words or fewer." })
+          }), { maxItems: MAX_OPTIONS })
+        ),
+        multiSelect: Type2.Optional(Type2.Boolean())
+      }), { minItems: 1, maxItems: 5 })
+    }),
+    execute: async (input) => {
+      if (!Array.isArray(input.questions) || input.questions.length < 1 || input.questions.length > 5) return "Ask between one and five questions.";
+      const questions = input.questions.map((raw) => {
+        const item = raw;
+        const summary = text2(item.summary);
+        const question = text2(item.question);
+        const options = (Array.isArray(item.options) ? item.options : []).map((option) => ({ label: text2(option.label), description: text2(option.description) })).filter((option) => option.label).slice(0, MAX_OPTIONS);
+        return { summary, question, options, multiSelect: options.length > 1 && item.multiSelect === true, allowText: true };
+      });
+      if (questions.some((question) => !question.summary || question.summary.length > 100)) return "Each question needs a short summary of no more than 100 characters.";
+      if (questions.some((question) => !question.question)) return "Every question needs a question sentence.";
+      if (questions.some((question) => question.options.some((option) => !option.description))) return "Every choice needs a short description. Aim for 25 words or fewer.";
+      const answers = await run2.requestAnswers(questions);
+      return questions.map((question, index) => `${question.summary}: ${describeAnswer(answers[index])}`).join("\n");
+    }
+  };
+}
+
 // src/terminal/piExtension.ts
 function resultSize(result) {
   const content = result?.content;
   if (!Array.isArray(content)) return typeof result === "string" ? result.length : null;
   return content.reduce((total, part) => total + (part?.type === "text" && typeof part.text === "string" ? part.text.length : 0), 0);
 }
+async function withParentCancellation(signal, work) {
+  const stop = () => {
+    void controlCall("terminal.interrupt").catch(() => {
+    });
+  };
+  if (signal?.aborted) stop();
+  signal?.addEventListener("abort", stop, { once: true });
+  try {
+    return await work();
+  } finally {
+    signal?.removeEventListener("abort", stop);
+  }
+}
 async function piExtension_default(pi) {
   await terminalCall("startup", { phase: "Pi extension loaded" });
   let context = null;
+  let nativeSubagents = false;
+  let subagentParent = false;
   let timer = null;
   let polling = false;
   let failure;
@@ -160,19 +876,48 @@ async function piExtension_default(pi) {
   try {
     await terminalCall("startup", { phase: stage });
     const connection = connectionFromEnv();
-    const control = await socketCall(connection, "control.claim", {}, 15e3).then((claimed) => claimed.key).catch(() => null);
+    const control = await claimTerminalControl(connection).catch(() => null);
+    pi.registerCommand("hub", {
+      description: "Browse and install reviewed skills, plugins, and reusable documents",
+      handler: async (_args, ctx) => {
+        if (!control) return ctx.ui.notify("This session cannot install hub items.", "warning");
+        await runHubMenu(
+          { select: (title, options) => ctx.ui.select(title, options), confirm: (title, message2) => ctx.ui.confirm(title, message2), notify: (message2, level) => ctx.ui.notify(message2, level) },
+          (method, params) => socketCall(connection, method, params ?? {}, 3e5, control)
+        );
+      }
+    });
     pi.registerCommand("plugins", {
       description: "See what this session loads, and switch a plugin on or off or trust its code",
       handler: async (_args, ctx) => {
         if (!control) return ctx.ui.notify("This session cannot change plugins.", "warning");
         const { projectId } = await socketCall(connection, "plugins.session", {}, 15e3, control).catch(() => ({ projectId: null }));
         await runPluginsMenu(
-          { select: (title, options) => ctx.ui.select(title, options), confirm: (title, message) => ctx.ui.confirm(title, message), notify: (message, level) => ctx.ui.notify(message, level) },
+          { select: (title, options) => ctx.ui.select(title, options), confirm: (title, message2) => ctx.ui.confirm(title, message2), notify: (message2, level) => ctx.ui.notify(message2, level) },
           (method, params) => socketCall(connection, method, params ?? {}, 6e4, control),
           projectId
         );
       }
     });
+    pi.registerCommand("accounts", {
+      description: "Add, sign in to, check, switch, or remove the Pi accounts this harness uses",
+      handler: async (_args, ctx) => {
+        if (!control) return ctx.ui.notify("This session cannot manage accounts.", "warning");
+        const session = await socketCall(connection, "accounts.session", {}, 15e3, control).catch(() => null);
+        if (!session) return ctx.ui.notify("This session has no account to manage.", "warning");
+        const outcome = await runAccountsMenu(
+          {
+            select: (title, options) => ctx.ui.select(title, options),
+            confirm: (title, message2) => ctx.ui.confirm(title, message2),
+            input: (title, placeholder) => ctx.ui.input(title, placeholder),
+            notify: (message2, level) => ctx.ui.notify(message2, level)
+          },
+          (method, params) => socketCall(connection, method, params ?? {}, 12e4, control),
+          session
+        );
+        if (outcome === "relaunch") ctx.shutdown();
+      }
+    });
     const { tools } = await socketCall(connection, "tools.list", {}, 15e3);
     stage = "Tool registration";
     for (const tool of tools) {
@@ -187,6 +932,18 @@ async function piExtension_default(pi) {
         }
       });
     }
+    const native = await controlCall("terminal.subagents.tools");
+    nativeSubagents = native.tools.length > 0;
+    for (const tool of native.tools) pi.registerTool({
+      name: tool.name,
+      label: tool.label,
+      description: tool.description,
+      parameters: Type.Unsafe(tool.parameters),
+      execute: async (_id, input, signal) => {
+        const result = await withParentCancellation(signal, () => controlCall("terminal.subagents.call", { name: tool.name, input }, 2147483647));
+        return { content: [{ type: "text", text: result.text }], details: result.details ?? {} };
+      }
+    });
   } catch (error) {
     await terminalCall("startupFailed", { reason: `${stage} failed: ${error instanceof Error ? error.message : "Unavailable"}` }).catch(() => {
     });
@@ -194,6 +951,7 @@ async function piExtension_default(pi) {
   }
   pi.on("session_start", async (_event, ctx) => {
     context = ctx;
+    if (timer) clearInterval(timer);
     await terminalCall("ready", { nativeSessionId: ctx.sessionManager.getSessionFile() });
     timer = setInterval(() => {
       if (polling || !context) return;
@@ -218,13 +976,26 @@ async function piExtension_default(pi) {
     usage = emptyUsage();
     reasoningTokens = void 0;
     costReported = false;
-    await terminalCall("begin", { text: event.messageType === "user" ? event.prompt : "" });
+    const begun = await terminalCall("begin", { text: event.messageType === "user" ? event.prompt : "" });
+    if (nativeSubagents) {
+      pi.appendEntry(SUBAGENT_OWNER, { runId: begun.runId });
+      await controlCall("terminal.subagents.register", { tools: pi.getActiveTools(), model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : null, effort: pi.getThinkingLevel(), history: subagentHistory(ctx.sessionManager.getBranch()) });
+      subagentParent = true;
+    }
   });
+  const deliverChildren = async (event, ctx, settle) => {
+    if (!nativeSubagents || settle && event.outcome !== "completed" || ctx.signal?.aborted) return;
+    const result = await withParentCancellation(ctx.signal, () => controlCall("terminal.subagents.delivery", { history: subagentHistory([...ctx.sessionManager.getBranch(), ...event.entries]), settle }, 2147483647));
+    if (!result) return;
+    return { entries: [...event.entries, { type: "custom_message", customType: SUBAGENT_RESULTS, content: result.text, display: false, details: { [SUBAGENT_RECEIPT]: result.receipt } }], continue: true };
+  };
+  pi.on("turn_end", (event, ctx) => deliverChildren(event, ctx, false));
+  pi.on("agent_before_settle", (event, ctx) => deliverChildren(event, ctx, true));
   pi.on("message_end", async (event) => {
     if (event.message.role !== "assistant") return;
     if (event.message.stopReason === "error" || event.message.stopReason === "aborted") failure = event.message.errorMessage ?? `Pi stopped: ${event.message.stopReason}`;
-    const text = event.message.content.filter((part) => part.type === "text").map((part) => part.text).join("\n");
-    if (text) await terminalCall("message", { text });
+    const text3 = event.message.content.filter((part) => part.type === "text").map((part) => part.text).join("\n");
+    if (text3) await terminalCall("message", { text: text3 });
     if (event.message.usage) {
       const reported = event.message.usage;
       usage.inputTokens += reported.input ?? 0;
@@ -269,9 +1040,9 @@ async function piExtension_default(pi) {
   });
   pi.on("tool_call", async (event) => {
     try {
-      const policy = await terminalCall("policy", { tool: event.toolName, args: event.input });
+      const policy = await controlCall("terminal.policy", { tool: event.toolName, args: event.input });
       if (policy.requiresApproval) {
-        const approval = await terminalCall("approval", { requestId: event.toolCallId, target: event.toolName, action: JSON.stringify(event.input), tool: event.toolName, args: event.input });
+        const approval = await controlCall("terminal.approval", { requestId: event.toolCallId, tool: event.toolName, args: event.input });
         if (approval.decision === "approved") return;
         return { block: true, reason: "The user denied this action. Ask how they would like to proceed." };
       }
@@ -294,17 +1065,38 @@ async function piExtension_default(pi) {
     fileTools.delete(event.toolCallId);
     if (!event.isError && path) await terminalCall("file", { path, change: "modified" });
   });
-  pi.on("agent_settled", async () => {
-    await terminalCall("settled", { error: failure });
+  pi.on("agent_settled", async (event, ctx) => {
+    if (subagentParent && !event.aborted && !failure) {
+      try {
+        await controlCall("terminal.subagents.verify", { history: subagentHistory(ctx.sessionManager.getBranch()) }, 2147483647);
+      } catch (error) {
+        failure = error instanceof Error ? error.message : String(error);
+      }
+    }
+    subagentParent = false;
+    await terminalCall("settled", { error: failure, aborted: event.aborted });
   });
   pi.on("user_bash", async () => {
     throw new Error("Use the bash tool so this action can be checked.");
   });
   pi.on("session_shutdown", async () => {
     if (timer) clearInterval(timer);
+    timer = null;
+    context = null;
     await terminalCall("shutdown").catch(() => {
     });
   });
+  const ask = askUserTool({ requestAnswers: (questions) => terminalCall("questions", { questions }, 123e4) });
+  pi.registerTool({
+    name: ask.name,
+    label: ask.label,
+    description: ask.description,
+    parameters: Type.Unsafe(ask.parameters(Type)),
+    async execute(_id, input) {
+      const result = await ask.execute(input);
+      return { content: [{ type: "text", text: typeof result === "string" ? result : result.text }], details: void 0 };
+    }
+  });
   pi.registerTool({
     name: "ask_user_question",
     label: "Ask a question",