@herbertgao/pi-subagents 0.19.0 → 0.22.0-local.1

package/src/schedule.ts

@@ -12,7 +12,7 @@
  *     of dispatching a user message — schedule fires bypass maxConcurrent so
  *     a 5-minute interval can't be deferred behind 4 long-running agents.
  *   - Result delivery is implicit: spawn → background completion → existing
- *     `subagent-notification` followUp path. No new delivery code.
+ *     `subagent-notification` path. No new delivery code.
  */
 
 import type {

package/src/settings.ts

@@ -294,6 +294,41 @@ export interface SubagentsSettings {
    * narrow terminal.
    */
   showModel?: boolean
+  /**
+   * Whether agents declared by installed pi packages load, and from which
+   * packages. Defaults to `true`.
+   *
+   *   - `true`  — every package whose `package.json` declares `pi.subagents`
+   *               (or the top-level `pi-subagents` key) contributes its agents.
+   *   - `false` — none do.
+   *   - list    — only packages matching an entry, compared case-insensitively
+   *               against the unscoped short name (`@scope/foo` matches `foo`),
+   *               the full package name, or the settings source string.
+   *
+   * On by default because installing is already the trust decision: pi executes
+   * an installed package's `extensions/` and injects its `skills/` into the
+   * system prompt with no further prompt, so a declared `.md` agent is strictly
+   * less privileged than what the same package already runs. The gate exists for
+   * users who want to narrow that anyway, not as a second install ritual.
+   *
+   * Package agents always load at the *lowest* precedence, below global and
+   * project files, so a same-named local agent silently takes the name back.
+   */
+  packageAgents?: boolean | string[]
+  /**
+   * The same gate for workflow scripts declared by installed pi packages
+   * (`pi.subagents.workflows`). Defaults to `true`.
+   *
+   * Deliberately separate from `packageAgents` rather than folded into it: an
+   * agent is markdown we hand to a model, a workflow is `.js` we execute. Both
+   * still sit below the package's own `extensions/`, which pi runs unsandboxed,
+   * so the default matches — but a user who wants package agents without package
+   * workflow scripts can have that without giving up either wholesale.
+   *
+   * No-op when `workflowsEnabled` is off: the tool is never registered, so there
+   * is nothing to resolve a workflow name against.
+   */
+  packageWorkflows?: boolean | string[]
   /**
    * How much of the conversation viewer's transcript renders as Markdown.
    * Defaults to `assistant`. Applied live — the viewer's `m` key cycles this
@@ -337,6 +372,8 @@ export interface SettingsAppliers {
   setShowCost: (b: boolean) => void
   setShowModel: (b: boolean) => void
   setViewerMarkdown: (mode: ViewerMarkdownMode) => void
+  setPackageAgents: (gate: boolean | string[]) => void
+  setPackageWorkflows: (gate: boolean | string[]) => void
 }
 
 /** Emit callback — a subset of `pi.events.emit` to keep helpers testable. */
@@ -367,6 +404,28 @@ const MAX_TURNS_CEILING = 10_000
 const GRACE_TURNS_CEILING = 1_000
 const SUBAGENT_DEPTH_CEILING = 16
 
+/**
+ * Normalize a package gate: a boolean passes through, an array is trimmed to its
+ * non-empty string entries, a bare string becomes a one-entry allowlist, and
+ * anything else is dropped.
+ *
+ * The two coercions exist for the same reason: this setting's default is `true`,
+ * so *dropping* a malformed value silently admits every package — the opposite
+ * of what someone narrowing the gate meant. So an array that trims to empty is
+ * kept as `[]` (matching nothing, like `false`) rather than dropped, and
+ * `"my-package"` — the obvious typo for a one-entry list — is read as
+ * `["my-package"]` rather than widened to everything.
+ */
+function sanitizePackageGate(val: unknown): boolean | string[] | undefined {
+  if (typeof val === "boolean") return val
+  if (typeof val === "string") return val.trim() ? [val.trim()] : []
+  if (!Array.isArray(val)) return undefined
+  return val
+    .filter((e): e is string => typeof e === "string")
+    .map((e) => e.trim())
+    .filter(Boolean)
+}
+
 /** Drop fields that don't match the expected shape. Silent — garbage becomes absent. */
 function sanitize(raw: unknown): SubagentsSettings {
   if (!raw || typeof raw !== "object") return {}
@@ -482,6 +541,10 @@ function sanitize(raw: unknown): SubagentsSettings {
   if (typeof r.workflowsEnabled === "boolean") {
     out.workflowsEnabled = r.workflowsEnabled
   }
+  const packageAgents = sanitizePackageGate(r.packageAgents)
+  if (packageAgents !== undefined) out.packageAgents = packageAgents
+  const packageWorkflows = sanitizePackageGate(r.packageWorkflows)
+  if (packageWorkflows !== undefined) out.packageWorkflows = packageWorkflows
   if (r.fallbackSubagent === false) {
     // The only non-string spelling worth accepting: a boolean would otherwise be
     // dropped, silently leaving the PERMISSIVE default in place. Every string is
@@ -595,6 +658,9 @@ export function applySettings(
   if (s.viewerMarkdown) appliers.setViewerMarkdown(s.viewerMarkdown)
   if (typeof s.workflowsEnabled === "boolean")
     appliers.setWorkflowsEnabled(s.workflowsEnabled)
+  if (s.packageAgents !== undefined) appliers.setPackageAgents(s.packageAgents)
+  if (s.packageWorkflows !== undefined)
+    appliers.setPackageWorkflows(s.packageWorkflows)
 }
 
 /**

package/src/types.ts

@@ -88,8 +88,12 @@ export interface AgentConfig {
   isDefault?: boolean
   /** false = agent is hidden from the registry */
   enabled?: boolean
-  /** Where this agent was loaded from */
-  source?: "default" | "project" | "global"
+  /**
+   * Where this agent was loaded from. `"package"` means an installed pi package
+   * declared it (see package-resources.ts) — those files live under pi's install
+   * root, so `/agents` treats them as read-only and offers Eject instead of Edit.
+   */
+  source?: "default" | "project" | "global" | "package"
   /** Path of the .md it was loaded from. Unset for embedded defaults. */
   sourcePath?: string
 }
@@ -157,6 +161,9 @@ export type MentionResolution =
   | { kind: "live"; record: AgentRecord }
   | { kind: "tombstone"; entry: AgentTombstone }
 
+/** Which concurrency pool a run is charged to. */
+export type Pool = "background" | "foreground"
+
 export interface AgentRecord {
   id: string
   type: SubagentType
@@ -197,8 +204,22 @@ export interface AgentRecord {
    * which says only that the agent has an inline result surface: a detached
    * cross-extension RPC spawn is foreground by that measure and yet blocks
    * nobody, so it takes no slot.
+   *
+   * Cleared when the inline caller stops waiting: by `sendToBackground`, or
+   * when the run settles.
    */
   blocking?: boolean
+  /**
+   * The concurrency pool this run's slot is charged to, set once when it
+   * starts. `settleRun` releases exactly this; `sendToBackground` is the only
+   * thing that moves it, together with the counters.
+   */
+  chargedPool?: Pool
+  /**
+   * Removes the listener that stops this run when its caller's signal aborts.
+   * At most one is armed at a time — queueing arms one, starting replaces it.
+   */
+  detachParentAbort?: () => void
   /**
    * Present only while the record is "queued": resolves when it leaves the
    * queue, started or aborted. `spawnAndWait` waits on this because a queued
@@ -244,8 +265,9 @@ export interface AgentRecord {
   /** Number of times this agent's session has compacted. Initialized to 0 at spawn. */
   compactionCount: number
   /**
-   * Whether this agent was spawned to run in the background. Tri-state, set at
-   * spawn from `SpawnOptions.isBackground`: `true` = background, `false` =
+   * Whether this agent runs in the background. Tri-state, initialized at spawn
+   * from `SpawnOptions.isBackground` and flipped `false` → `true` (once, never
+   * back) by `sendToBackground`: `true` = background, `false` =
    * foreground (has an inline Agent tool-result surface), `undefined` = the
    * caller never declared it (e.g. a cross-extension RPC spawn, which is detached
    * and has no inline surface). The widget's background-only filter keys off this

package/src/ui/agent-widget.ts

@@ -99,6 +99,8 @@ export interface AgentDetails {
   activity?: string
   /** Current spinner frame index (for animated running indicator). */
   spinnerFrame?: number
+  /** Show the ctrl+b hint on this running foreground call's row — one row per batch. */
+  backgroundHint?: boolean
   /** Short label for the model the run used, e.g. "haiku 4.5". */
   modelName?: string
   /** Notable config tags (e.g. ["thinking: high", "isolated"]). */