@xynogen/pix-runtime 0.3.0 → 0.4.0

package/README.md

@@ -10,7 +10,7 @@ See `DESIGN.md` for the full contract.
 ## What it does
 
 - Versioned, sparse `pix.json` (`$version: 1`) — defaults resolve in code.
-- Typed sections: `collapse`, `pretty`, `optimizer`, `gate`.
+- Typed sections: `collapse`, `pretty`, `io`, `optimizer`, `gate`.
 - Atomic writes behind a serialized in-process queue and a short-lived
   cross-process lock. A failed write leaves the old file intact.
 - Immutable, deeply frozen config snapshots with a monotonic revision.
@@ -38,8 +38,17 @@ import { prettySection } from "@xynogen/pix-runtime/sections";
 const icons = config(prettySection).icons;         // synchronous read
 await updateConfig(prettySection, { icons: "ascii" });
 const off = onConfigChange((c) => render(), { paths: ["pretty.icons"] });
+
+import { ioTimeoutMs, ioTimeoutSignal } from "@xynogen/pix-runtime/io";
+const timeoutMs = ioTimeoutMs();                    // shared network timeout
+const signal = ioTimeoutSignal(toolSignal);         // timeout + cancellation
 ```
 
+Set `io.timeoutSec` in `~/.pi/agent/pix.json`, or change **Network → timeout (sec)**
+with `/pix`. The default is 30 seconds. It applies to Pix network operations,
+including remote skills, web fetch/search/transcription, MCP requests and
+connection bootstrap, background model-data refreshes, and update downloads.
+
 Collapse policy helpers:
 
 ```ts

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@xynogen/pix-runtime",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"description": "Pix shared runtime — versioned pix.json config, atomic persistence, typed change events",
 	"type": "module",
 	"main": "src/index.ts",
@@ -24,6 +24,7 @@
 		"./config": "./src/runtime.ts",
 		"./sections": "./src/sections/index.ts",
 		"./collapse": "./src/collapse.ts",
+		"./io": "./src/io.ts",
 		"./once": "./src/once.ts",
 		"./testing": "./src/testing.ts"
 	},

package/src/index.ts

@@ -7,6 +7,7 @@ export type {
 	SubscribeOptions,
 } from "./events.ts";
 export { default } from "./extension.ts";
+export { ioTimeoutMs, ioTimeoutSignal } from "./io.ts";
 export {
 	config,
 	createRuntime,
@@ -34,6 +35,8 @@ export {
 	type GateConfig,
 	type GateRuleConfig,
 	gateSection,
+	type IoConfig,
+	ioSection,
 	type OptimizerConfig,
 	optimizerSection,
 	type PrettyConfig,

package/src/io.ts

@@ -0,0 +1,11 @@
+import { config } from "./runtime.ts";
+import { ioSection } from "./sections/io.ts";
+
+export function ioTimeoutMs(): number {
+	return config(ioSection).timeoutSec * 1000;
+}
+
+export function ioTimeoutSignal(signal?: AbortSignal): AbortSignal {
+	const timeout = AbortSignal.timeout(ioTimeoutMs());
+	return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}

package/src/pix-command.ts

@@ -7,11 +7,19 @@
  */
 
 import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
-import { matchesKey } from "@earendil-works/pi-tui";
+import {
+	Key,
+	type KeybindingsManager,
+	matchesKey,
+	truncateToWidth,
+	visibleWidth,
+	wrapTextWithAnsi,
+} from "@earendil-works/pi-tui";
 import type { PixRuntime } from "./runtime.ts";
 import type { DeepPartial, SectionHandle } from "./schema.ts";
 import { collapseSection } from "./sections/collapse.ts";
 import { gateSection } from "./sections/gate.ts";
+import { ioSection } from "./sections/io.ts";
 import { prettySection } from "./sections/pretty.ts";
 
 interface SettingRow<T> {
@@ -61,6 +69,14 @@ const SETTINGS: SettingRow<unknown>[] = [
 		read: (v) => String(v.delaySec),
 		patch: (value) => ({ delaySec: Number(value) }),
 	}),
+	row({
+		section: "Network",
+		label: "timeout (sec)",
+		handle: ioSection,
+		values: ["30", "10", "60", "120", "300"],
+		read: (v) => String(v.timeoutSec),
+		patch: (value) => ({ timeoutSec: Number(value) }),
+	}),
 	row({
 		section: "Gate",
 		label: "Guardrails",
@@ -104,16 +120,20 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 			const boxW = 52;
 			await ui.custom(
 				(
-					tui: { requestRender(): void },
+					tui: { requestRender(): void; terminal?: { rows?: number } },
 					theme: {
 						fg(c: string, t: string): string;
 						bg(c: string, t: string): string;
 						bold(t: string): string;
 					},
-					_kb: unknown,
+					kb: KeybindingsManager,
 					done: (v: null) => void,
 				) => {
 					let selected = 0;
+					let bodyOffset = 0;
+					let visibleBodyLines = 1;
+					let maxBodyOffset = 0;
+					let inspectingPage = false;
 
 					const cycle = (direction: -1 | 1) => {
 						const row = SETTINGS[selected];
@@ -126,18 +146,20 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 					};
 					const move = (direction: -1 | 1) => {
 						selected = (selected + direction + SETTINGS.length) % SETTINGS.length;
+						inspectingPage = false;
 					};
 
 					return {
 						render: () => {
 							const labelW = Math.max(...SETTINGS.map((r) => r.label.length));
-							const lines: string[] = [theme.fg("accent", theme.bold("  pix settings")), ""];
+							const body: string[] = [];
+							const settingBodyLines: number[] = [];
 							let lastSection = "";
 							for (let i = 0; i < SETTINGS.length; i++) {
 								const row = SETTINGS[i]!;
 								if (row.section !== lastSection) {
-									if (lastSection) lines.push("");
-									lines.push(theme.fg("dim", `  ${row.section}`));
+									if (lastSection) body.push("");
+									body.push(theme.fg("dim", `  ${row.section}`));
 									lastSection = row.section;
 								}
 								const sel = i === selected;
@@ -145,19 +167,40 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 								const label = theme.fg(sel ? "accent" : "text", row.label.padEnd(labelW));
 								const value = row.read(runtime.get(row.handle));
 								const isDefault = value === row.values[0];
-								lines.push(`${cursor} ${label}  ${theme.fg(isDefault ? "dim" : "success", value)}`);
+								settingBodyLines[i] = body.length;
+								body.push(`${cursor} ${label}  ${theme.fg(isDefault ? "dim" : "success", value)}`);
 							}
-							lines.push("");
-							lines.push(theme.fg("dim", "←→ change · ↑↓ move · esc close"));
-							return frameLines({
+							const result = frameModal({
 								width: boxW,
-								lines,
+								maxHeight: modalHeight(tui.terminal?.rows),
+								header: [theme.fg("accent", theme.bold("  pix settings")), ""],
+								body,
+								footer: [
+									"",
+									theme.fg("dim", "←→ change · ↑↓ move · PgUp/PgDn inspect · esc close"),
+								],
+								bodyOffset,
+								selectedBodyLine: inspectingPage ? undefined : settingBodyLines[selected],
 								color: (s: string) => theme.fg("accent", s),
 								bg: (s: string) => theme.bg("customMessageBg", s),
 							});
+							bodyOffset = result.bodyOffset;
+							visibleBodyLines = Math.max(1, result.visibleBodyLines);
+							maxBodyOffset = result.maxBodyOffset;
+							return result.lines;
 						},
 						invalidate: () => {},
 						handleInput: (data: string) => {
+							const pageUp = kb?.matches(data, "tui.select.pageUp") || matchesKey(data, Key.pageUp);
+							const pageDown =
+								kb?.matches(data, "tui.select.pageDown") || matchesKey(data, Key.pageDown);
+							if (pageUp || pageDown) {
+								const direction = pageUp ? -1 : 1;
+								bodyOffset = pageBodyOffset(bodyOffset, visibleBodyLines, maxBodyOffset, direction);
+								inspectingPage = true;
+								tui.requestRender();
+								return;
+							}
 							// matchesKey handles both legacy bytes and Kitty CSI-u encodings
 							// for letters and special keys alike — raw string compares like
 							// `data === "k"` silently fail under the Kitty keyboard protocol.
@@ -185,29 +228,96 @@ export function registerPixCommand(pi: ExtensionAPI, runtime: PixRuntime): void
 	});
 }
 
-// ── Inline frameLines (runtime must not depend on pix-pretty — pretty depends on us) ─
+// ── Inline modal engine (runtime cannot depend on pix-pretty: pretty depends on runtime) ─
 
-interface FrameOptions {
+interface RuntimeModalOptions {
 	width: number;
-	lines: string[];
+	maxHeight: number;
+	header: string[];
+	body: string[];
+	footer: string[];
+	bodyOffset: number;
+	selectedBodyLine?: number;
 	color: (s: string) => string;
 	bg?: (s: string) => string;
 }
 
-function visibleWidth(s: string): number {
-	// Strip ANSI escape sequences for width calculation.
-	return s.replace(/\x1b\[[0-9;]*m/g, "").length;
+interface RuntimeModalResult {
+	lines: string[];
+	bodyOffset: number;
+	visibleBodyLines: number;
+	maxBodyOffset: number;
+}
+
+function modalHeight(rows = 24): number {
+	const safe = Number.isFinite(rows) ? Math.max(1, Math.floor(rows)) : 24;
+	return Math.max(1, Math.min(safe, Math.floor(safe * 0.8)));
+}
+
+function pageBodyOffset(offset: number, size: number, max: number, direction: -1 | 1): number {
+	const s = Math.max(1, size);
+	const step = Math.max(1, Math.floor(s / 2));
+	return Math.min(max, Math.max(0, offset + direction * step));
+}
+
+function fitLines(lines: string[], width: number): string[] {
+	const rows: string[] = [];
+	for (const line of lines) {
+		if (line === "") rows.push("");
+		else rows.push(...wrapTextWithAnsi(line, Math.max(1, width)));
+	}
+	return rows;
 }
 
-/** Render a rounded bordered modal box (╭─╮╰─╯) with solid background fill. */
-function frameLines(opts: FrameOptions): string[] {
-	const { width, lines, color } = opts;
+function frameModal(opts: RuntimeModalOptions): RuntimeModalResult {
+	const inner = Math.max(1, opts.width - 4);
+	const header = fitLines(opts.header, inner);
+	const footer = fitLines(opts.footer, inner);
+	const body = fitLines(opts.body, inner);
+	const cap = Math.max(1, opts.maxHeight);
+	const bodyBudget = cap - 2 - header.length - footer.length;
+	const overflows = body.length > Math.max(0, bodyBudget);
+	const visibleBodyLines = overflows ? Math.max(0, bodyBudget - 1) : Math.max(0, bodyBudget);
+	if (visibleBodyLines === 0 && body.length > 0) {
+		return {
+			lines: frameRows(opts.width, ["Terminal too short — resize or press esc to cancel"], opts),
+			bodyOffset: 0,
+			visibleBodyLines: 0,
+			maxBodyOffset: 0,
+		};
+	}
+	const maxBodyOffset = Math.max(0, body.length - visibleBodyLines);
+	let offset = Math.min(maxBodyOffset, Math.max(0, opts.bodyOffset));
+	if (opts.selectedBodyLine !== undefined) {
+		const selected = Math.min(body.length - 1, Math.max(0, opts.selectedBodyLine));
+		if (selected < offset) offset = selected;
+		else if (selected >= offset + visibleBodyLines) offset = selected - visibleBodyLines + 1;
+	}
+	const end = Math.min(body.length, offset + visibleBodyLines);
+	const lines = [...header];
+	if (overflows) {
+		const step = Math.max(1, Math.floor(visibleBodyLines / 2));
+		const totalPages = Math.max(1, Math.ceil(maxBodyOffset / step) + 1);
+		const page = offset >= maxBodyOffset ? totalPages : Math.floor(offset / step) + 1;
+		lines.push(`PgUp/PgDn inspect • ${page}/${totalPages}`);
+	}
+	lines.push(...body.slice(offset, end), ...footer);
+	return {
+		lines: frameRows(opts.width, lines, opts),
+		bodyOffset: offset,
+		visibleBodyLines,
+		maxBodyOffset,
+	};
+}
+
+function frameRows(
+	width: number,
+	lines: string[],
+	opts: Pick<RuntimeModalOptions, "color" | "bg">,
+): string[] {
 	const bg = opts.bg ?? ((s: string) => s);
-	const inner = Math.max(1, width - 4); // 2 border + 2 padding
+	const inner = Math.max(1, width - 4);
 	const dashes = "─".repeat(width - 2);
-
-	// Re-assert the bg OPEN sequence after any full reset (\x1b[0m) or bg reset
-	// (\x1b[49m) embedded in themed content, so the fill has no transparent holes.
 	const SENTINEL = "\x00";
 	const bgOpen = bg(SENTINEL).split(SENTINEL)[0] ?? "";
 	const reassert = (s: string): string =>
@@ -216,15 +326,10 @@ function frameLines(opts: FrameOptions): string[] {
 					p === "0" || p.split(";").includes("49") ? `${seq}${bgOpen}` : seq,
 				)
 			: s;
-
 	const row = (content: string): string => {
-		const pad = inner - visibleWidth(content);
-		const padded = pad > 0 ? content + " ".repeat(pad) : content.slice(0, inner);
-		return bg(`${color("│")} ${reassert(padded)} ${color("│")}`);
+		const fitted = truncateToWidth(content, inner, "…");
+		const padded = fitted + " ".repeat(Math.max(0, inner - visibleWidth(fitted)));
+		return bg(`${opts.color("│")} ${reassert(padded)} ${opts.color("│")}`);
 	};
-
-	const out: string[] = [bg(color(`╭${dashes}╮`))];
-	for (const line of lines) out.push(row(line));
-	out.push(bg(color(`╰${dashes}╯`)));
-	return out;
+	return [bg(opts.color(`╭${dashes}╮`)), ...lines.map(row), bg(opts.color(`╰${dashes}╯`))];
 }

package/src/sections/index.ts

@@ -5,6 +5,7 @@ export {
 	type GateSeverity,
 	gateSection,
 } from "./gate.ts";
+export { type IoConfig, ioSection } from "./io.ts";
 export {
 	type CavemanLevel,
 	type OptimizerConfig,
@@ -22,6 +23,7 @@ export {
 
 import { collapseSection } from "./collapse.ts";
 import { gateSection } from "./gate.ts";
+import { ioSection } from "./io.ts";
 import { optimizerSection } from "./optimizer.ts";
 import { prettySection } from "./pretty.ts";
 
@@ -29,6 +31,7 @@ import { prettySection } from "./pretty.ts";
 export const builtinSections = [
 	collapseSection,
 	prettySection,
+	ioSection,
 	optimizerSection,
 	gateSection,
 ] as const;

package/src/sections/io.ts

@@ -0,0 +1,21 @@
+import { defineSection, isObj, posNumOr } from "../schema.ts";
+
+export interface IoConfig {
+	/** Default timeout in seconds for Pix network requests. */
+	timeoutSec: number;
+}
+
+const DEFAULTS: Readonly<IoConfig> = {
+	timeoutSec: 30,
+};
+
+export const ioSection = defineSection<"io", IoConfig>({
+	key: "io",
+	defaults: DEFAULTS,
+	parse(raw) {
+		if (!isObj(raw)) return { ...DEFAULTS };
+		return {
+			timeoutSec: posNumOr(raw.timeoutSec, DEFAULTS.timeoutSec),
+		};
+	},
+});