@prestyj/cli 5.30.2 → 5.31.0

package/dist/modes/acp-mode.d.ts

@@ -1,6 +1,12 @@
-import type { Message, Provider, ThinkingLevel } from "@prestyj/ai";
+import type { Message, MessageProvenance, Provider, ThinkingLevel } from "@prestyj/ai";
 import { type ToolExecuteResult } from "@prestyj/agent";
+import { AgentSession, type SessionAttachment } from "../core/agent-session.js";
+import type { ChildModelPick, SubAgentSnapshot } from "../core/subagent-manager.js";
+import { createAskUserTool } from "../tools/ask-user.js";
+import { type GoalBriefExtras, type GoalRecord } from "../core/goals-store.js";
 import type { EventBus } from "../core/event-bus.js";
+import type { AutopilotMarkerPayload } from "../core/session-manager.js";
+import { type AcpNolanReviewer } from "./acp-autopilot.js";
 /** The ACP major version this mode implements. Bumped only for breaking changes. */
 export declare const ACP_PROTOCOL_VERSION = 1;
 /**
@@ -13,7 +19,32 @@ export declare const ACP_PROTOCOL_VERSION = 1;
 export interface AcpAgentSession {
     readonly eventBus: Pick<EventBus, "on">;
     initialize(): Promise<void>;
-    prompt(content: string): Promise<void>;
+    /** `provenance` marks EZ Goals' hidden kickoff/resume instructions. */
+    prompt(content: string, provenance?: MessageProvenance): Promise<void>;
+    /** Image prompts (`promptCapabilities.image`); without it images are ignored. */
+    promptWithAttachments?(text: string, attachments: SessionAttachment[]): Promise<void>;
+    /**
+     * Mid-run steering (`_gg/queue`). Optional so a test double or alternative
+     * session need not support it; `_gg/queue` then answers -32602.
+     */
+    queueMessage?(text: string): number;
+    listQueuedMessages?(): Array<{
+        id: string;
+        text: string;
+    }>;
+    cancelQueuedMessage?(id: string): boolean;
+    drainQueue?(): string;
+    /** EZ Goals' workers, for `_gg/goal_state`. */
+    listSubAgents?(): SubAgentSnapshot[];
+    /** Adds a goal's attached folder to the workspace. */
+    addDirectory?(dir: string): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        error: string;
+    }>;
+    /** Tell the agent a fact at its next turn (goal settings changed). */
+    notify?(id: string, text: string): void;
     getState(): {
         sessionId: string;
         provider: Provider;
@@ -34,6 +65,16 @@ export interface AcpAgentSession {
     setSignal(signal: AbortSignal): void;
     /** Replay a session file from disk into this session. */
     loadSession(sessionPath: string): Promise<void>;
+    /**
+     * Nolan's verdict markers (desktop `persistAutopilotMarker`). Optional so a
+     * test double need not persist; without them a reopened session has no
+     * Nolan bubbles.
+     */
+    persistAutopilotMarker?(phase: AutopilotMarkerPayload["phase"], extra?: {
+        reason?: string;
+        body?: string;
+    }): Promise<void>;
+    getAutopilotMarkers?(): AutopilotMarkerPayload[];
     /** The conversation as restored, used to replay history to the client. */
     getMessages(): Message[];
     switchModel(provider: string, model: string): Promise<void>;
@@ -44,6 +85,12 @@ export interface AcpAgentSession {
     setPlanMode(active: boolean): Promise<void>;
     /** Bake an approved plan into the prompt so [DONE:n] progress markers work. */
     setApprovedPlan(planPath: string | undefined): Promise<void>;
+    /** Host verification evidence for Nolan's digest; optional for test doubles. */
+    getVerificationEvidence?(): AgentSession["getVerificationEvidence"] extends () => infer R ? R : never;
+    getVerificationProblem?(): string | null;
+    /** Fresh context for an accepted plan (desktop /plan/accept). Optional:
+     *  without it an accept keeps the current context and sends no reset. */
+    newSession?(preserveConversation?: boolean): Promise<void>;
     /**
      * Registry commands (/model, /compact, …), including any an extension
      * registered during `initialize`. Optional so a test double need not carry a
@@ -71,6 +118,52 @@ export interface AcpPlanHooks {
     /** Returns the instruction handed back to the model after approval. */
     onExitPlan: (planPath: string) => Promise<ToolExecuteResult>;
 }
+/**
+ * What a session is being built for, beyond the plan hooks.
+ *
+ * A third argument rather than a change to the first two so existing session
+ * factories (tests) keep working unchanged.
+ */
+export interface AcpSessionContext {
+    /** The session's working directory: the goal folder for a goal session. */
+    cwd: string;
+    /** Set when the cwd is a goal folder: build a EZ Goals coordinator. */
+    goal: {
+        dir: string;
+        record: GoalRecord;
+    } | null;
+    /** The goal's brief extras (memory, attached projects' rules), read once. */
+    goalExtras?: GoalBriefExtras;
+    /** Read live: true once the user has started the goal. */
+    isGoalActive: () => boolean;
+    /** Read live at each worker spawn. */
+    getChildModel: () => ChildModelPick | undefined;
+    /**
+     * The `ask_user` tool, present only when the client opted in with
+     * `clientCapabilities._meta.gg.askUser`. Goes in `additionalTools` at
+     * construction (the tool array is append-only for the prompt cache).
+     */
+    askUserTool?: ReturnType<typeof createAskUserTool>;
+    /**
+     * The client reviews plans itself (`clientCapabilities._meta.gg.planReview`):
+     * exit_plan parks the plan for a human decision instead of auto-approving,
+     * and the session gets the desktop's `planSubmissionGate`.
+     */
+    planReview?: boolean;
+}
+/**
+ * A plan submitted via exit_plan that awaits a decision (desktop parity:
+ * app-sidecar.ts pendingPlanPath/planGeneration/offeredPlanGeneration). One
+ * object so the autopilot cycle can read and settle it.
+ */
+export interface AcpPendingPlanState {
+    planPath: string | null;
+    content: string;
+    /** Bumped on every set/clear; a stale decision is refused. */
+    generation: number;
+    /** Generation last offered to the client; -1 when none. */
+    offeredGeneration: number;
+}
 export interface AcpModeOptions {
     provider: Provider;
     model: string;
@@ -86,7 +179,22 @@ export interface AcpModeOptions {
      * Builds the session for `session/new`. Overridden by tests; production
      * always gets a real {@link AgentSession}.
      */
-    createSession?: (signal: AbortSignal, hooks: AcpPlanHooks) => AcpAgentSession;
+    createSession?: (signal: AbortSignal, hooks: AcpPlanHooks, context: AcpSessionContext) => AcpAgentSession;
+    /** `~/.ezcoder` by default; where goals (`goals/`) and sessions live. */
+    agentDir?: string;
+    /**
+     * `ask_user` soft deadline (default: the desktop's interactive 10 min). Past
+     * it the model hears "no answer yet" and the client's question stays open.
+     */
+    askUserDeadlineMs?: number;
+    /**
+     * Builds Autopilot Nolan's reviewer for a session's project. Overridden by
+     * tests; production gets {@link createAcpNolanReviewer}.
+     */
+    createNolanReviewer?: (cwd: string, buildModel: () => {
+        provider: Provider;
+        model: string;
+    }) => AcpNolanReviewer;
 }
 /** The selectors this agent exposes. Ids are part of the wire contract. */
 export declare const MODEL_CONFIG_ID = "model";
@@ -107,6 +215,23 @@ export declare const MODE_CONFIG_ID = "mode";
  * the protocol needs of them.
  */
 export declare function historyUpdates(messages: readonly Message[]): Record<string, unknown>[];
+/** A replayed Nolan marker, as `_gg/autopilot_event` params (sans sessionId). */
+export interface HistoryAutopilotEvent {
+    phase: string;
+    reason?: string;
+    body?: string;
+    history: true;
+}
+/**
+ * {@link historyUpdates} with Nolan's verdict markers interleaved at their
+ * `afterMessageCount` (non-system messages, as the desktop history route
+ * counts them). Marker phase `plan_approved` replays as ACP `plan_accepted`.
+ */
+export declare function historyFrames(messages: readonly Message[], markers: readonly AutopilotMarkerPayload[]): Array<{
+    update: Record<string, unknown>;
+} | {
+    autopilot: HistoryAutopilotEvent;
+}>;
 /**
  * Serve ACP on stdio until the input stream ends.
  *