@diousk/pi-subagents-fast 0.20.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/abortable.d.ts

@@ -0,0 +1,12 @@
+/**
+ * abortable.ts — race a promise against an AbortSignal without cancelling the
+ * underlying work.
+ *
+ * Used by the `get_subagent_result` wait paths (top-level and nested): pressing
+ * Esc cancels only the caller's wait; the background child keeps running and its
+ * result stays unconsumed. The listener is removed on every settle path so the
+ * signal accumulates no handlers, and a late settlement of the wrapped promise
+ * after an abort is absorbed as a no-op (no unhandled rejection).
+ */
+/** Await a promise until it settles or the caller cancels, without aborting the underlying work. */
+export declare function abortable<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T>;

package/dist/abortable.js

@@ -0,0 +1,42 @@
+/**
+ * abortable.ts — race a promise against an AbortSignal without cancelling the
+ * underlying work.
+ *
+ * Used by the `get_subagent_result` wait paths (top-level and nested): pressing
+ * Esc cancels only the caller's wait; the background child keeps running and its
+ * result stays unconsumed. The listener is removed on every settle path so the
+ * signal accumulates no handlers, and a late settlement of the wrapped promise
+ * after an abort is absorbed as a no-op (no unhandled rejection).
+ */
+/** Await a promise until it settles or the caller cancels, without aborting the underlying work. */
+export function abortable(promise, signal) {
+    if (!signal)
+        return promise;
+    if (signal.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const cleanup = () => signal.removeEventListener("abort", onAbort);
+        const onAbort = () => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(signal.reason);
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then((value) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve(value);
+        }, (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(error);
+        });
+    });
+}

package/dist/agent-color.d.ts

@@ -0,0 +1,35 @@
+/**
+ * agent-color.ts — Claude Code-compatible agent name badges.
+ *
+ * Claude Code renders a subagent's name as a badge: the configured color is the
+ * background, the text an inverse foreground. Its eight named colors are
+ * reproduced here, along with six-digit hex and the extra palette names Agency
+ * Agents uses, so those definitions render as written.
+ */
+type ColorMode = "truecolor" | "256color";
+export interface AgentNameTheme {
+    fg(color: string, text: string): string;
+    bold(text: string): string;
+    getColorMode?(): ColorMode;
+}
+export interface AgentNameStyle {
+    /** Existing theme foreground used when no valid agent color is configured. */
+    fallbackColor?: string;
+    /** Reapply an enclosing background after the badge instead of resetting it. */
+    restoreBackground?: string;
+    bold?: boolean;
+}
+/** Resolve Claude Code/Agency Agents color syntax to normalized #RRGGBB. */
+export declare function resolveAgentColor(value: string | undefined): string | undefined;
+/**
+ * Render one name as a padded background badge when `color` is valid. Claude
+ * Code uses one inverse color for every badge's text; black or white is picked
+ * by WCAG contrast here instead, so each palette entry stays readable. Invalid
+ * or omitted colors preserve the caller's existing theme styling.
+ */
+export declare function renderAgentNameLabel(name: string, color: string | undefined, theme: AgentNameTheme, style?: AgentNameStyle): string;
+/** Whether an agent renders as a badge — i.e. it has a valid configured color. */
+export declare function hasAgentBadge(type: string | undefined): boolean;
+/** Render a registered agent's display name with its configured color. */
+export declare function renderAgentName(type: string | undefined, theme: AgentNameTheme, style?: AgentNameStyle): string;
+export {};

package/dist/agent-color.js

@@ -0,0 +1,123 @@
+/**
+ * agent-color.ts — Claude Code-compatible agent name badges.
+ *
+ * Claude Code renders a subagent's name as a badge: the configured color is the
+ * background, the text an inverse foreground. Its eight named colors are
+ * reproduced here, along with six-digit hex and the extra palette names Agency
+ * Agents uses, so those definitions render as written.
+ */
+import { getConfig } from "./agent-types.js";
+const NAMED_AGENT_COLORS = {
+    // Claude Code's eight subagent colors, as its default theme renders them.
+    red: "#DC2626",
+    blue: "#6A9BCC",
+    green: "#16A34A",
+    yellow: "#CA8A04",
+    purple: "#827DBD",
+    orange: "#D97757",
+    pink: "#C46686",
+    cyan: "#0891B2",
+    // Agency Agents palette aliases.
+    amber: "#F59E0B",
+    teal: "#008080",
+    indigo: "#6366F1",
+    gold: "#EAB308",
+    "neon-green": "#10B981",
+    "neon-cyan": "#06B6D4",
+    "metallic-blue": "#3B82F6",
+    violet: "#8B5CF6",
+    rose: "#F43F5E",
+    lime: "#84CC16",
+    gray: "#6B7280",
+    grey: "#6B7280",
+    fuchsia: "#D946EF",
+    slate: "#64748B",
+    navy: "#1E3A8A",
+};
+const CUBE_VALUES = [0, 95, 135, 175, 215, 255];
+const GRAY_VALUES = Array.from({ length: 24 }, (_, i) => 8 + i * 10);
+const BLACK = { r: 0, g: 0, b: 0 };
+const WHITE = { r: 255, g: 255, b: 255 };
+/** Resolve Claude Code/Agency Agents color syntax to normalized #RRGGBB. */
+export function resolveAgentColor(value) {
+    if (!value)
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    const resolved = NAMED_AGENT_COLORS[normalized] ?? normalized;
+    return /^#[0-9a-f]{6}$/i.test(resolved) ? resolved.toUpperCase() : undefined;
+}
+function parseHex(hex) {
+    return {
+        r: Number.parseInt(hex.slice(1, 3), 16),
+        g: Number.parseInt(hex.slice(3, 5), 16),
+        b: Number.parseInt(hex.slice(5, 7), 16),
+    };
+}
+/** Index of the entry in `values` closest to `value`. */
+function nearest(values, value) {
+    return values.reduce((best, v, i) => (Math.abs(value - v) < Math.abs(value - values[best]) ? i : best), 0);
+}
+/**
+ * Quantize to the xterm-256 palette the way pi's own theme does, returning both
+ * the index to emit and the color the terminal will actually show — badge
+ * contrast is judged against the latter.
+ */
+function rgbTo256({ r, g, b }) {
+    const [rIndex, gIndex, bIndex] = [r, g, b].map((channel) => nearest(CUBE_VALUES, channel));
+    const distance = ({ r: cr, g: cg, b: cb }) => 0.299 * (r - cr) ** 2 + 0.587 * (g - cg) ** 2 + 0.114 * (b - cb) ** 2;
+    const grayIndex = nearest(GRAY_VALUES, Math.round(0.299 * r + 0.587 * g + 0.114 * b));
+    const gray = { r: GRAY_VALUES[grayIndex], g: GRAY_VALUES[grayIndex], b: GRAY_VALUES[grayIndex] };
+    const cube = { r: CUBE_VALUES[rIndex], g: CUBE_VALUES[gIndex], b: CUBE_VALUES[bIndex] };
+    // Only near-neutral colors may take the gray ramp; anything else keeps its tint.
+    if (Math.max(r, g, b) - Math.min(r, g, b) < 10 && distance(gray) < distance(cube)) {
+        return { index: 232 + grayIndex, rgb: gray };
+    }
+    return { index: 16 + 36 * rIndex + 6 * gIndex + bIndex, rgb: cube };
+}
+function ansiColor(layer, color) {
+    const code = layer === "foreground" ? 38 : 48;
+    return typeof color === "number"
+        ? `\u001b[${code};5;${color}m`
+        : `\u001b[${code};2;${color.r};${color.g};${color.b}m`;
+}
+function relativeLuminance({ r, g, b }) {
+    const linear = (value) => {
+        const channel = value / 255;
+        return channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4;
+    };
+    return 0.2126 * linear(r) + 0.7152 * linear(g) + 0.0722 * linear(b);
+}
+/**
+ * Render one name as a padded background badge when `color` is valid. Claude
+ * Code uses one inverse color for every badge's text; black or white is picked
+ * by WCAG contrast here instead, so each palette entry stays readable. Invalid
+ * or omitted colors preserve the caller's existing theme styling.
+ */
+export function renderAgentNameLabel(name, color, theme, style = {}) {
+    const resolved = resolveAgentColor(color);
+    if (!resolved) {
+        const text = style.bold ? theme.bold(name) : name;
+        return style.fallbackColor ? theme.fg(style.fallbackColor, text) : text;
+    }
+    const rgb = parseHex(resolved);
+    const quantized = (theme.getColorMode?.() ?? "truecolor") === "256color" ? rgbTo256(rgb) : undefined;
+    const shown = quantized?.rgb ?? rgb;
+    const contrasting = relativeLuminance(shown) > 0.179 ? BLACK : WHITE;
+    const label = style.bold ? theme.bold(` ${name} `) : ` ${name} `;
+    return ansiColor("background", quantized?.index ?? rgb)
+        + ansiColor("foreground", quantized ? rgbTo256(contrasting).index : contrasting)
+        + label
+        + "\u001b[39m"
+        + (style.restoreBackground ?? "\u001b[49m");
+}
+/** Whether an agent renders as a badge — i.e. it has a valid configured color. */
+export function hasAgentBadge(type) {
+    return type !== undefined && resolveAgentColor(getConfig(type).color) !== undefined;
+}
+/** Render a registered agent's display name with its configured color. */
+export function renderAgentName(type, theme, style = {}) {
+    if (!type)
+        return renderAgentNameLabel("Agent", undefined, theme, style);
+    const config = getConfig(type);
+    return renderAgentNameLabel(config.displayName, config.color, theme, style);
+}

package/dist/agent-file-toggle.d.ts

@@ -0,0 +1,125 @@
+/**
+ * agent-file-toggle.ts — Pure helpers for the `/agents` file-editing operations:
+ * locating an agent's .md file, toggling its `enabled:` frontmatter flag, and
+ * serializing an AgentConfig back to frontmatter for eject.
+ *
+ * These live outside src/index.ts so they can be tested directly: the `/agents`
+ * command handler is an ~890-line closure reached only through `registerCommand`,
+ * which every test mocks.
+ *
+ * The read side of this data (src/custom-agents.ts) parses frontmatter with a
+ * real YAML parser, so it honors `enabled: false` at any position in the block.
+ * This module must agree with it, and splits the work accordingly:
+ *
+ * - Deciding whether a file is disabled is a *read*, so it calls that same parser
+ *   (`isDisabledContent`) instead of mirroring it. A mirror has to be right about
+ *   YAML's boolean spellings and about pi's fence scan, and a regex was wrong
+ *   about both.
+ * - *Editing* cannot go through the parser, because re-serializing a parsed
+ *   document would reformat a file the README tells users to hand-author —
+ *   discarding their comments, key order, and quoting. So the edits are line-wise
+ *   and preserve everything they don't touch.
+ *
+ * That leaves removal best-effort: it recognizes a lowercase bare `false`, and
+ * reports `changed: false` for the spellings it cannot rewrite, so the caller
+ * refuses honestly rather than announcing a change it did not make.
+ */
+import type { AgentConfig } from "./types.js";
+export type AgentFileLocation = "project" | "workspace" | "personal";
+export declare const projectAgentsDir: (cwd?: string) => string;
+export declare const workspaceAgentsDir: (cwd?: string) => string;
+export declare const personalAgentsDir: () => string;
+/**
+ * Find the file path of a custom agent by name, in discovery-precedence order
+ * (project, workspace, then global). Mirrors the load-side precedence in
+ * src/custom-agents.ts — if the two drift, `/agents` edits a file the loader
+ * isn't reading.
+ */
+export declare function findAgentFile(name: string, cwd?: string): {
+    path: string;
+    location: AgentFileLocation;
+} | undefined;
+/**
+ * Find the file behind a *loaded* agent, preferring the path the loader
+ * actually read (`AgentConfig.sourcePath`) over the `<type>.md` guess.
+ *
+ * An agent's type comes from its frontmatter `name:` now, so the two can
+ * disagree: `reviewer.md` declaring `name: code-reviewer` is loaded as
+ * `code-reviewer`, and probing for `code-reviewer.md` finds nothing. That is
+ * not a harmless miss — `/agents → Disable` would then take the no-file branch
+ * and write a NEW `code-reviewer.md` stub, which loses to `reviewer.md` on
+ * load, leaving the agent enabled while reporting success.
+ *
+ * The probe stays as the fallback: a built-in that was never ejected has no
+ * `sourcePath`, and a path can go stale between a load and this call.
+ */
+export declare function locateAgentFile(name: string, sourcePath: string | undefined, cwd?: string): {
+    path: string;
+    location: AgentFileLocation;
+} | undefined;
+export type DisableOutcome = "disabled" | "already-disabled" | "no-frontmatter";
+/**
+ * Does the loader consider this file disabled?
+ *
+ * Detection is a READ operation, so it asks the same parser the loader uses
+ * rather than mirroring it with a regex — that mirror has to be right about
+ * YAML's boolean spellings (`False`, `FALSE`, a trailing `# comment`, a quoted
+ * key) *and* about pi's fence scan, which closes the block on any line starting
+ * `---` and so ends it early on `----`. A throw means the file is already
+ * unparseable, which is what the loader sees too: it skips the agent, so there
+ * is no "disabled" state to report.
+ */
+export declare function isDisabledContent(content: string): boolean;
+/**
+ * Add `enabled: false` to a file's frontmatter.
+ *
+ * `outcome` distinguishes a real edit from a no-op so the caller can report
+ * honestly instead of unconditionally claiming success.
+ */
+export declare function disableInContent(content: string): {
+    content: string;
+    outcome: DisableOutcome;
+};
+/**
+ * Remove `enabled: false` from a file's frontmatter, wherever it appears in the
+ * block — the loader honors the key at any position, so the two must agree or a
+ * hand-authored agent can be disabled and never re-enabled.
+ *
+ * `changed` is false when the key wasn't found, so the caller can avoid
+ * reporting "Enabled <name>" for a write that did nothing.
+ */
+export declare function enableInContent(content: string): {
+    content: string;
+    changed: boolean;
+};
+/** Is this the empty stub `/agents` writes when disabling a built-in default? */
+export declare function isEmptyStub(content: string): boolean;
+/** The answers `/agents → Create agent → Manual` collects, before serialization. */
+export interface NewAgentInput {
+    description: string;
+    /** Already-resolved `tools:` value ("none", "all", or a CSV of tool names). */
+    tools: string;
+    /** `provider/modelId`, or undefined to inherit the parent's model. */
+    model?: string;
+    /** A pi thinking level, or undefined to inherit. */
+    thinking?: string;
+    systemPrompt: string;
+}
+/**
+ * Build the .md file the create wizard writes.
+ *
+ * `description` and `model` come straight from a free-text prompt, so they are
+ * quoted rather than interpolated — `serializeAgentFile` above quotes the
+ * description for the same reason. An unquoted YAML scalar mishandles ordinary
+ * input in two ways, and both are silent: a colon ("Scout: find things") makes
+ * the file unparseable, and since #212 an unparseable agent file is *skipped*,
+ * so the wizard reports success for an agent that does not exist; a `#`
+ * ("audit #security") opens a comment and truncates the value. `model` can
+ * carry a colon too — pi accepts a `provider/model:thinking` suffix.
+ *
+ * `tools` and `thinking` are not quoted: both are chosen from fixed menus, and
+ * `tools` is a CSV that must stay a bare scalar for the loader's parser.
+ */
+export declare function buildNewAgentFile(input: NewAgentInput): string;
+/** Serialize an AgentConfig to a full .md file (frontmatter + system prompt) for eject. */
+export declare function serializeAgentFile(cfg: AgentConfig): string;