@smooai/smooth-operator-core 0.10.0 → 0.10.1

package/dist/agent.d.ts

@@ -0,0 +1,276 @@
+/**
+ * The TypeScript smooth-operator core: a native agentic loop.
+ *
+ * Phase-0 sibling of the C# `SmoothAgent` (`dotnet/core`), the Python core
+ * (`python/core`), and the Rust reference engine. Drives an agentic tool-calling
+ * loop over any OpenAI-compatible chat client (the `openai` SDK pointed at a
+ * gateway): inject retrieved knowledge, call the model, run any requested tools,
+ * feed results back, and loop until the model answers without a tool call or the
+ * iteration budget is hit.
+ *
+ * Deliberately minimal (no compaction / budget / checkpointing yet) — those layer
+ * on exactly as they did when the C# core grew past Phase 0.
+ */
+import type { Clearance } from './cast.js';
+import type { CheckpointStore } from './checkpoint.js';
+import type { SmoothAgentThread } from './thread.js';
+import type { Memory } from './memory.js';
+import type { Reranker } from './rerank.js';
+import type { CostBudget, ModelPricing, Usage } from './cost.js';
+import type { HumanGate } from './humanGate.js';
+import type { Knowledge } from './knowledge.js';
+/** A callable tool the agent may invoke. Mirrors the reference engines' tool seam. */
+export interface Tool {
+    name: string;
+    description: string;
+    /** JSON Schema for the tool's arguments. */
+    parameters: Record<string, unknown>;
+    execute(args: Record<string, unknown>): Promise<string>;
+}
+export interface AgentOptions {
+    instructions?: string;
+    model?: string;
+    maxIterations?: number;
+    maxTokens?: number;
+    temperature?: number;
+    knowledge?: Knowledge;
+    knowledgeTopK?: number;
+    /** Reranker applied to retrieved hits before injection (default: passthrough). */
+    reranker?: Reranker;
+    /** Candidate pool size to retrieve before reranking; when > knowledgeTopK, more docs are fetched, reranked, then trimmed. */
+    knowledgeCandidateK?: number;
+    /** Optional long-term memory; relevant entries are recalled into context each turn. */
+    memory?: Memory;
+    /** How many memory entries to recall per turn (default 4). */
+    memoryTopK?: number;
+    tools?: Tool[];
+    /**
+     * When `true` and an assistant turn returns ≥2 tool calls, dispatch them
+     * concurrently (`Promise.all`) instead of sequentially. The tool-result
+     * messages are still appended in the original `tool_calls` order, so the
+     * transcript stays deterministic regardless of completion order. Default
+     * `false` preserves the sequential behaviour. Per-tool semantics (clearance,
+     * human-gate approval, tool_search promotion, JSON parsing, error handling)
+     * are unchanged — only the dispatch loop runs in parallel.
+     */
+    parallelToolCalls?: boolean;
+    /**
+     * Deferred tools — registered but with their schemas HIDDEN from the model.
+     * When any are present, a built-in `tool_search` meta-tool is advertised in
+     * their place; the model calls it to fuzzy-match and promote the ones it needs,
+     * which then become visible + dispatchable on subsequent turns. Keeps the tool
+     * schema payload small when there are many rarely-used tools. An unpromoted
+     * deferred tool is NOT dispatchable.
+     */
+    deferredTools?: Tool[];
+    /**
+     * Approximate token budget for the context window. Before each model call,
+     * older non-system messages are dropped (sliding window) to stay under it.
+     * `0` disables compaction. Defaults to 8000.
+     */
+    maxContextTokens?: number;
+    /** Optional ceiling for the turn (token and/or USD). The turn stops early once a model call pushes usage/cost over the budget. */
+    budget?: CostBudget;
+    /** Per-model pricing override for cost accounting (defaults to DEFAULT_PRICING). */
+    pricing?: Record<string, ModelPricing>;
+    /** Optional store for persisting/resuming the conversation. Used with `conversationId`. */
+    checkpointStore?: CheckpointStore;
+    /** Conversation id for the checkpoint store (required to use checkpointing). */
+    conversationId?: string;
+    /**
+     * Optional tool-access policy. When set, a tool the clearance forbids is not
+     * dispatched — a "tool not permitted" result is returned to the model instead.
+     * Undefined allows every tool (the prior behaviour).
+     */
+    clearance?: Clearance;
+    /**
+     * Optional human-in-the-loop gate. When set, the agent asks it for approval before
+     * running any tool call for which {@link requiresApproval} returns true. A denied call
+     * is not executed; the model is told it was denied and can adapt.
+     */
+    humanGate?: HumanGate;
+    /**
+     * Which tool calls need human approval (e.g. writes / destructive actions), given the
+     * tool name and parsed arguments. Default: none. Only consulted when `humanGate` is set.
+     * Example: `requiresApproval: (name) => name === 'delete_record' || name === 'send_email'`.
+     */
+    requiresApproval?: (name: string, args: Record<string, unknown>) => boolean;
+    /**
+     * Number of ADDITIONAL attempts after the first if the model call throws a transient
+     * error (rate-limit, 5xx, dropped connection). `0` (the default) preserves today's
+     * behaviour: a single attempt, error propagates immediately. Only the model call is
+     * retried — never tool execution.
+     */
+    maxRetries?: number;
+    /**
+     * Base delay (milliseconds) for exponential backoff between retries. The wait before
+     * retry attempt `n` (1-indexed) is `retryBackoffMs * 2 ** (n - 1)`. Defaults to 200.
+     * Set to `0` to retry without sleeping (used by tests).
+     */
+    retryBackoffMs?: number;
+}
+export interface AgentRunResponse {
+    text: string;
+    iterations: number;
+    toolCalls: number;
+    usage: Usage;
+    costUsd: number;
+    /** True if the turn stopped because the cost/token budget was hit. */
+    budgetExceeded: boolean;
+}
+/**
+ * One streamed chunk from a streaming chat completion — the standard OpenAI
+ * `chat.completions` streaming chunk shape. `content` deltas concatenate into the
+ * assistant text; `tool_calls` fragments are assembled by their `index` (the `id`
+ * + `function.name` appear when the call first opens, `function.arguments` arrives
+ * in fragments). `usage` is sent by gateways on (typically) the final chunk.
+ */
+export interface ChatChunk {
+    choices: Array<{
+        delta: {
+            content?: string | null;
+            tool_calls?: Array<{
+                index: number;
+                id?: string;
+                function?: {
+                    name?: string;
+                    arguments?: string;
+                };
+            }> | null;
+        };
+    }>;
+    usage?: {
+        prompt_tokens?: number | null;
+        completion_tokens?: number | null;
+    } | null;
+}
+/**
+ * The minimal shape of the OpenAI-compatible client the agent needs. The real
+ * `openai` SDK's `OpenAI` satisfies this; tests inject a fake.
+ *
+ * `chat.completions.create` is the non-streaming call the {@link SmoothAgent.run}
+ * loop uses. `createStream` is the optional streaming call the
+ * {@link SmoothAgent.runStream} loop uses — production wires it to the real SDK's
+ * `create({ ...body, stream: true })` (which returns an async-iterable of
+ * {@link ChatChunk}s). It is optional so non-streaming consumers and the existing
+ * fakes keep satisfying the interface; `runStream` throws if it is absent.
+ */
+export interface ChatClientLike {
+    chat: {
+        completions: {
+            create(body: Record<string, unknown>): Promise<{
+                choices: Array<{
+                    message: {
+                        content: string | null;
+                        tool_calls?: Array<{
+                            id: string;
+                            function: {
+                                name: string;
+                                arguments: string;
+                            };
+                        }> | null;
+                    };
+                }>;
+                usage?: {
+                    prompt_tokens?: number | null;
+                    completion_tokens?: number | null;
+                } | null;
+            }>;
+            /**
+             * Streaming variant of {@link create}. Production wires this to the real
+             * `openai` SDK's `create({ ...body, stream: true })`, which returns an
+             * `AsyncIterable<ChatChunk>`. Optional so non-streaming clients still satisfy
+             * the seam; {@link SmoothAgent.runStream} requires it.
+             */
+            createStream?(body: Record<string, unknown>): AsyncIterable<ChatChunk>;
+        };
+    };
+}
+/**
+ * A streamed event from {@link SmoothAgent.runStream}. A tagged union discriminated
+ * on `type`, mirroring the C# `RunStreamingAsync` update sequence and the Rust
+ * reference engine's event stream:
+ *
+ * - `text`     — an incremental assistant content delta as it streams in.
+ * - `tool_call`— a tool call the model requested, emitted once (after the model
+ *                stream for the iteration completes) before it is dispatched.
+ * - `tool_result` — a tool's result, emitted after it finishes.
+ * - `done`     — the single terminal event, carrying the same {@link AgentRunResponse}
+ *                that {@link SmoothAgent.run} would return for the same script.
+ */
+export type StreamEvent = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'tool_call';
+    name: string;
+    arguments: string;
+} | {
+    type: 'tool_result';
+    name: string;
+    result: string;
+} | {
+    type: 'done';
+    response: AgentRunResponse;
+};
+export declare class SmoothAgent {
+    private readonly client;
+    private readonly options;
+    private readonly toolsByName;
+    constructor(client: ChatClientLike, options?: AgentOptions);
+    private buildSystem;
+    private toolSpecs;
+    /**
+     * Run a single turn.
+     *
+     * `history` is prior OpenAI-format messages (multi-turn). `thread`, when given,
+     * is a {@link SmoothAgentThread} carrying the conversation across runs: the turn
+     * is seeded from the thread's messages, and this turn's new user + assistant
+     * (+ tool) messages are appended back to it before returning. The thread takes
+     * precedence over `history` as the prior context.
+     */
+    run(message: string, history?: Array<Record<string, unknown>>, thread?: SmoothAgentThread): Promise<AgentRunResponse>;
+    /**
+     * Stream a single turn, yielding incremental {@link StreamEvent}s as the model
+     * produces them. This drives the SAME agentic loop as {@link run} (system /
+     * knowledge / memory build, seed messages, per-iteration compaction, cost
+     * tracking, budget early-stop, deferred-tool specs, clearance + human-gate on
+     * dispatch, checkpoint/thread persistence on exit) — but calls the model in
+     * STREAMING mode and emits events as work happens:
+     *
+     * - a `text` event per non-empty content delta as it streams in;
+     * - a `tool_call` event per requested tool call, after that iteration's model
+     *   stream ends, BEFORE the call is dispatched;
+     * - a `tool_result` event per tool, after it finishes (in original call order
+     *   even when `parallelToolCalls` runs them concurrently);
+     * - exactly one terminal `done` event carrying the same {@link AgentRunResponse}
+     *   {@link run} would return for the same script.
+     *
+     * NOTE: retry-with-backoff (`maxRetries`/`retryBackoffMs`) is intentionally NOT
+     * applied here — re-running the call after a mid-stream failure would re-emit
+     * already-yielded chunks. Retry stays scoped to non-streaming {@link run}; this
+     * mirrors the C# `RunStreamingAsync` decision.
+     */
+    runStream(message: string, history?: Array<Record<string, unknown>>, thread?: SmoothAgentThread): AsyncGenerator<StreamEvent>;
+    /**
+     * Invoke the model with bounded retry-with-exponential-backoff.
+     *
+     * On a transient error (anything the client throws — rate-limit, 5xx, dropped
+     * connection) the call is retried up to `maxRetries` additional times, waiting
+     * `retryBackoffMs * 2 ** (n - 1)` ms before the n-th (1-indexed) retry. If all
+     * attempts fail the LAST error propagates, so the turn fails exactly as it did
+     * before retries existed. Only this model call is retried — tool execution is not.
+     */
+    private callModel;
+    private dispatchTool;
+}
+/**
+ * Build a {@link Tool} that delegates a subtask to a child {@link SmoothAgent}.
+ *
+ * A sub-agent is just a tool backed by another agent: the model calls this tool
+ * with a `task` argument, the child agent runs that task, and the child's final
+ * reply becomes the tool result — composing with the existing tool loop, no special
+ * wiring. The child can have its own instructions, tools, knowledge, etc.
+ */
+export declare function delegateTool(name: string, description: string, child: SmoothAgent, taskProperty?: string): Tool;
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

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