@smooai/smooth-operator-core 0.1.0 → 0.9.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +105 -0
- package/package.json +7 -2
- package/dist/agent.d.ts +0 -276
- package/dist/agent.d.ts.map +0 -1
- package/dist/agent.js +0 -450
- package/dist/agent.js.map +0 -1
- package/dist/cast.d.ts +0 -81
- package/dist/cast.d.ts.map +0 -1
- package/dist/cast.js +0 -103
- package/dist/cast.js.map +0 -1
- package/dist/checkpoint.d.ts +0 -25
- package/dist/checkpoint.d.ts.map +0 -1
- package/dist/checkpoint.js +0 -23
- package/dist/checkpoint.js.map +0 -1
- package/dist/compaction.d.ts +0 -21
- package/dist/compaction.d.ts.map +0 -1
- package/dist/compaction.js +0 -50
- package/dist/compaction.js.map +0 -1
- package/dist/cost.d.ts +0 -34
- package/dist/cost.d.ts.map +0 -1
- package/dist/cost.js +0 -42
- package/dist/cost.js.map +0 -1
- package/dist/humanGate.d.ts +0 -44
- package/dist/humanGate.d.ts.map +0 -1
- package/dist/humanGate.js +0 -30
- package/dist/humanGate.js.map +0 -1
- package/dist/index.d.ts +0 -32
- package/dist/index.d.ts.map +0 -1
- package/dist/index.js +0 -21
- package/dist/index.js.map +0 -1
- package/dist/knowledge.d.ts +0 -30
- package/dist/knowledge.d.ts.map +0 -1
- package/dist/knowledge.js +0 -43
- package/dist/knowledge.js.map +0 -1
- package/dist/llmProvider.d.ts +0 -106
- package/dist/llmProvider.d.ts.map +0 -1
- package/dist/llmProvider.js +0 -160
- package/dist/llmProvider.js.map +0 -1
- package/dist/memory.d.ts +0 -23
- package/dist/memory.d.ts.map +0 -1
- package/dist/memory.js +0 -40
- package/dist/memory.js.map +0 -1
- package/dist/rerank.d.ts +0 -27
- package/dist/rerank.d.ts.map +0 -1
- package/dist/rerank.js +0 -45
- package/dist/rerank.js.map +0 -1
- package/dist/thread.d.ts +0 -43
- package/dist/thread.d.ts.map +0 -1
- package/dist/thread.js +0 -60
- package/dist/thread.js.map +0 -1
- package/dist/toolSearch.d.ts +0 -55
- package/dist/toolSearch.d.ts.map +0 -1
- package/dist/toolSearch.js +0 -110
- package/dist/toolSearch.js.map +0 -1
- package/dist/vector.d.ts +0 -36
- package/dist/vector.d.ts.map +0 -1
- package/dist/vector.js +0 -75
- package/dist/vector.js.map +0 -1
- package/dist/workflow.d.ts +0 -62
- package/dist/workflow.d.ts.map +0 -1
- package/dist/workflow.js +0 -109
- package/dist/workflow.js.map +0 -1
package/README.md
ADDED
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://smoo.ai"><img src="https://raw.githubusercontent.com/SmooAI/smooth-operator-core/main/.github/banner-typescript.png" alt="smooth-operator-core — The TypeScript engine for orchestrated AI agents" width="100%" /></a>
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
<p align="center">
|
|
6
|
+
<a href="https://smoo.ai/th"><img src="https://img.shields.io/badge/Smoo_AI-platform-00A6A6?style=for-the-badge&labelColor=020618" alt="Smoo AI"></a>
|
|
7
|
+
<a href="https://github.com/SmooAI/smooth-operator-core/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-F49F0A?style=for-the-badge&labelColor=020618" alt="license"></a>
|
|
8
|
+
<a href="https://lom.smoo.ai"><img src="https://img.shields.io/badge/hosted-lom.smoo.ai-FF6B6C?style=for-the-badge&labelColor=020618" alt="lom.smoo.ai"></a>
|
|
9
|
+
</p>
|
|
10
|
+
|
|
11
|
+
<p align="center">
|
|
12
|
+
<a href="https://www.npmjs.com/package/@smooai/smooth-operator-core"><img src="https://img.shields.io/npm/v/@smooai/smooth-operator-core?style=flat-square&color=00A6A6&labelColor=020618" alt="npm"></a>
|
|
13
|
+
<img src="https://img.shields.io/badge/TypeScript-engine-3178C6?style=flat-square&labelColor=020618" alt="TypeScript engine">
|
|
14
|
+
</p>
|
|
15
|
+
|
|
16
|
+
---
|
|
17
|
+
|
|
18
|
+
> The TypeScript sibling of the [Rust reference engine](https://github.com/SmooAI/smooth-operator-core). Agents, tools, knowledge/RAG, memory, checkpointing, human-in-the-loop, cost budgets, and workflows — as one embeddable npm package. It's the engine, not a notebook demo.
|
|
19
|
+
|
|
20
|
+
`@smooai/smooth-operator-core` is the **native TypeScript implementation** of the Smoo AI agent engine — the in-process observe→think→act loop that powers [**lom.smoo.ai**](https://lom.smoo.ai). It's a sibling of the [Rust reference engine](https://github.com/SmooAI/smooth-operator-core) and one of the [polyglot set](https://github.com/SmooAI/smooth-operator-core/blob/main/docs/Polyglot-Engines.md) (Rust, TypeScript, Python, Go, C#/.NET) whose behavior is held at parity by a shared eval suite.
|
|
21
|
+
|
|
22
|
+
It's a library, not a client to a remote server: it *is* the agent, running in your Node process. Every surface is covered by **fast, offline tests** built on a deterministic `MockLlmProvider`, so the loop is verified — not vibe-coded.
|
|
23
|
+
|
|
24
|
+
## Install
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
npm install @smooai/smooth-operator-core
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
## Quickstart
|
|
31
|
+
|
|
32
|
+
A complete agent — no credentials needed — using the deterministic mock provider the engine's own tests run on:
|
|
33
|
+
|
|
34
|
+
```ts
|
|
35
|
+
import { SmoothAgent, MockLlmProvider } from '@smooai/smooth-operator-core';
|
|
36
|
+
|
|
37
|
+
const provider = new MockLlmProvider().pushText('the answer is 42');
|
|
38
|
+
const agent = new SmoothAgent(provider, { instructions: 'You are a helpful assistant' });
|
|
39
|
+
|
|
40
|
+
const response = await agent.run('what is the answer?');
|
|
41
|
+
console.log(response.text);
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
`SmoothAgent`'s constructor takes a `ChatClientLike` (the `MockLlmProvider` implements it — swap in any OpenAI-compatible client) and an `AgentOptions` object. `run` returns an `AgentRunResponse` whose `text` is the final answer.
|
|
45
|
+
|
|
46
|
+
## Features
|
|
47
|
+
|
|
48
|
+
The full parity surface — every engine in the [polyglot set](https://github.com/SmooAI/smooth-operator-core/blob/main/docs/Polyglot-Engines.md) ships it:
|
|
49
|
+
|
|
50
|
+
- **Agentic tool-calling loop** — observe→think→act, looping until the model answers.
|
|
51
|
+
- **Typed tools** — register `Tool`s the model can call, with parallel dispatch.
|
|
52
|
+
- **Knowledge / RAG + vectors** — `InMemoryKnowledge` / `VectorKnowledge` ground the turn in retrieved documents.
|
|
53
|
+
- **Memory** — `InMemoryMemory` recalls long-term entries into context each turn.
|
|
54
|
+
- **Compaction** — a sliding-window token budget keeps the prompt under a ceiling.
|
|
55
|
+
- **Cost / budget** — `CostTracker` + `CostBudget` with per-model pricing and early stop.
|
|
56
|
+
- **Checkpointing** — `InMemoryCheckpointStore` (and the `CheckpointStore` seam) persist/resume a conversation.
|
|
57
|
+
- **Rerank** — `LexicalReranker` reranks retrieved hits before injection.
|
|
58
|
+
- **Sub-agents / delegation** — `delegateTool` spawns child agents for sub-tasks.
|
|
59
|
+
- **Cast + clearance** — `Cast`, `Clearance`, `makeRole` for per-role tool-access policy.
|
|
60
|
+
- **Human-in-the-loop gate** — `HumanGate` requires approval before designated tool calls run.
|
|
61
|
+
- **Conversation thread** — `SmoothAgentThread` carries a conversation across multiple `run` calls.
|
|
62
|
+
- **`LlmProvider` seam + `MockLlmProvider`** — inject any OpenAI-compatible client; the record/replay mock drives the offline tests.
|
|
63
|
+
- **Deferred tools + `tool_search`** — `ToolSearch` hides rarely-used tool schemas behind a meta-tool the model calls to promote the ones it needs.
|
|
64
|
+
- **Typed workflow graph** — `Workflow` with typed nodes/edges, alongside the agent loop.
|
|
65
|
+
- **Parallel tool calls** — dispatch ≥2 tool calls concurrently (transcript order preserved).
|
|
66
|
+
- **Retry / backoff** — retry transient model-call failures with exponential backoff.
|
|
67
|
+
- **Streaming** — stream incremental text, tool calls, and tool results as the turn runs.
|
|
68
|
+
|
|
69
|
+
## Streaming
|
|
70
|
+
|
|
71
|
+
`runStream` is an async generator over a `StreamEvent` tagged union (discriminated on `type`): `text` deltas as the model produces them, each `tool_call` before dispatch, each `tool_result` after it finishes, and a terminal `done` event carrying the same response `run` would have returned.
|
|
72
|
+
|
|
73
|
+
```ts
|
|
74
|
+
for await (const event of agent.runStream('what is the answer?')) {
|
|
75
|
+
if (event.type === 'text') process.stdout.write(event.text);
|
|
76
|
+
if (event.type === 'done') console.log(`\n${event.response.text}`);
|
|
77
|
+
}
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
`runStream` requires a streaming-capable client (`chat.completions.createStream`); the `MockLlmProvider` supplies one, replaying the same script as the non-streaming path.
|
|
81
|
+
|
|
82
|
+
## Part of Smoo AI
|
|
83
|
+
|
|
84
|
+
`smooth-operator-core` is built and open-sourced by **[Smoo AI](https://smoo.ai)** — the AI-powered business platform with AI built into every product: CRM, customer support, campaigns, field service, observability, and developer tools.
|
|
85
|
+
|
|
86
|
+
- 🚀 **Smooth on the platform** — [smoo.ai/th](https://smoo.ai/th)
|
|
87
|
+
- 🧰 **More open source from Smoo AI** — [smoo.ai/open-source](https://smoo.ai/open-source)
|
|
88
|
+
- 🧩 **Run it hosted** — [lom.smoo.ai](https://lom.smoo.ai)
|
|
89
|
+
|
|
90
|
+
## Links
|
|
91
|
+
|
|
92
|
+
- [**lom.smoo.ai**](https://lom.smoo.ai) — run it hosted
|
|
93
|
+
- [smooth-operator-core](https://github.com/SmooAI/smooth-operator-core) — the polyglot engine repo
|
|
94
|
+
- [Polyglot Engines](https://github.com/SmooAI/smooth-operator-core/blob/main/docs/Polyglot-Engines.md) — install + hello-agent in all five languages
|
|
95
|
+
- [smoo.ai](https://smoo.ai) — the product · [smoo.ai/open-source](https://smoo.ai/open-source) — more open source
|
|
96
|
+
|
|
97
|
+
## License
|
|
98
|
+
|
|
99
|
+
MIT — see [LICENSE](https://github.com/SmooAI/smooth-operator-core/blob/main/LICENSE).
|
|
100
|
+
|
|
101
|
+
---
|
|
102
|
+
|
|
103
|
+
<p align="center">
|
|
104
|
+
Built by <a href="https://smoo.ai"><strong>Smoo AI</strong></a> — AI built into every product.
|
|
105
|
+
</p>
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@smooai/smooth-operator-core",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.9.0",
|
|
4
4
|
"description": "Native TypeScript implementation of the smooth-operator agent engine — an in-process, OpenAI-compatible agentic tool-calling loop with knowledge grounding. The TypeScript sibling of the Rust reference engine, the C# core, and the Python core.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -17,13 +17,18 @@
|
|
|
17
17
|
".": {
|
|
18
18
|
"types": "./dist/index.d.ts",
|
|
19
19
|
"import": "./dist/index.js"
|
|
20
|
+
},
|
|
21
|
+
"./extension": {
|
|
22
|
+
"types": "./dist/extension/index.d.ts",
|
|
23
|
+
"import": "./dist/extension/index.js"
|
|
20
24
|
}
|
|
21
25
|
},
|
|
22
26
|
"files": [
|
|
23
27
|
"dist"
|
|
24
28
|
],
|
|
25
29
|
"dependencies": {
|
|
26
|
-
"openai": "^4.77.0"
|
|
30
|
+
"openai": "^4.77.0",
|
|
31
|
+
"smol-toml": "^1.7.0"
|
|
27
32
|
},
|
|
28
33
|
"devDependencies": {
|
|
29
34
|
"@types/node": "^25.9.2",
|
package/dist/agent.d.ts
DELETED
|
@@ -1,276 +0,0 @@
|
|
|
1
|
-
/**
|
|
2
|
-
* The TypeScript smooth-operator core: a native agentic loop.
|
|
3
|
-
*
|
|
4
|
-
* Phase-0 sibling of the C# `SmoothAgent` (`dotnet/core`), the Python core
|
|
5
|
-
* (`python/core`), and the Rust reference engine. Drives an agentic tool-calling
|
|
6
|
-
* loop over any OpenAI-compatible chat client (the `openai` SDK pointed at a
|
|
7
|
-
* gateway): inject retrieved knowledge, call the model, run any requested tools,
|
|
8
|
-
* feed results back, and loop until the model answers without a tool call or the
|
|
9
|
-
* iteration budget is hit.
|
|
10
|
-
*
|
|
11
|
-
* Deliberately minimal (no compaction / budget / checkpointing yet) — those layer
|
|
12
|
-
* on exactly as they did when the C# core grew past Phase 0.
|
|
13
|
-
*/
|
|
14
|
-
import type { Clearance } from './cast.js';
|
|
15
|
-
import type { CheckpointStore } from './checkpoint.js';
|
|
16
|
-
import type { SmoothAgentThread } from './thread.js';
|
|
17
|
-
import type { Memory } from './memory.js';
|
|
18
|
-
import type { Reranker } from './rerank.js';
|
|
19
|
-
import type { CostBudget, ModelPricing, Usage } from './cost.js';
|
|
20
|
-
import type { HumanGate } from './humanGate.js';
|
|
21
|
-
import type { Knowledge } from './knowledge.js';
|
|
22
|
-
/** A callable tool the agent may invoke. Mirrors the reference engines' tool seam. */
|
|
23
|
-
export interface Tool {
|
|
24
|
-
name: string;
|
|
25
|
-
description: string;
|
|
26
|
-
/** JSON Schema for the tool's arguments. */
|
|
27
|
-
parameters: Record<string, unknown>;
|
|
28
|
-
execute(args: Record<string, unknown>): Promise<string>;
|
|
29
|
-
}
|
|
30
|
-
export interface AgentOptions {
|
|
31
|
-
instructions?: string;
|
|
32
|
-
model?: string;
|
|
33
|
-
maxIterations?: number;
|
|
34
|
-
maxTokens?: number;
|
|
35
|
-
temperature?: number;
|
|
36
|
-
knowledge?: Knowledge;
|
|
37
|
-
knowledgeTopK?: number;
|
|
38
|
-
/** Reranker applied to retrieved hits before injection (default: passthrough). */
|
|
39
|
-
reranker?: Reranker;
|
|
40
|
-
/** Candidate pool size to retrieve before reranking; when > knowledgeTopK, more docs are fetched, reranked, then trimmed. */
|
|
41
|
-
knowledgeCandidateK?: number;
|
|
42
|
-
/** Optional long-term memory; relevant entries are recalled into context each turn. */
|
|
43
|
-
memory?: Memory;
|
|
44
|
-
/** How many memory entries to recall per turn (default 4). */
|
|
45
|
-
memoryTopK?: number;
|
|
46
|
-
tools?: Tool[];
|
|
47
|
-
/**
|
|
48
|
-
* When `true` and an assistant turn returns ≥2 tool calls, dispatch them
|
|
49
|
-
* concurrently (`Promise.all`) instead of sequentially. The tool-result
|
|
50
|
-
* messages are still appended in the original `tool_calls` order, so the
|
|
51
|
-
* transcript stays deterministic regardless of completion order. Default
|
|
52
|
-
* `false` preserves the sequential behaviour. Per-tool semantics (clearance,
|
|
53
|
-
* human-gate approval, tool_search promotion, JSON parsing, error handling)
|
|
54
|
-
* are unchanged — only the dispatch loop runs in parallel.
|
|
55
|
-
*/
|
|
56
|
-
parallelToolCalls?: boolean;
|
|
57
|
-
/**
|
|
58
|
-
* Deferred tools — registered but with their schemas HIDDEN from the model.
|
|
59
|
-
* When any are present, a built-in `tool_search` meta-tool is advertised in
|
|
60
|
-
* their place; the model calls it to fuzzy-match and promote the ones it needs,
|
|
61
|
-
* which then become visible + dispatchable on subsequent turns. Keeps the tool
|
|
62
|
-
* schema payload small when there are many rarely-used tools. An unpromoted
|
|
63
|
-
* deferred tool is NOT dispatchable.
|
|
64
|
-
*/
|
|
65
|
-
deferredTools?: Tool[];
|
|
66
|
-
/**
|
|
67
|
-
* Approximate token budget for the context window. Before each model call,
|
|
68
|
-
* older non-system messages are dropped (sliding window) to stay under it.
|
|
69
|
-
* `0` disables compaction. Defaults to 8000.
|
|
70
|
-
*/
|
|
71
|
-
maxContextTokens?: number;
|
|
72
|
-
/** Optional ceiling for the turn (token and/or USD). The turn stops early once a model call pushes usage/cost over the budget. */
|
|
73
|
-
budget?: CostBudget;
|
|
74
|
-
/** Per-model pricing override for cost accounting (defaults to DEFAULT_PRICING). */
|
|
75
|
-
pricing?: Record<string, ModelPricing>;
|
|
76
|
-
/** Optional store for persisting/resuming the conversation. Used with `conversationId`. */
|
|
77
|
-
checkpointStore?: CheckpointStore;
|
|
78
|
-
/** Conversation id for the checkpoint store (required to use checkpointing). */
|
|
79
|
-
conversationId?: string;
|
|
80
|
-
/**
|
|
81
|
-
* Optional tool-access policy. When set, a tool the clearance forbids is not
|
|
82
|
-
* dispatched — a "tool not permitted" result is returned to the model instead.
|
|
83
|
-
* Undefined allows every tool (the prior behaviour).
|
|
84
|
-
*/
|
|
85
|
-
clearance?: Clearance;
|
|
86
|
-
/**
|
|
87
|
-
* Optional human-in-the-loop gate. When set, the agent asks it for approval before
|
|
88
|
-
* running any tool call for which {@link requiresApproval} returns true. A denied call
|
|
89
|
-
* is not executed; the model is told it was denied and can adapt.
|
|
90
|
-
*/
|
|
91
|
-
humanGate?: HumanGate;
|
|
92
|
-
/**
|
|
93
|
-
* Which tool calls need human approval (e.g. writes / destructive actions), given the
|
|
94
|
-
* tool name and parsed arguments. Default: none. Only consulted when `humanGate` is set.
|
|
95
|
-
* Example: `requiresApproval: (name) => name === 'delete_record' || name === 'send_email'`.
|
|
96
|
-
*/
|
|
97
|
-
requiresApproval?: (name: string, args: Record<string, unknown>) => boolean;
|
|
98
|
-
/**
|
|
99
|
-
* Number of ADDITIONAL attempts after the first if the model call throws a transient
|
|
100
|
-
* error (rate-limit, 5xx, dropped connection). `0` (the default) preserves today's
|
|
101
|
-
* behaviour: a single attempt, error propagates immediately. Only the model call is
|
|
102
|
-
* retried — never tool execution.
|
|
103
|
-
*/
|
|
104
|
-
maxRetries?: number;
|
|
105
|
-
/**
|
|
106
|
-
* Base delay (milliseconds) for exponential backoff between retries. The wait before
|
|
107
|
-
* retry attempt `n` (1-indexed) is `retryBackoffMs * 2 ** (n - 1)`. Defaults to 200.
|
|
108
|
-
* Set to `0` to retry without sleeping (used by tests).
|
|
109
|
-
*/
|
|
110
|
-
retryBackoffMs?: number;
|
|
111
|
-
}
|
|
112
|
-
export interface AgentRunResponse {
|
|
113
|
-
text: string;
|
|
114
|
-
iterations: number;
|
|
115
|
-
toolCalls: number;
|
|
116
|
-
usage: Usage;
|
|
117
|
-
costUsd: number;
|
|
118
|
-
/** True if the turn stopped because the cost/token budget was hit. */
|
|
119
|
-
budgetExceeded: boolean;
|
|
120
|
-
}
|
|
121
|
-
/**
|
|
122
|
-
* One streamed chunk from a streaming chat completion — the standard OpenAI
|
|
123
|
-
* `chat.completions` streaming chunk shape. `content` deltas concatenate into the
|
|
124
|
-
* assistant text; `tool_calls` fragments are assembled by their `index` (the `id`
|
|
125
|
-
* + `function.name` appear when the call first opens, `function.arguments` arrives
|
|
126
|
-
* in fragments). `usage` is sent by gateways on (typically) the final chunk.
|
|
127
|
-
*/
|
|
128
|
-
export interface ChatChunk {
|
|
129
|
-
choices: Array<{
|
|
130
|
-
delta: {
|
|
131
|
-
content?: string | null;
|
|
132
|
-
tool_calls?: Array<{
|
|
133
|
-
index: number;
|
|
134
|
-
id?: string;
|
|
135
|
-
function?: {
|
|
136
|
-
name?: string;
|
|
137
|
-
arguments?: string;
|
|
138
|
-
};
|
|
139
|
-
}> | null;
|
|
140
|
-
};
|
|
141
|
-
}>;
|
|
142
|
-
usage?: {
|
|
143
|
-
prompt_tokens?: number | null;
|
|
144
|
-
completion_tokens?: number | null;
|
|
145
|
-
} | null;
|
|
146
|
-
}
|
|
147
|
-
/**
|
|
148
|
-
* The minimal shape of the OpenAI-compatible client the agent needs. The real
|
|
149
|
-
* `openai` SDK's `OpenAI` satisfies this; tests inject a fake.
|
|
150
|
-
*
|
|
151
|
-
* `chat.completions.create` is the non-streaming call the {@link SmoothAgent.run}
|
|
152
|
-
* loop uses. `createStream` is the optional streaming call the
|
|
153
|
-
* {@link SmoothAgent.runStream} loop uses — production wires it to the real SDK's
|
|
154
|
-
* `create({ ...body, stream: true })` (which returns an async-iterable of
|
|
155
|
-
* {@link ChatChunk}s). It is optional so non-streaming consumers and the existing
|
|
156
|
-
* fakes keep satisfying the interface; `runStream` throws if it is absent.
|
|
157
|
-
*/
|
|
158
|
-
export interface ChatClientLike {
|
|
159
|
-
chat: {
|
|
160
|
-
completions: {
|
|
161
|
-
create(body: Record<string, unknown>): Promise<{
|
|
162
|
-
choices: Array<{
|
|
163
|
-
message: {
|
|
164
|
-
content: string | null;
|
|
165
|
-
tool_calls?: Array<{
|
|
166
|
-
id: string;
|
|
167
|
-
function: {
|
|
168
|
-
name: string;
|
|
169
|
-
arguments: string;
|
|
170
|
-
};
|
|
171
|
-
}> | null;
|
|
172
|
-
};
|
|
173
|
-
}>;
|
|
174
|
-
usage?: {
|
|
175
|
-
prompt_tokens?: number | null;
|
|
176
|
-
completion_tokens?: number | null;
|
|
177
|
-
} | null;
|
|
178
|
-
}>;
|
|
179
|
-
/**
|
|
180
|
-
* Streaming variant of {@link create}. Production wires this to the real
|
|
181
|
-
* `openai` SDK's `create({ ...body, stream: true })`, which returns an
|
|
182
|
-
* `AsyncIterable<ChatChunk>`. Optional so non-streaming clients still satisfy
|
|
183
|
-
* the seam; {@link SmoothAgent.runStream} requires it.
|
|
184
|
-
*/
|
|
185
|
-
createStream?(body: Record<string, unknown>): AsyncIterable<ChatChunk>;
|
|
186
|
-
};
|
|
187
|
-
};
|
|
188
|
-
}
|
|
189
|
-
/**
|
|
190
|
-
* A streamed event from {@link SmoothAgent.runStream}. A tagged union discriminated
|
|
191
|
-
* on `type`, mirroring the C# `RunStreamingAsync` update sequence and the Rust
|
|
192
|
-
* reference engine's event stream:
|
|
193
|
-
*
|
|
194
|
-
* - `text` — an incremental assistant content delta as it streams in.
|
|
195
|
-
* - `tool_call`— a tool call the model requested, emitted once (after the model
|
|
196
|
-
* stream for the iteration completes) before it is dispatched.
|
|
197
|
-
* - `tool_result` — a tool's result, emitted after it finishes.
|
|
198
|
-
* - `done` — the single terminal event, carrying the same {@link AgentRunResponse}
|
|
199
|
-
* that {@link SmoothAgent.run} would return for the same script.
|
|
200
|
-
*/
|
|
201
|
-
export type StreamEvent = {
|
|
202
|
-
type: 'text';
|
|
203
|
-
text: string;
|
|
204
|
-
} | {
|
|
205
|
-
type: 'tool_call';
|
|
206
|
-
name: string;
|
|
207
|
-
arguments: string;
|
|
208
|
-
} | {
|
|
209
|
-
type: 'tool_result';
|
|
210
|
-
name: string;
|
|
211
|
-
result: string;
|
|
212
|
-
} | {
|
|
213
|
-
type: 'done';
|
|
214
|
-
response: AgentRunResponse;
|
|
215
|
-
};
|
|
216
|
-
export declare class SmoothAgent {
|
|
217
|
-
private readonly client;
|
|
218
|
-
private readonly options;
|
|
219
|
-
private readonly toolsByName;
|
|
220
|
-
constructor(client: ChatClientLike, options?: AgentOptions);
|
|
221
|
-
private buildSystem;
|
|
222
|
-
private toolSpecs;
|
|
223
|
-
/**
|
|
224
|
-
* Run a single turn.
|
|
225
|
-
*
|
|
226
|
-
* `history` is prior OpenAI-format messages (multi-turn). `thread`, when given,
|
|
227
|
-
* is a {@link SmoothAgentThread} carrying the conversation across runs: the turn
|
|
228
|
-
* is seeded from the thread's messages, and this turn's new user + assistant
|
|
229
|
-
* (+ tool) messages are appended back to it before returning. The thread takes
|
|
230
|
-
* precedence over `history` as the prior context.
|
|
231
|
-
*/
|
|
232
|
-
run(message: string, history?: Array<Record<string, unknown>>, thread?: SmoothAgentThread): Promise<AgentRunResponse>;
|
|
233
|
-
/**
|
|
234
|
-
* Stream a single turn, yielding incremental {@link StreamEvent}s as the model
|
|
235
|
-
* produces them. This drives the SAME agentic loop as {@link run} (system /
|
|
236
|
-
* knowledge / memory build, seed messages, per-iteration compaction, cost
|
|
237
|
-
* tracking, budget early-stop, deferred-tool specs, clearance + human-gate on
|
|
238
|
-
* dispatch, checkpoint/thread persistence on exit) — but calls the model in
|
|
239
|
-
* STREAMING mode and emits events as work happens:
|
|
240
|
-
*
|
|
241
|
-
* - a `text` event per non-empty content delta as it streams in;
|
|
242
|
-
* - a `tool_call` event per requested tool call, after that iteration's model
|
|
243
|
-
* stream ends, BEFORE the call is dispatched;
|
|
244
|
-
* - a `tool_result` event per tool, after it finishes (in original call order
|
|
245
|
-
* even when `parallelToolCalls` runs them concurrently);
|
|
246
|
-
* - exactly one terminal `done` event carrying the same {@link AgentRunResponse}
|
|
247
|
-
* {@link run} would return for the same script.
|
|
248
|
-
*
|
|
249
|
-
* NOTE: retry-with-backoff (`maxRetries`/`retryBackoffMs`) is intentionally NOT
|
|
250
|
-
* applied here — re-running the call after a mid-stream failure would re-emit
|
|
251
|
-
* already-yielded chunks. Retry stays scoped to non-streaming {@link run}; this
|
|
252
|
-
* mirrors the C# `RunStreamingAsync` decision.
|
|
253
|
-
*/
|
|
254
|
-
runStream(message: string, history?: Array<Record<string, unknown>>, thread?: SmoothAgentThread): AsyncGenerator<StreamEvent>;
|
|
255
|
-
/**
|
|
256
|
-
* Invoke the model with bounded retry-with-exponential-backoff.
|
|
257
|
-
*
|
|
258
|
-
* On a transient error (anything the client throws — rate-limit, 5xx, dropped
|
|
259
|
-
* connection) the call is retried up to `maxRetries` additional times, waiting
|
|
260
|
-
* `retryBackoffMs * 2 ** (n - 1)` ms before the n-th (1-indexed) retry. If all
|
|
261
|
-
* attempts fail the LAST error propagates, so the turn fails exactly as it did
|
|
262
|
-
* before retries existed. Only this model call is retried — tool execution is not.
|
|
263
|
-
*/
|
|
264
|
-
private callModel;
|
|
265
|
-
private dispatchTool;
|
|
266
|
-
}
|
|
267
|
-
/**
|
|
268
|
-
* Build a {@link Tool} that delegates a subtask to a child {@link SmoothAgent}.
|
|
269
|
-
*
|
|
270
|
-
* A sub-agent is just a tool backed by another agent: the model calls this tool
|
|
271
|
-
* with a `task` argument, the child agent runs that task, and the child's final
|
|
272
|
-
* reply becomes the tool result — composing with the existing tool loop, no special
|
|
273
|
-
* wiring. The child can have its own instructions, tools, knowledge, etc.
|
|
274
|
-
*/
|
|
275
|
-
export declare function delegateTool(name: string, description: string, child: SmoothAgent, taskProperty?: string): Tool;
|
|
276
|
-
//# sourceMappingURL=agent.d.ts.map
|
package/dist/agent.d.ts.map
DELETED
|
@@ -1 +0,0 @@
|
|
|
1
|
-
{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}
|