@xingular/harness 0.1.6 → 0.1.7

package/dist/terminal-pi.js

@@ -6,8 +6,8 @@ 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;
   }
 };
@@ -60,6 +60,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, now = Date.now()) {
+  const minutes = Math.round((Date.parse(resetsAt) - now) / 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 lines = [
+    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 lines.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 lines = entries.map((entry) => `${new Date(entry.at).toLocaleString()} \xB7 ${entry.action} \xB7 ${entry.detail}`);
+  await ui.select(`${label}: activity
+${lines.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((text2) => text2 !== 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 text2 = 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(text2, 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(text2, options.map((option) => option.label));
+      value = options.find((option) => option.label === selected)?.id;
+    }
+  } else {
+    value = await ui.input(text2, 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 +406,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 +416,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 +426,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,6 +453,98 @@ 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;
+}
+
+// src/tools/askUser.ts
+var ASK_USER = "ask_user";
+var MAX_OPTIONS = 6;
+var text = (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(run) {
+  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 = text(item.summary);
+        const question = text(item.question);
+        const options = (Array.isArray(item.options) ? item.options : []).map((option) => ({ label: text(option.label), description: text(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 run.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;
@@ -160,19 +568,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) {
@@ -194,6 +631,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;
@@ -223,8 +661,8 @@ async function piExtension_default(pi) {
   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 text2 = event.message.content.filter((part) => part.type === "text").map((part) => part.text).join("\n");
+    if (text2) await terminalCall("message", { text: text2 });
     if (event.message.usage) {
       const reported = event.message.usage;
       usage.inputTokens += reported.input ?? 0;
@@ -302,9 +740,22 @@ async function piExtension_default(pi) {
   });
   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",

package/docs/README.md

@@ -0,0 +1,12 @@
+# Harness documentation
+
+Current implementation: [Harness terminal frontend](terminal-tui.md). The package-level
+[README](../README.md) describes the embedding API, accounts, plugins, memory and storage.
+
+| ID | Record | Type | Status | Related |
+|---|---|---|---|---|
+| ADR-0001 | [Own the terminal frontend and keep Pi as the session runtime](decisions/ADR-0001-owned-terminal.md) | Decision | Accepted; working tree implementation | [Terminal architecture and evidence](terminal-tui.md) |
+
+Living reference pages describe checked source behavior. Accepted decisions record the choice;
+they do not establish publication or release. Evidence references on the terminal page identify
+the inspected upstream artifacts and bound the verification claims.

package/docs/decisions/ADR-0001-owned-terminal.md

@@ -0,0 +1,87 @@
+---
+id: ADR-0001
+title: Own the terminal frontend and keep Pi as the session runtime
+status: accepted
+created: 2026-10-17
+updated: 2026-10-17
+related: []
+supersedes: null
+superseded_by: null
+---
+
+# ADR-0001 — Own the terminal frontend and keep Pi as the session runtime
+
+## Context and decision drivers
+
+The requested terminal must reproduce the supported Oh My Pi presentation using capabilities
+Harness already has. An extension can replace a header, footer or editor, but Pi's
+`InteractiveMode` still owns transcript layout, command routing, focus and screen lifecycle.
+That arrangement cannot give Harness full control over those surfaces.
+
+The existing terminal boundary already provides isolated accounts, a compiled prompt, trusted
+resource selection, a session socket and controller, a final tool gate and one writer for run
+records. Retaining that boundary avoids a second authority for authentication or run state.
+
+## Decision
+
+Own the terminal application in `src/terminal/tui/` and run a persistent Pi SDK
+`AgentSessionRuntime` inside the prepared terminal child. Harness owns composition, editor and
+input routing, dialogs, overlays and built-in command dispatch. Pi owns model/tool execution
+and native history. The frontend binds the public extension UI contract in `tui` mode and may
+reuse public rich content components.
+
+Keep `TerminalAssets` and `Terminals.prepare/send/state/input/dispose` compatible. Preserve the
+socket/controller bridge and its final gate. Keep the private control claim in process memory
+across native session replacement, revalidate prepared resource trust before every load, and
+scope native resume/import to the terminal's original working folder. Put unavoidable Pi
+implementation imports in one adapter checked against the pinned 1.2.0 version.
+
+Use the shipped OMP 18.11.3 artifacts as the visual reference, with Harness identity and existing
+commands. [The living reference](../terminal-tui.md) records artifact digests, evidence and
+verification limits. [NOTICE.md](../../NOTICE.md) preserves the upstream MIT license.
+
+## Alternatives and rejection reasons
+
+- **Only install a presentation extension:** leaves the default interactive frontend in control
+  of transcript geometry, built-in commands and terminal lifecycle, contrary to the requested ownership.
+- **Call `sessions.run` for each prompt:** recreates and disposes the runtime per turn, losing
+  persistent plugin UI/queue state and overlapping terminal controller run accounting.
+- **Replace the execution stack with OMP:** changes tools, model/provider behavior and product
+  capabilities beyond the requested presentation migration.
+- **Fork Pi's complete interactive mode:** introduces a large second implementation of session
+  and terminal behavior, making upgrades and account/governance boundaries harder to review.
+
+## Consequences and risks
+
+Harness must maintain its own command routing, focus, keybindings and extension UI lifecycle.
+The small internal adapter is an explicit upgrade constraint. Native session format and
+account storage stay compatible; cross-folder navigation requires a freshly prepared scope.
+Changes to trusted plugin code require review and reopening the terminal.
+
+This record accepts the architectural choice. Implementation exists in the working tree;
+publication and exhaustive visual/provider/platform parity are not implied. The living page
+records passed focused tests and the pending controlled PTY verification result.
+
+## Implementation and evidence
+
+- [`TerminalApplication`](../../src/terminal/tui/application.ts) owns the screen and input lifecycle.
+- [`runtime.ts`](../../src/terminal/tui/runtime.ts) owns the persistent SDK adapter and scoped navigation.
+- [`piAdapter.ts`](../../src/terminal/tui/piAdapter.ts) contains pinned compatibility imports.
+- [`piExtension.ts`](../../src/terminal/piExtension.ts) retains gate/telemetry integration.
+- [`runtime.socket.test.ts`](../../src/terminal/tui/runtime.socket.test.ts) checks the real isolated SDK/socket boundary without a provider request.
+- [Reference identities, retained REA evidence and verification limits](../terminal-tui.md#verification-and-remaining-limits).
+
+## Verification follow-up — 2026-10-17
+
+The earlier pending-PTY statement above records the state when this decision was written.
+The [living reference](../terminal-tui.md#verification-and-remaining-limits) now records passed
+production PTY scenarios at all three planned sizes, 419 Harness tests, a standalone proof and
+portable OMP/Harness comparison records. The implementation also scopes retained plugin UI
+callbacks and transcript components to a native resource generation, provides frozen runtime
+state, and submits grouped question answers through the existing registry atomically.
+
+The personal Codex live attempt reached the provider but was rejected because its usage limit
+had been reached. The isolated credentials were deleted, the source sign-in remained unchanged,
+and terminal restoration passed; see the [live evidence](../evidence/terminal-2026-10-17-followup/live-codex/README.md).
+Successful live streaming/tool acceptance and App renderer acceptance remain open. This evidence
+does not establish a released package or exhaustive platform/visual parity.