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

package/README.md

@@ -1,12 +1,13 @@
 # @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/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 +113,38 @@ 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`
-
-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,
-        },
-      ];
-    },
-  },
-];
-
-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 };
+      return [{ kind: 'repo', path: '/home/me/work/api', name: 'api', branch: 'main', dirty: false, ahead: 0, behind: 0 }];
     },
-  },
-];
+  });
+  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.
+
+## Folders — `@pimote/sdk/folders`
 
-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.
+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.
 
-### `FolderCreator`
+### `FolderSource`
 
-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.
+`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 +169,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 +209,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,3 @@
+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 { SUBAGENT_PROVIDER_REQUEST, SUBAGENT_PROVIDER_RESPONSE, discover, discoverProvider, register, registerProvider } from './provider.js';
+export type { DiscoverProviderOptions } from './provider.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/provider.d.ts

@@ -0,0 +1,27 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { SubagentEventBusOwner, SubagentProvider, SubagentProviderDiscovery } from './types.js';
+/** 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 interface DiscoverProviderOptions {
+    /** Called whenever the provider first appears or is replaced. */
+    onProvider?: (provider: SubagentProvider) => 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: SubagentProvider) => 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;

package/dist/subagents/provider.js

@@ -0,0 +1,123 @@
+/** 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;
+    return {
+        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,
+    };
+}
+/** 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,322 @@
+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';
+}>;
+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;
+    state: 'running' | 'waiting' | 'idle' | 'errored' | 'dead' | 'stopped';
+    output?: string;
+    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;
+    /** 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[];
+    pendingCorrelations: readonly string[];
+    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 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<{
+    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;
+}>;
+/** 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;
+    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>;
+}
+/** Per-session provider feed and borrowed-runtime contract. */
+export interface SubagentProvider {
+    subscribe(listener: (event: SubagentEvent) => void): () => void;
+    snapshot(): SubagentSnapshot;
+    replay(after?: FeedCursor): ReplayResult;
+    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: SubagentProvider;
+}>;
+/** A live discovery handle that tracks late registration and replacement. */
+export interface SubagentProviderDiscovery {
+    readonly provider: SubagentProvider | undefined;
+    /** Alias for callers that model discovery as a mutable current value. */
+    readonly current: SubagentProvider | undefined;
+    subscribe(listener: (provider: SubagentProvider | undefined) => void): () => void;
+    /** Alias for subscribe, useful at the host event boundary. */
+    onProvider(listener: (provider: SubagentProvider | 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-rc.2",
-  "description": "Pimote extensibility SDK: panel cards, background-activity reap guard, and folder discovery/creation seams for pi extensions",
+  "version": "0.16.0-rc.1",
+  "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"
   }