@pimote/sdk 0.14.0 → 0.15.0-rc.1

package/README.md

@@ -3,9 +3,10 @@
 Pimote's extensibility SDK — everything a [pi](https://github.com/mariozechner/pi-coding-agent) extension imports to talk to [pimote](https://github.com/alennartz/pimote). One subpath module per extension seam:
 
 - **`@pimote/sdk/panels`** — push structured card data to the pimote web client
-- **`@pimote/sdk/projects`** — contribute project discovery and creation to pimote's project layer
+- **`@pimote/sdk/folders`** — contribute folder discovery and creation to pimote's folder layer
+- **`@pimote/sdk/activity`** — answer pimote's idle-reap background-activity poll
 
-The root `@pimote/sdk` import re-exports both modules.
+The root `@pimote/sdk` import re-exports all modules.
 
 ## Install
 
@@ -13,7 +14,7 @@ The root `@pimote/sdk` import re-exports both modules.
 npm install @pimote/sdk
 ```
 
-Requires `@earendil-works/pi-coding-agent` as an optional peer dependency (already present in any pi extension; only the panels seam imports from it).
+Requires `@earendil-works/pi-coding-agent` as an optional peer dependency (already present in any pi extension; only the panels and activity seams import from it).
 
 ## Panels — `@pimote/sdk/panels`
 
@@ -111,17 +112,17 @@ 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.
 
-## Projects — `@pimote/sdk/projects`
+## Folders — `@pimote/sdk/folders`
 
-Type-only module for user-authored project-source modules: pimote scans a project-sources directory (default `~/.config/pimote/project-sources`, configurable via `projectSourcesDir`), dynamic-imports every JS/TS module it finds, and collects each module's exported `sources` and `creators` arrays. Sources contribute repos and multi-repo projects to pimote's project layer; creators make new project directories from user-supplied form params.
+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.
 
 ### Writing a module
 
 ```ts
-// ~/.config/pimote/project-sources/my-source.ts
-import type { ProjectSource, ProjectCreator } from '@pimote/sdk/projects';
+// ~/.config/pimote/folder-sources/my-source.ts
+import type { FolderSource, FolderCreator } from '@pimote/sdk/folders';
 
-export const sources: ProjectSource[] = [
+export const sources: FolderSource[] = [
   {
     id: 'my-source',
     async list() {
@@ -140,42 +141,42 @@ export const sources: ProjectSource[] = [
   },
 ];
 
-export const creators: ProjectCreator[] = [
+export const creators: FolderCreator[] = [
   {
     id: 'my-creator',
     describe() {
-      return { label: 'New API project', paramSchema: { name: 'string', tags: 'string[]' } };
+      return { label: 'New API folder', paramSchema: { name: 'string', tags: 'string[]' } };
     },
     async create(params) {
       const path = `/home/me/work/${String(params.name)}`;
-      // ... scaffold the project directory ...
+      // ... scaffold the folder ...
       return { path };
     },
   },
 ];
 ```
 
-### `ProjectSource`
+### `FolderSource`
 
-The discovery seam. `list()` is called on cache miss and must return the current entries without mutating anything. The optional `onProjectOpen(projectPath)` 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.
+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.
 
-### `ProjectCreator`
+### `FolderCreator`
 
-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 project directory, and returns its `{ path }`.
+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 }`.
 
 ### Entry shapes
 
-`list()` returns `SourceEntry[]` — a repo or a multi-repo project:
+`list()` returns `SourceEntry[]` — a repo or a hub folder:
 
 ```ts
-/** Feeds a single-repo project. Extends `RepoInfo`. */
+/** Feeds a single-repo folder. Extends `RepoInfo`. */
 interface RepoSourceEntry extends RepoInfo {
   kind: 'repo';
 }
 
-/** Feeds a multi-repo project over member paths. */
-interface MultiRepoSourceEntry {
-  kind: 'project';
+/** Feeds a hub folder over member paths. */
+interface HubSourceEntry {
+  kind: 'hub';
   path: string;
   name: string;
   memberPaths: string[];
@@ -188,6 +189,61 @@ interface MultiRepoSourceEntry {
 
 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.
 
+## Activity — `@pimote/sdk/activity`
+
+Answer pimote's background-activity poll so the idle reaper does not close a session that holds live work (for example: background subagents still running while the root session is settled).
+
+Pimote reaps sessions that are idle past a timeout with no connected client. Before closing, it emits `pimote:activity:request` on the session's EventBus and reads the answer synchronously. Register a responder if your extension manages work the root session cannot see:
+
+```ts
+import { answerActivity } from '@pimote/sdk/activity';
+import type { ExtensionFactory } from '@earendil-works/pi-coding-agent';
+
+const extension: ExtensionFactory = (pi) => {
+  answerActivity(pi, () => myAgents.some((a) => a.state === 'running'));
+};
+
+export default extension;
+```
+
+The callback must be synchronous — the round-trip is a plain inline emit, so an async answer is indistinguishable from no answer. It is read at poll time, not registration time, so it may consult live state through a stable owner object. If it throws, the responder answers `active: true`: a broken predicate parks the session (recoverable by explicit close) instead of destroying work.
+
+What counts as "live work" is extension policy — pimote learns only the boolean. With no responder, pimote reaps as it always did.
+
+### API
+
+#### `answerActivity(pi, isActive)`
+
+Registers the responder on the session's EventBus. Returns an unsubscribe function (for symmetry and tests — the bus dies with the session).
+
+- **`pi`** — The `ExtensionAPI` object passed to your extension factory.
+- **`isActive`** — Synchronous `() => boolean`: true when closing the session now would destroy live work.
+
+#### `askActivity(bus)`
+
+The pimote-side twin, used by the server's idle reaper. Performs the synchronous poll on an `EventBus` and returns whether any responder asserted live work (multiple answers are OR-ed). Extensions do not need it; it ships in the SDK so the whole protocol lives in one module.
+
+## Breaking changes
+
+### 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`).
+
 ## License
 
 MIT

package/dist/activity/answer.d.ts

@@ -0,0 +1,20 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+/**
+ * Answer pimote's background-activity polls for this session.
+ *
+ * Pimote's idle reaper calls this poll (DR-054) before closing an idle session
+ * with no connected client. Return true when closing the session now would
+ * destroy live work (for example: background subagents still running).
+ *
+ * The poll is a synchronous EventBus round-trip, mirroring `panels/detect`:
+ * pimote emits `pimote:activity:request` and reads the response inline. The
+ * `isActive` callback must therefore be synchronous — an async answer is
+ * indistinguishable from no answer. Answering is extension policy: pimote
+ * learns only the boolean, never what the work is.
+ *
+ * If `isActive` throws, the responder answers `active: true`: a broken
+ * predicate must park the session (recoverable by explicit close), not destroy
+ * work. Register once per session; the returned unsubscribe is for symmetry
+ * and tests — the bus dies with the session.
+ */
+export declare function answerActivity(pi: ExtensionAPI, isActive: () => boolean): () => void;

package/dist/activity/answer.js

@@ -0,0 +1,31 @@
+/**
+ * Answer pimote's background-activity polls for this session.
+ *
+ * Pimote's idle reaper calls this poll (DR-054) before closing an idle session
+ * with no connected client. Return true when closing the session now would
+ * destroy live work (for example: background subagents still running).
+ *
+ * The poll is a synchronous EventBus round-trip, mirroring `panels/detect`:
+ * pimote emits `pimote:activity:request` and reads the response inline. The
+ * `isActive` callback must therefore be synchronous — an async answer is
+ * indistinguishable from no answer. Answering is extension policy: pimote
+ * learns only the boolean, never what the work is.
+ *
+ * If `isActive` throws, the responder answers `active: true`: a broken
+ * predicate must park the session (recoverable by explicit close), not destroy
+ * work. Register once per session; the returned unsubscribe is for symmetry
+ * and tests — the bus dies with the session.
+ */
+export function answerActivity(pi, isActive) {
+    return pi.events.on('pimote:activity:request', () => {
+        let active;
+        try {
+            active = isActive();
+        }
+        catch (error) {
+            console.error('[pimote:activity] responder threw; answering active to protect live work', error);
+            active = true;
+        }
+        pi.events.emit('pimote:activity:response', { active });
+    });
+}

package/dist/activity/ask.d.ts

@@ -0,0 +1,14 @@
+import type { EventBus } from '@earendil-works/pi-coding-agent';
+/**
+ * Poll a session's extensions for background activity (DR-054).
+ *
+ * Synchronous round-trip, mirroring `panels/detect`: responders run inline
+ * during `emit`, so their answers are captured before this returns. Call only
+ * for sessions already past the idle-reap threshold — the poll is invisible
+ * until it matters.
+ *
+ * Fails open: no responder, or any responder answering `active: false`, means
+ * no background work and the caller may reap. When several extensions answer,
+ * responses are OR-ed — any assertion of live work holds the session.
+ */
+export declare function askActivity(bus: EventBus): boolean;

package/dist/activity/ask.js

@@ -0,0 +1,23 @@
+/**
+ * Poll a session's extensions for background activity (DR-054).
+ *
+ * Synchronous round-trip, mirroring `panels/detect`: responders run inline
+ * during `emit`, so their answers are captured before this returns. Call only
+ * for sessions already past the idle-reap threshold — the poll is invisible
+ * until it matters.
+ *
+ * Fails open: no responder, or any responder answering `active: false`, means
+ * no background work and the caller may reap. When several extensions answer,
+ * responses are OR-ed — any assertion of live work holds the session.
+ */
+export function askActivity(bus) {
+    let active = false;
+    const unsubscribe = bus.on('pimote:activity:response', (data) => {
+        const message = data;
+        if (message?.active === true)
+            active = true;
+    });
+    bus.emit('pimote:activity:request', {});
+    unsubscribe();
+    return active;
+}

package/dist/activity/index.d.ts

@@ -0,0 +1,3 @@
+export type { ActivityMessage } from './types.js';
+export { answerActivity } from './answer.js';
+export { askActivity } from './ask.js';

package/dist/activity/index.js

@@ -0,0 +1,2 @@
+export { answerActivity } from './answer.js';
+export { askActivity } from './ask.js';

package/dist/activity/types.d.ts

@@ -0,0 +1,5 @@
+/** Response payload for pimote's background-activity poll. */
+export interface ActivityMessage {
+    /** True when the responder asserts that closing the session would destroy live work. */
+    active: boolean;
+}

package/dist/folders/index.d.ts

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

package/dist/{projects → folders}/types.d.ts

@@ -18,33 +18,33 @@ export interface RepoInfo {
     tags?: string[];
 }
 /** Human-readable parameter type for a creator form field. */
-export type ProjectCreatorParamType = 'string' | 'string[]';
-/** A repo entry contributed to the discovery index (feeds single-repo projects). */
+export type FolderCreatorParamType = 'string' | 'string[]';
+/** A repo entry contributed to the discovery index (feeds single-repo folders). */
 export interface RepoSourceEntry extends RepoInfo {
     kind: 'repo';
 }
 /**
- * A multi-repo project entry contributed to the project layer. `memberPaths`
+ * A hub folder entry contributed to the folder layer. `memberPaths`
  * are concrete paths that may not exist on disk yet; the server derives
  * existence state itself — sources never flag "virtual".
  */
-export interface MultiRepoSourceEntry {
-    kind: 'project';
+export interface HubSourceEntry {
+    kind: 'hub';
     path: string;
     name: string;
     memberPaths: string[];
     /** Source-contributed tags; shown to the user but not user-removable. */
     tags?: string[];
 }
-/** Anything a source lists: a repo, or a multi-repo project over member paths. */
-export type SourceEntry = RepoSourceEntry | MultiRepoSourceEntry;
+/** Anything a source lists: a repo, or a hub folder over member paths. */
+export type SourceEntry = RepoSourceEntry | HubSourceEntry;
 /**
- * Extensible discovery seam: a source contributes repos and multi-repo
- * projects to the project layer. Built in: the filesystem walker over
+ * 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 project-sources directory.
+ * configured folder-sources directory.
  */
-export interface ProjectSource {
+export interface FolderSource {
     readonly id: string;
     /** Discover entries; called on cache miss. Must not mutate anything. */
     list(): Promise<SourceEntry[]>;
@@ -55,22 +55,22 @@ export interface ProjectSource {
      * 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.
      */
-    onProjectOpen?(projectPath: string): Promise<void>;
+    onFolderOpen?(folderPath: string): Promise<void>;
 }
 /** Human-readable description of a creator's form, for the creation UI. */
-export interface ProjectCreatorDescriptor {
+export interface FolderCreatorDescriptor {
     label: string;
-    paramSchema: Record<string, ProjectCreatorParamType>;
+    paramSchema: Record<string, FolderCreatorParamType>;
 }
 /**
- * Extensible creation seam: a creator makes a new project directory from
+ * 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 project-sources directory.
+ * are dynamic-imported from the configured folder-sources directory.
  */
-export interface ProjectCreator {
+export interface FolderCreator {
     readonly id: string;
     /** Human-readable description for the creation UI. */
-    describe(): ProjectCreatorDescriptor;
+    describe(): FolderCreatorDescriptor;
     create(params: Record<string, unknown>): Promise<{
         path: string;
     }>;

package/dist/folders/types.js

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

package/dist/index.d.ts

@@ -1,2 +1,2 @@
 export * from './panels/index.js';
-export * from './projects/index.js';
+export * from './folders/index.js';

package/dist/index.js

@@ -1,2 +1,2 @@
 export * from './panels/index.js';
-export * from './projects/index.js';
+export * from './folders/index.js';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pimote/sdk",
-  "version": "0.14.0",
-  "description": "Pimote extensibility SDK: panel cards and project discovery/creation seams for pi extensions",
+  "version": "0.15.0-rc.1",
+  "description": "Pimote extensibility SDK: panel cards, background-activity reap guard, and folder discovery/creation seams for pi extensions",
   "type": "module",
   "license": "MIT",
   "author": "Antoine Lennartz <alennartz@gmail.com>",
@@ -17,14 +17,16 @@
     "pimote",
     "extension",
     "sdk",
-    "projects",
+    "folders",
     "panels",
-    "cards"
+    "cards",
+    "activity"
   ],
   "exports": {
     ".": "./dist/index.js",
     "./panels": "./dist/panels/index.js",
-    "./projects": "./dist/projects/index.js"
+    "./activity": "./dist/activity/index.js",
+    "./folders": "./dist/folders/index.js"
   },
   "types": "./dist/index.d.ts",
   "files": [
@@ -39,7 +41,7 @@
     "prepublishOnly": "npm run build"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.99.2"
+    "@earendil-works/pi-coding-agent": "*"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {
@@ -47,7 +49,7 @@
     }
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.99.2",
+    "@earendil-works/pi-coding-agent": "^1.1.0",
     "typescript": "^6.0.2",
     "vitest": "^4.1.2"
   }

package/dist/projects/index.d.ts

@@ -1 +0,0 @@
-export type { ProjectSource, ProjectCreator, ProjectCreatorDescriptor, ProjectCreatorParamType, SourceEntry, RepoSourceEntry, MultiRepoSourceEntry, RepoInfo } from './types.js';