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

package/README.md

@@ -120,7 +120,23 @@ This module defines the per-session presentation provider for interactive subage
 
 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.
+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.
+
+Tool-backed final payloads use `{ operation, parameters, result }`. Parameters contain the complete normalized public inputs. Results retain output, errors, outcome flags, and received metadata. Target references use root-relative agent paths. Router correlation IDs stay inside my-pi. Asynchronous custom messages carry result-only payloads rather than invented tool parameters. Pimote renders these fields as labeled data and uses its transcript Markdown renderer for free-form prose.
+
+Await starts only after complete tool arguments arrive. Omitted or empty `parameters.agents` means all agents. Named targets remain in the final parameters, including when a wait is interrupted or returns no child results. Send and respond retain progressive prose in `parameters.message`; send responses stream into `result.response`. Existing lifecycle event types remain unchanged.
+
+An await result contains the child completions returned by that tool call. Standalone completion operations replace asynchronous subagent custom messages only. Pimote restores persisted operations through provider hydration. The provider normalizes older saved payloads into the current envelope rather than making the client decode extension details.
+
+```ts
+{
+  operation: 'await',
+  parameters: { agents: [['worker']] },
+  result: {
+    statuses: [{ path: ['worker'], state: 'idle', output: 'Checks passed.' }]
+  }
+}
+```
 
 ## Pimote extensions — `@pimote/sdk/pimote`
 

package/dist/subagents/index.d.ts

@@ -1,4 +1,4 @@
 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';
+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, SubagentToolParameters, SubagentTopologyEvent, } from './presentation.js';

package/dist/subagents/presentation.d.ts

@@ -3,7 +3,9 @@ export type SubagentPresentationManifest = Readonly<{
     hiddenToolNames: readonly string[];
     hiddenCustomTypes: readonly string[];
 }>;
-export type SubagentOperationKind = 'send' | 'respond' | 'await' | 'delegation' | 'completion' | 'interrupt' | 'teardown' | 'resurrect';
+export type SubagentOperationKind = 'send' | 'message_received' | 'respond' | 'await' | 'delegation' | 'completion' | 'interrupt' | 'teardown' | 'resurrect';
+/** Normalized public tool inputs. Final operations carry complete values. */
+export type SubagentToolParameters = Readonly<Record<string, unknown>>;
 export type SubagentPlacement = Readonly<{
     toolCallId: string;
     contentIndex: number;
@@ -37,17 +39,19 @@ export type SubagentAwaitResult = Readonly<{
 }>;
 export type SubagentStartData = Readonly<{
     operation: 'send';
-    to: AgentPath;
-    request: string;
-    response: string;
-    phase: 'ready' | 'sending' | 'waiting' | 'responding';
+    parameters: SubagentToolParameters;
+    result: Readonly<{
+        response: string;
+        phase: 'ready' | 'sending' | 'waiting' | 'responding';
+    }>;
 }> | Readonly<{
     operation: 'respond';
-    body: string;
+    parameters: SubagentToolParameters;
+    result: Readonly<Record<string, unknown>>;
 }> | Readonly<{
     operation: 'await';
-    requested: readonly AgentPath[];
-    statuses: readonly SubagentAwaitStatus[];
+    parameters: SubagentToolParameters;
+    result: SubagentAwaitResult;
 }>;
 export type SubagentDeltaData = Readonly<{
     operation: 'send';
@@ -65,22 +69,34 @@ export type SubagentDeltaData = Readonly<{
 }>;
 export type SubagentEndData = Readonly<{
     operation: 'send';
-    to: AgentPath;
-    request: string;
-    response: string;
-    error?: string;
+    parameters?: SubagentToolParameters;
+    result: Readonly<Record<string, unknown>>;
 }> | Readonly<{
     operation: 'respond';
-    body: string;
-    error?: string;
+    parameters?: SubagentToolParameters;
+    result: Readonly<Record<string, unknown>>;
 }> | Readonly<{
     operation: 'await';
+    parameters: SubagentToolParameters;
     result: SubagentAwaitResult;
 }>;
 export type SubagentDelegatedChild = Readonly<{
     path: AgentPath;
     task: string;
     persona?: string;
+    status?: SubagentAwaitStatus['state'];
+}>;
+/** One agent touched by a teardown, carrying its final identity and usage. */
+export type SubagentAffectedAgent = Readonly<{
+    path: AgentPath;
+    sessionId: string;
+    incarnation: string;
+    state: SubagentAwaitStatus['state'];
+    usage: SubagentUsage;
+    /** Pre-attach usage the reported delta excludes; present only when non-zero. */
+    usageBaseline?: SubagentUsage;
+    output?: string;
+    error?: string;
 }>;
 export type SubagentInterruptTarget = Readonly<{
     path: AgentPath;
@@ -98,40 +114,41 @@ export type SubagentResurrectedAgent = Readonly<{
     incarnation: string;
     state: 'idle' | 'running';
     usage: SubagentUsage;
+    usageBaseline?: SubagentUsage;
     output?: string;
     error?: string;
 }>;
 export type SubagentFiniteData = Readonly<{
     operation: 'delegation';
-    children: readonly SubagentDelegatedChild[];
+    parameters: SubagentToolParameters;
+    result: Readonly<{
+        children: readonly SubagentDelegatedChild[];
+    }>;
 }> | Readonly<{
     operation: 'completion';
     result: SubagentCompletionResult;
 }> | Readonly<{
     operation: 'interrupt';
+    parameters: SubagentToolParameters;
     result: SubagentInterruptResult;
 }> | Readonly<{
     operation: 'teardown';
+    parameters: SubagentToolParameters;
     result: Readonly<{
-        affectedAgents: readonly Readonly<{
-            path: AgentPath;
-            sessionId: string;
-            incarnation: string;
-            state: SubagentAwaitStatus['state'];
-            usage: SubagentUsage;
-            output?: string;
-            error?: string;
-        }>[];
+        affectedAgents: readonly SubagentAffectedAgent[];
         status: 'removed' | 'already_removed' | 'not_found';
     }>;
 }> | Readonly<{
     operation: 'resurrect';
+    parameters: SubagentToolParameters;
     result: Readonly<{
         affectedAgents: readonly SubagentResurrectedAgent[];
     }>;
 }> | Readonly<{
     operation: 'protocol_error';
-    message: string;
+    result: Readonly<{
+        error: string;
+    }>;
 }>;
 export type SubagentFinalData = SubagentEndData | SubagentFiniteData;
 export type SubagentProtocolErrorData = Readonly<{

package/dist/subagents/types.d.ts

@@ -144,6 +144,8 @@ export type BorrowedSessionManager = Pick<AgentSession['sessionManager'], 'getEn
  */
 export type BorrowedAgentSession = Pick<AgentSession, 'sessionId' | 'sessionFile' | 'messages' | 'model' | 'thinkingLevel' | 'isStreaming' | 'isIdle' | 'isCompacting' | 'subscribe' | 'prompt' | 'steer' | 'followUp' | 'abort' | 'executeBash' | 'abortBash' | 'setModel' | 'cycleModel' | 'setThinkingLevel' | 'cycleThinkingLevel' | 'setAutoCompactionEnabled' | 'compact' | 'navigateTree' | 'getContextUsage' | 'getSessionStats'> & {
     readonly sessionManager: BorrowedSessionManager;
+    /** Current native steering queue, when supported by the provider. */
+    readonly getSteeringMessages?: AgentSession['getSteeringMessages'];
     /** Full-resync native state projection. */
     readonly state: Pick<AgentSession['state'], 'streamingMessage' | 'pendingToolCalls' | 'errorMessage'>;
 };

package/package.json

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