@pimote/sdk 0.16.0-rc.1 → 0.16.0-rc.2

package/README.md

@@ -5,6 +5,7 @@ Pimote's extensibility SDK provides APIs for [Pi](https://github.com/earendil-wo
 - **`@pimote/sdk/panels`** — push structured card data to the Pimote web client
 - **`@pimote/sdk/folders`** — type-only folder discovery entries for Pimote extensions
 - **`@pimote/sdk/activity`** — answer Pimote's idle-reap background-activity poll
+- **`@pimote/sdk/subagents`** — register or discover a typed per-session subagent provider
 - **`@pimote/sdk/pimote`** — define global `PimoteExtension` factories for sources and Settings files
 
 The root `@pimote/sdk` import re-exports session-scoped modules and Pimote extension types.
@@ -113,6 +114,14 @@ Detection uses pi's EventBus for a synchronous in-process round-trip — pimote'
 
 When pimote isn't present, the EventBus emit fires with no listener, `detect()` returns `null`, and there's zero overhead.
 
+## Subagents — `@pimote/sdk/subagents`
+
+This module defines the per-session presentation provider for interactive subagent views. A provider publishes a root-relative hierarchy, typed subagent operations, one ordered replay cursor, and leases to existing child sessions. Pimote discovers providers on the root session's EventBus; child runtimes stay owned by the extension that created them.
+
+Use `registerProvider(pi, provider)` to publish a provider. Use `discoverProvider(pi, onProvider)` or the discovery handle to find providers, including late registration and replacement. Registration and discovery return cleanup functions or handles. Cleanup stops discovery or registration; it does not dispose the provider or child sessions. The `SubagentPresentationProvider` contract, typed operation data, cursors, snapshots, and borrowed-session lease types are exported from this module. The my-pi subagents extension implements this provider for Pimote.
+
+Provider operations carry typed placement through `toolCallId` and `contentIndex`, or through the containing custom entry's `entryId`. Pimote's server projector suppresses the declared native renderers and places each operation as typed subagent content inside its originating assistant row, preserving surrounding native content order. Router correlation IDs stay inside my-pi. Pimote restores persisted operations through provider hydration rather than decoding extension details.
+
 ## Pimote extensions — `@pimote/sdk/pimote`
 
 Pimote extensions are process-global modules. The host loads direct JavaScript/TypeScript modules and entry-bearing directories from `$XDG_CONFIG_HOME/pimote/extensions/`. User-scoped Pi packages can contribute entries through their `pimote.extensions` manifest field. Project packages and `pi.extensions` entries never load in this host. A module listed in both sections is an explicit dual-host module and runs twice with independent lifecycles.

package/dist/subagents/index.d.ts

@@ -1,3 +1,4 @@
-export type { AgentPath, BorrowedAgentSession, BorrowedSessionManager, CommunicationData, CompletionData, DelegationData, FeedCursor, PiEventRef, ReplayResult, SubagentAwaitChildStatus, SubagentAwaitData, SubagentCapabilities, SubagentCompletionData, SubagentDelegationData, SubagentEvent, SubagentEventData, SubagentEventKind, SubagentLease, SubagentLeaseEvent, SubagentLifecycleData, SubagentMessageData, SubagentNode, SubagentNodeEventData, SubagentNodeSnapshot, SubagentNodeState, SubagentOperation, SubagentOwnerControlPort, SubagentProvider, SubagentProviderDiscovery, SubagentProviderRequest, SubagentProviderResponse, SubagentResurrectRequest, SubagentResurrectResult, SubagentSemanticFact, SubagentSnapshot, SubagentState, SubagentStopRequest, SubagentTeardownReason, SubagentTeardownResult, SubagentUsage, SubagentUsageSnapshot, SubagentRuntimeReplacedData, SubagentCostBreakdown, } from './types.js';
+export type { AgentPath, BorrowedAgentSession, BorrowedSessionManager, FeedCursor, PiEventRef, SubagentAwaitChildStatus, SubagentCapabilities, SubagentLease, SubagentLeaseEvent, SubagentNode, SubagentNodeEventData, SubagentNodeSnapshot, SubagentNodeState, SubagentOperation, SubagentOwnerControlPort, SubagentProviderDiscovery, SubagentProviderRequest, SubagentProviderResponse, SubagentResurrectRequest, SubagentResurrectResult, SubagentState, SubagentStopRequest, SubagentTeardownReason, SubagentTeardownResult, SubagentUsage, SubagentUsageSnapshot, SubagentRuntimeReplacedData, SubagentCostBreakdown, } from './types.js';
 export { SUBAGENT_PROVIDER_REQUEST, SUBAGENT_PROVIDER_RESPONSE, discover, discoverProvider, register, registerProvider } from './provider.js';
 export type { DiscoverProviderOptions } from './provider.js';
+export type { ActiveSubagentOperation, PersistedSubagentContent, SubagentDelegatedChild, SubagentInterruptResult, SubagentInterruptTarget, SubagentResurrectedAgent, SubagentAwaitResult, SubagentAwaitStatus, SubagentCompletionResult, SubagentDeltaData, SubagentDeltaEvent, SubagentEndData, SubagentEndEvent, SubagentFiniteData, SubagentFiniteEvent, SubagentFinalData, SubagentOperationKind, SubagentOperationTarget, SubagentPlacement, SubagentPresentationManifest, SubagentPresentationProvider, SubagentPresentationReplay, SubagentProtocolErrorData, SubagentProviderEvent, SubagentProviderSnapshot, SubagentStartData, SubagentStartEvent, SubagentTopologyEvent, } from './presentation.js';

package/dist/subagents/presentation.d.ts

@@ -0,0 +1,228 @@
+import type { AgentPath, BorrowedAgentSession, FeedCursor, PiEventRef, SubagentNodeEventData, SubagentNodeSnapshot, SubagentProviderControls, SubagentRuntimeReplacedData, SubagentUsage } from './types.js';
+export type SubagentPresentationManifest = Readonly<{
+    hiddenToolNames: readonly string[];
+    hiddenCustomTypes: readonly string[];
+}>;
+export type SubagentOperationKind = 'send' | 'respond' | 'await' | 'delegation' | 'completion' | 'interrupt' | 'teardown' | 'resurrect';
+export type SubagentPlacement = Readonly<{
+    toolCallId: string;
+    contentIndex: number;
+    entryId?: string;
+}> | Readonly<{
+    entryId: string;
+}>;
+export type SubagentOperationTarget = Readonly<{
+    operationId: string;
+    kind: SubagentOperationKind;
+    path: AgentPath;
+    placement?: SubagentPlacement;
+}>;
+export type SubagentAwaitStatus = Readonly<{
+    path: AgentPath;
+    state: 'running' | 'waiting' | 'idle' | 'errored' | 'dead' | 'stopped';
+    output?: string;
+    error?: string;
+    sessionId?: string;
+}>;
+export type SubagentCompletionResult = Readonly<{
+    state: 'idle' | 'errored' | 'dead' | 'stopped';
+    output?: string;
+    error?: string;
+    usage?: SubagentUsage;
+}>;
+export type SubagentAwaitResult = Readonly<{
+    statuses: readonly SubagentAwaitStatus[];
+    interrupted?: boolean;
+    error?: string;
+}>;
+export type SubagentStartData = Readonly<{
+    operation: 'send';
+    to: AgentPath;
+    request: string;
+    response: string;
+    phase: 'ready' | 'sending' | 'waiting' | 'responding';
+}> | Readonly<{
+    operation: 'respond';
+    body: string;
+}> | Readonly<{
+    operation: 'await';
+    requested: readonly AgentPath[];
+    statuses: readonly SubagentAwaitStatus[];
+}>;
+export type SubagentDeltaData = Readonly<{
+    operation: 'send';
+    field: 'request' | 'response';
+    delta: string;
+}> | Readonly<{
+    operation: 'send';
+    phase: 'waiting' | 'responding';
+}> | Readonly<{
+    operation: 'respond';
+    delta: string;
+}> | Readonly<{
+    operation: 'await';
+    statuses: readonly SubagentAwaitStatus[];
+}>;
+export type SubagentEndData = Readonly<{
+    operation: 'send';
+    to: AgentPath;
+    request: string;
+    response: string;
+    error?: string;
+}> | Readonly<{
+    operation: 'respond';
+    body: string;
+    error?: string;
+}> | Readonly<{
+    operation: 'await';
+    result: SubagentAwaitResult;
+}>;
+export type SubagentDelegatedChild = Readonly<{
+    path: AgentPath;
+    task: string;
+    persona?: string;
+}>;
+export type SubagentInterruptTarget = Readonly<{
+    path: AgentPath;
+    output?: string;
+    error?: string;
+}>;
+export type SubagentInterruptResult = Readonly<{
+    interrupted: readonly SubagentInterruptTarget[];
+    pending: readonly SubagentInterruptTarget[];
+    failed: readonly SubagentInterruptTarget[];
+}>;
+export type SubagentResurrectedAgent = Readonly<{
+    path: AgentPath;
+    sessionId: string;
+    incarnation: string;
+    state: 'idle' | 'running';
+    usage: SubagentUsage;
+    output?: string;
+    error?: string;
+}>;
+export type SubagentFiniteData = Readonly<{
+    operation: 'delegation';
+    children: readonly SubagentDelegatedChild[];
+}> | Readonly<{
+    operation: 'completion';
+    result: SubagentCompletionResult;
+}> | Readonly<{
+    operation: 'interrupt';
+    result: SubagentInterruptResult;
+}> | Readonly<{
+    operation: 'teardown';
+    result: Readonly<{
+        affectedAgents: readonly Readonly<{
+            path: AgentPath;
+            sessionId: string;
+            incarnation: string;
+            state: SubagentAwaitStatus['state'];
+            usage: SubagentUsage;
+            output?: string;
+            error?: string;
+        }>[];
+        status: 'removed' | 'already_removed' | 'not_found';
+    }>;
+}> | Readonly<{
+    operation: 'resurrect';
+    result: Readonly<{
+        affectedAgents: readonly SubagentResurrectedAgent[];
+    }>;
+}> | Readonly<{
+    operation: 'protocol_error';
+    message: string;
+}>;
+export type SubagentFinalData = SubagentEndData | SubagentFiniteData;
+export type SubagentProtocolErrorData = Readonly<{
+    operationId: string;
+    operation: SubagentOperationKind;
+    message: string;
+}>;
+export type ActiveSubagentOperation = Readonly<{
+    target: SubagentOperationTarget;
+    data: SubagentStartData;
+}>;
+type PresentationEventBase = Readonly<{
+    eventId: string;
+    cursor: FeedCursor;
+    target: SubagentOperationTarget;
+}>;
+export type SubagentStartEvent = PresentationEventBase & Readonly<{
+    type: 'subagent_start';
+    data: SubagentStartData;
+}>;
+export type SubagentDeltaEvent = PresentationEventBase & Readonly<{
+    type: 'subagent_delta';
+    data: SubagentDeltaData;
+}>;
+export type SubagentEndEvent = PresentationEventBase & Readonly<{
+    type: 'subagent_end';
+    state: 'complete' | 'error' | 'aborted';
+    data: SubagentEndData;
+}>;
+export type SubagentFiniteEvent = PresentationEventBase & Readonly<{
+    type: 'subagent_snapshot_event';
+    state: 'complete' | 'error' | 'aborted';
+    data: SubagentFinalData;
+}>;
+type SubagentTopologyData = Readonly<{
+    kind: 'node_added' | 'node_updated';
+    data: SubagentNodeEventData;
+}> | Readonly<{
+    kind: 'node_removed';
+    data: Readonly<{
+        node: SubagentNodeSnapshot;
+        reason: string;
+    }>;
+}> | Readonly<{
+    kind: 'runtime_replaced';
+    data: SubagentRuntimeReplacedData;
+}>;
+export type SubagentTopologyEvent = Readonly<{
+    eventId: string;
+    cursor: FeedCursor;
+    path: AgentPath;
+    relatedPiEvents: readonly PiEventRef[];
+}> & SubagentTopologyData;
+export type SubagentProviderEvent = SubagentTopologyEvent | SubagentStartEvent | SubagentDeltaEvent | SubagentEndEvent | SubagentFiniteEvent;
+export type PersistedSubagentContent = Readonly<{
+    operationId: string;
+    kind: SubagentOperationKind;
+    state: 'complete' | 'error' | 'aborted';
+    data: SubagentFinalData;
+}> & (Readonly<{
+    source: 'tool';
+    placement: Extract<SubagentPlacement, {
+        toolCallId: string;
+    }>;
+}> | Readonly<{
+    source: 'custom_entry';
+    placement?: Extract<SubagentPlacement, {
+        entryId: string;
+    }>;
+}>);
+export type SubagentProviderSnapshot = Readonly<{
+    manifest: SubagentPresentationManifest;
+    nodes: readonly SubagentNodeSnapshot[];
+    cursor: FeedCursor;
+    activeOperations: readonly ActiveSubagentOperation[];
+}>;
+export type SubagentPresentationReplay = Readonly<{
+    kind: 'events';
+    cursor: FeedCursor;
+    events: readonly SubagentProviderEvent[];
+}> | Readonly<{
+    kind: 'snapshot_required';
+    reason: 'epoch_changed' | 'history_unavailable';
+}>;
+export interface SubagentPresentationProvider extends SubagentProviderControls {
+    snapshot(): SubagentProviderSnapshot;
+    subscribe(listener: (event: SubagentProviderEvent) => void): () => void;
+    replay(after?: FeedCursor): SubagentPresentationReplay;
+    rehydrate(input: {
+        session: BorrowedAgentSession;
+        path: AgentPath;
+    }): Promise<void>;
+}
+export {};

package/dist/subagents/presentation.js

@@ -0,0 +1 @@
+export {};

package/dist/subagents/provider.d.ts

@@ -1,13 +1,15 @@
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-import type { SubagentEventBusOwner, SubagentProvider, SubagentProviderDiscovery } from './types.js';
+import type { SubagentEventBusOwner, SubagentProviderDiscovery } from './types.js';
+import type { SubagentPresentationProvider } from './presentation.js';
+type RegisteredProvider = SubagentPresentationProvider;
 /** EventBus channel emitted by a Pimote host to discover a provider. */
 export declare const SUBAGENT_PROVIDER_REQUEST: "pimote:subagents:request";
 /** EventBus channel carrying the currently registered provider. */
 export declare const SUBAGENT_PROVIDER_RESPONSE: "pimote:subagents:response";
-export declare function registerProvider(owner: SubagentEventBusOwner | ExtensionAPI, provider: SubagentProvider): () => void;
+export declare function registerProvider(owner: SubagentEventBusOwner | ExtensionAPI, provider: RegisteredProvider): () => void;
 export interface DiscoverProviderOptions {
     /** Called whenever the provider first appears or is replaced. */
-    onProvider?: (provider: SubagentProvider) => void;
+    onProvider?: (provider: RegisteredProvider) => void;
 }
 /**
  * Discover the provider on a session EventBus and keep listening for late
@@ -19,9 +21,10 @@ export interface DiscoverProviderOptions {
  * after installing its response listener, so a provider registered before or
  * during the handshake cannot be missed.
  */
-export declare function discoverProvider(owner: SubagentEventBusOwner | ExtensionAPI, onProvider: (provider: SubagentProvider) => void): () => void;
+export declare function discoverProvider(owner: SubagentEventBusOwner | ExtensionAPI, onProvider: (provider: RegisteredProvider) => void): () => void;
 export declare function discoverProvider(owner: SubagentEventBusOwner | ExtensionAPI, options?: DiscoverProviderOptions): SubagentProviderDiscovery;
 /** Short alias for hosts that use the request/response verb. */
 export declare const discover: typeof discoverProvider;
 /** Short alias for extensions that use the registration verb. */
 export declare const register: typeof registerProvider;
+export {};

package/dist/subagents/provider.js

@@ -91,7 +91,7 @@ export function discoverProvider(owner, callbackOrOptions) {
     };
     if (callback)
         return close;
-    return {
+    const discovery = {
         get provider() {
             return current;
         },
@@ -116,6 +116,7 @@ export function discoverProvider(owner, callbackOrOptions) {
         },
         close,
     };
+    return discovery;
 }
 /** Short alias for hosts that use the request/response verb. */
 export const discover = discoverProvider;

package/dist/subagents/types.d.ts

@@ -13,46 +13,6 @@ export type PiEventRef = Readonly<{
     toolCallId?: string;
     kind: 'message' | 'tool_call' | 'custom_message' | 'lifecycle';
 }>;
-export type SubagentEventKind = 'node_added' | 'node_updated' | 'node_removed' | 'runtime_replaced' | 'delegation' | 'message_thread' | 'await_started' | 'child_settled' | 'await_interrupted' | 'await_released' | 'completion' | 'interrupt' | 'teardown' | 'resurrect';
-export type SubagentDelegationData = Readonly<{
-    invocationId: string;
-    awaitsResult: boolean;
-    children: readonly Readonly<{
-        path: AgentPath;
-        task: string;
-        persona?: string;
-    }>[];
-}>;
-/** Alias used by the my-pi provider implementation. */
-export type DelegationData = SubagentDelegationData;
-export type SubagentCompletionData = Readonly<{
-    status: 'idle' | 'errored' | 'dead' | 'stopped';
-    output?: string;
-    error?: string;
-    usage?: SubagentUsage;
-}> & (Readonly<{
-    delivery: 'awaited';
-    invocationId: string;
-}> | Readonly<{
-    delivery: 'asynchronous';
-    invocationId?: string;
-}>);
-/** Alias used by the my-pi provider implementation. */
-export type CompletionData = SubagentCompletionData;
-export type SubagentMessageData = Readonly<{
-    from: AgentPath;
-    to: AgentPath;
-    text: string;
-    correlationId?: string;
-    responseExpected: boolean;
-}> & (Readonly<{
-    phase: 'sent' | 'received' | 'response';
-}> | Readonly<{
-    phase: 'failure';
-    error: string;
-}>);
-/** Alias used by the my-pi provider implementation. */
-export type CommunicationData = SubagentMessageData;
 /** One child state included in await progress and settlement facts. */
 export type SubagentAwaitChildStatus = Readonly<{
     path: AgentPath;
@@ -61,31 +21,6 @@ export type SubagentAwaitChildStatus = Readonly<{
     error?: string;
     sessionId?: string;
 }>;
-/** Await progress, interruption, and release details. */
-export type SubagentAwaitData = Readonly<{
-    invocationId?: string;
-    requested?: readonly AgentPath[];
-    statuses?: readonly SubagentAwaitChildStatus[];
-    path?: AgentPath;
-    output?: string;
-    error?: string;
-    reason?: 'settled' | 'detach' | 'stop' | 'message';
-    message?: SubagentMessageData;
-    /** Provider implementations can carry additional typed await facts. */
-    readonly [key: string]: unknown;
-}>;
-/** Lifecycle operation details carried by interrupt, teardown, and resurrection facts. */
-export type SubagentLifecycleData = Readonly<{
-    operation?: 'interrupt' | 'teardown' | 'resurrect';
-    outcome?: string;
-    path?: AgentPath;
-    output?: string;
-    error?: string;
-    sessionId?: string;
-    recovery?: Readonly<Record<string, unknown>>;
-    /** Provider implementations can carry operation-specific recovery data. */
-    readonly [key: string]: unknown;
-}>;
 /** A public node projection carried by topology events and snapshots. */
 export type SubagentNodeSnapshot = Readonly<{
     path: AgentPath;
@@ -104,7 +39,6 @@ export type SubagentNodeSnapshot = Readonly<{
     contextFill?: number;
     channels: readonly string[];
     waitingFor: readonly AgentPath[];
-    pendingCorrelations: readonly string[];
     hasSubgroup: boolean;
     lastOutput?: string;
     lastError?: string;
@@ -120,44 +54,6 @@ export type SubagentRuntimeReplacedData = Readonly<{
     oldSessionId: string;
     newSessionId: string;
 }>;
-export type SubagentEventData = Readonly<{
-    kind: 'node_added' | 'node_updated';
-    data: SubagentNodeEventData;
-}> | Readonly<{
-    kind: 'node_removed';
-    data: Readonly<{
-        node: SubagentNodeSnapshot;
-        reason: string;
-    }>;
-}> | Readonly<{
-    kind: 'runtime_replaced';
-    data: SubagentRuntimeReplacedData;
-}> | Readonly<{
-    kind: 'delegation';
-    data: SubagentDelegationData;
-}> | Readonly<{
-    kind: 'message_thread';
-    data: SubagentMessageData;
-}> | Readonly<{
-    kind: 'await_started' | 'child_settled' | 'await_interrupted' | 'await_released';
-    data: SubagentAwaitData;
-}> | Readonly<{
-    kind: 'completion';
-    data: SubagentCompletionData;
-}> | Readonly<{
-    kind: 'interrupt' | 'teardown' | 'resurrect';
-    data: SubagentLifecycleData;
-}>;
-/** A semantic overlay. Native Pi entries remain the transcript source. */
-export type SubagentSemanticFact = Readonly<{
-    eventId: string;
-    path: AgentPath;
-    relatedPiEvents: readonly PiEventRef[];
-}> & SubagentEventData;
-/** A typed live feed event with its provider-owned replay cursor. */
-export type SubagentEvent = SubagentSemanticFact & Readonly<{
-    cursor: FeedCursor;
-}>;
 export type SubagentState = 'running' | 'waiting' | 'idle' | 'errored' | 'dead';
 export type SubagentNodeState = SubagentState;
 export type SubagentCostBreakdown = Readonly<{
@@ -176,19 +72,6 @@ export type SubagentUsage = Readonly<{
     costBreakdown?: SubagentCostBreakdown;
     turns: number;
 }>;
-/** Snapshot boundary for the current provider epoch. */
-export type SubagentSnapshot = Readonly<{
-    cursor: FeedCursor;
-    nodes: readonly SubagentNodeSnapshot[];
-}>;
-export type ReplayResult = Readonly<{
-    kind: 'events';
-    cursor: FeedCursor;
-    events: readonly SubagentEvent[];
-}> | Readonly<{
-    kind: 'snapshot_required';
-    reason: 'epoch_changed' | 'history_unavailable';
-}>;
 export type SubagentTeardownReason = 'not_found' | 'already_removed' | 'removed';
 export type SubagentTeardownResult = Readonly<{
     path: AgentPath;
@@ -287,11 +170,8 @@ export interface SubagentOwnerControlPort {
     stop(request: SubagentStopRequest): Promise<void>;
     resurrect(request: SubagentResurrectRequest): Promise<SubagentResurrectResult>;
 }
-/** Per-session provider feed and borrowed-runtime contract. */
-export interface SubagentProvider {
-    subscribe(listener: (event: SubagentEvent) => void): () => void;
-    snapshot(): SubagentSnapshot;
-    replay(after?: FeedCursor): ReplayResult;
+/** Provider-owned leases and guarded lifecycle controls shared by the presentation seam. */
+export interface SubagentProviderControls {
     acquire(path: AgentPath): Promise<SubagentLease>;
     teardown(path: AgentPath, incarnation: string): Promise<SubagentTeardownResult>;
     stop(request: SubagentStopRequest): Promise<void>;
@@ -304,16 +184,16 @@ export type SubagentProviderRequest = Readonly<{
 }>;
 /** EventBus response payload used by provider registration and discovery. */
 export type SubagentProviderResponse = Readonly<{
-    provider: SubagentProvider;
+    provider: import('./presentation.js').SubagentPresentationProvider;
 }>;
 /** A live discovery handle that tracks late registration and replacement. */
 export interface SubagentProviderDiscovery {
-    readonly provider: SubagentProvider | undefined;
+    readonly provider: import('./presentation.js').SubagentPresentationProvider | undefined;
     /** Alias for callers that model discovery as a mutable current value. */
-    readonly current: SubagentProvider | undefined;
-    subscribe(listener: (provider: SubagentProvider | undefined) => void): () => void;
+    readonly current: import('./presentation.js').SubagentPresentationProvider | undefined;
+    subscribe(listener: (provider: import('./presentation.js').SubagentPresentationProvider | undefined) => void): () => void;
     /** Alias for subscribe, useful at the host event boundary. */
-    onProvider(listener: (provider: SubagentProvider | undefined) => void): () => void;
+    onProvider(listener: (provider: import('./presentation.js').SubagentPresentationProvider | undefined) => void): () => void;
     close(): void;
 }
 /** Extract the EventBus from either ExtensionAPI or an EventBus itself. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pimote/sdk",
-  "version": "0.16.0-rc.1",
+  "version": "0.16.0-rc.2",
   "description": "Pimote extensibility SDK: panel cards, background-activity reap guard, Pimote extensions, and source-only folder discovery",
   "type": "module",
   "license": "MIT",