@preapexis/piexis 0.2.2 → 0.2.4

package/tests/ask-question.test.mjs

@@ -0,0 +1,269 @@
+import assert from "node:assert/strict";
+import { EventEmitter, getEventListeners } from "node:events";
+import test from "node:test";
+import { visibleWidth } from "@earendil-works/pi-tui";
+import askQuestion from "../extensions/ask-question.ts";
+import { normalizeQuestions, initialDraft, validateAnswer } from "../lib/question-model.ts";
+import { QuestionScreen } from "../lib/question-ui.ts";
+
+const theme = { fg: (_color, text) => text };
+const keys = { up: "\x1b[A", down: "\x1b[B", enter: "\r", escape: "\x1b", tab: "\t", backtab: "\x1b[Z", space: " ", ctrlC: "\x03" };
+const question = (patch = {}) => normalizeQuestions({ questions: [{ question: "Which?", options: [{ id: "a", label: "A", description: "First choice" }, { id: "b", label: "B" }], ...patch }] })[0];
+const draft = (indices, patch = {}) => ({ indices, text: "", custom: false, ...patch });
+
+function screen(questions = [question()], signal) {
+  const stream = new EventEmitter();
+  let completions = 0, result;
+  let resolve;
+  const promise = new Promise((done) => { resolve = done; });
+  const component = new QuestionScreen(questions, { requestRender() {}, terminal: { rows: 24 } }, theme, (value) => {
+    completions++;
+    result = value;
+    resolve(value);
+  }, signal, stream);
+  component.focused = true;
+  return { component, stream, promise, get result() { return result; }, get completions() { return completions; } };
+}
+
+function send(ui, ...inputs) { inputs.forEach((key) => ui.component.handleInput(keys[key] ?? key)); }
+
+for (const [name, indices] of [["invalid", [999]], ["mixed valid/invalid", [0, 999]], ["malformed", ["1"]], ["fractional", [0.5]], ["negative", [-1]]]) {
+  test(`rejects ${name} selections without discarding values`, () => {
+    assert.throws(() => validateAnswer(question({ type: "multi" }), draft(indices)), /listed options/);
+  });
+}
+
+test("single and multi validation, deterministic duplicate removal, min/max limits", () => {
+  assert.equal(validateAnswer(question(), draft([1])).answer, "B");
+  const multi = question({ type: "multi" });
+  assert.deepEqual(validateAnswer(multi, draft([1, 0, 1])).optionIds, ["a", "b"]);
+  assert.deepEqual(validateAnswer(multi, draft([1, 0, 1])).answer, ["A", "B"]);
+  assert.throws(() => validateAnswer(question(), draft([])), /at least 1/);
+  assert.throws(() => validateAnswer(question({ type: "multi", minSelections: 0 }), draft([])), /at least 1/);
+  assert.throws(() => validateAnswer(question({ type: "multi", minSelections: 2 }), draft([0])), /at least 2/);
+  assert.throws(() => validateAnswer(question({ type: "multi", maxSelections: 1 }), draft([0, 1])), /at most 1/);
+  assert.equal(validateAnswer(question({ required: false }), draft([])).answer, "");
+});
+
+test("custom text is explicit, untrimmed, Unicode-aware and never parsed as numbers", () => {
+  const q = question({ allowOther: true, maxLength: 20 });
+  for (const text of ["1, 999", "1, hello", "  café 🦊 & <>  "]) {
+    assert.equal(validateAnswer(q, draft([], { custom: true, text })).answer, text);
+  }
+  assert.throws(() => validateAnswer(q, draft([], { custom: true, text: "  " })), /required/);
+  assert.throws(() => validateAnswer(question(), draft([], { custom: true, text: "A" })), /not enabled/);
+  assert.throws(() => validateAnswer(q, draft([], { custom: true, text: "x".repeat(21) })), /at most 20/);
+  assert.equal(validateAnswer(question({ type: "text", options: [], required: false }), draft([], { custom: true, text: "" })).answer, "");
+  assert.equal(validateAnswer(question({ allowOther: true, maxLength: 1 }), draft([], { custom: true, text: "🦊" })).answer, "🦊");
+});
+
+test("normalization preserves legacy calls and rejects unusable contracts", () => {
+  assert.equal(question({ multiSelect: true }).type, "multi");
+  assert.equal(question({ options: [], allowOther: true }).type, "text");
+  assert.equal(question({ options: [], multiSelect: true, allowOther: true }).type, "text");
+  assert.deepEqual(initialDraft(question({ defaultSelection: "b" })).indices, [1]);
+  for (const patch of [
+    { options: [] }, { type: "single", options: [] }, { type: "text" },
+    { defaultSelection: "unknown" }, { defaultSelection: ["a", "b"] },
+    { type: "multi", minSelections: 2, maxSelections: 1 },
+    { type: "multi", maxSelections: 3 }, { type: "single", multiSelect: true },
+    { options: [{ id: "a", label: "A" }, { id: "a", label: "B" }] }
+  ]) assert.throws(() => question(patch));
+  assert.throws(() => normalizeQuestions({ questions: [] }));
+  assert.throws(() => normalizeQuestions({ questions: [{ ...question(), id: "same" }, { ...question(), id: "same" }] }));
+});
+
+test("arrow navigation, description rendering, default focus and Enter", async () => {
+  const ui = screen([question({ defaultSelection: "b" })]);
+  assert.match(ui.component.render(80).join("\n"), /❯ 2\. B/);
+  send(ui, "up");
+  assert.match(ui.component.render(80).join("\n"), /❯ 1\. A\n     First choice/);
+  send(ui, "down", "enter");
+  assert.equal((await ui.promise).answers[0].answer, "B");
+  assert.equal(ui.stream.listenerCount("end"), 0);
+  assert.equal(ui.stream.listenerCount("close"), 0);
+});
+
+test("Space toggles multi selections; errors retain screen and allow retry", async () => {
+  const ui = screen([question({ type: "multi", minSelections: 2 })]);
+  send(ui, "space", "enter");
+  assert.equal(ui.result, undefined);
+  assert.match(ui.component.render(80).join("\n"), /at least 2/);
+  assert.match(ui.component.render(80).join("\n"), /❯ \[x\] 1\. A/);
+  send(ui, "space", "space", "down", "space", "enter");
+  assert.deepEqual((await ui.promise).answers[0].optionIds, ["a", "b"]);
+  const max = screen([question({ type: "multi", maxSelections: 1 })]);
+  send(max, "space", "down", "space", "enter");
+  assert.match(max.component.render(80).join("\n"), /at most 1/);
+  send(max, "space", "enter");
+  assert.deepEqual((await max.promise).answers[0].optionIds, ["a"]);
+});
+
+test("Other label collisions cannot activate text; Other is enabled only explicitly", async () => {
+  for (const allowOther of [false, true]) {
+    const ui = screen([question({ allowOther, options: [{ id: "other", label: "Other — type your own answer" }, { id: "__other__", label: "Type something else" }] })]);
+    send(ui, "enter");
+    assert.equal((await ui.promise).answers[0].custom, false);
+    assert.equal(ui.result.answers[0].answer, "Other — type your own answer");
+  }
+  const ui = screen([question({ allowOther: true })]);
+  send(ui, "down", "down", "enter", "enter");
+  assert.match(ui.component.render(80).join("\n"), /An answer is required/);
+  send(ui, "1, 999 café 🦊", "enter");
+  assert.equal((await ui.promise).answers[0].answer, "1, 999 café 🦊");
+  assert.equal(ui.result.answers[0].custom, true);
+});
+
+test("text required/optional, optional single skip, and maximum text length", async () => {
+  const ui = screen([question({ type: "text", options: [], maxLength: 3 })]);
+  send(ui, "  ", "enter");
+  assert.equal(ui.result, undefined);
+  send(ui, "abcd", "enter");
+  assert.match(ui.component.render(80).join("\n"), /at most 3/);
+  send(ui, "escape");
+  assert.equal((await ui.promise).status, "cancelled");
+  const optional = screen([question({ type: "text", options: [], required: false })]);
+  send(optional, "enter");
+  assert.equal((await optional.promise).answers[0].answer, "");
+  assert.equal(optional.result.status, "answered");
+  const skip = screen([question({ required: false })]);
+  send(skip, "up", "enter");
+  assert.equal((await skip.promise).answers[0].answer, "");
+});
+
+test("Tab navigation preserves text and selections; review requires every confirmation", async () => {
+  const ui = screen([question(), { ...question({ type: "text", options: [] }), id: "second" }]);
+  send(ui, "down", "enter", "hello", "backtab");
+  assert.match(ui.component.render(80).join("\n"), /Question 1\/2/);
+  send(ui, "tab");
+  assert.match(ui.component.render(80).join("\n"), /hello/);
+  send(ui, "tab", "enter");
+  assert.match(ui.component.render(80).join("\n"), /Confirm this question/);
+  send(ui, "enter");
+  assert.match(ui.component.render(80).join("\n"), /Review answers/);
+  send(ui, "enter");
+  assert.deepEqual((await ui.promise).answers.map((a) => a.answer), ["B", "hello"]);
+});
+
+test("abort before render, pending abort, both submit/abort races, listener cleanup", async () => {
+  for (const order of ["before", "pending", "submit-first", "abort-first"]) {
+    const controller = new AbortController();
+    if (order === "before") controller.abort();
+    const ui = screen(undefined, controller.signal);
+    if (order === "submit-first") send(ui, "enter");
+    controller.abort();
+    send(ui, "enter");
+    const result = await ui.promise;
+    assert.equal(result.status, order === "submit-first" ? "answered" : "aborted");
+    assert.equal(ui.completions, 1);
+    assert.equal(getEventListeners(controller.signal, "abort").length, 0);
+    assert.equal(ui.stream.listenerCount("end"), 0);
+    assert.deepEqual(ui.component.render(80), []);
+  }
+});
+
+test("Esc/Ctrl+C cancellation and unexpected input closure always settle", async () => {
+  for (const key of ["escape", "ctrlC"]) {
+    const ui = screen();
+    send(ui, key);
+    assert.equal((await ui.promise).status, "cancelled");
+  }
+  for (const event of ["end", "close", "error"]) {
+    const ui = screen();
+    ui.stream.emit(event, new Error("broken input"));
+    assert.equal((await ui.promise).status, "error");
+    assert.equal(ui.stream.listenerCount(event), 0);
+  }
+});
+
+test("narrow terminals, long menus and untrusted labels render safely", () => {
+  const ui = screen([question({ question: "Very long question 🦊", options: Array.from({ length: 50 }, (_, i) => ({ label: `Choice ${i}\x1b[2J` })) })]);
+  for (const width of [1, 8, 20, 80]) {
+    const lines = ui.component.render(width);
+    assert.ok(lines.every((line) => visibleWidth(line) <= width));
+    assert.ok(lines.length < 24);
+    assert.ok(lines.every((line) => !line.includes("\x1b[2J")));
+  }
+  send(ui, "up");
+  assert.match(ui.component.render(80).join("\n"), /❯ 50\. Choice 49/);
+  send(ui, "escape");
+});
+
+test("render/input failures settle rather than leaving an active question", async () => {
+  let result;
+  const stream = new EventEmitter();
+  const ui = new QuestionScreen([question()], { requestRender() { throw new Error("render unavailable"); }, terminal: { rows: 24 } }, theme, (value) => { result = value; }, undefined, stream);
+  ui.handleInput(keys.down);
+  assert.equal(result.status, "error");
+  assert.equal(stream.listenerCount("end"), 0);
+  const badTheme = new QuestionScreen([question()], { requestRender() {}, terminal: { rows: 24 } }, { fg() { throw new Error("bad theme"); } }, (value) => { result = value; }, undefined, stream);
+  badTheme.render(80);
+  assert.equal(result.status, "error");
+});
+
+async function tty(work) {
+  const streams = [process.stdin, process.stdout];
+  const saved = streams.map((stream) => Object.getOwnPropertyDescriptor(stream, "isTTY"));
+  streams.forEach((stream) => Object.defineProperty(stream, "isTTY", { configurable: true, value: true }));
+  try { await work(); } finally {
+    streams.forEach((stream, i) => saved[i] ? Object.defineProperty(stream, "isTTY", saved[i]) : delete stream.isTTY);
+  }
+}
+
+function toolHarness() {
+  let tool, component, restorations = 0;
+  const handlers = new Map();
+  askQuestion({ registerTool(value) { tool = value; }, on(name, handler) { handlers.set(name, handler); } });
+  const ctx = { mode: "tui", hasUI: true, ui: { custom(factory) {
+    return new Promise((resolve) => {
+      component = factory({ requestRender() {}, terminal: { rows: 24 } }, theme, {}, (value) => { restorations++; resolve(value); });
+    });
+  } } };
+  const params = { questions: [{ question: "Which?", options: [{ label: "A" }] }] };
+  return { tool, ctx, params, handlers, get component() { return component; }, get restorations() { return restorations; } };
+}
+
+test("result renderer supports retained legacy sessions and missing details", () => {
+  const { tool } = toolHarness();
+  const old = { content: [], details: { answers: [{ question: "Which?", answer: "A" }], cancelled: false } };
+  assert.match(tool.renderResult(old, {}, theme).render(80).join("\n"), /✓ Which\?: A/);
+  assert.match(tool.renderResult({ content: [{ type: "text", text: "Original result" }] }, {}, theme).render(80).join("\n"), /Original result/);
+});
+
+test("tool protects non-TTY, legacy calls, concurrency, shutdown and failures", async () => {
+  const h = toolHarness();
+  assert.equal((await h.tool.execute("id", h.params, undefined, undefined, h.ctx)).details.status, "requires_interaction");
+  await tty(async () => {
+    for (const patch of [{ hasUI: false }, { mode: "json" }, { mode: "rpc" }]) {
+      assert.equal((await h.tool.execute("unavailable", h.params, undefined, undefined, { ...h.ctx, ...patch })).details.status, "requires_interaction");
+    }
+    const first = h.tool.execute("id", h.params, undefined, undefined, h.ctx);
+    const conflict = await h.tool.execute("second", h.params, undefined, undefined, h.ctx);
+    assert.equal(conflict.details.status, "error");
+    assert.match(conflict.details.error, /already active/);
+    h.component.handleInput(keys.enter);
+    const result = await first;
+    assert.equal(result.details.status, "answered");
+    assert.equal(result.details.answers[0].answer, "A");
+    assert.deepEqual(JSON.parse(result.content[0].text), result.details);
+    assert.equal(h.restorations, 1);
+    const pending = h.tool.execute("next", h.params, undefined, undefined, h.ctx);
+    await h.handlers.get("session_shutdown")();
+    assert.equal((await pending).details.status, "aborted");
+    const invalid = await h.tool.execute("bad", { questions: [] }, undefined, undefined, h.ctx);
+    assert.equal(invalid.details.status, "error");
+    const failed = await h.tool.execute("bad", h.params, undefined, undefined, { ...h.ctx, ui: { custom() { throw new Error("UI unavailable"); } } });
+    assert.equal(failed.details.status, "error");
+    const controller = new AbortController();
+    controller.abort();
+    const aborted = await h.tool.execute("aborted", h.params, controller.signal, undefined, h.ctx);
+    assert.equal(aborted.details.status, "aborted");
+    const runningController = new AbortController();
+    const running = h.tool.execute("agent-abort", h.params, runningController.signal, undefined, h.ctx);
+    runningController.abort();
+    assert.equal((await running).details.status, "aborted");
+    const waiting = h.tool.execute("waiting", h.params, undefined, undefined, h.ctx);
+    h.component.handleInput(keys.escape);
+    assert.equal((await waiting).details.status, "cancelled");
+  });
+});

package/tests/fixtures/agents-provider.ts

@@ -0,0 +1,55 @@
+// Deterministic, offline provider for the real CLI/subagent integration test.
+import { createAssistantMessageEventStream } from "@earendil-works/pi-ai";
+
+export default function (pi: any) {
+  pi.registerProvider("piexis-test", {
+    api: "piexis-test-api",
+    apiKey: "disposable-test-key",
+    baseUrl: "http://unused.invalid",
+    models: ["main", "small"].map((id) => ({
+      id, name: id, reasoning: true, input: ["text"], contextWindow: 32000, maxTokens: 1024,
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+    })),
+    streamSimple(model: any, context: any) {
+      const stream = createAssistantMessageEventStream();
+      queueMicrotask(() => {
+        const last = context.messages.at(-1);
+        const depth = Number(process.env.PIEXIS_SUBAGENT_DEPTH ?? 0);
+        const delegated = depth > 0;
+        const orchestration = !delegated && JSON.stringify(last?.content).includes("orchestrator");
+        const exploration = !delegated && JSON.stringify(last?.content).includes("exploration");
+        const orchestrator = /Piexis agent profile: orchestrator/.test(context.systemPrompt ?? JSON.stringify(context.messages.filter((message: any) => message.role === "system")));
+        const delegate = last?.role === "user" && (!delegated || (depth === 1 && orchestrator));
+        const content = delegate
+          ? [{ type: "toolCall", id: `delegate-${depth}`, name: "subagent", arguments: {
+            agent: orchestration ? "orchestrator" : "ask", ...(exploration ? { purpose: "explore" } : {}),
+            task: orchestration ? "Coordinate a configuration lookup" : "Locate the configuration loader",
+          } }]
+          : [{ type: "text", text: delegated
+            ? (orchestrator ? `orchestrated:${JSON.stringify(last?.content)}` : `child:${model.id};depth:${depth}`)
+            : "parent completed" }];
+        const message = {
+          role: "assistant", api: "piexis-test-api", provider: model.provider, model: model.id,
+          timestamp: Date.now(), content: [], stopReason: "pending",
+          usage: { input: 10, output: 5, cacheRead: 0, cacheWrite: 0, totalTokens: 15,
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
+        };
+        stream.push({ type: "start", partial: message });
+        message.content = content as any;
+        const block = content[0];
+        if (block.type === "toolCall") {
+          stream.push({ type: "toolcall_start", contentIndex: 0, partial: message });
+          stream.push({ type: "toolcall_end", contentIndex: 0, toolCall: block, partial: message });
+        } else {
+          stream.push({ type: "text_start", contentIndex: 0, partial: message });
+          stream.push({ type: "text_delta", contentIndex: 0, delta: block.text, partial: message });
+          stream.push({ type: "text_end", contentIndex: 0, content: block.text, partial: message });
+        }
+        message.stopReason = block.type === "toolCall" ? "toolUse" : "stop";
+        stream.push({ type: "done", reason: message.stopReason, message });
+        stream.end();
+      });
+      return stream;
+    },
+  });
+}

package/tests/fixtures/ask-question-pty.py

@@ -0,0 +1,91 @@
+"""Drive actual pi-tui keyboard input using only Python's standard library."""
+import errno
+import fcntl
+import json
+import os
+import pty
+import select
+import struct
+import subprocess
+import sys
+import termios
+import time
+
+fixture, scenario, node = sys.argv[1:]
+startup = scenario.startswith("setup-")
+ready_text = b"Piexis setup for this project?" if startup else b"Question 1/"
+master, slave = pty.openpty()
+fcntl.ioctl(slave, termios.TIOCSWINSZ, struct.pack("HHHH", 24, 72, 0, 0))
+before = termios.tcgetattr(slave)
+child = subprocess.Popen([node, fixture, scenario], stdin=slave, stdout=slave, stderr=slave,
+                         env={**os.environ, "TERM": "xterm-256color"})
+output = bytearray()
+
+def drain(wait=0.1):
+    if select.select([master], [], [], wait)[0]:
+        try:
+            output.extend(os.read(master, 65536))
+        except OSError as error:
+            if error.errno != errno.EIO:
+                raise
+
+actions = {
+    "single": [b"\x1b[B", b"\r"],
+    "multi": [b"\r", b" ", b"\x1b[B", b" ", b"\r"],
+    "text": [b"\r", "\x1b[200~1, 999 café 🦊 & <>\x1b[201~".encode(), b"\r"],
+    "other": [b"\x1b[B", b"\x1b[B", b"\r", b"1, 999", b"\r"],
+    "navigation": [b"\x1b[B", b"\r", b"hello", b"\x1b[Z", b"\t", b"\r", b"\r"],
+    "cancel": [b"\x1b"],
+    "ctrl-c": [b"\x03"],
+    "abort": [b"!"],
+    "setup-enable": [b"\x1b[B", b"\r"],
+    "setup-agent-upgrade": [b"\x1b[B", b"\r"],
+    "setup-not-now": [b"\r"],
+    "setup-disabled": [b"\x1b[B", b"\x1b[B", b"\r"],
+}
+try:
+    deadline = time.monotonic() + 8
+    while ready_text not in output and child.poll() is None and time.monotonic() < deadline:
+        drain()
+    if ready_text not in output:
+        raise AssertionError("Question did not render: " + output.decode(errors="replace"))
+    for action in actions[scenario]:
+        os.write(master, action)
+        end = time.monotonic() + 0.15
+        while time.monotonic() < end:
+            drain(0.03)
+    while child.poll() is None and time.monotonic() < deadline:
+        drain()
+    if child.poll() is None:
+        raise AssertionError("Terminal interaction did not settle")
+    drain()
+    assert child.returncode == 0, output.decode(errors="replace")
+    assert termios.tcgetattr(slave) == before, "Terminal attributes were not restored"
+    assert b"\x1b[?25h" in output, "Cursor was not restored"
+    decoded = output.decode(errors="replace")
+    result_line = decoded.split("RESULT:")[-1].splitlines()[0]
+    result = json.loads(result_line)
+    assert result["rawRestored"] and result["listenersRestored"] and result["restored"] == 1
+    if scenario in ("single", "navigation"):
+        assert result["answers"][0]["optionIds"] == ["b"]
+    if scenario == "multi":
+        assert "Choose at least 2" in decoded
+        assert result["answers"][0]["optionIds"] == ["a", "b"]
+        assert "[x]" in decoded
+    if scenario == "text":
+        assert "An answer is required" in decoded
+        assert result["answers"][0]["answer"] == "1, 999 café 🦊 & <>"
+    if scenario == "other":
+        assert result["answers"][0]["answer"] == "1, 999"
+        assert result["answers"][0]["custom"]
+    if scenario == "navigation":
+        assert result["answers"][1]["answer"] == "hello"
+    expected = "aborted" if scenario == "abort" else "cancelled" if scenario in ("cancel", "ctrl-c") else "answered"
+    assert result["status"] == expected, result
+    print(json.dumps({"scenario": scenario, "status": result["status"], "terminalRestored": True}))
+finally:
+    if child.poll() is None:
+        child.kill()
+    child.wait()
+    os.close(master)
+    os.close(slave)

package/tests/fixtures/ask-question-terminal.mjs

@@ -0,0 +1,69 @@
+import assert from "node:assert/strict";
+import { Input, ProcessTerminal, TuiMainScreen } from "@earendil-works/pi-tui";
+import askQuestion from "../../extensions/ask-question.ts";
+
+const scenario = process.argv[2];
+const controller = new AbortController();
+let tool;
+askQuestion({ on() {}, registerTool(value) { tool = value; } });
+const terminal = new ProcessTerminal();
+const tui = new TuiMainScreen(terminal, true);
+const editor = new Input();
+const originalRaw = !!process.stdin.isRaw;
+const originalDataListeners = process.stdin.listenerCount("data");
+const originalEndListeners = process.stdin.listenerCount("end");
+const theme = { fg: (_color, text) => text };
+let restored = 0;
+
+// Exercise the production component with Pi's real renderer/input transport.
+// This adapter mirrors ctx.ui.custom's editor restoration/completion contract.
+const ctx = { mode: "tui", hasUI: true, ui: { custom(factory) {
+  return new Promise((resolve) => {
+    let component;
+    let closed = false;
+    const done = (value) => {
+      if (closed) return;
+      closed = true;
+      tui.clear();
+      tui.addChild(editor);
+      tui.setFocus(editor);
+      tui.requestRender();
+      component?.dispose();
+      restored++;
+      resolve(value);
+    };
+    component = factory(tui, theme, {}, done);
+    if (!closed) {
+      tui.clear();
+      tui.addChild(component);
+      tui.setFocus(component);
+      tui.requestRender();
+    }
+  });
+} } };
+const options = [{ id: "a", label: "JWT Authentication", description: "Stateless tokens" }, { id: "b", label: "OAuth 2.0" }];
+let questions = [{ question: "Authentication method?", options }];
+if (scenario === "multi") questions[0] = { ...questions[0], multiSelect: true, minSelections: 2 };
+if (scenario === "text") questions = [{ question: "Your response?", type: "text", required: true }];
+if (scenario === "other") questions[0].allowOther = true;
+if (scenario === "navigation") questions.push({ question: "Your response?", type: "text" });
+const removeListener = tui.addInputListener((data) => {
+  if (data === "!") { controller.abort(); return { consume: true }; }
+});
+tui.addChild(editor);
+tui.setFocus(editor);
+tui.start();
+let details;
+try {
+  details = (await tool.execute("pty", { questions }, controller.signal, undefined, ctx)).details;
+  assert.equal(restored, 1);
+  assert.equal(tui.getFocusedComponent(), editor);
+  assert.equal(editor.focused, true);
+  assert.equal(process.stdin.listenerCount("end"), originalEndListeners);
+} finally {
+  removeListener();
+  tui.stop();
+}
+assert.equal(!!process.stdin.isRaw, originalRaw);
+assert.equal(process.stdin.listenerCount("data"), originalDataListeners);
+process.stdout.write(`\nRESULT:${JSON.stringify({ ...details, restored, rawRestored: true, listenersRestored: true })}\n`);

package/tests/fixtures/recommended-tools-terminal.mjs

@@ -0,0 +1,103 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { getEventListeners } from "node:events";
+import { ExtensionSelectorComponent, initTheme } from "@earendil-works/pi-coding-agent";
+import { Input, ProcessTerminal, TuiMainScreen } from "@earendil-works/pi-tui";
+import recommendedTools from "../../extensions/recommended-tools.ts";
+
+const scenario = process.argv[2];
+const root = await mkdtemp(join(tmpdir(), "piexis-setup-pty-"));
+const cwd = join(root, "project");
+await mkdir(cwd);
+process.env.PI_CODING_AGENT_DIR = join(root, "agent");
+initTheme("dark", false);
+const handlers = new Map();
+let active = ["read", "bash", "edit", "write", "AskQuestion"];
+if (scenario === "setup-agent-upgrade") {
+  active.push("grep", "find", "ls");
+  await mkdir(join(cwd, ".pi"));
+  await writeFile(join(cwd, ".pi", "settings.json"), JSON.stringify({
+    defaultTools: ["read", "bash", "edit", "write", "grep", "find", "ls"],
+    piexis: { recommendedTools: "enabled" }
+  }));
+}
+const available = ["read", "bash", "edit", "write", "grep", "find", "ls"].map((name) => ({ name, sourceInfo: { source: "builtin" } }));
+available.push({ name: "subagent", sourceInfo: { source: "extension" } });
+recommendedTools({
+  on(name, handler) { handlers.set(name, handler); },
+  getActiveTools: () => active,
+  getAllTools: () => available,
+  setActiveTools: (tools) => { active = tools; }
+});
+const originalRaw = !!process.stdin.isRaw;
+const originalListeners = process.stdin.listenerCount("data");
+const tui = new TuiMainScreen(new ProcessTerminal(), true);
+const editor = new Input();
+let restored = 0;
+const ctx = { cwd, mode: "tui", hasUI: true, model: { provider: "test", id: "default" }, isProjectTrusted: () => true, ui: {
+  notify() {},
+  select(title, options, { signal }) {
+    return new Promise((resolve) => {
+      let closed = false;
+      const finish = (value) => {
+        if (closed) return;
+        closed = true;
+        signal.removeEventListener("abort", abort);
+        selector.dispose();
+        tui.clear();
+        tui.addChild(editor);
+        tui.setFocus(editor);
+        tui.requestRender();
+        restored++;
+        resolve(value);
+      };
+      const abort = () => finish(undefined);
+      const selector = new ExtensionSelectorComponent(title, options, finish, () => finish(undefined));
+      signal.addEventListener("abort", abort, { once: true });
+      tui.clear();
+      tui.addChild(selector);
+      tui.setFocus(selector);
+      tui.requestRender();
+      if (signal.aborted) abort();
+    }).then((value) => {
+      assert.equal(getEventListeners(signal, "abort").length, 0);
+      return value;
+    });
+  }
+} };
+tui.addChild(editor);
+tui.setFocus(editor);
+tui.start();
+let saved;
+try {
+  await handlers.get("session_start")({}, ctx);
+  assert.equal(restored, 1);
+  assert.equal(tui.getFocusedComponent(), editor);
+  try { saved = JSON.parse(await readFile(join(cwd, ".pi", "settings.json"), "utf8")); }
+  catch (error) { if (error.code !== "ENOENT") throw error; }
+  if (scenario === "setup-enable" || scenario === "setup-agent-upgrade") {
+    assert.equal(saved.piexis.recommendedTools, "enabled");
+    assert.deepEqual(active, ["read", "bash", "edit", "write", "AskQuestion", "grep", "find", "ls"]);
+    const agentConfig = JSON.parse(await readFile(join(cwd, ".pi", "agent.json"), "utf8"));
+    assert.equal(agentConfig.model, "test/default");
+    assert.deepEqual(agentConfig.subagent_variant_overrides, {
+      plan: { model: "test/default", effort: "high" },
+      orchestrator: { model: "test/default", effort: "high" },
+      debug: { model: "test/default", effort: "high" },
+      ask: { model: "test/default", effort: "low" },
+      code: { model: "test/default", effort: "medium" },
+    });
+    if (scenario === "setup-agent-upgrade") assert.deepEqual(saved.defaultTools, ["read", "bash", "edit", "write", "grep", "find", "ls"]);
+  } else if (scenario === "setup-disabled") {
+    assert.deepEqual(saved, { piexis: { recommendedTools: "disabled", agentSetup: "disabled" } });
+  } else assert.equal(saved, undefined);
+  if (scenario !== "setup-enable" && scenario !== "setup-agent-upgrade") await assert.rejects(readFile(join(cwd, ".pi", "agent.json")), { code: "ENOENT" });
+} finally {
+  tui.stop();
+  await rm(root, { recursive: true, force: true });
+}
+assert.equal(!!process.stdin.isRaw, originalRaw);
+assert.equal(process.stdin.listenerCount("data"), originalListeners);
+process.stdout.write(`\nRESULT:${JSON.stringify({ status: "answered", restored, rawRestored: true, listenersRestored: true, scenario })}\n`);

package/tests/init-workflow.test.mjs

@@ -0,0 +1,31 @@
+import assert from "node:assert/strict";
+import { access, readFile } from "node:fs/promises";
+import test from "node:test";
+
+const root = new URL("../", import.meta.url);
+
+test("init writes skill workflow guidance without installing or granting permissions", async () => {
+  const prompt = await readFile(new URL("prompts/init.md", root), "utf8");
+  assert.match(prompt, /Include an \*\*Agent workflow\*\* section/);
+  for (const name of ["caveman", "grilling", "ponytail"]) {
+    assert.match(prompt, new RegExp(`\\*\\*${name}:\\*\\*`));
+    await access(new URL(`skills/${name}/SKILL.md`, root));
+  }
+  assert.match(prompt, /Read the matching `SKILL\.md`/);
+  assert.match(prompt, /otherwise ask in chat/);
+  assert.match(prompt, /Cancellation is not consent/);
+  assert.match(prompt, /not runtime enforcement or tool permissions/);
+  assert.match(prompt, /do not install anything during `\/init`/);
+  assert.match(prompt, /Only create or edit `AGENTS\.md`/);
+});
+
+test("bundled third-party skills retain provenance and licenses", async () => {
+  for (const name of ["caveman", "ponytail"]) {
+    await access(new URL(`skills/${name}/LICENSE`, root));
+    const notice = await readFile(new URL(`skills/${name}/NOTICE`, root), "utf8");
+    assert.match(notice, /https:\/\/github\.com\//);
+    assert.match(notice, /Commit: [a-f0-9]{40}/);
+  }
+  const caveman = await readFile(new URL("skills/caveman/SKILL.md", root), "utf8");
+  assert.doesNotMatch(caveman, /`(?:ultracave|megacave|\/caveman-compress)`/);
+});

package/tests/recommended-tools-pty.test.mjs

@@ -0,0 +1,16 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import test from "node:test";
+
+const python = spawnSync("python3", ["-c", "import pty, termios"], { encoding: "utf8" });
+const driver = fileURLToPath(new URL("fixtures/ask-question-pty.py", import.meta.url));
+const fixture = fileURLToPath(new URL("fixtures/recommended-tools-terminal.mjs", import.meta.url));
+
+for (const scenario of ["setup-enable", "setup-agent-upgrade", "setup-not-now", "setup-disabled"]) {
+  test(`real terminal startup: ${scenario}`, { skip: python.status !== 0 ? "Python/Unix PTY support unavailable" : false }, () => {
+    const result = spawnSync("python3", [driver, fixture, scenario, process.execPath], { encoding: "utf8", timeout: 12000 });
+    assert.equal(result.status, 0, result.stderr + result.stdout);
+    assert.equal(JSON.parse(result.stdout).terminalRestored, true);
+  });
+}