@gotgenes/pi-subagents 16.3.1 → 16.5.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [16.5.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v16.4.0...pi-subagents-v16.5.0) (2026-06-17)
+
+
+### Features
+
+* accumulate live activity in record-observer ([#420](https://github.com/gotgenes/pi-packages/issues/420)) ([c75e7cf](https://github.com/gotgenes/pi-packages/commit/c75e7cf20e44116743fc847238b4364a1edda25a))
+* add live-activity fields to SubagentState ([#420](https://github.com/gotgenes/pi-packages/issues/420)) ([713f19a](https://github.com/gotgenes/pi-packages/commit/713f19aa13306b6c41dc54f3ddfa73fcdfc65427))
+* expose live-activity getters on Subagent ([#420](https://github.com/gotgenes/pi-packages/issues/420)) ([6438d6c](https://github.com/gotgenes/pi-packages/commit/6438d6ca0fdb25b1dfeffa0f76a1eae8630f0cce))
+
+## [16.4.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v16.3.1...pi-subagents-v16.4.0) (2026-06-16)
+
+
+### Features
+
+* **pi-subagents:** add loadLayeredSettings layered config loader ([2eeba78](https://github.com/gotgenes/pi-packages/commit/2eeba78230bd4537fa568641d4a77a6f1824271c))
+* **pi-subagents:** export loadLayeredSettings via ./settings subpath ([cefe7f6](https://github.com/gotgenes/pi-packages/commit/cefe7f6b7a9133cd0bbcc523ac8b34e48fce0a58))
+
 ## [16.3.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v16.3.0...pi-subagents-v16.3.1) (2026-06-16)
 
 

package/README.md

@@ -360,6 +360,53 @@ When [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-permissio
 No configuration is required.
 When `@gotgenes/pi-permission-system` is not installed, the lifecycle events have no subscriber — a harmless no-op.
 
+## For Extension Authors
+
+This package exposes two public subpath exports for companion extensions to import from the published tarball.
+
+### `@gotgenes/pi-subagents` — cross-extension service contract
+
+Access the subagent service from another extension at runtime:
+
+```typescript
+const { getSubagentsService } = await import("@gotgenes/pi-subagents");
+const svc = getSubagentsService();
+svc?.spawn("Explore", "Check for stale TODOs");
+```
+
+Declare this package as an optional peer dependency.
+See `src/service/service.ts` for the full `SubagentsService` interface and the `WorkspaceProvider` seam.
+
+### `@gotgenes/pi-subagents/settings` — layered config loader
+
+Extensions that store configuration in JSON files can use the shared layered loader, which reads a global file (`<agentDir>/<filename>`) and a project file (`<cwd>/.pi/<filename>`) and merges them — project wins on conflicts, missing files are silent, malformed files warn and fall back:
+
+```typescript
+import { loadLayeredSettings, type LayeredSettingsSource } from "@gotgenes/pi-subagents/settings";
+
+interface MyConfig { enabled?: boolean; limit?: number }
+
+function sanitize(raw: unknown): Partial<MyConfig> {
+  if (!raw || typeof raw !== "object") return {};
+  const r = raw as Record<string, unknown>;
+  const out: Partial<MyConfig> = {};
+  if (typeof r.enabled === "boolean") out.enabled = r.enabled;
+  if (typeof r.limit === "number") out.limit = r.limit;
+  return out;
+}
+
+const config = loadLayeredSettings<MyConfig>({
+  agentDir,          // Pi runtime agent home directory
+  cwd,               // project root — project file lives at <cwd>/.pi/<filename>
+  filename: "my-extension.json",
+  sanitize,
+  warnLabel: "my-extension",  // prefix for the malformed-file stderr warning
+});
+```
+
+`loadLayeredSettings` returns `Partial<T>` (all fields optional); apply your defaults after the call.
+It never throws — all error conditions produce a `console.warn` and return `{}`.
+
 ## Architecture
 
 This extension is a minimal, composable core: it owns agent spawning, execution, and result retrieval, and exposes a typed `SubagentsService` plus lifecycle events that other extensions build on.

package/dist/public.d.ts

@@ -30,12 +30,15 @@ type LifetimeUsage = {
 };
 
 /**
- * subagent-state.ts — SubagentState value object: lifecycle status and metrics.
+ * subagent-state.ts — SubagentState value object: lifecycle status, metrics, and live activity.
  *
  * Owns the passive, readable state of a subagent — status, result, error,
- * timestamps, and stats (toolUses, lifetimeUsage, compactionCount) — together
- * with the transition methods (markRunning, markCompleted, …) and accumulation
- * methods (incrementToolUses, addUsage, incrementCompactions) that mutate it.
+ * timestamps, stats (toolUses, lifetimeUsage, compactionCount), and live-activity
+ * fields (turnCount, activeTools, responseText) — together with the transition
+ * methods (markRunning, markCompleted, …), accumulation methods
+ * (incrementToolUses, addUsage, incrementCompactions), and live-activity
+ * transition methods (incrementTurnCount, addActiveTool, removeActiveTool,
+ * resetResponseText, appendResponseText) that mutate them.
  *
  * State is encapsulated behind getters; external code reads through them but
  * mutates only via the transition/accumulation methods. The value object owns

package/dist/settings.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Generic layered settings loader for `@gotgenes/pi-*` extensions.
+ *
+ * Extensions that store configuration in JSON files under a global agent
+ * directory and a per-project `.pi/` folder share the same three-step idiom:
+ *
+ *   1. Read the global file (`<agentDir>/<filename>`).
+ *   2. Read the project file (`<cwd>/.pi/<filename>`).
+ *   3. Merge them — project wins on conflicts — and return the result.
+ *
+ * Both layers are optional: a missing file is silent (`{}`), and a file that
+ * cannot be parsed warns to stderr and is treated as absent so startup
+ * proceeds normally.
+ *
+ * ## Usage
+ *
+ * ```typescript
+ * import { loadLayeredSettings, type LayeredSettingsSource } from "@gotgenes/pi-subagents/settings";
+ *
+ * interface MyConfig { enabled?: boolean; limit?: number }
+ *
+ * function sanitize(raw: unknown): Partial<MyConfig> {
+ *   if (!raw || typeof raw !== "object") return {};
+ *   const r = raw as Record<string, unknown>;
+ *   const out: Partial<MyConfig> = {};
+ *   if (typeof r.enabled === "boolean") out.enabled = r.enabled;
+ *   if (typeof r.limit === "number") out.limit = r.limit;
+ *   return out;
+ * }
+ *
+ * const config = loadLayeredSettings<MyConfig>({
+ *   agentDir,     // e.g. from the Pi runtime env — the agent home directory
+ *   cwd,          // project root — project file is at <cwd>/.pi/<filename>
+ *   filename: "my-extension.json",
+ *   sanitize,
+ *   warnLabel: "my-extension",
+ * });
+ * ```
+ *
+ * @public
+ */
+/**
+ * Parameters for one layered settings load: describes where the files live,
+ * how to validate their contents, and what label to use in warnings.
+ *
+ * @public
+ */
+interface LayeredSettingsSource<T> {
+    /** Directory holding the global settings file (typically the Pi agent dir). */
+    agentDir: string;
+    /** Project root; the project file lives at `<cwd>/.pi/<filename>`. */
+    cwd: string;
+    /** Base filename for both layers, e.g. `"subagents.json"`. */
+    filename: string;
+    /**
+     * Validate and coerce parsed JSON into a partial settings object.
+     * Unknown or invalid fields should be silently dropped — return `{}` for
+     * unrecognised shapes. Never throw.
+     */
+    sanitize: (raw: unknown) => Partial<T>;
+    /**
+     * Short label used in the malformed-file warning prefix,
+     * e.g. `"pi-subagents"` → `"[pi-subagents] Ignoring malformed settings at …"`.
+     */
+    warnLabel: string;
+}
+/**
+ * Load merged layered settings: global provides defaults, project overrides.
+ *
+ * - A missing file is silent — returns `{}` for that layer.
+ * - A file that exists but cannot be parsed warns to stderr and returns `{}` for
+ *   that layer, so startup proceeds normally.
+ * - The two layers are merged with a shallow spread; project keys win.
+ *
+ * Throws nothing. All error conditions produce a warning and fall back to `{}`.
+ *
+ * @public
+ */
+declare function loadLayeredSettings<T>(source: LayeredSettingsSource<T>): Partial<T>;
+
+export { loadLayeredSettings };
+export type { LayeredSettingsSource };