@esso0428/pi-subagents 0.15.0

package/SECURITY.md

@@ -0,0 +1,95 @@
+# Security Policy
+
+This document explains the security model behind `@tintinweb/pi-subagents` and
+where the boundaries are.
+
+`pi-subagents` is a [pi](https://pi.dev) extension. It spawns and orchestrates
+autonomous sub-agents that run locally within the same security boundary as the
+user running pi, and inherit pi's trust model. It is the responsibility of the
+user to monitor those agents' operations or to contain them within a container,
+virtual machine, or other sandbox solution.
+
+Sub-agents run with the local user account's privileges and can use the tools
+they are granted (reading and writing files, running commands, network access,
+etc.). They treat the local user account and files writable by that account as
+inside the same trust boundary as the pi process itself. If an attacker can
+modify files under the user's home directory, workspace, shell startup files,
+environment, pi configuration, or this extension's configuration, they can
+generally influence pi, its sub-agents, or other local developer tools. Reports
+that depend on such prior local write access are not security vulnerabilities
+unless they demonstrate how `pi-subagents` grants that write access or crosses an
+operating-system privilege boundary.
+
+`pi-subagents` relies on the user only loading trustworthy agent definitions
+(`.pi/agents/*.md`, `.agents/agents/*.md`, and global agents), skills, and
+tools, and only using pi within trusted repositories. Files like `AGENTS.md`,
+custom agent frontmatter/system prompts, preloaded skills, or instructions
+embedded in repository content and comments can be used to prompt-inject the
+coding agent and its sub-agents trivially, and this cannot be protected against.
+
+## Reporting a Vulnerability
+
+If you believe you found a security vulnerability in `pi-subagents`, please
+report it privately by opening a draft advisory through
+[GitHub Security Advisories](https://github.com/tintinweb/pi-subagents/security/advisories/new)
+for this repository.
+
+Please include:
+
+- A description of the issue and its impact
+- Steps to reproduce, proof of concept, or relevant logs
+- Affected version, commit, or configuration
+- Any known mitigations
+
+Do not open a public issue for security-sensitive reports. Reports will be
+reviewed and disclosure coordinated as appropriate.
+
+## Scope
+
+Security issues in the published npm package and the code in this repository are
+in scope — for example, a flaw in `pi-subagents` that crosses an
+operating-system privilege boundary, or that causes the extension to bypass a
+tool restriction, denylist, or agent boundary it claims to enforce.
+
+## Out Of Scope
+
+- Local code execution or sandboxing behavior (sub-agents intentionally do not
+  have a sandbox and run with the user's privileges)
+- Behavior of pi itself, or of other pi extensions, skills, or tools installed by
+  the user (report those to their respective projects)
+- Risks from working in untrusted repositories
+- Risks from installing or loading untrusted agent definitions, skills,
+  extensions, packages, or tools
+- Issues caused by non-trustworthy MITM proxies
+- Public internet exposure of a pi installation
+- Prompt injection attacks (including via `AGENTS.md`, agent frontmatter, custom
+  system prompts, preloaded skills, repository content, or context inheritance)
+- Exposed secrets that are third-party/user-controlled credentials
+- Reports requiring the ability to create, modify, delete, or replace files,
+  directories, symlinks, environment variables, shell configuration, or other
+  user-controlled local state on the target machine. This includes `.pi/agents/`,
+  `.agents/agents/`, agent and extension configuration, persistent agent memory,
+  workspace files, `AGENTS.md`, skills, dotfiles, and files synchronized through NFS, roaming
+  profiles, or dotfile managers, unless the report shows how `pi-subagents`
+  itself grants that access.
+- Issues caused by intentionally weakened user configuration
+- Resource/DOS claims that require trusted local input/config
+- Reports about malicious model output
+- User-approved or user-initiated local actions presented as vulnerabilities
+
+## Notes for Reporters
+
+The most useful reports show a current, reproducible security boundary bypass
+with demonstrated impact. Reports that only show expected local-agent behavior,
+prompt injection, or a malicious trusted agent definition/skill are not security
+vulnerabilities under this model.
+
+For example, a report showing that malicious contents written to a trusted agent
+definition or extension configuration cause a sub-agent to execute commands, load
+attacker-controlled tools, or send credentials to an attacker-controlled endpoint
+is out of scope.
+
+When possible, include the exact affected path, package version or commit SHA,
+configuration, and a proof of concept against the latest release or latest
+`master`. For dependency reports, include evidence that the shipped dependency is
+affected and that the issue is reachable through `pi-subagents`.

package/dist/agent-manager.d.ts

@@ -0,0 +1,144 @@
+/**
+ * agent-manager.ts — Tracks agents, background execution, resume support.
+ *
+ * Background agents are subject to a configurable concurrency limit (default: 4).
+ * Excess agents are queued and auto-started as running agents complete.
+ * Foreground agents bypass the queue (they block the parent anyway).
+ */
+import type { Model } from "@earendil-works/pi-ai";
+import type { AgentSession, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type ToolActivity } from "./agent-runner.js";
+import type { AgentInvocation, AgentRecord, IsolationMode, SubagentType, ThinkingLevel } from "./types.js";
+export type OnAgentComplete = (record: AgentRecord) => void;
+export type OnAgentStart = (record: AgentRecord) => void;
+export type OnAgentCompact = (record: AgentRecord, info: CompactionInfo) => void;
+export type CompactionInfo = {
+    reason: "manual" | "threshold" | "overflow";
+    tokensBefore: number;
+};
+interface SpawnOptions {
+    description: string;
+    model?: Model<any>;
+    maxTurns?: number;
+    isolated?: boolean;
+    inheritContext?: boolean;
+    thinkingLevel?: ThinkingLevel;
+    isBackground?: boolean;
+    /**
+     * Skip the maxConcurrent queue check for this spawn — start immediately even
+     * if the configured concurrency limit would otherwise queue it. Used by the
+     * scheduler so a fired job can't be deferred past its trigger window.
+     */
+    bypassQueue?: boolean;
+    /** Isolation mode — "worktree" creates a temp git worktree for the agent. */
+    isolation?: IsolationMode;
+    /**
+     * Working directory for the agent (absolute path). Default: parent session
+     * cwd. The agent's tools operate here, but .pi config (extensions, skills,
+     * settings, memory) still loads from the parent session's project — the
+     * target directory's `.pi` extensions never execute. With isolation:
+     * "worktree", the worktree is created FROM this directory and the result
+     * branch lands in that repo.
+     */
+    cwd?: string;
+    /** Resolved invocation snapshot captured for UI display. */
+    invocation?: AgentInvocation;
+    /** Parent abort signal — when aborted, the subagent is also stopped. */
+    signal?: AbortSignal;
+    /** Called on tool start/end with activity info (for streaming progress to UI). */
+    onToolActivity?: (activity: ToolActivity) => void;
+    /** Called on streaming text deltas from the assistant response. */
+    onTextDelta?: (delta: string, fullText: string) => void;
+    /** Called when the agent session is created (for accessing session stats). */
+    onSessionCreated?: (session: AgentSession) => void;
+    /** Called at the end of each agentic turn with the cumulative count. */
+    onTurnEnd?: (turnCount: number) => void;
+    /** Called once per assistant message_end with that message's usage delta. */
+    onAssistantUsage?: (usage: {
+        input: number;
+        output: number;
+        cacheWrite: number;
+    }) => void;
+    /** Called when the session successfully compacts. */
+    onCompaction?: (info: CompactionInfo) => void;
+}
+export declare class AgentManager {
+    private agents;
+    private cleanupInterval;
+    private onComplete?;
+    private onStart?;
+    private onCompact?;
+    private maxConcurrent;
+    /** Base repos worktrees were created from — so dispose() can prune them all,
+     *  not just the parent repo (caller-supplied cwd can target other repos). */
+    private worktreeRepos;
+    /** Queue of background agents waiting to start. */
+    private queue;
+    /** Number of currently running background agents. */
+    private runningBackground;
+    constructor(onComplete?: OnAgentComplete, maxConcurrent?: number, onStart?: OnAgentStart, onCompact?: OnAgentCompact);
+    /** Update the max concurrent background agents limit. */
+    setMaxConcurrent(n: number): void;
+    getMaxConcurrent(): number;
+    /**
+     * Spawn an agent and return its ID immediately (for background use).
+     * If the concurrency limit is reached, the agent is queued.
+     */
+    spawn(pi: ExtensionAPI, ctx: ExtensionContext, type: SubagentType, prompt: string, options: SpawnOptions): string;
+    /** Actually start an agent (called immediately or from queue drain). */
+    private startAgent;
+    /** Start queued agents up to the concurrency limit. */
+    private drainQueue;
+    /**
+     * Called synchronously right after spawn, before onSessionCreated fires.
+     * Lets the caller set up the output file path on the record.
+     * The record is guaranteed to be in this.agents at this point.
+     */
+    private onSpawned?;
+    /**
+     * Spawn an agent and wait for completion (foreground use).
+     * Foreground agents bypass the concurrency queue.
+     * Returns { id, record } so callers can access the agent ID.
+     *
+     * @param onSpawned - Called synchronously after spawn(), before onSessionCreated fires.
+     *   Use this to set record.outputFile so streamToOutputFile can pick it up.
+     */
+    spawnAndWait(pi: ExtensionAPI, ctx: ExtensionContext, type: SubagentType, prompt: string, options: Omit<SpawnOptions, "isBackground">, onSpawned?: (id: string) => void): Promise<{
+        id: string;
+        record: AgentRecord;
+    }>;
+    /**
+     * Resume an existing agent session with a new prompt.
+     */
+    resume(id: string, prompt: string, signal?: AbortSignal): Promise<AgentRecord | undefined>;
+    /**
+     * Send a steering message to an agent from the UI (mirrors the steer_subagent
+     * tool). A live session delivers it now — it interrupts the agent after its
+     * current tool execution and appears as a user message. If the session isn't
+     * ready yet, the message is queued on `pendingSteers` and flushed when the
+     * session is created. Returns false if the agent can't accept steering
+     * (unknown id, or no longer running/queued).
+     */
+    steer(id: string, message: string): boolean;
+    getRecord(id: string): AgentRecord | undefined;
+    listAgents(): AgentRecord[];
+    abort(id: string): boolean;
+    /** Dispose a record's session and remove it from the map. */
+    private removeRecord;
+    private cleanup;
+    /**
+     * Remove all completed/stopped/errored records immediately.
+     * Called on session start/switch so tasks from a prior session don't persist.
+     * Pass skipUnconsumed=true to preserve records the LLM hasn't read yet
+     * (resultConsumed=false) — they will be evicted by the 10-minute cleanup timer instead.
+     */
+    clearCompleted(skipUnconsumed?: boolean): void;
+    /** Whether any agents are still running or queued. */
+    hasRunning(): boolean;
+    /** Abort all running and queued agents immediately. */
+    abortAll(): number;
+    /** Wait for all running and queued agents to complete (including queued ones). */
+    waitForAll(): Promise<void>;
+    dispose(): void;
+}
+export {};