@saifymatteo/pi-extensions 0.0.0-stage → 0.1.0

package/packages/pi-wait/README.md

@@ -0,0 +1,37 @@
+# @saifymatteo/pi-wait
+
+## Purpose and registrations
+
+Registers the `wait` tool, joining 1..64 unique explicit `shell:<id>` / `agent:<id>` jobs. Returns results in requested order. Timeout releases claims without stopping work; abort/session changes invalidate the join. No commands or configuration files; no external CLI/model service.
+
+## Cooperative delivery contract
+
+Synchronous session-scoped `async-work:providers:v1` discovery receives `{sessionFile, add(provider)}`. Providers expose `source` and atomic `claim(ids, owner)` returning `{result, commit, release}`. Wait validates all results and serializes a snapshot before committing; finally it releases all leases. Commit/release must be synchronous, idempotent and nonthrowing. Duplicate providers, already consumed/submitted work and missing providers fail rather than duplicate delivery. See `src/lib/async-work.ts`.
+
+Load `pi-bg-bash` for shell jobs. An orchestrator implementing the same contract is separate and external, not bundled or created by this package; it supplies agent jobs and parent-abort fleet cancellation.
+
+## Host limitations and security
+
+Requires Pi's shared synchronous event bus and session manager; does not join arbitrary OS processes or persist jobs across runtime restarts. No network/filesystem operations of its own. Provider job output becomes model-visible; do not join secret-bearing results. Timeout is 300000ms by default, maximum 1800000ms.
+
+## Tests
+
+From the monorepo root with its existing test dependencies available:
+
+```sh
+node --test packages/pi-wait/test/*.test.mjs
+```
+
+Tests use the shared test-only TypeScript/VM loader, fixtures, and host/service stubs. They do not prove compatibility with a live host, CLI, or model service.
+
+## Running locally
+
+From the monorepo root:
+
+```sh
+pi -e ./packages/pi-wait
+```
+
+Node >=24; host imports are peers, not bundled dependencies. Load only one copy: for an isolated session use `--no-extensions` with explicit `-e` paths so the original live extension is not also discovered. Set `PI_CODING_AGENT_DIR` to a disposable agent directory before launch; unset means the normal `~/.pi/agent` fallback. Extension config continues to resolve there, never relative to this package.
+
+Examples are manually authored, sanitized reference documents, not runtime defaults. Review and manually create only the needed files in the isolated agent directory; do not copy live credentials or endpoints. No example is automatically loaded or copied. Loading an extension grants Pi-process OS permissions. Licensed AGPL-3.0-only; see [NOTICE.md](NOTICE.md).

package/packages/pi-wait/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@saifymatteo/pi-wait",
+  "version": "0.1.0",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "keywords": [
+    "pi-package"
+  ],
+  "files": [
+    "src",
+    "examples",
+    "README.md",
+    "NOTICE.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "description": "Join background jobs (shell:/agent:) with lease-based delivery.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/saifymatteo/pi-extensions.git",
+    "directory": "packages/pi-wait"
+  }
+}

package/packages/pi-wait/src/index.ts

@@ -0,0 +1,88 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { ASYNC_WORK_PROVIDERS, type Lease, type Provider, type ProviderDiscovery, type WorkSource } from "./lib/async-work";
+
+export default function (pi: ExtensionAPI) {
+	let sequence = 0;
+	pi.registerTool({
+		name: "wait",
+		label: "Wait",
+		description: "Join explicit background jobs (shell:1, agent:2). Returns all results together. Timeout releases delivery ownership without stopping jobs; Escape/parent abort retains fleet cancellation. Already consumed or externally submitted results cannot be joined.",
+		parameters: Type.Object({
+			jobs: Type.Array(Type.String({ pattern: "^(shell|agent):[1-9][0-9]*$" }), { minItems: 1, maxItems: 64, uniqueItems: true }),
+			timeoutMs: Type.Optional(Type.Integer({ minimum: 1, maximum: 1800000, default: 300000 })),
+		}),
+		promptGuidelines: ["After dispatch, do independent work first. When blocked on explicit jobs, use wait with their shell:<id>/agent:<id> references. Never sleep or poll to wait. Do not answer redundant messages for results already known individually."],
+		async execute(toolCallId, params, signal, _onUpdate, ctx) {
+			const { jobs, timeoutMs = 300000 } = params;
+			if (!Array.isArray(jobs) || jobs.length < 1 || jobs.length > 64 || new Set(jobs).size !== jobs.length)
+				throw new Error("wait requires 1..64 unique job references");
+			if (!Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 1800000)
+				throw new Error("timeoutMs must be an integer from 1 to 1800000");
+			const groups = new Map<WorkSource, number[]>();
+			for (const ref of jobs) {
+				const match = typeof ref === "string" && /^(shell|agent):([1-9][0-9]*)$/.exec(ref);
+				if (!match || !Number.isSafeInteger(Number(match[2]))) throw new Error(`Invalid job reference: ${ref}`);
+				const source = match[1] as WorkSource;
+				groups.set(source, [...(groups.get(source) ?? []), Number(match[2])]);
+			}
+			const providers = new Map<WorkSource, Provider>();
+			const duplicates = new Set<WorkSource>();
+			const discovery: ProviderDiscovery = {
+				sessionFile: ctx.sessionManager.getSessionFile(),
+				add(provider) {
+					if (providers.has(provider.source)) duplicates.add(provider.source);
+					providers.set(provider.source, provider);
+				},
+			};
+			pi.events.emit(ASYNC_WORK_PROVIDERS, discovery);
+			const leases: Lease[] = [];
+			let timer: ReturnType<typeof setTimeout> | undefined;
+			let onAbort: (() => void) | undefined;
+			const cancelled = "wait cancelled; delivery claims released (parent abort may cancel agents)";
+			const checkActive = () => {
+				if (signal?.aborted) throw new Error(cancelled);
+				if (ctx.sessionManager.getSessionFile() !== discovery.sessionFile)
+					throw new Error("wait session changed; delivery claims released");
+			};
+			try {
+				checkActive();
+				const owner = `wait:${toolCallId}:${++sequence}`;
+				for (const [source, ids] of groups) {
+					if (duplicates.has(source)) throw new Error(`Multiple ${source} providers for this session`);
+					const provider = providers.get(source);
+					if (!provider) throw new Error(`No ${source} provider for this session`);
+					leases.push(provider.claim(ids, owner));
+				}
+				const interrupted = new Promise<never>((_resolve, reject) => {
+					onAbort = () => reject(new Error(cancelled));
+					signal?.addEventListener("abort", onAbort, { once: true });
+					if (signal?.aborted) onAbort();
+					timer = setTimeout(() => reject(new Error(`wait timed out after ${timeoutMs}ms; jobs continue running`)), timeoutMs);
+				});
+				const batches = await Promise.race([Promise.all(leases.map((lease) => lease.result)), interrupted]);
+				checkActive();
+				const all = batches.flat();
+				// Validate producer output before consuming any lease.
+				const results = jobs.map((ref) => {
+					const matches = all.filter((result) => `${result.source}:${result.id}` === ref);
+					if (matches.length !== 1 || !Number.isSafeInteger(matches[0].id) || typeof matches[0].content !== "string" ||
+						!matches[0].details || typeof matches[0].details !== "object" || Array.isArray(matches[0].details))
+						throw new Error(`Invalid provider result for ${ref}`);
+					return matches[0];
+				});
+				if (all.length !== jobs.length) throw new Error("Unexpected provider results");
+				// Materialize a JSON-safe snapshot before committing: producer metadata may be invalid.
+				const response = JSON.parse(JSON.stringify({ content: [{ type: "text", text:
+					results.map((result) => `[${result.source}:${result.id}]\n${result.content}`).join("\n\n") }], details: { results } }));
+				checkActive();
+				for (const lease of leases) lease.commit();
+				return response;
+			} finally {
+				if (timer !== undefined) clearTimeout(timer);
+				if (onAbort) signal?.removeEventListener("abort", onAbort);
+				for (const lease of leases) lease.release();
+			}
+		},
+	});
+}

package/packages/pi-wait/src/lib/async-work.ts

@@ -0,0 +1,27 @@
+/** Synchronous, session-scoped discovery. Providers retain all execution state.
+ * claim must validate the whole group before changing ownership (or roll itself back).
+ * commit/release are synchronous, idempotent, and must not throw. commit consumes;
+ * release restores normal delivery without cancelling work. Never retract native queues.
+ */
+export const ASYNC_WORK_PROVIDERS = "async-work:providers:v1";
+export type WorkSource = "shell" | "agent";
+export interface WorkResult {
+	source: WorkSource;
+	id: number;
+	content: string;
+	details: Record<string, unknown>;
+}
+export interface Lease {
+	result: Promise<WorkResult[]>;
+	commit(): void;
+	release(): void;
+}
+export interface Provider {
+	source: WorkSource;
+	claim(ids: number[], owner: string): Lease;
+}
+export interface ProviderDiscovery {
+	sessionFile?: string;
+	/** Must be called synchronously: EventBus.emit returns void. */
+	add(provider: Provider): void;
+}

package/packages/pi-wait/test/wait.test.mjs

@@ -0,0 +1,43 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { fileURLToPath } from 'node:url';
+import { loadExtension } from '../../../test/load-extension.mjs';
+
+function setup(providers) {
+  let tool;
+  const Type = new Proxy({}, { get: () => () => ({}) });
+  const { default: extension } = loadExtension(fileURLToPath(new URL('../src/index.ts', import.meta.url)), { typebox: { Type } });
+  extension({ registerTool: value => { tool = value; }, events: { emit: (name, discovery) => {
+    assert.equal(name, 'async-work:providers:v1');
+    for (const provider of providers) discovery.add(provider);
+  } } });
+  return params => tool.execute('test', params, undefined, undefined, { sessionManager: { getSessionFile: () => 'fixture-session' } });
+}
+
+test('wait validates references before discovery', async () => {
+  const run = setup([]);
+  await assert.rejects(run({ jobs: ['shell:0'] }), /Invalid job reference/);
+  await assert.rejects(run({ jobs: ['shell:1', 'shell:1'] }), /unique job references/);
+  await assert.rejects(run({ jobs: ['shell:1'], timeoutMs: 0 }), /timeoutMs/);
+  await assert.rejects(run({ jobs: ['shell:1'] }), /No shell provider/);
+});
+
+test('wait joins in requested order and commits then releases all leases', async () => {
+  const actions = [];
+  const provider = source => ({ source, claim: ids => ({
+    result: Promise.resolve(ids.map(id => ({ source, id, content: `${source} output`, details: {} }))),
+    commit: () => actions.push(`commit:${source}`), release: () => actions.push(`release:${source}`),
+  }) });
+  const result = await setup([provider('shell'), provider('agent')])({ jobs: ['agent:2', 'shell:1'] });
+  assert.match(result.content[0].text, /^\[agent:2\][\s\S]*\[shell:1\]/);
+  assert.equal(actions.join(','), 'commit:agent,commit:shell,release:agent,release:shell');
+});
+
+test('malformed provider output is released without consumption', async () => {
+  let committed = false;
+  let released = false;
+  const run = setup([{ source: 'shell', claim: () => ({ result: Promise.resolve([]), commit: () => { committed = true; }, release: () => { released = true; } }) }]);
+  await assert.rejects(run({ jobs: ['shell:1'] }), /Invalid provider result/);
+  assert.equal(committed, false);
+  assert.equal(released, true);
+});