@dougbots/avenor-pi 0.8.3 → 0.10.0

package/README.md

@@ -86,8 +86,9 @@ packages/pi/
 ├── package.json
 ├── tsdown.config.ts
 ├── src/
-│   ├── index.ts          # main extension (tools, commands, hooks, rendering)
-│   ├── types.ts          # shared types, status emoji mapping
+│   ├── index.ts          # main extension, tool registration, commands, and hooks
+│   ├── render.ts         # host-only tool-call and result presentation
+│   ├── types.ts          # shared types and status emoji mapping
 │   └── watch.ts          # EventFeedOverlay TUI component
 └── dist/
     └── index.js          # built output (loaded by pi)
@@ -111,7 +112,7 @@ Available tools for LLM sub-agent management:
 
 | Tool | Description |
 |---|---|
-| `avenor_spawn` | Dispatch an agent run (blocking or fire-and-forget). Uses the `pi` backend by default; accepts `agent`, `model`, `prompt`, and `dir`. |
+| `avenor_spawn` | Dispatch an agent run (blocking or fire-and-forget). Uses the `pi` backend by default in direct mode; accepts optional `agent`, `model`, `prompt`, `dir`, `roster_file`, and `roster_entry`. |
 | `avenor_status` | Get status of a run or all runs; use `view="lifecycle"` for compact progress and permission checks |
 | `avenor_result` | Wait for a run and return its complete final output without transcript details |
 | `avenor_inspect` | Review a bounded transcript, tool activity, permissions, and final output |
@@ -120,20 +121,49 @@ Available tools for LLM sub-agent management:
 | `avenor_events` | Read events from a run |
 | `avenor_shutdown` | Shut down the avenor supervisor |
 
+### Direct and roster spawns
+
+Direct mode permits `agent`, `model`, and `backend` to be omitted independently, including a backend-only request; omitted values use runtime defaults. Pi supplies `backend: "pi"` for direct tool calls when no backend is given. Roster mode uses both `roster_file` and `roster_entry`, and leaves backend selection to the roster entry instead of applying Pi's direct default:
+
+```json
+{
+  "prompt": "Review the repository",
+  "roster_file": "/repo/roster.json",
+  "roster_entry": "reviewer"
+}
+```
+
+Each roster entry must contain `backend` and at least one of `agent` or `model`. Do not combine roster mode with direct `agent`, `model`, or `backend` overrides. Roster entries currently do not support `system` or `thinking`; `thinking` remains a run-level option and is validated against the effective backend. A resumed session must stay on its original backend. Use an absolute `roster_file` path when the Pi process and target project have different working directories.
+
 ### Pi-specific features
 
 Beyond the tools, the extension integrates with Pi's TUI and event system:
 
 - **Status widget** — persistent widget showing all active runs with status, phase, and permission state
-- **Footer status** — active runs shown in the Pi footer bar
+- **Footer status** — active runs and polling error counts shown in the Pi footer bar
+- **Polling diagnostics** — bounded polling errors are emitted on `avenor:poll:error` for companion extensions
 - **Live progress** — blocking `avenor_spawn` calls stream progress updates via `onUpdate`
 - **Context enrichment** — active sub-agents are automatically surfaced in the system prompt via `before_agent_start`
-- **Custom rendering** — tool calls and results are rendered with status emojis and color-coded output
+- **Custom rendering** — The Pi extension renders all Avenor tool calls and results as themed, bounded summaries. Results have collapsed and expanded views.
 - **Commands** — interactive commands for run management:
   - `/avenor-status` — show status of all runs
+  - `/avenor-errors` — show and clear recent polling errors
   - `/avenor-watch <run_id>` — open a live event feed overlay
   - `/avenor-cancel <run_id>` — cancel a running sub-agent
 
+### Tool-result channels
+
+Pi returns JSON model content in `content[0].text` and structured `details` for
+all tools except `avenor_spawn`. The renderer creates themed, bounded summaries
+for display. It does not modify the underlying model content or the `details`
+object.
+
+Pi's rendered summaries sanitize and bound the output, events, and snapshot rows
+they display. Use `avenor_result`, `avenor_inspect`, or `avenor_events` for the
+corresponding data.
+
+MCP clients render their own results.
+
 ### Agent profiles
 
 The `avenor_spawn` tool accepts an optional `agent` parameter that maps to a named profile in pi's `agents.json`:

package/dist/index.d.ts

@@ -1,9 +1,13 @@
 import { InspectResult, StatusResult, Supervisor, answerPermissionTool, dial, eventsTool, followUpTool, inspectTool, observeRun, resultTool, shutdownTool, spawnTool, statusTool } from "@dougbots/avenor-core";
-import { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { EventBus, ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 //#region src/types.d.ts
 interface RunStatusEntry {
   runId: string;
+  /** Supervisor socket provided at spawn time for namespace scoping. */
+  supervisorId?: string;
+  /** Runtime ID scoped to the explicit or singleton supervisor. */
+  runtimeId?: string;
   label: string;
   status: string;
   phase?: string;
@@ -19,6 +23,92 @@ interface RunStatusEntry {
   nestedCount?: number;
 }
 //#endregion
+//#region src/events.d.ts
+/** Emitted when the official extension completes a polling cycle. */
+declare const CHANNEL_POLL_COMPLETED: "avenor:poll:completed";
+/** Emitted when the extension observes a terminal run result. */
+declare const CHANNEL_RUN_TERMINAL: "avenor:run:terminal";
+/** Emitted when a best-effort polling operation fails. */
+declare const CHANNEL_POLL_ERROR: "avenor:poll:error";
+type PollErrorSource = 'singleton-list' | 'run-status' | 'spawn-status';
+interface PollErrorPayload {
+  /** Polling operation that failed. */
+  readonly source: PollErrorSource;
+  /** Run associated with the failure, when the operation was run-specific. */
+  readonly runId?: string;
+  /** Human-readable operation description. */
+  readonly message: string;
+  /** Bounded, sanitized error text suitable for debug consumers. */
+  readonly error: string;
+  /** Number of polling errors observed by this extension instance. */
+  readonly count: number;
+  /** Wall-clock timestamp in epoch milliseconds. */
+  readonly timestamp: number;
+}
+interface PollErrorPayloadInput {
+  readonly source: PollErrorSource;
+  readonly runId?: string;
+  readonly message: string;
+  readonly error: unknown;
+  readonly count: number;
+  readonly timestamp: number;
+}
+type AvenorRunStatus = Readonly<Omit<RunStatusEntry, 'supervisorId' | 'pid' | 'permissionDescription'> & {
+  supervisorKey: string;
+}>;
+interface PollCompletedPayload {
+  /** Status for each direct run tracked by the official extension. */
+  readonly entries: readonly AvenorRunStatus[];
+  /** Wall-clock timestamp in epoch milliseconds. */
+  readonly timestamp: number;
+  /** Monotonic counter for this official-extension instance. */
+  readonly generation: number;
+}
+interface RunTerminalPayload {
+  readonly runId: string;
+  /** Stable opaque scope for the explicit or singleton supervisor. */
+  readonly supervisorKey: string;
+  readonly runtimeId?: string;
+  readonly label: string;
+  readonly agent: string;
+  readonly status: string;
+  /** Number of active descendants when the run was removed, if available. */
+  readonly nestedCount?: number;
+  readonly backend?: string;
+}
+interface RunTerminalPayloadInput {
+  readonly runId: string;
+  /** Local supervisor socket, converted to an opaque supervisorKey. */
+  readonly supervisorId?: string;
+  readonly runtimeId?: string;
+  readonly label: string;
+  readonly agent: string;
+  readonly status: string;
+  readonly nestedCount?: number;
+  readonly backend?: string;
+}
+interface AvenorEventMap {
+  [CHANNEL_POLL_COMPLETED]: PollCompletedPayload;
+  [CHANNEL_RUN_TERMINAL]: RunTerminalPayload;
+  [CHANNEL_POLL_ERROR]: PollErrorPayload;
+}
+type AvenorEventChannel = keyof AvenorEventMap;
+type AvenorEventBus = Pick<EventBus, 'emit' | 'on'>;
+/** Emit an Avenor event with a type-checked payload. */
+declare function emitAvenorEvent<K extends AvenorEventChannel>(bus: Pick<EventBus, 'emit'>, event: K, data: AvenorEventMap[K]): void;
+/** Subscribe to an Avenor event and return Pi's unsubscribe function. */
+declare function onAvenorEvent<K extends AvenorEventChannel>(bus: Pick<EventBus, 'on'>, event: K, handler: (data: AvenorEventMap[K]) => void): () => void;
+/**
+ * Copy and freeze the selected fields exposed to companion consumers.
+ * Keep this allowlist explicit so future private RunStatusEntry fields are not
+ * included in the event accidentally.
+ */
+declare function createPollCompletedPayload(entries: readonly RunStatusEntry[], timestamp: number, generation: number): PollCompletedPayload;
+/** Copy and freeze a terminal payload before publishing it. */
+declare function createRunTerminalPayload(payload: RunTerminalPayloadInput): RunTerminalPayload;
+/** Copy, bound, sanitize, and freeze a polling error before publishing it. */
+declare function createPollErrorPayload(payload: PollErrorPayloadInput): PollErrorPayload;
+//#endregion
 //#region src/index.d.ts
 interface ExtensionDeps {
   spawnTool: typeof spawnTool;
@@ -34,6 +124,15 @@ interface ExtensionDeps {
   Supervisor: typeof Supervisor;
 }
 declare function statusSupervisorId(requestedSupervisorId: string | undefined, spawnedSupervisorId: string): string | undefined;
+type SpawnHostParams = {
+  agent?: string;
+  model?: string;
+  backend?: string;
+  roster_file?: string;
+  roster_entry?: string;
+};
+/** Project shared spawn identity into Pi tool metadata without resolving rosters here. */
+declare function spawnIdentityMetadata(params: SpawnHostParams, status?: Pick<StatusResult, 'roster_file' | 'roster_entry' | 'agent' | 'model' | 'backend' | 'effective_agent' | 'effective_model' | 'effective_backend'>): Record<string, unknown>;
 declare function buildCompletionText(run: {
   runId: string;
   label: string;
@@ -45,4 +144,4 @@ declare function buildInspectPayload(result: InspectResult): Record<string, unkn
 declare function createExtension(deps?: ExtensionDeps): (pi: ExtensionAPI) => Promise<void>;
 declare const _default: (pi: ExtensionAPI) => Promise<void>;
 //#endregion
-export { ExtensionDeps, buildCompletionText, buildInspectPayload, compactWhitespace, createExtension, _default as default, isTerminalStatus, renderStatusLines, statusSupervisorId };
+export { type AvenorEventBus, type AvenorEventChannel, type AvenorEventMap, type AvenorRunStatus, CHANNEL_POLL_COMPLETED, CHANNEL_POLL_ERROR, CHANNEL_RUN_TERMINAL, ExtensionDeps, type PollCompletedPayload, type PollErrorPayload, type PollErrorPayloadInput, type PollErrorSource, type RunTerminalPayload, type RunTerminalPayloadInput, buildCompletionText, buildInspectPayload, compactWhitespace, createExtension, createPollCompletedPayload, createPollErrorPayload, createRunTerminalPayload, _default as default, emitAvenorEvent, isTerminalStatus, onAvenorEvent, renderStatusLines, spawnIdentityMetadata, statusSupervisorId };