pi-async 0.0.0-stage → 0.1.0

package/src/core/watch.ts

@@ -0,0 +1,272 @@
+import type { Condition, WatchSpec } from "./task.ts";
+
+const compiledRegexes = new WeakMap<Condition, RegExp>();
+
+export function validateWatchSpec(spec: WatchSpec): { ok: true } | { ok: false; error: string } {
+  const invalid = (error: string) => ({ ok: false as const, error });
+  if (!spec || typeof spec !== "object") return invalid("watch must be an object");
+  if (!Number.isFinite(spec.intervalMs) || !Number.isInteger(spec.intervalMs) || spec.intervalMs < 1_000) {
+    return invalid("intervalMs must be an integer greater than or equal to 1000");
+  }
+  if (!Number.isFinite(spec.timeoutMs) || !Number.isInteger(spec.timeoutMs) || spec.timeoutMs <= 0) {
+    return invalid("timeoutMs must be a positive finite integer");
+  }
+  if (spec.blind_checks !== undefined &&
+      (!Number.isFinite(spec.blind_checks) || !Number.isInteger(spec.blind_checks) || spec.blind_checks < 1)) {
+    return invalid("blind_checks must be a positive integer");
+  }
+  if (!Array.isArray(spec.success_when) || !Array.isArray(spec.failure_when)) {
+    return invalid("success_when and failure_when must be arrays");
+  }
+
+  for (const [group, conditions] of [
+    ["success_when", spec.success_when],
+    ["failure_when", spec.failure_when],
+  ] as const) {
+    for (const [index, condition] of conditions.entries()) {
+      const location = `${group}[${index}]`;
+      if (!condition || typeof condition !== "object" || !("type" in condition)) {
+        return invalid(`${location} is invalid`);
+      }
+      switch (condition.type) {
+        case "exit_code":
+          if (!Number.isFinite(condition.equals)) return invalid(`${location}: equals must be finite`);
+          break;
+        case "stdout_contains":
+        case "stderr_contains":
+          if (typeof condition.value !== "string") return invalid(`${location}: value must be a string`);
+          break;
+        case "json_path_exists":
+          if (typeof condition.path !== "string" || parseJsonPath(condition.path) === undefined) {
+            return invalid(`${location}: invalid JSON path`);
+          }
+          break;
+        case "output_matches":
+          if (typeof condition.regex !== "string") return invalid(`${location}: regex must be a string`);
+          try {
+            compiledRegexes.set(condition, new RegExp(condition.regex));
+          } catch {
+            return invalid(`${location}: invalid regex`);
+          }
+          break;
+        default:
+          return invalid(`${location}: unknown condition type`);
+      }
+    }
+  }
+  return { ok: true };
+}
+
+export function evalConditions(conds: Condition[], ctx: { output: string; exitCode?: number }): boolean {
+  const result = evaluateConditionsDetailed(conds, ctx);
+  return result.status === "matched" && result.matched;
+}
+
+export interface WatchLoopDeps {
+  taskId: string;
+  spec: WatchSpec;
+  readOutput: () => string;
+  getExitCode: () => number | undefined;
+  onSuccess: (detail: string) => void;
+  onFailure: () => void;
+  onBlindExhausted: () => void;
+  onWatchTimeout: () => void;
+}
+
+export class WatchLoop {
+  private timer: ReturnType<typeof setTimeout> | undefined;
+  private stopped = true;
+  private finished = false;
+  private deadline = 0;
+  private blindCount = 0;
+  private readonly deps: WatchLoopDeps;
+
+  constructor(deps: WatchLoopDeps) {
+    this.deps = deps;
+  }
+
+  start(): void {
+    if (!this.stopped || this.finished) return;
+    this.stopped = false;
+    this.blindCount = 0;
+    this.deadline = Date.now() + this.deps.spec.timeoutMs;
+    this.check();
+  }
+
+  stop(): void {
+    this.stopped = true;
+    if (this.timer !== undefined) {
+      clearTimeout(this.timer);
+      this.timer = undefined;
+    }
+  }
+
+  private check(): void {
+    if (this.stopped) return;
+    if (Date.now() >= this.deadline) {
+      this.finish(this.deps.onWatchTimeout);
+      return;
+    }
+
+    const conditions = [...this.deps.spec.failure_when, ...this.deps.spec.success_when];
+    const needsOutput = conditions.some((condition) => condition.type !== "exit_code");
+    const needsExitCode = conditions.some((condition) => condition.type === "exit_code");
+    let output = "";
+    let exitCode: number | undefined;
+    try {
+      if (needsOutput) output = this.deps.readOutput();
+      if (needsExitCode) exitCode = this.deps.getExitCode();
+    } catch {
+      this.countBlindCheck();
+      return;
+    }
+
+    const ctx = { output, exitCode };
+    const failure = evaluateConditionsDetailed(this.deps.spec.failure_when, ctx);
+    if (failure.status === "matched" && failure.matched) {
+      this.finish(this.deps.onFailure);
+      return;
+    }
+    const success = evaluateConditionsDetailed(this.deps.spec.success_when, ctx);
+    if (success.status === "matched" && success.matched) {
+      const matched = success.condition;
+      this.finish(() => this.deps.onSuccess(`success_when matched: ${JSON.stringify(matched)}`));
+      return;
+    }
+
+    // Pending observations (e.g. a process still running or incomplete JSON output)
+    // are not infrastructure failures and must not consume the blind-check budget.
+    if (failure.status === "error" || success.status === "error") {
+      this.countBlindCheck();
+    } else {
+      this.blindCount = 0;
+      this.scheduleNext();
+    }
+  }
+
+  private countBlindCheck(): void {
+    this.blindCount++;
+    if (this.blindCount >= (this.deps.spec.blind_checks ?? 3)) {
+      this.finish(this.deps.onBlindExhausted);
+      return;
+    }
+    this.scheduleNext();
+  }
+
+  private scheduleNext(): void {
+    if (this.stopped) return;
+    const remaining = this.deadline - Date.now();
+    if (remaining <= 0) {
+      this.finish(this.deps.onWatchTimeout);
+      return;
+    }
+    this.timer = setTimeout(() => {
+      this.timer = undefined;
+      this.check();
+    }, Math.min(this.deps.spec.intervalMs, remaining));
+  }
+
+  private finish(callback: () => void): void {
+    this.finished = true;
+    this.stop();
+    callback();
+  }
+}
+
+type ConditionEvaluation =
+  | { status: "matched"; matched: boolean; condition?: Condition }
+  | { status: "pending" }
+  | { status: "error" };
+
+function evaluateConditionsDetailed(conditions: Condition[], ctx: { output: string; exitCode?: number }): ConditionEvaluation {
+  let pending = false;
+  let error = false;
+  for (const condition of conditions) {
+    const result = evaluateCondition(condition, ctx);
+    if (result.status === "matched" && result.matched) return { status: "matched", matched: true, condition };
+    if (result.status === "pending") pending = true;
+    if (result.status === "error") error = true;
+  }
+  if (error) return { status: "error" };
+  if (pending) return { status: "pending" };
+  return { status: "matched", matched: false };
+}
+
+function evaluateCondition(condition: Condition, ctx: { output: string; exitCode?: number }): ConditionEvaluation {
+  switch (condition.type) {
+    case "exit_code":
+      return ctx.exitCode === undefined
+        ? { status: "pending" }
+        : { status: "matched", matched: ctx.exitCode === condition.equals };
+    case "stdout_contains":
+    case "stderr_contains":
+      // The frozen WatchLoop context exposes the captured merged output stream.
+      return { status: "matched", matched: ctx.output.includes(condition.value) };
+    case "output_matches": {
+      let regex = compiledRegexes.get(condition);
+      if (!regex) {
+        try {
+          regex = new RegExp(condition.regex);
+          compiledRegexes.set(condition, regex);
+        } catch {
+          return { status: "error" };
+        }
+      }
+      // Global/sticky expressions otherwise retain lastIndex between watch polls.
+      regex.lastIndex = 0;
+      return { status: "matched", matched: regex.test(ctx.output) };
+    }
+    case "json_path_exists": {
+      let root: unknown;
+      try {
+        root = JSON.parse(ctx.output);
+      } catch {
+        return { status: "pending" };
+      }
+      const tokens = parseJsonPath(condition.path);
+      if (tokens === undefined) return { status: "error" };
+      let current = root;
+      for (const token of tokens) {
+        if (typeof token === "number") {
+          if (!Array.isArray(current) || token >= current.length) return { status: "matched", matched: false };
+          current = current[token];
+        } else {
+          if (current === null || typeof current !== "object" || !Object.hasOwn(current, token)) {
+            return { status: "matched", matched: false };
+          }
+          current = (current as Record<string, unknown>)[token];
+        }
+      }
+      return { status: "matched", matched: true };
+    }
+  }
+}
+
+function parseJsonPath(path: string): Array<string | number> | undefined {
+  if (!path.startsWith("$") || path.length === 0) return undefined;
+  const tokens: Array<string | number> = [];
+  let index = 1;
+  while (index < path.length) {
+    if (path[index] === ".") {
+      const start = ++index;
+      if (index >= path.length || !/[A-Za-z_$]/.test(path[index]!)) return undefined;
+      index++;
+      while (index < path.length && /[A-Za-z0-9_$-]/.test(path[index]!)) index++;
+      tokens.push(path.slice(start, index));
+      continue;
+    }
+    if (path[index] === "[") {
+      const end = path.indexOf("]", index + 1);
+      if (end < 0) return undefined;
+      const raw = path.slice(index + 1, end);
+      if (!/^\d+$/.test(raw)) return undefined;
+      const arrayIndex = Number(raw);
+      if (!Number.isSafeInteger(arrayIndex)) return undefined;
+      tokens.push(arrayIndex);
+      index = end + 1;
+      continue;
+    }
+    return undefined;
+  }
+  return tokens;
+}

package/src/guard/settle-guard.ts

@@ -0,0 +1,78 @@
+import type { PiCtx } from "../core/notify.ts";
+import type { TaskRegistry } from "../core/registry.ts";
+
+export class SettleGuard {
+  private readonly maxReminders: number;
+  private readonly heartbeatMs: number;
+  private reminders = 0;
+  private heartbeat?: ReturnType<typeof setInterval>;
+  private removeHooks: Array<() => void> = [];
+  private readonly pi: PiCtx;
+  private readonly registry: TaskRegistry;
+
+  constructor(pi: PiCtx, registry: TaskRegistry, opts?: { maxReminders?: number; heartbeatMs?: number }) {
+    this.pi = pi;
+    this.registry = registry;
+    this.maxReminders = opts?.maxReminders ?? 3;
+    this.heartbeatMs = opts?.heartbeatMs ?? finiteEnvNumber("PI_ASYNC_HEARTBEAT_MS", 60_000);
+  }
+
+  register(): void {
+    // SAFETY: PiCtx hooks vary by runtime; these optional operations are only invoked after presence checks.
+    const hooks = this.pi as unknown as {
+      on?: (event: string, handler: (...args: unknown[]) => unknown) => void;
+      off?: (event: string, handler: (...args: unknown[]) => unknown) => void;
+      appendEntry?: (customType: string, data: unknown) => void;
+    };
+    const beforeSettle = () => {
+      const active = this.registry.list({ includeHistory: false });
+      if (active.length === 0) { this.reminders = 0; this.reportActivity(); return; }
+      this.reportActivity();
+      if (this.reminders >= this.maxReminders) {
+        hooks.appendEntry?.("async-task-unresolved", { message: `${active.length} async task(s) remain unresolved: ${active.map((task) => task.taskId).join(", ")}` });
+        return;
+      }
+      this.reminders++;
+      hooks.appendEntry?.("async-task-settle-reminder", { message: `${active.length} async task(s) not collected (${active.map((task) => task.taskId).join(", ")}); use async_wait/async_status before reporting verdict.` });
+      return { continue: true };
+    };
+    const beforeRun = () => { this.reminders = 0; };
+    // SAFETY: PI_LEGION_NODE_ID is the documented legion-child marker; presence opts into settle reminders.
+    const legionChild = process.env.PI_LEGION_NODE_ID !== undefined;
+    if (legionChild) hooks.on?.("agent_before_settle", beforeSettle);
+    hooks.on?.("agent_start", beforeRun);
+    const cleanup = () => {
+      if (this.heartbeat) clearInterval(this.heartbeat);
+      if (legionChild) hooks.off?.("agent_before_settle", beforeSettle);
+      hooks.off?.("agent_start", beforeRun);
+      this.removeHooks = [];
+    };
+    hooks.on?.("session_shutdown", () => { void cleanup(); });
+    this.removeHooks.push(cleanup);
+    this.startHeartbeat(hooks);
+    this.reportActivity();
+  }
+
+  private reportActivity(): void {
+    // SAFETY: setActivity is feature-detected because older Pi hosts do not implement the optional API.
+    const ui = (this.pi as unknown as { ui?: { setActivity?: (id: string, value: { message: string } | undefined) => void } }).ui;
+    if (typeof ui?.setActivity !== "function") return;
+    const count = this.registry.activeCount();
+    const total = count.running + count.pending;
+    ui.setActivity("pi-async", total ? { message: `${total} async tasks` } : undefined);
+  }
+
+  private startHeartbeat(hooks: { appendEntry?: (customType: string, data: unknown) => void }): void {
+    if (this.heartbeat || this.heartbeatMs <= 0) return;
+    this.heartbeat = setInterval(() => {
+      if (!this.registry.hasActiveWork()) return;
+      hooks.appendEntry?.("async-task-heartbeat", { timestamp: Date.now(), active: this.registry.activeCount() });
+    }, this.heartbeatMs);
+    this.heartbeat.unref?.();
+  }
+}
+
+function finiteEnvNumber(name: string, fallback: number): number {
+  const parsed = Number(process.env[name] ?? fallback);
+  return Number.isFinite(parsed) ? parsed : fallback;
+}

package/src/tools/index.ts

@@ -0,0 +1,92 @@
+import type { PiCtx } from "../core/notify.ts";
+import type { TaskRegistry } from "../core/registry.ts";
+import type { WatchSpec } from "../core/task.ts";
+
+/**
+ * Wrap an extension-tool return value into pi's ToolResultMessage shape.
+ *
+ * pi 1.2.0 does NOT auto-wrap extension tool return values (the executor
+ * passes `await tool.execute(...)` through verbatim; only builtin tools
+ * return `{content:[{type:"text",...}]}`). A bare object without `content`
+ * crashes the TUI's ToolExecutionComponent.getTextOutput
+ * (`result.content.filter` on undefined) and persists as content:[] —
+ * see the user-reported uncaughtException on 2026-10-15.
+ *
+ * Every async_* tool MUST route its return value through this helper so the
+ * result satisfies the ToolResultMessage contract: content is an array of
+ * typed blocks, and the original payload rides along in `details` for tests
+ * and structured consumers.
+ */
+function toolResult(payload: unknown, isError = false): { content: Array<{ type: "text"; text: string }>; details: unknown; isError: boolean } {
+  return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }], details: { payload }, isError };
+}
+
+const promptGuidelines = "Check commands must not swallow errors with || true; map unknown states to failure; prefer structured output and jq -e; anchor output_matches regexes to avoid premature matches.";
+const MAX_LOG_BYTES = 50 * 1024;
+const schema = (properties: Record<string, unknown>, required: string[] = [], allOf: unknown[] = []) => ({ type: "object", properties, required, additionalProperties: false, ...(allOf.length ? { allOf } : {}) });
+const stringField = { type: "string" };
+const timeoutField = { type: "number", minimum: 0 };
+const conditionSchema = {
+  oneOf: [
+    { type: "object", properties: { type: { const: "exit_code" }, equals: { type: "number" } }, required: ["type", "equals"], additionalProperties: false },
+    ...["stdout_contains", "stderr_contains"].map((type) => ({ type: "object", properties: { type: { const: type }, value: stringField }, required: ["type", "value"], additionalProperties: false })),
+    { type: "object", properties: { type: { const: "json_path_exists" }, path: stringField }, required: ["type", "path"], additionalProperties: false },
+    { type: "object", properties: { type: { const: "output_matches" }, regex: stringField }, required: ["type", "regex"], additionalProperties: false },
+  ],
+};
+const watchSchema = {
+  type: "object", properties: {
+    intervalMs: { type: "number", minimum: 1000 }, timeoutMs: { type: "number", minimum: 1 },
+    success_when: { type: "array", items: conditionSchema }, failure_when: { type: "array", items: conditionSchema },
+    blind_checks: { type: "number", minimum: 1 },
+  }, required: ["intervalMs", "timeoutMs", "success_when", "failure_when"], additionalProperties: false,
+};
+
+/** Register the frozen five-tool surface. */
+export function registerTools(pi: PiCtx, registry: TaskRegistry): void {
+  type ToolDef = { name: string; label: string; description: string; parameters: unknown; execute: (toolCallId: string, params: Record<string, unknown>, signal?: AbortSignal) => Promise<unknown> };
+  // SAFETY: ExtensionAPI exposes registerTool at runtime; this local structural view keeps schemas dependency-free.
+  const api = pi as unknown as { registerTool?: (tool: ToolDef) => void };
+  if (!api.registerTool) throw new Error("Pi host does not expose registerTool");
+  api.registerTool({
+    name: "async_run", label: "Run async command", description: `Run a background, delayed, or synchronous shell command. ${promptGuidelines}`,
+    parameters: schema({ command: stringField, name: stringField, mode: { type: "string", enum: ["background", "sync", "delayed"], default: "background" }, timeoutMs: timeoutField, delayMs: timeoutField, taskTimeoutMs: timeoutField, onTimeout: { type: "string", enum: ["promote", "abort"], default: "promote" }, notifyOnCompletion: { type: "boolean" }, triggerOnCompletion: { type: "boolean" }, env: { type: "object", additionalProperties: { type: "string" } }, watch: watchSchema }, ["command"], [
+      { if: { properties: { mode: { const: "sync" } }, required: ["mode"] }, then: { required: ["timeoutMs"] } },
+      { if: { properties: { mode: { const: "delayed" } }, required: ["mode"] }, then: { required: ["delayMs"] } },
+      { if: { properties: { mode: { const: "sync" } }, required: ["mode"] }, then: { not: { required: ["watch"] } } },
+    ]),
+    execute: async (_id, params, signal) => {
+      const mode = String(params.mode ?? "background");
+      if (mode !== "background" && mode !== "sync" && mode !== "delayed") throw new Error(`Unsupported async_run mode: ${mode}`);
+      const command = String(params.command ?? "");
+      if (mode === "sync" && params.timeoutMs === undefined) throw new Error("timeoutMs is required for sync mode");
+      if (mode === "delayed" && params.delayMs === undefined) throw new Error("delayMs is required for delayed mode");
+      if (params.watch !== undefined && mode === "sync") throw new Error("watch is only supported for background and delayed modes");
+      const options = {
+        command,
+        ...(typeof params.name === "string" ? { name: params.name } : {}),
+        ...(typeof params.taskTimeoutMs === "number" ? { taskTimeoutMs: params.taskTimeoutMs } : {}),
+        ...(typeof params.notifyOnCompletion === "boolean" ? { notifyOnCompletion: params.notifyOnCompletion } : {}),
+        ...(typeof params.triggerOnCompletion === "boolean" ? { triggerOnCompletion: params.triggerOnCompletion } : {}),
+        ...(params.env && typeof params.env === "object" ? { env: params.env as Record<string, string> } : {}),
+        ...(params.watch && typeof params.watch === "object" ? { watch: params.watch as WatchSpec } : {}),
+      };
+      if (mode === "sync") { const r = await registry.runSync({ ...options, mode: "sync" }, Number(params.timeoutMs), params.onTimeout === "abort" ? "abort" : "promote", signal); return toolResult(r); }
+      const task = mode === "delayed"
+        ? registry.scheduleDelayed({ ...options, mode: "delayed" }, Number(params.delayMs))
+        : registry.submit({ ...options, mode: "background" });
+      return toolResult({ taskId: task.taskId, name: task.name, status: task.status, mode: task.mode, outputHint: `Use async_logs with taskId ${task.taskId} to inspect early output.` });
+    },
+  });
+  api.registerTool({ name: "async_wait", label: "Wait for async tasks", description: "Wait for tasks to finish or return notReady; waiting does not kill tasks.", parameters: schema({ taskIds: { type: "array", items: stringField }, timeoutMs: timeoutField }, ["taskIds", "timeoutMs"]), execute: async (_id, params, signal) => {
+    if (params.timeoutMs === undefined) throw new Error("timeoutMs is required");
+    return toolResult(await registry.wait(params.taskIds as string[], Number(params.timeoutMs), signal));
+  } });
+  api.registerTool({ name: "async_logs", label: "Read async output", description: "Read bounded, ANSI-stripped task output.", parameters: schema({ taskId: stringField, maxBytes: { type: "number", minimum: 0, maximum: MAX_LOG_BYTES }, tail: { type: "boolean" } }, ["taskId"]), execute: async (_id, params) => {
+    const maxBytes = params.maxBytes === undefined ? MAX_LOG_BYTES : Number(params.maxBytes);
+    if (maxBytes > MAX_LOG_BYTES) throw new Error("maxBytes must be at most 50 KiB");
+    return toolResult(registry.logs(String(params.taskId), { maxBytes, tail: params.tail !== false }));
+  } });
+  api.registerTool({ name: "async_status", label: "Async task status", description: "List async tasks and current status.", parameters: schema({ includeHistory: { type: "boolean" } }), execute: async (_id, params) => toolResult(registry.list({ includeHistory: params.includeHistory !== false })) });
+  api.registerTool({ name: "async_kill", label: "Kill async task", description: "Terminate an async task and its process group.", parameters: schema({ taskId: stringField }, ["taskId"]), execute: async (_id, params) => { await registry.kill(String(params.taskId), "user"); return toolResult({ taskId: params.taskId, status: registry.get(String(params.taskId))?.status }); } });
+}

package/src/tui/host.ts

@@ -0,0 +1,30 @@
+/**
+ * Bound TUI host context.
+ *
+ * pi's factory-time ExtensionAPI exposes neither `mode` nor `ui` — those live
+ * on event-handler contexts (`pi.on(event, (event, ctx) => ...)`), and `ctx.ui`
+ * is the only object whose setWidget/setStatus/custom actually work. All TUI
+ * surfaces therefore bind lazily from the first event context whose
+ * `mode === "tui"`, and read `tuiHost()` afterwards.
+ */
+export type TuiHost = { mode: string; ui: Record<string, unknown> };
+
+let bound: TuiHost | undefined;
+
+/** Bind the first TUI-capable event context. Idempotent; only the first wins. */
+export function bindTuiHost(ctx: unknown): boolean {
+  const c = ctx as { mode?: string; ui?: Record<string, unknown> } | undefined;
+  if (bound || c?.mode !== "tui" || !c.ui) return false;
+  bound = { mode: c.mode, ui: c.ui };
+  return true;
+}
+
+/** The bound TUI host, or undefined when no TUI context has been seen. */
+export function tuiHost(): TuiHost | undefined {
+  return bound;
+}
+
+/** Test-only: forget the bound host so isolated unit tests can re-bind. */
+export function resetTuiHostForTests(): void {
+  bound = undefined;
+}