@oharness/engine 0.9.2 → 0.10.0

package/dist/agent/agent.d.ts

@@ -1,9 +1,10 @@
+import type { SessionGoal } from "./goal.ts";
 import type { RuntimeAuditEvent } from "../core/audit.ts";
 import type { Message, StopReason, Usage } from "../core/types.ts";
 import type { McpManager } from "../mcp/manager.ts";
 import type { ThinkingConfig } from "../providers/types.ts";
 import type { ToolFilter, ToolRegistry } from "../tools/registry.ts";
-import type { SubagentRunOptions, SubagentRunResult, ToolHost, ToolProgress, ToolResult } from "../tools/types.ts";
+import type { BackgroundTaskHost, BackgroundTaskView, SubagentRunOptions, SubagentRunResult, ToolHost, ToolProgress, ToolResult, WorktreeLauncher, WorktreeStartOptions, WorktreeStartResult } from "../tools/types.ts";
 import type { ArtifactDescriptor } from "../artifacts/store.ts";
 import type { Logger } from "../util/logger.ts";
 import type { WorkspacePolicy } from "./workspace.ts";
@@ -89,6 +90,8 @@ export type AgentEvent = {
     reason?: string;
     /** Pattern written to settings, when the approval was persisted. */
     remembered?: string;
+    /** Held back by plan mode: the mode doing its job, not a refusal. */
+    plan?: boolean;
 }
 /**
  * Something the user said while the turn was already running has just been
@@ -99,6 +102,15 @@ export type AgentEvent = {
     type: "interjected";
     id: string;
     text: string;
+}
+/**
+ * Background tasks have ended and their results were just read into the
+ * conversation, as `text`. Emitted where they enter, like an interjection.
+ */
+ | {
+    type: "task_notification";
+    tasks: BackgroundTaskView[];
+    text: string;
 } | {
     type: "compacted";
     tokensBefore: number;
@@ -130,6 +142,11 @@ export type AgentEvent = {
     type: "notice";
     message: string;
 }
+/** The session's goal was set, nudged, achieved or reported blocked. */
+ | {
+    type: "goal";
+    goal: SessionGoal;
+}
 /**
  * `status` is the HTTP status behind a provider failure, when one could be
  * recovered. It travels beside the message because some statuses are not
@@ -191,6 +208,11 @@ export interface AgentOptions {
     onSkillsChanged?: () => Promise<unknown>;
     /** Restricts where writes may land. A policy gate, not an OS sandbox. */
     workspace?: WorkspacePolicy;
+    /**
+     * Who can host a session in a new worktree. A getter, because the frontend
+     * wires it after the harness — and so the agent it builds — already exists.
+     */
+    worktreeLauncher?: () => WorktreeLauncher | undefined;
     /** Enable provider prompt caching where the model supports it. */
     cache?: boolean;
     agentId?: string;
@@ -200,8 +222,38 @@ export interface AgentOptions {
     onAudit?: (event: RuntimeAuditEvent) => void;
     /** Internal host lifecycle accounting; inherited by subagents. */
     onRunStart?: () => () => void;
+    /**
+     * Who starts a turn to read in background results that end while this agent
+     * is idle. A getter, like worktreeLauncher, because the frontend wires it
+     * after the agent exists. Without one, background tasks are not offered:
+     * a result arriving after the run had ended would reach nobody.
+     */
+    taskWaker?: () => ((sessionId: string) => void) | undefined;
+    /** How many background tasks run at once; the rest queue. */
+    maxBackgroundTasks?: number;
+    /**
+     * Give a subagent its own browser and computer, so it never drives the
+     * parent's tabs or acts under the parent's window leases. Rebinds the
+     * per-conversation tools already in `tools`; `release` closes them again.
+     */
+    equipSubagent?: (sessionId: string, label: string, tools: ToolRegistry) => SubagentEquipment;
+    /**
+     * The conversation this agent's permission cards belong to. A subagent's
+     * own session is invisible to every frontend, so its questions are placed
+     * in the conversation that started it.
+     */
+    interactionSessionId?: string;
+    /** Who is asking, on those cards: "general: fix the flaky test". */
+    interactionLabel?: string;
     logger?: Logger;
 }
+export interface SubagentEquipment {
+    /** Replaces the parent's run accounting, which would release the parent's leases. */
+    onRunStart?: () => () => void;
+    /** Rebind its tools into another registry: the same browser and computer, for a later run. */
+    bind?(tools: ToolRegistry): void;
+    release(): Promise<void>;
+}
 /**
  * Notes attached to messages still in the transcript.
  *
@@ -218,6 +270,22 @@ export declare function recalledInTranscript(messages: readonly Message[]): Set<
  * same regardless of which model is selected — including when the model
  * changes partway through a session.
  */
+/** How a conversation fills the model's window; see Agent.contextBreakdown(). */
+export interface ContextBreakdown {
+    /** Tokens in use: measured from the last request when there was one. */
+    total: number;
+    window: number;
+    /** Estimated: the system prompt, with skills, memory and project notes. */
+    system: number;
+    /** Estimated: the definitions of the tools offered to the model. */
+    tools: number;
+    /** The rest of the total: the conversation itself. */
+    messages: number;
+    /** Whether `total` came from the provider rather than an estimate. */
+    measured: boolean;
+    /** Tokens at which automatic compaction fires; absent when it is off. */
+    compactAt?: number;
+}
 export declare class Agent implements ToolHost {
     readonly session: Session;
     readonly tools: ToolRegistry;
@@ -248,6 +316,18 @@ export declare class Agent implements ToolHost {
     private pluginSections;
     /** Recall over `memory` for agents embedded without a plugin host. */
     private legacyMemory?;
+    /** Subagents running in the background; made on first use. */
+    private background?;
+    private wakeTimer?;
+    /** Frontends watching background tasks, kept until the tasks exist. */
+    private readonly changeListeners;
+    /** What each background task was asked, and its subagent once it has one. */
+    private readonly taskStates;
+    private restoring?;
+    private saveTimer?;
+    /** Closed or deleted: nothing more is saved, and nothing more starts. */
+    private tasksClosed;
+    private saveChain;
     constructor(opts: AgentOptions);
     /**
      * Announce a model switch so a UI can render it and hooks can react.
@@ -295,14 +375,106 @@ export declare class Agent implements ToolHost {
      * tools ask rather than each re-deriving a notion of "inside the project".
      */
     resolvePath(input: string, access: "read" | "write"): string;
+    startWorktree(opts: WorktreeStartOptions): Promise<WorktreeStartResult>;
     listSubagentTypes(): Array<{
         name: string;
         description: string;
+        readOnly?: boolean;
+        isolation?: "worktree";
     }>;
     runSubagent(opts: SubagentRunOptions): Promise<SubagentRunResult>;
+    /**
+     * Subagents running behind this conversation, offered only while someone
+     * can start a turn to read their results in. Once any exist they stay
+     * reachable, so they can still be listed, messaged and stopped.
+     */
+    get backgroundTasks(): BackgroundTaskHost | undefined;
+    /** A task's conversation so far, for a frontend to show. */
+    backgroundTranscript(id: string): readonly Message[] | undefined;
+    /** Every change to a background task, for a frontend to redraw from. */
+    onBackgroundChange(listener: (task: BackgroundTaskView) => void): () => void;
+    /**
+     * The conversation is being closed, not ended: write its tasks down as they
+     * stand, then stop them. Opened again, the ones that were running come back
+     * interrupted and can be followed up — as after a restart.
+     */
+    closeBackgroundTasks(): Promise<void>;
+    /**
+     * The conversation is being deleted: stop its tasks and write nothing more.
+     * Resolves once a write already under way has landed, so deleting the
+     * store afterwards cannot be undone by it.
+     */
+    discardBackgroundTasks(): Promise<void>;
+    private endBackgroundTasks;
+    private backgroundAvailable;
+    private tasks;
+    /**
+     * A background task's subagent, made for each run and let go after it.
+     *
+     * Between runs a task holds only its conversation and, if it changed
+     * anything, its worktree: no browser, no claim on the computer, no agent.
+     * A follow-up — or the first one after a restart — builds the subagent
+     * again from those, so both paths are the same path.
+     */
+    private backgroundSpec;
+    /**
+     * Put back the background tasks this conversation had before a restart.
+     *
+     * Called by a frontend when it opens the conversation; safe to call again.
+     * A task that was still running when the app closed comes back as failed
+     * and says why — its subagent's process is gone — but keeps its
+     * conversation, so a follow-up carries on from where it stopped. A result
+     * nobody had been told about is still read in with the next turn.
+     */
+    restoreBackgroundTasks(): Promise<number>;
+    /** Write the tasks down a moment after they change, so a burst is one write. */
+    private scheduleSave;
+    /**
+     * One write at a time, in order. Each takes its snapshot when its turn
+     * comes, so a later state is never overwritten by an earlier one landing
+     * last — a task that ended would come back as running.
+     */
+    private saveTasks;
+    private writeTasks;
+    private scheduleWake;
+    /**
+     * Read the results of background tasks that have ended into the
+     * conversation, as one message saying what is still running.
+     *
+     * Synthetic, like a goal nudge: nobody typed it, so it skips the prompt hook
+     * and memory recall, and never titles the session.
+     */
+    private takeNotices;
+    /** Where this agent's permission cards go, and who they say is asking. */
+    private interactionPlace;
+    /** A subagent ready to run: its agent, the tree it works in, what it holds. */
+    private prepareSubagent;
+    /**
+     * One run of a subagent, to its end: its first prompt, or a later message.
+     *
+     * `report` is there only for a background task: it is what lets a look at
+     * the task say what the subagent is doing now.
+     */
+    private runChild;
+    /** What a subagent left in its worktree, when it left anything. */
+    private worktreeNote;
+    /**
+     * A subagent is finished with: its browser and computer go, and a worktree
+     * it changed nothing in is removed. One that it changed is kept — the
+     * parent has to decide what happens to that work.
+     */
+    private disposeChild;
+    private dropIfUntouched;
     run(input: string | Message[], runOpts?: {
         signal?: AbortSignal;
     }): AsyncGenerator<AgentEvent, void, void>;
+    /**
+     * Where a reply ends with a goal still active: ask for more work.
+     *
+     * Returns whether the loop should go on. A model that keeps stopping short
+     * of its goal gets a bounded number of reminders, not an endless supply.
+     */
+    private pushTowardGoal;
     private ingestInput;
     /**
      * Put what the user said into the conversation, as its own message.
@@ -343,12 +515,46 @@ export declare class Agent implements ToolHost {
     private scheduleExtraction;
     /** Where the next end-of-run extraction starts, clamped to the transcript. */
     private extractedUpTo;
+    /**
+     * How full the model's window is, in tokens: what the last request measured,
+     * or, before one has (a new or reopened conversation), an estimate of the
+     * next request — system prompt and tools included, which are a large share
+     * of a short conversation.
+     */
+    contextTokens(): number;
+    /**
+     * The window, split the way the context panel draws it. Providers report one
+     * number for the prompt, so the system prompt and the tool definitions are
+     * estimated and the messages are what is left of the measured total; until
+     * something is measured all three are estimates.
+     */
+    contextBreakdown(): ContextBreakdown;
+    private contextEstimate;
+    /**
+     * Compact now, whatever the window says: the /compact command. Goes through
+     * the same path as the automatic kind, so what it drops is archived for
+     * recall and handed to memory extraction rather than simply discarded.
+     * Returns what happened, or undefined when there was nothing safe to cut.
+     */
+    compactNow(): Promise<AgentEvent | undefined>;
     private maybeCompact;
+    /**
+     * The tools offered to the model: the goal tool only while there is a goal,
+     * and the computer tools only while this conversation has Computer Use on.
+     */
+    private visibleTools;
     private systemPrompt;
     private buildRequest;
     /** Consume the provider stream, emitting deltas and assembling the message. */
     private streamAssistant;
     private executeCalls;
     private executeOne;
+    /**
+     * Ask about a write the workspace policy would refuse.
+     *
+     * Bypass mode approves it as it approves everything else. Read-only and plan
+     * mode refuse it, as does a frontend with no way to ask.
+     */
+    private askOutsideRoots;
     private checkPermission;
 }