@oharness/engine 0.1.0

package/dist/agent/agent.d.ts

@@ -0,0 +1,196 @@
+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 { ArtifactDescriptor } from "../artifacts/store.ts";
+import type { Logger } from "../util/logger.ts";
+import type { WorkspacePolicy } from "./workspace.ts";
+import { SkillRegistry } from "./skills.ts";
+import { MemoryStore } from "./memory.ts";
+import type { CompactionOptions } from "./compaction.ts";
+import { HookRegistry } from "./hooks.ts";
+import type { PermissionPrompt, PermissionRequest } from "./permissions.ts";
+import type { Session } from "./session.ts";
+import { SubagentRegistry } from "./subagent.ts";
+export type AgentEvent = {
+    type: "turn_start";
+    turn: number;
+    model: string;
+} | {
+    type: "text_delta";
+    text: string;
+} | {
+    type: "thinking_delta";
+    text: string;
+} | {
+    type: "assistant_message";
+    message: Message;
+} | {
+    type: "tool_start";
+    toolCallId: string;
+    toolName: string;
+    title: string;
+    input: unknown;
+} | {
+    type: "tool_progress";
+    progress: ToolProgress;
+} | {
+    type: "tool_end";
+    toolCallId: string;
+    toolName: string;
+    result: ToolResult;
+    durationMs: number;
+}
+/**
+ * An artifact was created or revised. Carries a descriptor, never the body:
+ * see artifacts/store.ts for why. A frontend that cannot render this kind is
+ * still expected to acknowledge it — test/artifacts.test.ts enforces that.
+ */
+ | {
+    type: "artifact";
+    artifact: ArtifactDescriptor;
+} | {
+    type: "permission_request";
+    request: PermissionRequest;
+} | {
+    type: "permission_result";
+    toolCallId: string;
+    allowed: boolean;
+    reason?: string;
+    /** Pattern written to settings, when the approval was persisted. */
+    remembered?: string;
+} | {
+    type: "compacted";
+    tokensBefore: number;
+    tokensAfter: number;
+    droppedMessages: number;
+} | {
+    type: "model_changed";
+    from: string;
+    to: string;
+} | {
+    type: "notice";
+    message: string;
+}
+/**
+ * `status` is the HTTP status behind a provider failure, when one could be
+ * recovered. It travels beside the message because some statuses are not
+ * errors to print at all: a 402 means the account is out of credits, which
+ * is a screen with a button on it, and telling that apart from a bad key by
+ * matching text in a sentence is a thing that breaks on rewording.
+ */
+ | {
+    type: "error";
+    error: string;
+    fatal: boolean;
+    status?: number;
+    provider?: string;
+} | {
+    type: "done";
+    stopReason: StopReason;
+    usage: Usage;
+    costUsd: number;
+    turns: number;
+};
+export interface AgentOptions {
+    session: Session;
+    tools: ToolRegistry;
+    hooks?: HookRegistry;
+    subagents?: SubagentRegistry;
+    mcp?: McpManager;
+    /** Called when a tool needs approval. Without it, `ask` becomes `deny`. */
+    permissionPrompt?: PermissionPrompt;
+    systemPrompt?: string;
+    appendSystemPrompt?: string;
+    projectInstructions?: string;
+    toolFilter?: ToolFilter;
+    thinking?: ThinkingConfig;
+    maxTurns?: number;
+    compaction?: CompactionOptions | false;
+    /**
+     * Character cap on a single tool result before it is truncated and archived.
+     * Defaults to `DEFAULT_TOOL_RESULT_LIMIT`; set 0 to disable.
+     */
+    toolResultLimit?: number;
+    /** Cheaper model for compaction summaries; defaults to the session model. */
+    smallModel?: string;
+    /** Skills available to this agent; their descriptions enter the prompt. */
+    skills?: SkillRegistry;
+    /** Durable notes carried between sessions. */
+    memory?: MemoryStore;
+    /** Called after the agent writes into a skills directory. */
+    onSkillsChanged?: () => Promise<unknown>;
+    /** Restricts where writes may land. A policy gate, not an OS sandbox. */
+    workspace?: WorkspacePolicy;
+    /** Enable provider prompt caching where the model supports it. */
+    cache?: boolean;
+    agentId?: string;
+    logger?: Logger;
+}
+/**
+ * The agentic loop: prompt the model, run whatever tools it asks for, feed the
+ * results back, repeat until it stops calling tools.
+ *
+ * Everything provider-specific lives behind `Provider`, so this loop is the
+ * same regardless of which model is selected — including when the model
+ * changes partway through a session.
+ */
+export declare class Agent implements ToolHost {
+    readonly session: Session;
+    readonly tools: ToolRegistry;
+    readonly hooks: HookRegistry;
+    readonly subagents: SubagentRegistry;
+    readonly skills: SkillRegistry;
+    readonly memory?: MemoryStore;
+    readonly state: Map<string, unknown>;
+    private readonly opts;
+    private readonly logger;
+    private readonly agentId;
+    private controller;
+    private running;
+    private sessionStarted;
+    /** Set when a hook asks the turn to end; read by the main loop. */
+    private stopRequested?;
+    /** Memory index for this run's system prompt. */
+    private memoryIndex?;
+    constructor(opts: AgentOptions);
+    /**
+     * Announce a model switch so a UI can render it and hooks can react.
+     * Called by whoever changes the session's model.
+     */
+    switchModel(ref: string): AsyncGenerator<AgentEvent, void, void>;
+    /**
+     * The model used for compaction summaries. Falls back to the session model
+     * if `smallModel` is unset or unresolvable — a bad alias should degrade to a
+     * pricier summary, never break the turn.
+     */
+    private summarizerModel;
+    /** Run the SessionEnd hook. Call when the session is finished with. */
+    end(): Promise<void>;
+    /** Cancel the in-flight turn. The loop exits with `stopReason: "aborted"`. */
+    abort(): void;
+    get isRunning(): boolean;
+    /**
+     * Where the file tools are allowed to look. The policy lives here, so the
+     * tools ask rather than each re-deriving a notion of "inside the project".
+     */
+    resolvePath(input: string, access: "read" | "write"): string;
+    listSubagentTypes(): Array<{
+        name: string;
+        description: string;
+    }>;
+    runSubagent(opts: SubagentRunOptions): Promise<SubagentRunResult>;
+    run(input: string | Message[], runOpts?: {
+        signal?: AbortSignal;
+    }): AsyncGenerator<AgentEvent, void, void>;
+    private ingestInput;
+    private maybeCompact;
+    private systemPrompt;
+    private buildRequest;
+    /** Consume the provider stream, emitting deltas and assembling the message. */
+    private streamAssistant;
+    private executeCalls;
+    private executeOne;
+    private checkPermission;
+}