@a5c-ai/agent-platform 5.0.1-staging.b436b3b3e611

package/dist/harness/piWrapper.js

@@ -0,0 +1,389 @@
+"use strict";
+/**
+ * Pi programmatic API wrapper.
+ *
+ * Wraps `@mariozechner/pi-coding-agent`'s `createAgentSession()` to expose
+ * a persistent `AgentSession` through a babysitter-friendly interface.
+ *
+ * The session is lazily initialized on first use and reused across prompts.
+ * Events are forwarded through the `subscribe()` method.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentCoreSessionHandle = void 0;
+exports.createAgentCoreSession = createAgentCoreSession;
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const babysitter_sdk_1 = require("@a5c-ai/babysitter-sdk");
+const piSecureSandbox_1 = require("./piSecureSandbox");
+const compaction_1 = require("./piWrapper/compaction");
+const instructionPrompts_1 = require("./piWrapper/instructionPrompts");
+const moduleSupport_1 = require("./piWrapper/moduleSupport");
+const DEFAULT_TIMEOUT_MS = 900_000;
+const DEFAULT_BASH_SANDBOX_MODE = "local";
+const AGENT_END_PROMPT_SETTLE_GRACE_MS = 250;
+const PI_AGENT_DIR_ENV = "PI_CODING_AGENT_DIR";
+const DEFAULT_PI_AGENT_DIR = (0, node_path_1.join)((0, node_os_1.homedir)(), ".pi", "agent");
+const CODING_TOOL_NAMES = ["read", "bash", "edit", "write"];
+const READONLY_TOOL_NAMES = ["read", "grep", "find", "ls"];
+function resolvePiAgentDir(agentDir) {
+    const configured = agentDir?.trim() || process.env[PI_AGENT_DIR_ENV]?.trim();
+    if (!configured) {
+        return DEFAULT_PI_AGENT_DIR;
+    }
+    if (configured === "~") {
+        return (0, node_os_1.homedir)();
+    }
+    if (configured.startsWith("~/")) {
+        return (0, node_path_1.join)((0, node_os_1.homedir)(), configured.slice(2));
+    }
+    return configured;
+}
+// ---------------------------------------------------------------------------
+// AgentCoreSessionHandle
+// ---------------------------------------------------------------------------
+/**
+ * Handle for interacting with the Pi coding agent programmatically.
+ *
+ * Wraps `AgentSession` from `@mariozechner/pi-coding-agent`. The underlying
+ * session is created lazily on first `prompt()` call and reused thereafter.
+ */
+class AgentCoreSessionHandle {
+    options;
+    session = null;
+    initPromise = null;
+    cleanupTasks = [];
+    constructor(options = {}) {
+        this.options = options;
+    }
+    /**
+     * Initialize the underlying AgentSession.
+     *
+     * Called automatically by `prompt()` if the session hasn't been created yet.
+     * Safe to call multiple times — subsequent calls are no-ops.
+     */
+    async initialize() {
+        if (this.session)
+            return;
+        if (this.initPromise) {
+            await this.initPromise;
+            return;
+        }
+        this.initPromise = this.doInitialize().catch((err) => {
+            this.initPromise = null;
+            throw err;
+        });
+        await this.initPromise;
+    }
+    /**
+     * Send a prompt to the Pi agent and wait for completion.
+     *
+     * Initializes the session if needed, sends the prompt, waits for the
+     * `agent_end` event, and returns collected output.
+     */
+    async prompt(text, timeout) {
+        await this.initialize();
+        const session = this.requireSession();
+        const effectiveTimeout = timeout ?? this.options.timeout ?? DEFAULT_TIMEOUT_MS;
+        const start = Date.now();
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let timer;
+            let agentEndGraceTimer;
+            let agentEndResult = null;
+            let promptSettled = false;
+            const finishWithResult = (result) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timer)
+                    clearTimeout(timer);
+                if (agentEndGraceTimer)
+                    clearTimeout(agentEndGraceTimer);
+                resolve(result);
+            };
+            const finishWithPromptError = (err) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timer)
+                    clearTimeout(timer);
+                if (agentEndGraceTimer)
+                    clearTimeout(agentEndGraceTimer);
+                const message = err instanceof Error ? err.message : String(err);
+                resolve({
+                    output: message,
+                    exitCode: 1,
+                    duration: Date.now() - start,
+                    success: false,
+                });
+            };
+            // Set up timeout
+            if (effectiveTimeout > 0) {
+                timer = setTimeout(() => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    unsubscribe();
+                    void session.abort();
+                    reject(new babysitter_sdk_1.BabysitterRuntimeError("PiTimeoutError", `Pi prompt timed out after ${effectiveTimeout}ms`, { category: babysitter_sdk_1.ErrorCategory.External }));
+                }, effectiveTimeout);
+            }
+            // Subscribe to events to detect completion
+            const unsubscribe = session.subscribe((event) => {
+                if (settled)
+                    return;
+                if (event.type === "agent_end") {
+                    const messages = Array.isArray(event.messages)
+                        ? event.messages
+                        : undefined;
+                    unsubscribe();
+                    const assistantFailure = (0, moduleSupport_1.extractAssistantFailure)(messages);
+                    const assistantText = session.getLastAssistantText();
+                    const output = assistantText && assistantText.trim().length > 0
+                        ? assistantText
+                        : assistantFailure ?? "";
+                    agentEndResult = {
+                        output,
+                        exitCode: assistantFailure ? 1 : 0,
+                        duration: Date.now() - start,
+                        success: !assistantFailure,
+                    };
+                    if (promptSettled) {
+                        finishWithResult(agentEndResult);
+                        return;
+                    }
+                    agentEndGraceTimer = setTimeout(() => {
+                        if (agentEndResult) {
+                            finishWithResult(agentEndResult);
+                        }
+                    }, AGENT_END_PROMPT_SETTLE_GRACE_MS);
+                }
+            });
+            // Fire the prompt — errors are caught and resolved as failures
+            session.prompt(text)
+                .then(() => {
+                promptSettled = true;
+                if (agentEndResult) {
+                    finishWithResult(agentEndResult);
+                }
+            })
+                .catch((err) => {
+                promptSettled = true;
+                if (agentEndResult) {
+                    finishWithResult(agentEndResult);
+                    return;
+                }
+                unsubscribe();
+                finishWithPromptError(err);
+            });
+        });
+    }
+    /**
+     * Steer the running agent with an instruction.
+     *
+     * Steering messages are delivered immediately to the agent while it is
+     * processing a prompt.
+     */
+    async steer(text) {
+        const session = this.requireSession();
+        await session.steer(text);
+    }
+    /** Queue a follow-up message for after the current turn completes. */
+    async followUp(text) {
+        const session = this.requireSession();
+        await session.followUp(text);
+    }
+    /**
+     * Subscribe to session events.
+     *
+     * Returns an unsubscribe function.
+     */
+    subscribe(listener) {
+        const session = this.requireSession();
+        return session.subscribe(listener);
+    }
+    /** Execute a bash command through the agent's sandbox. */
+    async executeBash(command, onChunk) {
+        await this.initialize();
+        const session = this.requireSession();
+        const result = await session.executeBash(command, onChunk);
+        return {
+            output: result.output,
+            exitCode: result.exitCode,
+            cancelled: result.cancelled,
+        };
+    }
+    /** Abort the current prompt execution. */
+    async abort() {
+        if (this.session) {
+            await this.session.abort();
+        }
+    }
+    /** Dispose of the session and release resources. */
+    dispose() {
+        if (this.session) {
+            const session = this.session;
+            if (session.isStreaming) {
+                void session.abort().catch(() => undefined);
+            }
+            session.dispose();
+            this.session = null;
+            this.initPromise = null;
+        }
+        while (this.cleanupTasks.length > 0) {
+            const cleanup = this.cleanupTasks.pop();
+            if (cleanup) {
+                void cleanup();
+            }
+        }
+    }
+    /** The underlying pi session ID, if initialized. */
+    get sessionId() {
+        return this.session?.sessionId;
+    }
+    /** Whether the session is currently streaming a response. */
+    get isStreaming() {
+        return this.session?.isStreaming ?? false;
+    }
+    /** Whether the session has been initialized. */
+    get isInitialized() {
+        return this.session !== null;
+    }
+    // ---------------------------------------------------------------------------
+    // Internal helpers
+    // ---------------------------------------------------------------------------
+    async cleanupPendingTasks() {
+        while (this.cleanupTasks.length > 0) {
+            const cleanup = this.cleanupTasks.pop();
+            if (cleanup) {
+                await cleanup();
+            }
+        }
+    }
+    async doInitialize() {
+        const mod = await (0, moduleSupport_1.loadPiModule)();
+        // Bridge common Azure env var aliases that pi-coding-agent doesn't know
+        // about.  Pi expects AZURE_OPENAI_RESOURCE_NAME; the user's profile may
+        // set AZURE_OPENAI_PROJECT_NAME instead.
+        (0, moduleSupport_1.configureAzureOpenAiEnvDefaults)(typeof this.options.model === "string" ? this.options.model : undefined);
+        const createOpts = {};
+        const cwd = this.options.workspace ?? process.cwd();
+        const agentDir = resolvePiAgentDir(this.options.agentDir);
+        const compressionConfig = (0, compaction_1.loadCompressionConfigSafe)(cwd);
+        const compactionEnabled = this.options.enableCompaction ??
+            Boolean(compressionConfig?.enabled && compressionConfig.layers.sdkContextHook.enabled);
+        const compactionSettings = (0, compaction_1.buildCompactionSettings)(compactionEnabled);
+        createOpts.cwd = cwd;
+        createOpts.agentDir = agentDir;
+        if (this.options.thinkingLevel)
+            createOpts.thinkingLevel = this.options.thinkingLevel;
+        const customTools = [...(this.options.customTools ?? [])];
+        if (this.options.ephemeral) {
+            createOpts.sessionManager = mod.SessionManager.inMemory();
+        }
+        const secureBashBackend = this.options.toolsMode === "coding" || this.options.toolsMode === "readonly"
+            ? await (0, piSecureSandbox_1.createSecureBashBackend)({
+                workspace: cwd,
+                mode: this.options.bashSandbox ?? DEFAULT_BASH_SANDBOX_MODE,
+            })
+            : null;
+        if (secureBashBackend) {
+            this.cleanupTasks.push(() => secureBashBackend.dispose());
+        }
+        if (this.options.toolsMode === "coding") {
+            createOpts.tools = [...CODING_TOOL_NAMES];
+        }
+        else if (this.options.toolsMode === "readonly") {
+            createOpts.tools = [...READONLY_TOOL_NAMES];
+        }
+        if (secureBashBackend && typeof mod.createBashToolDefinition === "function") {
+            customTools.unshift(mod.createBashToolDefinition(cwd, {
+                operations: secureBashBackend.operations,
+            }));
+        }
+        if (customTools.length > 0) {
+            createOpts.customTools = customTools;
+        }
+        const appendedSystemPrompt = [
+            ...(0, instructionPrompts_1.discoverRepoInstructionPrompts)(cwd),
+            ...(this.options.appendSystemPrompt ?? []),
+            ...(secureBashBackend ? [secureBashBackend.promptNote] : []),
+        ];
+        if (this.options.systemPrompt ||
+            appendedSystemPrompt.length > 0 ||
+            this.options.isolated ||
+            compactionEnabled) {
+            const settingsManager = mod.SettingsManager.inMemory({
+                quietStartup: true,
+                compaction: compactionSettings.compaction,
+                branchSummary: compactionSettings.branchSummary,
+            });
+            createOpts.settingsManager = settingsManager;
+            if (this.options.systemPrompt ||
+                appendedSystemPrompt.length > 0 ||
+                this.options.isolated) {
+                const resourceLoader = new mod.DefaultResourceLoader({
+                    cwd,
+                    agentDir,
+                    settingsManager,
+                    noExtensions: this.options.isolated === true,
+                    noSkills: this.options.isolated === true,
+                    noPromptTemplates: this.options.isolated === true,
+                    noThemes: this.options.isolated === true,
+                    agentsFilesOverride: this.options.isolated === true
+                        ? () => ({ agentsFiles: [] })
+                        : undefined,
+                    systemPromptOverride: this.options.systemPrompt
+                        ? () => this.options.systemPrompt
+                        : undefined,
+                    appendSystemPromptOverride: appendedSystemPrompt.length > 0
+                        ? (base) => [...base, ...appendedSystemPrompt]
+                        : undefined,
+                });
+                await resourceLoader.reload();
+                createOpts.resourceLoader = resourceLoader;
+            }
+        }
+        // Resolve model string to a model object from pi's ModelRegistry.
+        // The `createAgentSession` API expects a model object (with provider,
+        // api, baseUrl, etc.), not a plain string.  We accept formats:
+        //   "provider:modelId"  e.g. "azure-openai-responses:gpt-4.1"
+        //   "modelId"           e.g. "gpt-4.1" (searches all providers)
+        if (typeof this.options.model === "string") {
+            const resolved = await (0, moduleSupport_1.resolvePiModel)(mod, this.options.model);
+            if (resolved) {
+                createOpts.model = resolved;
+            }
+            else {
+                await this.cleanupPendingTasks();
+                throw new babysitter_sdk_1.BabysitterRuntimeError("PiModelResolutionFailed", (0, moduleSupport_1.describePiModelResolutionFailure)(this.options.model), { category: babysitter_sdk_1.ErrorCategory.Configuration });
+            }
+        }
+        try {
+            const { session } = await mod.createAgentSession(createOpts);
+            if (this.options.uiContext && typeof session.bindExtensions === "function") {
+                await session.bindExtensions({ uiContext: this.options.uiContext });
+            }
+            this.session = session;
+        }
+        catch (error) {
+            await this.cleanupPendingTasks();
+            throw error;
+        }
+    }
+    requireSession() {
+        if (!this.session) {
+            throw new babysitter_sdk_1.BabysitterRuntimeError("PiSessionNotInitialized", "Pi session has not been initialized — call initialize() or prompt() first", { category: babysitter_sdk_1.ErrorCategory.Runtime });
+        }
+        return this.session;
+    }
+}
+exports.AgentCoreSessionHandle = AgentCoreSessionHandle;
+/**
+ * Create a new Pi session handle.
+ *
+ * The underlying `AgentSession` is created lazily on first use.
+ */
+function createAgentCoreSession(options) {
+    return new AgentCoreSessionHandle(options);
+}

package/dist/harness/piWrapper.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=piWrapper.test.d.ts.map

package/dist/harness/piWrapper.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"piWrapper.test.d.ts","sourceRoot":"","sources":["../../src/harness/piWrapper.test.ts"],"names":[],"mappings":""}

package/dist/harness/piWrapper.test.js

@@ -0,0 +1,193 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const vitest_1 = require("vitest");
+const mockCreateSecureBashBackend = vitest_1.vi.fn(() => Promise.resolve(null));
+const mockLoadCompressionConfigSafe = vitest_1.vi.fn(() => null);
+const mockBuildCompactionSettings = vitest_1.vi.fn(() => ({
+    compaction: {},
+    branchSummary: {},
+}));
+const mockDiscoverRepoInstructionPrompts = vitest_1.vi.fn(() => []);
+const mockConfigureAzureOpenAiEnvDefaults = vitest_1.vi.fn();
+const mockDescribePiModelResolutionFailure = vitest_1.vi.fn((model) => `Explicit model "${model}" could not be resolved.`);
+const mockResolvePiModel = vitest_1.vi.fn(() => Promise.resolve(undefined));
+const mockLoadPiModule = vitest_1.vi.fn();
+let defaultResourceLoaderOptions;
+let createAgentSessionOptions;
+const mockCreateBashToolDefinition = vitest_1.vi.fn((cwd, options) => ({
+    name: "bash",
+    cwd,
+    options,
+}));
+vitest_1.vi.mock("./piSecureSandbox", () => ({
+    createSecureBashBackend: mockCreateSecureBashBackend,
+}));
+vitest_1.vi.mock("./piWrapper/compaction", () => ({
+    loadCompressionConfigSafe: mockLoadCompressionConfigSafe,
+    buildCompactionSettings: mockBuildCompactionSettings,
+}));
+vitest_1.vi.mock("./piWrapper/instructionPrompts", () => ({
+    discoverRepoInstructionPrompts: mockDiscoverRepoInstructionPrompts,
+}));
+vitest_1.vi.mock("./piWrapper/moduleSupport", () => ({
+    configureAzureOpenAiEnvDefaults: mockConfigureAzureOpenAiEnvDefaults,
+    describePiModelResolutionFailure: mockDescribePiModelResolutionFailure,
+    extractAssistantFailure: vitest_1.vi.fn(() => undefined),
+    loadPiModule: mockLoadPiModule,
+    resolvePiModel: mockResolvePiModel,
+}));
+(0, vitest_1.describe)("AgentCoreSessionHandle", () => {
+    (0, vitest_1.beforeEach)(() => {
+        defaultResourceLoaderOptions = undefined;
+        createAgentSessionOptions = undefined;
+        delete process.env.PI_CODING_AGENT_DIR;
+        vitest_1.vi.clearAllMocks();
+        mockLoadPiModule.mockResolvedValue({
+            createAgentSession: vitest_1.vi.fn((options) => {
+                createAgentSessionOptions = options;
+                return Promise.resolve({
+                    session: {
+                        prompt: vitest_1.vi.fn(() => Promise.resolve(undefined)),
+                        steer: vitest_1.vi.fn(() => Promise.resolve(undefined)),
+                        followUp: vitest_1.vi.fn(() => Promise.resolve(undefined)),
+                        subscribe: vitest_1.vi.fn(() => () => { }),
+                        executeBash: vitest_1.vi.fn(() => Promise.resolve({
+                            output: "",
+                            exitCode: 0,
+                            cancelled: false,
+                            truncated: false,
+                        })),
+                        abort: vitest_1.vi.fn(() => Promise.resolve(undefined)),
+                        dispose: vitest_1.vi.fn(),
+                        getLastAssistantText: vitest_1.vi.fn(() => ""),
+                        get sessionId() {
+                            return "session-1";
+                        },
+                        get isStreaming() {
+                            return false;
+                        },
+                        get messages() {
+                            return [];
+                        },
+                    },
+                });
+            }),
+            DefaultResourceLoader: class {
+                constructor(options) {
+                    defaultResourceLoaderOptions = options;
+                }
+                async reload() { }
+            },
+            AuthStorage: {
+                create: vitest_1.vi.fn(() => ({})),
+            },
+            ModelRegistry: class {
+                find() {
+                    return undefined;
+                }
+                getAll() {
+                    return [];
+                }
+            },
+            SessionManager: {
+                inMemory: vitest_1.vi.fn(() => ({ kind: "memory-session-manager" })),
+            },
+            SettingsManager: {
+                inMemory: vitest_1.vi.fn(() => ({ kind: "memory-settings-manager" })),
+            },
+            createBashToolDefinition: mockCreateBashToolDefinition,
+            createCodingTools: vitest_1.vi.fn(() => []),
+            createReadOnlyTools: vitest_1.vi.fn(() => []),
+            codingTools: [],
+            readOnlyTools: [],
+        });
+    });
+    (0, vitest_1.it)("defaults agentDir for resource loading when none is provided", async () => {
+        const { AgentCoreSessionHandle } = await Promise.resolve().then(() => __importStar(require("./piWrapper")));
+        const session = new AgentCoreSessionHandle({
+            workspace: process.cwd(),
+            toolsMode: "coding",
+            isolated: true,
+            ephemeral: true,
+        });
+        await session.initialize();
+        const expectedAgentDir = (0, node_path_1.join)((0, node_os_1.homedir)(), ".pi", "agent");
+        (0, vitest_1.expect)(defaultResourceLoaderOptions).toMatchObject({
+            agentDir: expectedAgentDir,
+            cwd: process.cwd(),
+        });
+        (0, vitest_1.expect)(createAgentSessionOptions).toMatchObject({
+            agentDir: expectedAgentDir,
+            cwd: process.cwd(),
+        });
+    });
+    (0, vitest_1.it)("passes tool names instead of tool objects and injects the secure bash override through customTools", async () => {
+        mockCreateSecureBashBackend.mockResolvedValueOnce({
+            operations: { kind: "secure-bash-ops" },
+            promptNote: "secure bash",
+            dispose: vitest_1.vi.fn(),
+        });
+        const { AgentCoreSessionHandle } = await Promise.resolve().then(() => __importStar(require("./piWrapper")));
+        const session = new AgentCoreSessionHandle({
+            workspace: process.cwd(),
+            toolsMode: "coding",
+            customTools: [{ name: "babysitter_run_iterate" }],
+        });
+        await session.initialize();
+        (0, vitest_1.expect)(createAgentSessionOptions?.tools).toEqual(["read", "bash", "edit", "write"]);
+        (0, vitest_1.expect)(mockCreateBashToolDefinition).toHaveBeenCalledWith(process.cwd(), vitest_1.expect.objectContaining({
+            operations: { kind: "secure-bash-ops" },
+        }));
+        (0, vitest_1.expect)(createAgentSessionOptions?.customTools).toEqual([
+            vitest_1.expect.objectContaining({ name: "bash" }),
+            { name: "babysitter_run_iterate" },
+        ]);
+    });
+    (0, vitest_1.it)("fails fast when an explicit model cannot be resolved", async () => {
+        const { AgentCoreSessionHandle } = await Promise.resolve().then(() => __importStar(require("./piWrapper")));
+        const session = new AgentCoreSessionHandle({
+            workspace: process.cwd(),
+            model: "gemini-3.1-pro-preview",
+        });
+        await (0, vitest_1.expect)(session.initialize()).rejects.toThrow('Explicit model "gemini-3.1-pro-preview" could not be resolved.');
+        (0, vitest_1.expect)(mockConfigureAzureOpenAiEnvDefaults).toHaveBeenCalledWith("gemini-3.1-pro-preview");
+        (0, vitest_1.expect)(mockResolvePiModel).toHaveBeenCalled();
+        (0, vitest_1.expect)(mockDescribePiModelResolutionFailure).toHaveBeenCalledWith("gemini-3.1-pro-preview");
+        (0, vitest_1.expect)(createAgentSessionOptions).toBeUndefined();
+    });
+});

package/dist/harness/planMode.d.ts

@@ -0,0 +1,68 @@
+/**
+ * GAP-USER-012: Plan Mode with Verification
+ *
+ * Interactive plan-verify-execute loop. Generates structured plans,
+ * presents for approval, executes with per-step verification,
+ * and allows plan modification mid-execution.
+ */
+/** A single step in an execution plan. */
+export interface PlanStep {
+    /** Unique step identifier. */
+    id: string;
+    /** Human-readable title. */
+    title: string;
+    /** Description of what this step does. */
+    description: string;
+    /** Step status. */
+    status: PlanStepStatus;
+    /** Dependencies (IDs of steps that must complete first). */
+    dependsOn: string[];
+    /** Verification criteria for this step. */
+    verificationCriteria?: string;
+    /** Task ID if this step was dispatched as an effect. */
+    effectId?: string;
+    /** Timestamp of completion. */
+    completedAt?: string;
+    /** Feedback received during verification. */
+    feedback?: string;
+}
+export type PlanStepStatus = "pending" | "in_progress" | "completed" | "failed" | "skipped" | "modified";
+/** An execution plan. */
+export interface ExecutionPlan {
+    /** Plan ID. */
+    id: string;
+    /** Plan title. */
+    title: string;
+    /** Overall goal/description. */
+    description: string;
+    /** Ordered steps. */
+    steps: PlanStep[];
+    /** Plan status. */
+    status: PlanStatus;
+    /** Creation timestamp. */
+    createdAt: string;
+    /** Last update timestamp. */
+    updatedAt: string;
+}
+export type PlanStatus = "draft" | "approved" | "executing" | "completed" | "failed" | "modified";
+/** Create a new execution plan. */
+export declare function createPlan(id: string, title: string, description: string, steps: Array<Omit<PlanStep, "status">>): ExecutionPlan;
+/** Update a step's status. */
+export declare function updateStepStatus(plan: ExecutionPlan, stepId: string, status: PlanStepStatus, feedback?: string): ExecutionPlan;
+/** Insert a new step into the plan at a given position. */
+export declare function insertStep(plan: ExecutionPlan, step: Omit<PlanStep, "status">, afterStepId?: string): ExecutionPlan;
+/** Remove a step from the plan. Also removes it from other steps' dependsOn lists. */
+export declare function removeStep(plan: ExecutionPlan, stepId: string): ExecutionPlan;
+/** Get the next executable step (all dependencies satisfied). */
+export declare function getNextStep(plan: ExecutionPlan): PlanStep | undefined;
+/** Get plan progress summary. */
+export declare function getPlanProgress(plan: ExecutionPlan): {
+    total: number;
+    completed: number;
+    failed: number;
+    pending: number;
+    percentComplete: number;
+};
+/** Format plan for display. */
+export declare function formatPlanForDisplay(plan: ExecutionPlan): string;
+//# sourceMappingURL=planMode.d.ts.map

package/dist/harness/planMode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planMode.d.ts","sourceRoot":"","sources":["../../src/harness/planMode.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAMH,0CAA0C;AAC1C,MAAM,WAAW,QAAQ;IACvB,8BAA8B;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAC;IACpB,mBAAmB;IACnB,MAAM,EAAE,cAAc,CAAC;IACvB,4DAA4D;IAC5D,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,2CAA2C;IAC3C,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+BAA+B;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,aAAa,GAAG,WAAW,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;AAEzG,yBAAyB;AACzB,MAAM,WAAW,aAAa;IAC5B,eAAe;IACf,EAAE,EAAE,MAAM,CAAC;IACX,kBAAkB;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,WAAW,EAAE,MAAM,CAAC;IACpB,qBAAqB;IACrB,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,mBAAmB;IACnB,MAAM,EAAE,UAAU,CAAC;IACnB,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,UAAU,GAAG,WAAW,GAAG,WAAW,GAAG,QAAQ,GAAG,UAAU,CAAC;AAMlG,mCAAmC;AACnC,wBAAgB,UAAU,CACxB,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,GACrC,aAAa,CAWf;AAED,8BAA8B;AAC9B,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,cAAc,EACtB,QAAQ,CAAC,EAAE,MAAM,GAChB,aAAa,CAuBf;AAED,2DAA2D;AAC3D,wBAAgB,UAAU,CACxB,IAAI,EAAE,aAAa,EACnB,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAC9B,WAAW,CAAC,EAAE,MAAM,GACnB,aAAa,CAiBf;AAED,sFAAsF;AACtF,wBAAgB,UAAU,CAAC,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,CAc7E;AAED,iEAAiE;AACjE,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,QAAQ,GAAG,SAAS,CAWrE;AAED,iCAAiC;AACjC,wBAAgB,eAAe,CAAC,IAAI,EAAE,aAAa,GAAG;IACpD,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;CACzB,CAYA;AAED,+BAA+B;AAC/B,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CA2BhE"}