@zelari/core 0.7.9

package/dist/core/AgentHarness.d.ts

@@ -0,0 +1,250 @@
+/**
+ * AgentHarness — provider-neutral agent loop.
+ *
+ * Encapsulates a single agent turn: given a (model, provider, messages, tools)
+ * configuration and a provider streaming function, it drives the stream and
+ * yields the full {@link BrainEvent} lifecycle as an `AsyncIterable<BrainEvent>`.
+ *
+ * Electron-free: this module imports ONLY from `electron/shared/` (the event
+ * contract + bus) and `electron/main/core/tools/` (the tool registry). It has
+ * zero coupling to `llm.ts` or any main-process IPC, so it can run in the
+ * Electron main process today and be reused from the Ink CLI in Phase 14.
+ *
+ * When `toolRegistry` is provided, tool_call deltas trigger real tool
+ * execution and emit a matching `tool_execution_end` event. Without it, the
+ * harness only emits `tool_execution_start` (legacy behavior, useful for
+ * streaming-only consumers).
+ *
+ * @see docs/plans/2026-06-28-zelari-code.md (Task 12.1 + 14.8)
+ */
+import { EventBus } from '../shared/eventBus.js';
+import { type BrainEvent, type UsageBreakdown } from '../shared/events.js';
+import { ToolRegistry } from './tools/registry.js';
+export interface AgentMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    /** For tool messages: the tool call id this result corresponds to. */
+    toolCallId?: string;
+    /**
+     * For assistant messages that requested tool calls: the list of tool
+     * invocations the model emitted in this turn. The provider maps this to
+     * OpenAI `tool_calls` so a subsequent request can continue the conversation
+     * after tool results are appended.
+     */
+    toolCalls?: {
+        id: string;
+        name: string;
+        args: Record<string, unknown>;
+    }[];
+}
+export interface AgentToolSpec {
+    /** Tool name (must match the tool registry). */
+    name: string;
+    /** JSON-schema-like description for the LLM. */
+    description: string;
+    /** JSON Schema for the tool's input arguments. */
+    parameters: Record<string, unknown>;
+}
+export interface AgentHarnessConfig {
+    /** Model identifier (e.g. 'grok-4', 'MiniMax-M2.5'). */
+    model: string;
+    /** Provider id (e.g. 'grok', 'minimax', 'glm', 'custom'). */
+    provider: string;
+    /** Conversation transcript (system prompt is composed by the caller). */
+    messages: AgentMessage[];
+    /** Tools available to the agent (may be empty). */
+    tools: AgentToolSpec[];
+    /** Optional event bus. When omitted, events are silently dropped. */
+    eventBus?: EventBus;
+    /** Optional session id for event grouping. Defaults to a UUID. */
+    sessionId?: string;
+    /**
+     * Provider function that yields raw text deltas + finish reason.
+     * Implementation in Task 12.5 (currently lives in llm.ts).
+     */
+    providerStream: ProviderStreamFn;
+    /**
+     * Optional tool registry. When provided, tool_call deltas trigger real
+     * tool execution and emit a matching `tool_execution_end` event.
+     */
+    toolRegistry?: ToolRegistry;
+    /** Optional cwd for tool execution. Defaults to process.cwd(). */
+    cwd?: string;
+    /**
+     * Maximum tool calls per single turn (Task G.2, carryover from v3-C
+     * C.1.5). When the harness sees more than this many `tool_call`
+     * deltas in a single turn, the extra ones are NOT executed by the
+     * registry — instead a synthetic `tool_execution_end` event is
+     * emitted with `isError: true, result: '[skipped] maxToolCallsPerTurn
+     * reached'`. The `tool_execution_start` event still fires so the UI
+     * can render the tool attempt.
+     *
+     * Default: undefined (no limit — backward compatible with v3-C behavior).
+     * Council sets it to 5 by default via `PureCouncilConfig.maxToolCallsPerTurn`.
+     *
+     * Mitigation rationale: a council member prompted with "explore the repo"
+     * could otherwise fire 50 read_file calls in one turn, ballooning the
+     * message context to the point where the next provider call fails with
+     * HTTP 400 (context length exceeded).
+     */
+    maxToolCallsPerTurn?: number;
+    /**
+     * Maximum number of drained queued prompts per run() invocation.
+     * When the queue is non-empty after a turn, the harness re-enters
+     * the providerStream loop up to this many times before yielding
+     * agent_end. Default 3. Set to 0 to disable queue draining.
+     */
+    maxQueuedIterations?: number;
+    /**
+     * Optional council-member identity, propagated to every event the
+     * harness emits (`agent_start`, `agent_end`, `message_start`,
+     * `message_delta`, `message_end`). When set, the event stream
+     * becomes self-describing for visible-reasoning UIs.
+     *
+     * Direct user prompts (non-council) leave this undefined.
+     *
+     * @since 0.5.0
+     */
+    memberId?: string;
+    /** Human-readable member label (e.g. "Caronte"). See `memberId`. */
+    memberName?: string;
+}
+export type ProviderStreamFn = (params: {
+    messages: AgentMessage[];
+    model: string;
+    provider: string;
+    tools: AgentToolSpec[];
+    signal?: AbortSignal;
+}) => AsyncIterable<ProviderDelta>;
+/** Provider-neutral streaming delta (one chunk from a provider). */
+export type ProviderDelta = {
+    kind: 'text';
+    delta: string;
+} | {
+    kind: 'thinking';
+    delta: string;
+} | {
+    kind: 'tool_call';
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+} | {
+    kind: 'finish';
+    reason: string;
+} | {
+    kind: 'error';
+    message: string;
+}
+/** Provider-reported token usage (Task G.4). Emitted as a standalone
+ * delta so it can arrive anywhere in the stream — typically right
+ * before `[DONE]` when `stream_options.include_usage` is set. */
+ | {
+    kind: 'usage';
+    usage: UsageBreakdown;
+};
+export declare class AgentHarness {
+    private readonly config;
+    private readonly eventBus;
+    private readonly sessionId;
+    private readonly maxQueuedIterations;
+    private cancelled;
+    private activeController;
+    private queue;
+    /**
+     * Per-run cache of executed tool calls keyed by `hash(toolName + canonical
+     * args)`. v0.7.1 (A2): when the model re-issues an identical call (a
+     * observed failure mode where read_file hit the same path ×3 / cat the
+     * same file ×3), the cached result is replayed with a "duplicate call"
+     * prefix instead of re-executing — preserving the iteration budget for
+     * real progress. Reset on every `run()` so it does not leak across turns.
+     */
+    private toolCallCache;
+    constructor(config: AgentHarnessConfig);
+    /**
+     * Member identity fields (memberId + memberName) to merge into every
+     * event payload. Returns an empty object when the run is a direct
+     * user prompt (no member context), so call sites can spread it
+     * unconditionally.
+     *
+     * @since 0.5.0
+     */
+    private memberFields;
+    /**
+     * Cancel the in-flight run. Events drain until end of stream.
+     *
+     * Idempotent: calling cancel() multiple times is safe — the cancelled
+     * flag stays true and AbortController.abort() is itself a no-op on
+     * already-aborted controllers. If no turn is running, this is a
+     * no-op (the next run() invocation will check the cancelled flag
+     * and emit `agent_end` with `reason: 'cancelled'` before any work).
+     *
+     * After cancel() returns, the harness should be discarded by the
+     * caller (the run() generator finishes after the current turn ends).
+     * For mid-stream interrupt + new-prompt injection, see Task C.3.2.
+     */
+    cancel(): void;
+    /** Current size of the queued user-prompt buffer. */
+    get queueLength(): number;
+    /**
+     * Enqueue a user prompt to be processed at the next opportunity.
+     * The next prompt in the queue will be appended to the conversation
+     * transcript and re-enter the provider stream loop after the current
+     * turn finishes. Emits a `queue_update` event so UIs can refresh
+     * the displayed counter.
+     *
+     * If `run()` has already returned (no active loop), the queued
+     * prompt will be picked up on the *next* run() call — note this
+     * helper does NOT itself trigger a run. Callers wire the
+     * dequeue step inside `run()` (Task 18.1).
+     */
+    enqueue(userText: string): void;
+    /**
+     * Dequeue the next queued prompt, or `null` if the queue is empty.
+     * Emits a `queue_update` event with the new length so UIs can
+     * decrement the counter.
+     */
+    dequeueNext(): string | null;
+    /**
+     * Run a single agent turn and yield provider-neutral BrainEvents.
+     * The returned AsyncIterable emits all BrainEvents for the run, then completes.
+     * Callers can subscribe via eventBus AND iterate the returned iterable.
+     */
+    run(): AsyncIterable<BrainEvent>;
+    /**
+     * Run a single provider turn for the current message buffer.
+     * Streams from the provider, dispatches deltas to events, executes
+     * any tool calls (if a registry was provided). Yields each
+     * `BrainEvent` it produces so the caller can re-emit them in
+     * the outer generator.
+     *
+     * Does NOT emit `message_start` / `message_end` — those are the
+     * caller's responsibility (so the outer generator can wrap them
+     * around the yielded event stream and compute the right
+     * `totalLength` from observed deltas).
+     *
+     * Extracted from the original monolithic `run()` body to enable
+     * the queue-draining loop in Task 18.1.
+     */
+    private runSingleTurn;
+    private emit;
+    /**
+     * Final-answer turn (v0.7.1 A2). Called when the tool-call loop hit its
+     * iteration cap without the model producing a non-tool finish. Makes ONE
+     * provider call with `tools` OMITTED and a synthetic system nudge appended,
+     * so the run always ends with assistant text answering the user with what
+     * has been gathered — instead of trailing off after the last tool box.
+     *
+     * Yields the full message lifecycle (start/deltas/end) so the UI renders
+     * the closing answer like any other assistant turn. Errors are swallowed
+     * into a recoverable error event (best-effort: the guarantee must never
+     * turn a near-success into a hard failure).
+     */
+    private runFinalAnswerTurn;
+}
+/**
+ * Stable hash key for a tool call (v0.7.1 A2). Canonicalizes args via a sorted
+ * JSON.stringify so `{a:1,b:2}` and `{b:2,a:1}` collide (same logical call).
+ * Exported for unit tests.
+ */
+export declare function hashToolCall(toolName: string, args: unknown): string;
+//# sourceMappingURL=AgentHarness.d.ts.map

package/dist/core/AgentHarness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentHarness.d.ts","sourceRoot":"","sources":["../../src/core/AgentHarness.ts"],"names":[],"mappings":"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"}