@clanker-code/pi-subagents 0.10.5

package/dist/peek.js

@@ -0,0 +1,121 @@
+/**
+ * peek.ts — Lightweight tail/filter view of an agent's result or streaming
+ * output file for `get_subagent_result`'s `peek` parameter.
+ *
+ * Design:
+ * - Source precedence: streaming output file (best for running agents) → record
+ *   result (finished agents) → "no output yet".
+ * - The output file is JSONL (one entry per message). We extract human-readable
+ *   text lines (assistant text + tool-result text) so a peek shows useful
+ *   progress, not raw JSON.
+ * - Semantics: filter-then-tail. If `regex` is given, only matching source lines
+ *   are kept; then `after` (return all lines past an index) or `lines` (last N)
+ *   is applied. Line numbers always refer to the FULL source so callers can use
+ *   `after` for incremental updates without missing anything.
+ */
+import { existsSync, readFileSync } from "node:fs";
+/** Default number of tail lines when neither `after` nor `lines` is given. */
+const DEFAULT_LINES = 20;
+/**
+ * Produce a peek view of an agent's output. Returns null when there is no
+ * source content at all (the caller renders a "no output yet" message).
+ */
+export function peekAgentOutput(record, opts = {}) {
+    const lines = readSourceLines(record);
+    if (lines.length === 0)
+        return null;
+    const regex = opts.regex ? compileRegex(opts.regex) : undefined;
+    const after = typeof opts.after === "number" ? opts.after : -1;
+    const tail = typeof opts.lines === "number" && opts.lines >= 1 ? opts.lines : DEFAULT_LINES;
+    // Index each source line with its original position (1-based for display).
+    const indexed = lines.map((text, i) => ({ no: i + 1, text }));
+    // Filter-then-select.
+    const filtered = regex ? indexed.filter((l) => regex.test(l.text)) : indexed;
+    const selected = after >= 0
+        ? filtered.filter((l) => l.no > after)
+        : filtered.slice(-tail);
+    const totalLines = lines.length;
+    const isRunning = record.status === "running" || record.status === "queued";
+    const source = isRunning && record.outputFile && existsSync(record.outputFile) ? "outputFile" : "result";
+    const header = buildHeader(opts, selected.length, totalLines, source);
+    const body = selected.map((l) => `[${l.no}] ${l.text}`).join("\n");
+    return { text: `${header}\n\n${body}`, totalLines, source };
+}
+/** Read the most useful text lines from the agent's output. */
+function readSourceLines(record) {
+    const isRunning = record.status === "running" || record.status === "queued";
+    const outputFileLines = record.outputFile && existsSync(record.outputFile) ? parseOutputFileLines(record.outputFile) : [];
+    // While running, the live output file is the only source of progress.
+    if (isRunning && outputFileLines.length > 0)
+        return outputFileLines;
+    // Finished (or no live file): prefer the clean result text.
+    if (record.result?.trim()) {
+        return record.result.split("\n");
+    }
+    // Last resort: the output file (e.g. agent errored before producing a result).
+    return outputFileLines;
+}
+/**
+ * Parse the JSONL output file and extract human-readable text lines.
+ * Each entry has `{ type, message: { role, content } }`. We pull assistant text
+ * and tool-result text so a peek reflects actual progress.
+ */
+function parseOutputFileLines(path) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf-8");
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(trimmed);
+        }
+        catch {
+            continue;
+        }
+        const content = entry?.message?.content;
+        if (!Array.isArray(content)) {
+            // Some entries may carry a plain string content.
+            if (typeof content === "string" && content.trim())
+                out.push(content.trim());
+            continue;
+        }
+        for (const block of content) {
+            if (block?.type === "text" && typeof block.text === "string" && block.text.trim()) {
+                out.push(block.text.trimEnd());
+            }
+        }
+    }
+    return out;
+}
+function compileRegex(pattern) {
+    // Anchor-free; case-sensitive by default. Invalid patterns fall back to a
+    // substring literal match so a bad regex never throws into the tool result.
+    try {
+        return new RegExp(pattern);
+    }
+    catch {
+        return new RegExp(pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+    }
+}
+function buildHeader(opts, shown, total, source) {
+    const parts = [];
+    if (typeof opts.after === "number") {
+        parts.push(`after line number ${opts.after}`);
+    }
+    else {
+        const n = typeof opts.lines === "number" && opts.lines >= 1 ? opts.lines : DEFAULT_LINES;
+        parts.push(`last ${n} lines`);
+    }
+    if (opts.regex)
+        parts.push(`filtered by regex /${opts.regex}/`);
+    parts.push(`of ${total} total (${source === "outputFile" ? "live output file" : "result"})`);
+    return `Showing ${shown} ${parts.join(", ")}. Line numbers index the full source.`;
+}

package/dist/prompts.d.ts

@@ -0,0 +1,40 @@
+/**
+ * prompts.ts — System prompt builder for agents.
+ */
+import type { AgentConfig, EnvInfo } from "./types.js";
+/** Extra sections to inject into the system prompt (memory, skills, etc.). */
+export interface PromptExtras {
+    /** Persistent memory content to inject (first 200 lines of MEMORY.md + instructions). */
+    memoryBlock?: string;
+    /** Preloaded skill contents to inject. */
+    skillBlocks?: {
+        name: string;
+        content: string;
+    }[];
+    /** Manager-assigned agent id, used for recursive subagent metadata. */
+    agentId?: string;
+    /** Parent subagent id when this agent was spawned recursively. */
+    parentAgentId?: string;
+    /** Recursive subagent depth. */
+    depth?: number;
+    /** Maximum recursive subagent depth. */
+    maxDepth?: number;
+}
+/**
+ * Build the system prompt for an agent from its config.
+ *
+ * - "replace" mode: env header + config.systemPrompt (full control, no parent identity)
+ * - "append" mode: parent system prompt + sub-agent context + env header + config.systemPrompt
+ * - "append" with empty systemPrompt: pure parent clone
+ *
+ * Both modes include an `<active_agent name="${config.name}"/>` tag so downstream
+ * extensions (e.g. permission/policy systems) can resolve per-agent policy
+ * inside the child session by parsing the system prompt. In replace mode the tag
+ * is prepended; in append mode it follows the shared inherited content so the
+ * parent prompt forms an identical, cacheable byte prefix with the parent
+ * session (the LLM's KV cache can then reuse those tokens across every spawn).
+ *
+ * @param parentSystemPrompt  The parent agent's effective system prompt (for append mode).
+ * @param extras  Optional extra sections to inject (memory, preloaded skills).
+ */
+export declare function buildAgentPrompt(config: AgentConfig, cwd: string, env: EnvInfo, parentSystemPrompt?: string, extras?: PromptExtras): string;

package/dist/prompts.js

@@ -0,0 +1,95 @@
+/**
+ * prompts.ts — System prompt builder for agents.
+ */
+function xmlAttr(value) {
+    if (value == null)
+        return undefined;
+    return String(value)
+        .replace(/&/g, "&")
+        .replace(/"/g, """)
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}
+/**
+ * Build the system prompt for an agent from its config.
+ *
+ * - "replace" mode: env header + config.systemPrompt (full control, no parent identity)
+ * - "append" mode: parent system prompt + sub-agent context + env header + config.systemPrompt
+ * - "append" with empty systemPrompt: pure parent clone
+ *
+ * Both modes include an `<active_agent name="${config.name}"/>` tag so downstream
+ * extensions (e.g. permission/policy systems) can resolve per-agent policy
+ * inside the child session by parsing the system prompt. In replace mode the tag
+ * is prepended; in append mode it follows the shared inherited content so the
+ * parent prompt forms an identical, cacheable byte prefix with the parent
+ * session (the LLM's KV cache can then reuse those tokens across every spawn).
+ *
+ * @param parentSystemPrompt  The parent agent's effective system prompt (for append mode).
+ * @param extras  Optional extra sections to inject (memory, preloaded skills).
+ */
+export function buildAgentPrompt(config, cwd, env, parentSystemPrompt, extras) {
+    const activeAgentAttrs = [
+        ["name", config.name],
+        ["agent_id", extras?.agentId],
+        ["parent_agent_id", extras?.parentAgentId],
+        ["depth", extras?.depth],
+        ["max_depth", extras?.maxDepth],
+    ]
+        .map(([name, value]) => {
+        const escaped = xmlAttr(value);
+        return escaped == null ? undefined : `${name}="${escaped}"`;
+    })
+        .filter(Boolean)
+        .join(" ");
+    const activeAgentTag = `<active_agent ${activeAgentAttrs}/>\n\n`;
+    const envBlock = `# Environment
+Working directory: ${cwd}
+${env.isGitRepo ? `Git repository: yes\nBranch: ${env.branch}` : "Not a git repository"}
+Platform: ${env.platform}`;
+    // Build optional extras suffix
+    const extraSections = [];
+    if (extras?.memoryBlock) {
+        extraSections.push(extras.memoryBlock);
+    }
+    if (extras?.skillBlocks?.length) {
+        for (const skill of extras.skillBlocks) {
+            extraSections.push(`\n# Preloaded Skill: ${skill.name}\n${skill.content}`);
+        }
+    }
+    const extrasSuffix = extraSections.length > 0 ? "\n\n" + extraSections.join("\n") : "";
+    if (config.promptMode === "append") {
+        const identity = parentSystemPrompt || genericBase;
+        const bridge = `<sub_agent_context>
+You are operating as a sub-agent invoked to handle a specific task.
+- Use the read tool instead of cat/head/tail
+- Use the edit tool instead of sed/awk
+- Use the write tool instead of echo/heredoc
+- Use the find tool instead of bash find/ls for file search
+- Use the grep tool instead of bash grep/rg for content search
+- Make independent tool calls in parallel
+- Use absolute file paths
+- Do not use emojis
+- Be concise but complete
+</sub_agent_context>`;
+        const customSection = config.systemPrompt?.trim()
+            ? `\n\n<agent_instructions>\n${config.systemPrompt}\n</agent_instructions>`
+            : "";
+        // Place shared/stable content first so the LLM's KV cache can reuse the
+        // inherited prefix across all subagent invocations. The parent prompt is
+        // placed verbatim (no wrapper tag) so it forms an identical byte prefix
+        // with the parent session, maximising KV cache hits. The <active_agent>
+        // tag and env block vary per call and are placed after the cached prefix.
+        return identity + "\n\n" + bridge + "\n\n" + activeAgentTag + envBlock + customSection + extrasSuffix;
+    }
+    // "replace" mode — env header + the config's full system prompt
+    const replaceHeader = `You are a pi coding agent sub-agent.
+You have been invoked to handle a specific task autonomously.
+
+${envBlock}`;
+    return activeAgentTag + replaceHeader + "\n\n" + config.systemPrompt + extrasSuffix;
+}
+/** Fallback base prompt when parent system prompt is unavailable in append mode. */
+const genericBase = `# Role
+You are a general-purpose coding agent for complex, multi-step tasks.
+You have full access to read, write, edit files, and execute commands.
+Do what has been asked; nothing more, nothing less.`;

package/dist/schedule-store.d.ts

@@ -0,0 +1,38 @@
+/**
+ * schedule-store.ts — File-backed store for scheduled subagents.
+ *
+ * Session-scoped: each pi session owns its own schedules at
+ * `<cwd>/.pi/subagent-schedules/<sessionId>.json`. `/new` starts a fresh
+ * empty store; `/resume` reloads.
+ *
+ * Concurrency model lifted from pi-chonky-tasks/src/task-store.ts: every
+ * mutation acquires a PID-based exclusion lock, re-reads the latest state
+ * from disk, applies the change, atomic-writes via temp+rename, releases.
+ */
+import type { ScheduledSubagent } from "./types.js";
+/** Resolve the storage path for a session-scoped store. */
+export declare function resolveStorePath(cwd: string, sessionId: string): string;
+export declare class ScheduleStore {
+    private filePath;
+    private lockPath;
+    private jobs;
+    constructor(filePath: string);
+    /** Create the backing directory lazily — only when we're about to persist. */
+    private ensureDir;
+    /** Load from disk into the in-memory cache. Silent on parse errors. */
+    private load;
+    /** Atomic write via temp file + rename (POSIX-atomic). */
+    private save;
+    /** Acquire lock → reload → mutate → save → release. */
+    private withLock;
+    /** Read-only — returns a snapshot of the in-memory cache. */
+    list(): ScheduledSubagent[];
+    /** Read-only check — uses the cache. */
+    hasName(name: string, exceptId?: string): boolean;
+    get(id: string): ScheduledSubagent | undefined;
+    add(job: ScheduledSubagent): void;
+    update(id: string, patch: Partial<ScheduledSubagent>): ScheduledSubagent | undefined;
+    remove(id: string): boolean;
+    /** Delete the backing file (used when no jobs remain, optional cleanup). */
+    deleteFileIfEmpty(): void;
+}

package/dist/schedule-store.js

@@ -0,0 +1,155 @@
+/**
+ * schedule-store.ts — File-backed store for scheduled subagents.
+ *
+ * Session-scoped: each pi session owns its own schedules at
+ * `<cwd>/.pi/subagent-schedules/<sessionId>.json`. `/new` starts a fresh
+ * empty store; `/resume` reloads.
+ *
+ * Concurrency model lifted from pi-chonky-tasks/src/task-store.ts: every
+ * mutation acquires a PID-based exclusion lock, re-reads the latest state
+ * from disk, applies the change, atomic-writes via temp+rename, releases.
+ */
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+const LOCK_RETRY_MS = 50;
+const LOCK_MAX_RETRIES = 100;
+function isProcessRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function acquireLock(lockPath) {
+    for (let i = 0; i < LOCK_MAX_RETRIES; i++) {
+        try {
+            writeFileSync(lockPath, `${process.pid}`, { flag: "wx" });
+            return;
+        }
+        catch (e) {
+            if (e.code === "EEXIST") {
+                try {
+                    const pid = parseInt(readFileSync(lockPath, "utf-8"), 10);
+                    if (pid && !isProcessRunning(pid)) {
+                        unlinkSync(lockPath);
+                        continue;
+                    }
+                }
+                catch { /* ignore — try again */ }
+                const start = Date.now();
+                while (Date.now() - start < LOCK_RETRY_MS) { /* busy wait */ }
+                continue;
+            }
+            throw e;
+        }
+    }
+    throw new Error(`Failed to acquire schedule lock: ${lockPath}`);
+}
+function releaseLock(lockPath) {
+    try {
+        unlinkSync(lockPath);
+    }
+    catch { /* ignore */ }
+}
+/** Resolve the storage path for a session-scoped store. */
+export function resolveStorePath(cwd, sessionId) {
+    return join(cwd, ".pi", "subagent-schedules", `${sessionId}.json`);
+}
+export class ScheduleStore {
+    filePath;
+    lockPath;
+    jobs = new Map();
+    constructor(filePath) {
+        this.filePath = filePath;
+        this.lockPath = filePath + ".lock";
+        this.load();
+    }
+    /** Create the backing directory lazily — only when we're about to persist. */
+    ensureDir() {
+        mkdirSync(dirname(this.filePath), { recursive: true });
+    }
+    /** Load from disk into the in-memory cache. Silent on parse errors. */
+    load() {
+        if (!existsSync(this.filePath))
+            return;
+        try {
+            const data = JSON.parse(readFileSync(this.filePath, "utf-8"));
+            this.jobs.clear();
+            for (const j of data.jobs ?? [])
+                this.jobs.set(j.id, j);
+        }
+        catch { /* corrupt — start fresh, next save rewrites */ }
+    }
+    /** Atomic write via temp file + rename (POSIX-atomic). */
+    save() {
+        const data = { version: 1, jobs: [...this.jobs.values()] };
+        const tmp = this.filePath + ".tmp";
+        writeFileSync(tmp, JSON.stringify(data, null, 2));
+        renameSync(tmp, this.filePath);
+    }
+    /** Acquire lock → reload → mutate → save → release. */
+    withLock(fn) {
+        this.ensureDir();
+        acquireLock(this.lockPath);
+        try {
+            this.load();
+            const result = fn();
+            this.save();
+            return result;
+        }
+        finally {
+            releaseLock(this.lockPath);
+        }
+    }
+    /** Read-only — returns a snapshot of the in-memory cache. */
+    list() {
+        return [...this.jobs.values()];
+    }
+    /** Read-only check — uses the cache. */
+    hasName(name, exceptId) {
+        for (const j of this.jobs.values()) {
+            if (j.id !== exceptId && j.name === name)
+                return true;
+        }
+        return false;
+    }
+    get(id) {
+        return this.jobs.get(id);
+    }
+    add(job) {
+        this.withLock(() => {
+            this.jobs.set(job.id, job);
+        });
+    }
+    update(id, patch) {
+        // No-op fast path — an unknown id changes nothing, so don't lock or touch
+        // disk (which would otherwise lazily create the backing directory).
+        if (!this.jobs.has(id))
+            return undefined;
+        return this.withLock(() => {
+            const existing = this.jobs.get(id);
+            if (!existing)
+                return undefined;
+            const updated = { ...existing, ...patch };
+            this.jobs.set(id, updated);
+            return updated;
+        });
+    }
+    remove(id) {
+        // No-op fast path — see update().
+        if (!this.jobs.has(id))
+            return false;
+        return this.withLock(() => this.jobs.delete(id));
+    }
+    /** Delete the backing file (used when no jobs remain, optional cleanup). */
+    deleteFileIfEmpty() {
+        if (this.jobs.size === 0 && existsSync(this.filePath)) {
+            try {
+                unlinkSync(this.filePath);
+            }
+            catch { /* ignore */ }
+        }
+    }
+}

package/dist/schedule.d.ts

@@ -0,0 +1,109 @@
+/**
+ * schedule.ts — `SubagentScheduler`: timer-driven dispatcher of scheduled subagents.
+ *
+ * Mirrors the engine shape of pi-cron-schedule/src/scheduler.ts:
+ *   - two-Map split (jobs = croner Cron, intervals = setInterval/setTimeout)
+ *   - addJob/removeJob/updateJob/scheduleJob/unscheduleJob/executeJob
+ *   - static parsers for cron / "+10m" / "5m" / ISO formats
+ *
+ * Differences vs pi-cron-schedule:
+ *   - Persistence is via ScheduleStore (PID-locked, session-scoped, atomic).
+ *   - `executeJob` calls `manager.spawn(..., { bypassQueue: true })` instead
+ *     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
+ *     steering-style `subagent-notification` path. No new delivery code.
+ */
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AgentManager } from "./agent-manager.js";
+import type { ScheduleStore } from "./schedule-store.js";
+import type { IsolationMode, ScheduledSubagent, SubagentType, ThinkingLevel } from "./types.js";
+/** Event emitted on `pi.events` for cross-extension consumers. */
+export type ScheduleChangeEvent = {
+    type: "added";
+    job: ScheduledSubagent;
+} | {
+    type: "removed";
+    jobId: string;
+} | {
+    type: "updated";
+    job: ScheduledSubagent;
+} | {
+    type: "fired";
+    jobId: string;
+    agentId: string;
+    name: string;
+} | {
+    type: "error";
+    jobId: string;
+    error: string;
+};
+/** Params accepted at job creation — ID, timestamps, and state are derived. */
+export interface NewJobInput {
+    name: string;
+    description: string;
+    schedule: string;
+    subagent_type: SubagentType;
+    prompt: string;
+    model?: string;
+    thinking?: ThinkingLevel;
+    max_turns?: number;
+    isolated?: boolean;
+    isolation?: IsolationMode;
+}
+export declare class SubagentScheduler {
+    private jobs;
+    private intervals;
+    private store;
+    private pi;
+    private ctx;
+    private manager;
+    /** Start the scheduler: bind to a session's store and arm enabled jobs. */
+    start(pi: ExtensionAPI, ctx: ExtensionContext, manager: AgentManager, store: ScheduleStore): void;
+    /** Stop all timers; drop refs. Safe to call repeatedly. */
+    stop(): void;
+    /** True if start() has bound a store and the scheduler is active. */
+    isActive(): boolean;
+    list(): ScheduledSubagent[];
+    /**
+     * Build a `ScheduledSubagent` from user input. Validates the schedule
+     * format and tags `scheduleType`. Throws on invalid input.
+     */
+    buildJob(input: NewJobInput): ScheduledSubagent;
+    /** Add a job, persist, and arm if enabled. Returns the stored job. */
+    addJob(input: NewJobInput): ScheduledSubagent;
+    removeJob(id: string): boolean;
+    /** Toggle / mutate a job. Re-arms based on the new `enabled` state. */
+    updateJob(id: string, patch: Partial<ScheduledSubagent>): ScheduledSubagent | undefined;
+    /** Next-run time as ISO, or undefined if not currently armed. */
+    getNextRun(jobId: string): string | undefined;
+    private scheduleJob;
+    private unscheduleJob;
+    /**
+     * Fire a job: persist running state, spawn (bypassing the concurrency
+     * queue), persist completion. Fire-and-forget: the timer tick returns
+     * immediately so other jobs keep firing.
+     */
+    private executeJob;
+    private emit;
+    private requireStore;
+    /**
+     * Sniff a schedule string and tag its type. Throws on invalid input.
+     * Order matters: relative ("+10m") and interval ("5m") both match digit+unit;
+     * relative requires the leading "+" to disambiguate.
+     */
+    static detectSchedule(s: string): {
+        type: "cron" | "once" | "interval";
+        intervalMs?: number;
+        normalized: string;
+    };
+    /** 6-field cron — 'second minute hour dom month dow'. */
+    static validateCronExpression(expr: string): {
+        valid: boolean;
+        error?: string;
+    };
+    /** "+10s"/"+5m"/"+1h"/"+2d" → ISO timestamp. */
+    static parseRelativeTime(s: string): string | null;
+    /** "10s"/"5m"/"1h"/"2d" → milliseconds. */
+    static parseInterval(s: string): number | null;
+}