@pimote/sdk 0.15.5 → 0.16.0-rc.2

package/README.md

@@ -1,12 +1,14 @@
 # @pimote/sdk
 
-Pimote's extensibility SDK — everything a [pi](https://github.com/earendil-works/pi) extension imports to talk to [pimote](https://github.com/alennartz/pimote). One subpath module per extension seam:
+Pimote's extensibility SDK provides APIs for [Pi](https://github.com/earendil-works/pi) session extensions and process-global Pimote extensions. These hosts have separate entry points:
 
-- **`@pimote/sdk/panels`** — push structured card data to the pimote web client
-- **`@pimote/sdk/folders`** — contribute folder discovery and creation to pimote's folder layer
-- **`@pimote/sdk/activity`** — answer pimote's idle-reap background-activity poll
+- **`@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 all modules.
+The root `@pimote/sdk` import re-exports session-scoped modules and Pimote extension types.
 
 ## Install
 
@@ -112,57 +114,46 @@ 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.
 
-## Folders — `@pimote/sdk/folders`
+## 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.
 
-Type-only module for user-authored folder-source modules: pimote scans a folder-sources directory (default `~/.config/pimote/folder-sources`, configurable via `folderSourcesDir`), dynamic-imports every JS/TS module it finds, and collects each module's exported `sources` and `creators` arrays. Sources contribute repos and hub folders to pimote's folder layer; creators make new folders from user-supplied form params.
+## Pimote extensions — `@pimote/sdk/pimote`
 
-### Writing a module
+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.
 
 ```ts
-// ~/.config/pimote/folder-sources/my-source.ts
-import type { FolderSource, FolderCreator } from '@pimote/sdk/folders';
+import type { PimoteExtension } from '@pimote/sdk/pimote';
 
-export const sources: FolderSource[] = [
-  {
+const extension: PimoteExtension = (context) => {
+  context.folders.registerSource({
     id: 'my-source',
     async list() {
-      return [
-        {
-          kind: 'repo',
-          path: '/home/me/work/api',
-          name: 'api',
-          branch: 'main',
-          dirty: false,
-          ahead: 0,
-          behind: 0,
-        },
-      ];
+      return [{ kind: 'repo', path: '/home/me/work/api', name: 'api', branch: 'main', dirty: false, ahead: 0, behind: 0 }];
     },
-  },
-];
-
-export const creators: FolderCreator[] = [
-  {
-    id: 'my-creator',
-    describe() {
-      return { label: 'New API folder', paramSchema: { name: 'string', tags: 'string[]' } };
-    },
-    async create(params) {
-      const path = `/home/me/work/${String(params.name)}`;
-      // ... scaffold the folder ...
-      return { path };
-    },
-  },
-];
+  });
+  context.settings.registerFile('./instructions.md');
+  context.on('shutdown', async () => {
+    // Release process-global resources here.
+  });
+};
+
+export default extension;
 ```
 
-### `FolderSource`
+`registerSource()` contributes folder discovery. `registerFile()` contributes a global Settings tab. Relative file paths resolve from the extension entry module, while absolute and leading-`~` paths remain explicit. Registrations become inert after shutdown or reload. The host replaces all extension registrations on `/reload`, awaits shutdown handlers, and reports isolated diagnostics while continuing valid modules. Shutdown handlers have no timeout, so an extension must let them settle. Folder creation remains a Pimote core capability, so the public SDK has no external creator registration seam.
 
-The discovery seam. `list()` is called on cache miss and must return the current entries without mutating anything. The optional `onFolderOpen(folderPath)` hook is awaited before any open of a listed entry proceeds — whether the target exists on disk or not, and from every open path (row click, new session, manager tool). Sources self-filter by path: probe the disk and scaffold if the entry is theirs and missing; do other open-time work otherwise. A thrown error aborts the open and surfaces the message to the user.
+## Folders — `@pimote/sdk/folders`
 
-### `FolderCreator`
+This type-only module defines the source discovery seam used by `PimoteExtensionContext.folders.registerSource()`. Sources contribute repos and hubs. Their optional `onFolderOpen(folderPath)` hook runs before an open and can provision a missing entry. Pimote materializes standard hubs and owns the dashboard and manager folder-creation flows.
 
-The creation seam. `describe()` returns the human-readable form for the creation UI — a `label` plus a `paramSchema` mapping param names to `'string' | 'string[]'`. `create(params)` receives the user-supplied params, makes the folder, and returns its `{ path }`. Pimote resolves that path to the folder's canonical filesystem identity before seeding, broadcasting, or opening a session, so a creator can return the lexical path it used to reach the folder. The path must name the successfully created folder.
+### `FolderSource`
+
+`list()` returns current entries without mutation. The optional `onFolderOpen(folderPath)` hook is awaited before row, new-session, and manager opens. A thrown error aborts the open.
 
 ### Entry shapes
 
@@ -187,7 +178,7 @@ interface HubSourceEntry {
 
 ### `RepoInfo`
 
-Repo facts as contributed by sources: `path`, `name`, `branch` (`string | null`), `dirty`, `ahead`, `behind`, and optional `lastActivity` (epoch ms), `missing` (repo path no longer exists on disk), and `tags`. It mirrors pimote's wire `RepoInfo` type — same name, same fields — so extension authors can write `interface MyEntry extends RepoInfo` against the SDK alone.
+Repo facts: `path`, `name`, `branch` (`string | null`), `dirty`, `ahead`, `behind`, and optional `worktreePath`, `lastActivity` (epoch ms), `missing` (repo path no longer exists on disk), and `tags`. In a worktree hub row, `path` stays the canonical source path; `worktreePath` identifies the nested checkout whose Git status Pimote reports. It mirrors Pimote's wire `RepoInfo` type — same name, same fields — so extension authors can write `interface MyEntry extends RepoInfo` against the SDK alone.
 
 ## Activity — `@pimote/sdk/activity`
 
@@ -227,22 +218,12 @@ The pimote-side twin, used by the server's idle reaper. Performs the synchronous
 
 ### 0.15.0 (0.x breaking)
 
-The discovery/creation seam is renamed to folder vocabulary — "project" is gone from the SDK surface. No compatibility type aliases exist; source modules must be updated against these successors:
-
-| Retired name (≤0.14.x)                         | Replacement (0.15.0)                                                                   |
-| ---------------------------------------------- | -------------------------------------------------------------------------------------- |
-| `@pimote/sdk/projects` subpath                 | `@pimote/sdk/folders`                                                                  |
-| `ProjectSource`                                | `FolderSource`                                                                         |
-| `ProjectCreator`                               | `FolderCreator`                                                                        |
-| `ProjectCreatorDescriptor`                     | `FolderCreatorDescriptor`                                                              |
-| `ProjectCreatorParamType`                      | `FolderCreatorParamType`                                                               |
-| `MultiRepoSourceEntry`                         | `HubSourceEntry`                                                                       |
-| entry discriminator `kind: 'project'`          | entry discriminator `kind: 'hub'`                                                      |
-| `onProjectOpen(projectPath)`                   | `onFolderOpen(folderPath)`                                                             |
-| config key `projectSourcesDir`                 | `folderSourcesDir` (legacy key still read as a deprecated fallback)                    |
-| sources dir `~/.config/pimote/project-sources` | `~/.config/pimote/folder-sources` (legacy dir still loaded when the new one is absent) |
-
-Every name in the left column is retired; each is listed here only so existing modules can be migrated. The wire command for the built-in creation flow is likewise renamed (`create_project` → `create_folder`).
+The SDK now exposes two independent hosts:
+
+- `@pimote/sdk/pimote` runs process-global Pimote extensions for folder sources and Settings files.
+- `@pimote/sdk` and its `panels` and `activity` modules run inside Pi sessions through EventBus bridges.
+
+Folder creation is a Pimote core operation. External creation registration was removed. Existing source modules must move their exported source arrays into a default `PimoteExtension` factory and call `context.folders.registerSource()`. Pi package manifests can list separate `pi.extensions` and `pimote.extensions` entries; Pimote loads only the latter from user scope.
 
 ## License
 

package/dist/folders/index.d.ts

@@ -1 +1 @@
-export type { FolderSource, FolderCreator, FolderCreatorDescriptor, FolderCreatorParamType, SourceEntry, RepoSourceEntry, HubSourceEntry, RepoInfo } from './types.js';
+export type { FolderSource, SourceEntry, RepoSourceEntry, HubSourceEntry, RepoInfo } from './types.js';

package/dist/folders/types.d.ts

@@ -10,6 +10,9 @@ export interface RepoInfo {
     /** Commits ahead of upstream; 0 when unknown. */
     ahead: number;
     behind: number;
+    /** Present for worktree hub members: the nested checkout inside the hub
+     *  whose git facts these are. The canonical `path` stays the source repo. */
+    worktreePath?: string;
     /** Epoch ms of last session activity in this repo, when known. */
     lastActivity?: number;
     /** True when the repo path no longer exists on disk (deleted member, broken symlink). */
@@ -17,8 +20,6 @@ export interface RepoInfo {
     /** Effective tags (user + source-contributed). Absent when untagged. */
     tags?: string[];
 }
-/** Human-readable parameter type for a creator form field. */
-export type FolderCreatorParamType = 'string' | 'string[]';
 /** A repo entry contributed to the discovery index (feeds single-repo folders). */
 export interface RepoSourceEntry extends RepoInfo {
     kind: 'repo';
@@ -41,8 +42,8 @@ export type SourceEntry = RepoSourceEntry | HubSourceEntry;
 /**
  * Extensible discovery seam: a source contributes repos and hub
  * folders to the folder layer. Built in: the filesystem walker over
- * configured roots. User-authored sources are dynamic-imported from the
- * configured folder-sources directory.
+ * configured roots. User-authored sources are registered by the global
+ * Pimote extension host.
  */
 export interface FolderSource {
     readonly id: string;
@@ -57,27 +58,3 @@ export interface FolderSource {
      */
     onFolderOpen?(folderPath: string): Promise<void>;
 }
-/** Human-readable description of a creator's form, for the creation UI. */
-export interface FolderCreatorDescriptor {
-    label: string;
-    paramSchema: Record<string, FolderCreatorParamType>;
-}
-/**
- * Extensible creation seam: a creator makes a new folder from
- * user-supplied params. Built in: mkdir + git init. User-authored creators
- * are dynamic-imported from the configured folder-sources directory.
- */
-export interface FolderCreator {
-    readonly id: string;
-    /** Human-readable description for the creation UI. */
-    describe(): FolderCreatorDescriptor;
-    /**
-     * Make the folder and return its path. Pimote resolves the path to its
-     * canonical filesystem identity before seeding, broadcasting, or opening a
-     * session, so a creator can return the lexical path it used to reach the
-     * folder. The path must name the successfully created folder.
-     */
-    create(params: Record<string, unknown>): Promise<{
-        path: string;
-    }>;
-}

package/dist/index.d.ts

@@ -1,3 +1,5 @@
 export * from './panels/index.js';
 export * from './folders/index.js';
 export * from './activity/index.js';
+export type { PimoteExtension, PimoteExtensionContext, PimoteShutdownHandler } from './pimote/index.js';
+export * from './subagents/index.js';

package/dist/index.js

@@ -1,3 +1,4 @@
 export * from './panels/index.js';
 export * from './folders/index.js';
 export * from './activity/index.js';
+export * from './subagents/index.js';

package/dist/pimote/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A server-global Pimote extension.
+ *
+ * The host creates a fresh context for each runtime. Extensions must keep all
+ * registrations behind that context because the host invalidates it on reload.
+ */
+export type PimoteExtension = (context: PimoteExtensionContext) => void | Promise<void>;
+/**
+ * Context exposed to server-global Pimote extensions.
+ *
+ * This is intentionally separate from pi's session-scoped ExtensionAPI. Pimote
+ * extensions contribute folder discovery and global settings files only.
+ */
+export interface PimoteExtensionContext {
+    readonly folders: {
+        registerSource(source: import('../folders/types.js').FolderSource): void;
+    };
+    readonly settings: {
+        registerFile(path: string): void;
+    };
+    on(event: 'shutdown', handler: () => void | Promise<void>): () => void;
+}
+export type PimoteShutdownHandler = () => void | Promise<void>;

package/dist/pimote/index.js

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

package/dist/subagents/index.d.ts

@@ -0,0 +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';

package/dist/subagents/index.js

@@ -0,0 +1 @@
+export { SUBAGENT_PROVIDER_REQUEST, SUBAGENT_PROVIDER_RESPONSE, discover, discoverProvider, register, registerProvider } from './provider.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

@@ -0,0 +1,30 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+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: RegisteredProvider): () => void;
+export interface DiscoverProviderOptions {
+    /** Called whenever the provider first appears or is replaced. */
+    onProvider?: (provider: RegisteredProvider) => void;
+}
+/**
+ * Discover the provider on a session EventBus and keep listening for late
+ * registration or replacement.
+ *
+ * With a callback, the return value is an unsubscribe function. Without a
+ * callback, the return value is a discovery handle whose `provider` getter
+ * reflects the latest registration. In both forms discovery emits one request
+ * 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: 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

@@ -0,0 +1,124 @@
+/** EventBus channel emitted by a Pimote host to discover a provider. */
+export const SUBAGENT_PROVIDER_REQUEST = 'pimote:subagents:request';
+/** EventBus channel carrying the currently registered provider. */
+export const SUBAGENT_PROVIDER_RESPONSE = 'pimote:subagents:response';
+/**
+ * Narrow an ExtensionAPI/EventBus-like value to its EventBus.
+ *
+ * The SDK keeps this adapter structural so extensions can use the same seam in
+ * tests without constructing a complete ExtensionAPI object.
+ */
+function eventBusOf(owner) {
+    if ('events' in owner)
+        return owner.events;
+    return owner;
+}
+function providerFrom(data) {
+    if (data && typeof data === 'object' && 'provider' in data) {
+        const provider = data.provider;
+        return provider && typeof provider === 'object' ? provider : undefined;
+    }
+    return data && typeof data === 'object' ? data : undefined;
+}
+function response(provider) {
+    return { provider };
+}
+/**
+ * One provider registration per session EventBus.
+ *
+ * Registration is a live responder rather than a one-shot value. A host can
+ * begin discovery before the extension binds, and a later registration or
+ * replacement is delivered immediately. Calling this again on the same bus
+ * deactivates the previous responder. The function never owns or disposes the
+ * provider; the owner controls its lifecycle.
+ */
+const registrations = new WeakMap();
+export function registerProvider(owner, provider) {
+    const bus = eventBusOf(owner);
+    const key = bus;
+    const previous = registrations.get(key);
+    previous?.unsubscribeRequest();
+    if (previous)
+        previous.active = false;
+    const registration = {
+        active: true,
+        unsubscribeRequest: () => undefined,
+    };
+    registration.unsubscribeRequest = bus.on(SUBAGENT_PROVIDER_REQUEST, () => {
+        if (!registration.active)
+            return;
+        bus.emit(SUBAGENT_PROVIDER_RESPONSE, response(provider));
+    });
+    registrations.set(key, registration);
+    // Hosts that already started discovery receive a replacement without a
+    // second request. Hosts that have not started simply have this value ignored.
+    bus.emit(SUBAGENT_PROVIDER_RESPONSE, response(provider));
+    return () => {
+        if (!registration.active)
+            return;
+        registration.active = false;
+        registration.unsubscribeRequest();
+        if (registrations.get(key) === registration)
+            registrations.delete(key);
+    };
+}
+export function discoverProvider(owner, callbackOrOptions) {
+    const bus = eventBusOf(owner);
+    let current;
+    let closed = false;
+    const listeners = new Set();
+    const callback = typeof callbackOrOptions === 'function' ? callbackOrOptions : callbackOrOptions?.onProvider;
+    if (callback)
+        listeners.add((provider) => {
+            if (provider)
+                callback(provider);
+        });
+    const publish = (provider) => {
+        if (closed || provider === current)
+            return;
+        current = provider;
+        for (const listener of [...listeners])
+            listener(provider);
+    };
+    const unsubscribeResponse = bus.on(SUBAGENT_PROVIDER_RESPONSE, (data) => publish(providerFrom(data)));
+    bus.emit(SUBAGENT_PROVIDER_REQUEST, {});
+    const close = () => {
+        if (closed)
+            return;
+        closed = true;
+        unsubscribeResponse();
+        listeners.clear();
+    };
+    if (callback)
+        return close;
+    const discovery = {
+        get provider() {
+            return current;
+        },
+        get current() {
+            return current;
+        },
+        subscribe(listener) {
+            if (closed)
+                return () => undefined;
+            listeners.add(listener);
+            if (current)
+                listener(current);
+            return () => listeners.delete(listener);
+        },
+        onProvider(listener) {
+            if (closed)
+                return () => undefined;
+            listeners.add(listener);
+            if (current)
+                listener(current);
+            return () => listeners.delete(listener);
+        },
+        close,
+    };
+    return discovery;
+}
+/** Short alias for hosts that use the request/response verb. */
+export const discover = discoverProvider;
+/** Short alias for extensions that use the registration verb. */
+export const register = registerProvider;

package/dist/subagents/types.d.ts

@@ -0,0 +1,202 @@
+import type { AgentSession, EventBus } from '@earendil-works/pi-coding-agent';
+/** Root-relative identity of a my-pi child runtime. */
+export type AgentPath = readonly string[];
+/** Provider-owned replay position. Pimote keeps this separate from parent cursors. */
+export type FeedCursor = Readonly<{
+    epoch: string;
+    sequence: number;
+}>;
+/** Native Pi transcript/session provenance for one semantic event. */
+export type PiEventRef = Readonly<{
+    sessionId: string;
+    entryId?: string;
+    toolCallId?: string;
+    kind: 'message' | 'tool_call' | 'custom_message' | 'lifecycle';
+}>;
+/** One child state included in await progress and settlement facts. */
+export type SubagentAwaitChildStatus = Readonly<{
+    path: AgentPath;
+    state: 'running' | 'waiting' | 'idle' | 'errored' | 'dead' | 'stopped';
+    output?: string;
+    error?: string;
+    sessionId?: string;
+}>;
+/** A public node projection carried by topology events and snapshots. */
+export type SubagentNodeSnapshot = Readonly<{
+    path: AgentPath;
+    /** Stable for runtime replacement. Changes when a path is removed or reused. */
+    incarnation: string;
+    sessionId: string;
+    task?: string;
+    persona?: string;
+    personaIcon?: string;
+    model?: string;
+    thinkingLevel?: string;
+    state: SubagentState;
+    activity?: string;
+    usage: SubagentUsage;
+    /** Context fill as an integer percentage from 0 through 100. */
+    contextFill?: number;
+    channels: readonly string[];
+    waitingFor: readonly AgentPath[];
+    hasSubgroup: boolean;
+    lastOutput?: string;
+    lastError?: string;
+}>;
+/** Compatibility alias for consumers that call hierarchy rows nodes. */
+export type SubagentNode = SubagentNodeSnapshot;
+export type SubagentUsageSnapshot = SubagentUsage;
+/** Topology events accept the complete projection and old session-id facts. */
+export type SubagentNodeEventData = SubagentNodeSnapshot | Readonly<{
+    sessionId: string;
+}>;
+export type SubagentRuntimeReplacedData = Readonly<{
+    oldSessionId: string;
+    newSessionId: string;
+}>;
+export type SubagentState = 'running' | 'waiting' | 'idle' | 'errored' | 'dead';
+export type SubagentNodeState = SubagentState;
+export type SubagentCostBreakdown = Readonly<{
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+}>;
+/** Provider usage accumulated for one child runtime. */
+export type SubagentUsage = Readonly<{
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cost: number;
+    costBreakdown?: SubagentCostBreakdown;
+    turns: number;
+}>;
+export type SubagentTeardownReason = 'not_found' | 'already_removed' | 'removed';
+export type SubagentTeardownResult = Readonly<{
+    path: AgentPath;
+    removed: boolean;
+    sessionId?: string;
+    incarnation?: string;
+    reason?: SubagentTeardownReason;
+}>;
+/** Guarded request to stop the child that owns one public path incarnation. */
+export type SubagentStopRequest = Readonly<{
+    path: AgentPath;
+    incarnation: string;
+    /** The host rejects a request for a replacement runtime at this path. */
+    expectedSessionId: string;
+}>;
+/** Input to the normal my-pi resurrection path. */
+export type SubagentResurrectRequest = Readonly<{
+    /** Saved child session id returned by teardown. */
+    sessionId: string;
+    /** Owning root-relative parent path. */
+    parentPath: AgentPath;
+    /** New local id under `parentPath`. */
+    localId: string;
+    task: string;
+    channels: readonly string[];
+    model?: string;
+}>;
+/** Result of a normal resurrection operation. */
+export type SubagentResurrectResult = Readonly<{
+    path: AgentPath;
+    node?: SubagentNodeSnapshot;
+    sessionId?: string;
+    incarnation?: string;
+}>;
+/** Operations that preserve the identity of the borrowed child runtime. */
+export type SubagentOperation = 'prompt' | 'steer' | 'follow_up' | 'stop' | 'bash' | 'abort_bash' | 'set_model' | 'cycle_model' | 'set_thinking_level' | 'cycle_thinking_level' | 'set_auto_compaction' | 'compact' | 'tree' | 'completion' | 'state' | 'meta';
+/** Provider-owned child capabilities. It never exposes extension machinery. */
+export interface SubagentCapabilities {
+    /** Explicitly admitted identity-preserving operations. */
+    readonly operations?: readonly SubagentOperation[];
+    /** Whether the child renderer can expose a view. */
+    readonly renderer?: Readonly<{
+        visible?: boolean;
+        [key: string]: unknown;
+    }>;
+    /** Child-local model resolution and settings. */
+    readonly resolveModel?: (provider: string, modelId: string) => Promise<unknown> | unknown;
+    readonly getSettings?: () => unknown;
+    /** Native bash admission and dispatch. */
+    readonly nativeBash?: Readonly<{
+        admitted?: boolean;
+        execute?: (...args: readonly unknown[]) => Promise<unknown> | unknown;
+        abort?: (...args: readonly unknown[]) => Promise<void> | void;
+        [key: string]: unknown;
+    }>;
+    readonly executeBash?: (...args: readonly unknown[]) => Promise<unknown> | unknown;
+    /** Filtered command and argument-completion descriptors. */
+    readonly getCommands?: (...args: readonly unknown[]) => Promise<unknown> | unknown;
+    readonly completeArgs?: (...args: readonly unknown[]) => Promise<unknown> | unknown;
+    readonly completeFileRefs?: (...args: readonly unknown[]) => Promise<unknown> | unknown;
+    readonly [key: string]: unknown;
+}
+/** Minimal session-manager projection exposed beside a borrowed native session. */
+export type BorrowedSessionManager = Pick<AgentSession['sessionManager'], 'getEntries' | 'getBranch' | 'buildContextEntries' | 'getTree' | 'getLeafId' | 'getCwd' | 'getLabel' | 'appendLabelChange'>;
+/**
+ * Structural projection of the native child runtime borrowed by a view.
+ *
+ * The projection intentionally omits dispose, runtime replacement, session creation,
+ * fork/switch/reload, extension binding, and unrestricted manager mutation.
+ */
+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;
+    /** Full-resync native state projection. */
+    readonly state: Pick<AgentSession['state'], 'streamingMessage' | 'pendingToolCalls' | 'errorMessage'>;
+};
+export type SubagentLeaseEvent = Readonly<{
+    kind: 'rebound';
+    session: BorrowedAgentSession;
+    capabilities?: SubagentCapabilities;
+}> | Readonly<{
+    kind: 'closed';
+    reason: 'removed' | 'unavailable';
+}>;
+/** A borrowed child runtime. Release is idempotent and never disposes it. */
+export interface SubagentLease {
+    readonly path: AgentPath;
+    /** Current native session; access throws after the lease closes or releases. */
+    readonly session: BorrowedAgentSession;
+    readonly capabilities: SubagentCapabilities;
+    subscribe(listener: (event: SubagentLeaseEvent) => void): () => void;
+    release(): Promise<void>;
+}
+/** Root-scoped lifecycle authority used by the provider. */
+export interface SubagentOwnerControlPort {
+    teardown(path: AgentPath, incarnation: string): Promise<SubagentTeardownResult>;
+    stop(request: SubagentStopRequest): Promise<void>;
+    resurrect(request: SubagentResurrectRequest): Promise<SubagentResurrectResult>;
+}
+/** 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>;
+    resurrect(request: SubagentResurrectRequest): Promise<SubagentResurrectResult>;
+}
+/** EventBus request payload used by provider discovery. */
+export type SubagentProviderRequest = Readonly<{
+    /** Reserved for future handshake versions. */
+    version?: number;
+}>;
+/** EventBus response payload used by provider registration and discovery. */
+export type SubagentProviderResponse = Readonly<{
+    provider: import('./presentation.js').SubagentPresentationProvider;
+}>;
+/** A live discovery handle that tracks late registration and replacement. */
+export interface SubagentProviderDiscovery {
+    readonly provider: import('./presentation.js').SubagentPresentationProvider | undefined;
+    /** Alias for callers that model discovery as a mutable current value. */
+    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: import('./presentation.js').SubagentPresentationProvider | undefined) => void): () => void;
+    close(): void;
+}
+/** Extract the EventBus from either ExtensionAPI or an EventBus itself. */
+export type SubagentEventBusOwner = Pick<EventBus, 'on' | 'emit'> | {
+    readonly events: Pick<EventBus, 'on' | 'emit'>;
+};

package/dist/subagents/types.js

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pimote/sdk",
-  "version": "0.15.5",
-  "description": "Pimote extensibility SDK: panel cards, background-activity reap guard, and folder discovery/creation seams for pi extensions",
+  "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",
   "author": "Antoine Lennartz <alennartz@gmail.com>",
@@ -26,7 +26,9 @@
     ".": "./dist/index.js",
     "./panels": "./dist/panels/index.js",
     "./activity": "./dist/activity/index.js",
-    "./folders": "./dist/folders/index.js"
+    "./folders": "./dist/folders/index.js",
+    "./pimote": "./dist/pimote/index.js",
+    "./subagents": "./dist/subagents/index.js"
   },
   "types": "./dist/index.d.ts",
   "files": [
@@ -49,7 +51,7 @@
     }
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@earendil-works/pi-coding-agent": "1.5.0",
     "typescript": "^6.0.2",
     "vitest": "^4.1.2"
   }