pi-async 0.0.0-stage → 0.2.0

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "pi-async",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Pi extension for async shell tasks: background/delayed/sync modes, output-matching watches, event-driven waiting, settle guard for legion children, and a TUI task rail — completion notifications wake your session.",
+  "type": "module",
+  "license": "MIT",
+  "author": "zzjcool",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zzjcool/pi-async.git"
+  },
+  "homepage": "https://github.com/zzjcool/pi-async#readme",
+  "bugs": {
+    "url": "https://github.com/zzjcool/pi-async/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "coding-agent",
+    "async",
+    "background-tasks",
+    "task-manager",
+    "shell",
+    "watch",
+    "delayed",
+    "pi-legion"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ]
+  },
+  "files": [
+    "extensions/",
+    "src/",
+    "README.md",
+    "LICENSE",
+    "docs/CONTRACT.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "node --experimental-strip-types --test tests/*.test.ts"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^1.2.0",
+    "@earendil-works/pi-tui": "^1.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.19",
+    "typescript": "^5.9.3"
+  }
+}

package/src/core/bus.ts

@@ -0,0 +1,36 @@
+import type { PiCtx } from "./notify.ts";
+
+/** Aggregate activity source id (frozen §7). */
+const AGGREGATE_ACTIVITY_ID = "pi-async";
+
+/** Per-task activity id — legion #156 / osc-busy-plugin: `plugin/<name>/…`. */
+export function taskActivityId(taskId: string): string {
+  return `plugin/pi-async/${taskId}`;
+}
+
+/** Report aggregate async work through Pi's activity API when the host exposes it. */
+export function reportActivity(pi: PiCtx, active: { running: number; pending: number }): void {
+  // SAFETY: PiCtx is the installed extension API; ui.setActivity is feature-detected for versions without it.
+  const ui = (pi as unknown as { ui?: { setActivity?: (id: string, activity: { message: string } | undefined) => void } }).ui;
+  if (typeof ui?.setActivity !== "function") return;
+  const count = active.running + active.pending;
+  ui.setActivity(AGGREGATE_ACTIVITY_ID, count === 0 ? undefined : { message: `${count} async tasks` });
+  // Activity uses the host API; never emit terminal OSC/printf escapes. In particular,
+  // leave PI_PROGRAM_STATUS untouched for hosts which own that status channel.
+}
+
+/** Raise task-scoped activity when the host supports Pi's optional activity API. */
+export function raiseTaskActivity(pi: PiCtx, taskId: string, message = "Async task running"): void {
+  // SAFETY: PiCtx is the installed extension API; ui.setActivity is feature-detected for versions without it.
+  const ui = (pi as unknown as { ui?: { setActivity?: (id: string, activity: { message: string } | undefined) => void } }).ui;
+  if (typeof ui?.setActivity !== "function") return;
+  ui.setActivity(taskActivityId(taskId), { message });
+}
+
+/** Clear task-scoped activity when the host supports Pi's optional activity API. */
+export function clearTaskActivity(pi: PiCtx, taskId: string): void {
+  // SAFETY: PiCtx is the installed extension API; ui.setActivity is feature-detected for versions without it.
+  const ui = (pi as unknown as { ui?: { setActivity?: (id: string, activity: { message: string } | undefined) => void } }).ui;
+  if (typeof ui?.setActivity !== "function") return;
+  ui.setActivity(taskActivityId(taskId), undefined);
+}

package/src/core/duration.ts

@@ -0,0 +1,16 @@
+import type { TaskSnapshot } from "./task.ts";
+
+/**
+ * Format a task's elapsed duration for TUI surfaces.
+ * - pending → em dash (not started)
+ * - end base = finishedAt ?? now (terminal states freeze; live tasks tick)
+ * - three tiers: Ns / Mm Ss / Hh Mm
+ */
+export function formatDuration(task: TaskSnapshot, now: number): string {
+  if (task.status === "pending") return "—";
+  const end = task.finishedAt ?? now;
+  const seconds = Math.floor(Math.max(0, end - (task.startedAt ?? task.createdAt)) / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  return minutes < 60 ? `${minutes}m ${seconds % 60}s` : `${Math.floor(minutes / 60)}h ${minutes % 60}m`;
+}

package/src/core/env.ts

@@ -0,0 +1,23 @@
+export interface EnvNumberOpts {
+  min?: number;
+  max?: number;
+  /** When true, non-integers fall back (avoids Number("")===0 and 2.7→3 surprises). */
+  integer?: boolean;
+}
+
+/**
+ * Parse a numeric env var with empty-string → fallback (not Number("")===0).
+ * Non-finite / out-of-range / non-integer (when requested) also fall back.
+ */
+export function envNumber(name: string, fallback: number, opts?: EnvNumberOpts): number {
+  const raw = process.env[name];
+  if (raw === undefined) return fallback;
+  const trimmed = raw.trim();
+  if (trimmed === "") return fallback;
+  const parsed = Number(trimmed);
+  if (!Number.isFinite(parsed)) return fallback;
+  if (opts?.integer && !Number.isInteger(parsed)) return fallback;
+  if (opts?.min !== undefined && parsed < opts.min) return fallback;
+  if (opts?.max !== undefined && parsed > opts.max) return fallback;
+  return parsed;
+}

package/src/core/notify.ts

@@ -0,0 +1,57 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { TaskRegistry } from "./registry.ts";
+import type { FailureKind, KillKind, TaskStatus } from "./task.ts";
+
+export type PiCtx = ExtensionAPI;
+export interface NotifyPayload {
+  taskId: string; name: string; status: TaskStatus; exitCode?: number;
+  outputFile: string; summary?: string; guidance?: string;
+  killKind?: KillKind;
+  failureKind?: FailureKind;
+  summaryTruncated?: boolean;
+}
+
+/** XML 1.0 Char excludes C0 (except TAB/LF/CR), lone surrogates, and U+FFFE/FFFF (#19). */
+const ILLEGAL_XML = /[\x00-\x08\x0b\x0c\x0e-\x1f\ud800-\udfff\ufffe\uffff]/g;
+
+const escapeXml = (value: unknown): string =>
+  String(value)
+    .replace(ILLEGAL_XML, "")
+    .replace(/[<&>\"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", "\"": "&quot;", "'": "&apos;" })[char]!);
+
+export function buildNotificationXml(p: NotifyPayload): string {
+  const fields: Array<[string, unknown]> = [["task-id", p.taskId], ["name", p.name], ["status", p.status]];
+  if (p.exitCode !== undefined) fields.push(["exit-code", p.exitCode]);
+  if (p.killKind) fields.push(["kill-kind", p.killKind]);
+  if (p.failureKind) fields.push(["failure-kind", p.failureKind]);
+  fields.push(["output-file", p.outputFile]);
+  if (p.summary) fields.push(["summary", p.summary]);
+  if (p.summaryTruncated) fields.push(["summary-truncated", "true"]);
+  if (p.status === "failed" && p.guidance) fields.push(["guidance", p.guidance]);
+  return `<async-task-notification>${fields.map(([tag, value]) => `<${tag}>${escapeXml(value)}</${tag}>`).join("")}</async-task-notification>`;
+}
+
+export async function sendCompletionNotification(
+  pi: PiCtx,
+  registry: TaskRegistry,
+  p: NotifyPayload,
+  options: { triggerTurn?: boolean } = {},
+): Promise<boolean> {
+  if (registry.get(p.taskId)?.outputConsumed || !registry.claimNotification(p.taskId)) return false;
+  // SAFETY: The pi extension API provides sendMessage in supported hosts; detect it at runtime for other contexts.
+  const target = pi as unknown as { sendMessage?: (message: unknown, options: unknown) => unknown };
+  if (!target.sendMessage) { registry.rollbackNotification(p.taskId); return false; }
+  for (let attempt = 0; attempt < 3; attempt++) {
+    try {
+      await target.sendMessage(
+        { customType: "async-task-notification", content: buildNotificationXml(p) },
+        { deliverAs: "followUp", ...(options.triggerTurn === false ? {} : { triggerTurn: true }) },
+      );
+      return true;
+    } catch {
+      if (attempt < 2) await Promise.resolve();
+    }
+  }
+  registry.rollbackNotification(p.taskId);
+  return false;
+}

package/src/core/output.ts

@@ -0,0 +1,52 @@
+const ANSI_ESCAPE =
+  /\x1B(?:\][\s\S]*?(?:\x07|\x1B\\|\x9C)|\][\s\S]*$|\[[0-?]*[ -/]*[@-~]|\[[0-?]*[ -/]*$|[PX^_][\s\S]*?\x1B\\|[ -/]*[0-~])|\x9B[0-?]*[ -/]*[@-~]|\x9D[\s\S]*?(?:\x07|\x1B\\|\x9C)/g;
+
+/** Keep tab/LF/CR; drop other C0 controls that must not reach model/TUI/XML. */
+const C0_CONTROLS = /[\x00-\x08\x0b\x0c\x0e-\x1f]/g;
+
+/** Remove ANSI escape, CSI, OSC, and string-control sequences from text.
+ *  Unterminated OSC/CSI are dropped through end-of-string so truncation mid-sequence
+ *  does not leave the payload as visible garbage (#32). */
+export function stripAnsi(text: string): string {
+  return text.replace(ANSI_ESCAPE, "");
+}
+
+/**
+ * Strip bare C0 control bytes (except TAB/LF/CR which are folded to spaces)
+ * and collapse runs of whitespace. Use after stripAnsi for TUI-visible text.
+ * Keeps panel and rail sanitization aligned (CONTRACT §9 / issue #3).
+ */
+export function stripControl(text: string): string {
+  return text
+    .replace(C0_CONTROLS, "")
+    .replace(/[\r\n\t]+/g, " ");
+}
+
+/** ANSI + C0 sanitizer for TUI labels (task names, panel rows). */
+export function visibleText(value: unknown): string {
+  return stripControl(stripAnsi(String(value ?? "")));
+}
+
+/** Model/logs path: strip ANSI then bare C0, preserve TAB/LF/CR (#18). */
+export function stripLogControls(text: string): string {
+  return stripAnsi(text).replace(C0_CONTROLS, "");
+}
+
+/**
+ * Truncate a UTF-8 buffer to at most `maxBytes`, cutting on a leading-byte boundary
+ * so multi-byte characters are never split into U+FFFD (#17).
+ * When `tail` is true, keep the end of the buffer (advance past continuation bytes).
+ */
+export function truncateUtf8Bytes(bytes: Buffer, maxBytes: number, tail = true): string {
+  if (maxBytes <= 0) return "";
+  if (bytes.byteLength <= maxBytes) return bytes.toString("utf8");
+  if (!tail) {
+    let end = maxBytes;
+    // Walk back while on a UTF-8 continuation byte so we don't cut mid-sequence.
+    while (end > 0 && (bytes[end]! & 0xc0) === 0x80) end--;
+    return bytes.subarray(0, end).toString("utf8");
+  }
+  let start = bytes.byteLength - maxBytes;
+  while (start < bytes.byteLength && (bytes[start]! & 0xc0) === 0x80) start++;
+  return bytes.subarray(start).toString("utf8");
+}