@ymy88/pi-subagents 0.0.0-stage → 0.24.0

package/dist/prompts.js

@@ -0,0 +1,121 @@
+/**
+ * prompts.ts — System prompt builder for agents.
+ */
+/**
+ * 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 activeAgentTag = `<active_agent name="${config.name}"/>\n\n`;
+    const envBlock = `# Environment
+Working directory: ${cwd}
+${env.isGitRepo ? `Git repository: yes\nBranch: ${env.branch}` : "Not a git repository"}
+Platform: ${env.platform}`;
+    // A worktree agent is told its cwd twice: by the env block above (the copy)
+    // and by whatever names the main checkout — the inherited parent prompt in
+    // append mode, or the task prompt in either mode. It follows the latter and
+    // works in the shared tree (#187), so resolve the contradiction explicitly.
+    const worktreeBlock = extras?.worktreeBase
+        ? `\n\n<worktree_isolation>
+Your working directory is an isolated git worktree copy of ${extras.worktreeBase}.
+Work only inside it — never in ${extras.worktreeBase}, even if other instructions name that path as your working directory.
+</worktree_isolation>`
+        : "";
+    // The script, not a person, reads what this child returns — see
+    // `PromptExtras.workflowChild` for why only workflow children get this.
+    const workflowBlock = extras?.workflowChild
+        ? `\n\n<workflow_child>
+Your final message IS the return value of this task. A workflow script captures it and passes it to the next stage; no person reads it.
+Return only the answer, in exactly the shape the prompt asks for — no preamble, no summary of what you did, no offer to continue.
+</workflow_child>`
+        : "";
+    // 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 + worktreeBlock + workflowBlock + 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 + worktreeBlock + workflowBlock + "\n\n" + config.systemPrompt + extrasSuffix;
+}
+/**
+ * The part of the parent's rendered system prompt that an append-mode child inherits.
+ *
+ * Pi renders a prompt as the preamble followed by tagged sections in a fixed order:
+ * `tools`, `rules`, `docs` (default preamble only), `addendum`, `project_context`,
+ * `skills`, `cwd`, then the sections extensions add during a turn. The child session renders its own `skills` (from its `skills:`
+ * setting), its own `cwd` and its own extension sections after the inherited text.
+ * Inheriting the parent's copies too listed them twice, showed the parent's skills to
+ * children configured with `skills: false` or a preload list, and left copies that
+ * section-editing extensions in the child cannot reach. It also made the result depend
+ * on timing: `getSystemPrompt()` includes the extension sections only while the
+ * parent's turn runs.
+ *
+ * Returns the text before the `skills` section, or before the `cwd` section when there
+ * are no skills. A prompt without the `cwd` section (for example, a forced prompt) is
+ * returned unchanged.
+ *
+ * @param rendered  The parent's `ctx.getSystemPrompt()`.
+ * @param cwd  The cwd the parent's prompt was rendered with.
+ */
+export function inheritableParentPrompt(rendered, cwd) {
+    const cwdAt = rendered.lastIndexOf(`\n\n<cwd>\n${cwd.replace(/\\/g, "/")}\n</cwd>`);
+    if (cwdAt < 0)
+        return rendered;
+    const head = rendered.slice(0, cwdAt);
+    if (!head.endsWith("\n</skills>"))
+        return head;
+    const skillsAt = head.lastIndexOf("\n\n<skills>\n");
+    return skillsAt < 0 ? head : head.slice(0, skillsAt);
+}
+/** 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
+ *     `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;
+}