@cogitator-ai/types 0.28.0 → 0.30.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 +203 -94
- package/dist/causal.d.ts +6 -0
- package/dist/causal.d.ts.map +1 -1
- package/dist/causal.js.map +1 -1
- package/dist/channel.d.ts +97 -5
- package/dist/channel.d.ts.map +1 -1
- package/dist/errors.d.ts +2 -0
- package/dist/errors.d.ts.map +1 -1
- package/dist/errors.js +4 -0
- package/dist/errors.js.map +1 -1
- package/dist/learning.d.ts +18 -0
- package/dist/learning.d.ts.map +1 -1
- package/dist/learning.js.map +1 -1
- package/dist/llm.d.ts +11 -1
- package/dist/llm.d.ts.map +1 -1
- package/dist/runtime.d.ts +18 -0
- package/dist/runtime.d.ts.map +1 -1
- package/dist/sandbox.d.ts +13 -0
- package/dist/sandbox.d.ts.map +1 -1
- package/dist/session.d.ts +2 -0
- package/dist/session.d.ts.map +1 -1
- package/dist/swarm.d.ts +60 -11
- package/dist/swarm.d.ts.map +1 -1
- package/dist/tool-cache.d.ts +4 -5
- package/dist/tool-cache.d.ts.map +1 -1
- package/dist/workflow.d.ts +14 -4
- package/dist/workflow.d.ts.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -11,6 +11,10 @@ Shared TypeScript types for the Cogitator AI agent runtime.
|
|
|
11
11
|
pnpm add @cogitator-ai/types
|
|
12
12
|
```
|
|
13
13
|
|
|
14
|
+
Types only, plus a few runtime values (`CogitatorError`, `ErrorCode`, `DEFAULT_*` configs). `zod` is a dependency because tool parameters and structured output schemas are Zod types. Most applications get these types re-exported from `@cogitator-ai/core`; install this package directly to implement adapters or stores without the runtime.
|
|
15
|
+
|
|
16
|
+
Reference on the website: [Types API](https://cogitator.app/docs/api-reference/types).
|
|
17
|
+
|
|
14
18
|
## Quick Start
|
|
15
19
|
|
|
16
20
|
```typescript
|
|
@@ -27,20 +31,21 @@ import type {
|
|
|
27
31
|
|
|
28
32
|
## Type Categories
|
|
29
33
|
|
|
30
|
-
| Category | Description
|
|
31
|
-
| ------------------------------------------------- |
|
|
32
|
-
| [Message](#message-types) | Chat messages, tool calls, tool results
|
|
33
|
-
| [Tool](#tool-types) | Tool definitions with Zod schemas
|
|
34
|
-
| [Agent](#agent-types) | Agent configuration and interface
|
|
35
|
-
| [LLM](#llm-types) | LLM backend and provider types
|
|
36
|
-
| [Runtime](#runtime-types) | Cogitator config, run options, results
|
|
37
|
-
| [Errors](#error-types) | Structured error handling
|
|
38
|
-
| [Reflection](#reflection-types) | Self-analyzing agent types
|
|
39
|
-
| [Reasoning](#reasoning-types) | Tree-of-Thought reasoning
|
|
40
|
-
| [Learning](#learning-types) | DSPy-style optimization
|
|
41
|
-
| [Time Travel](#time-travel-types) | Execution debugging
|
|
42
|
-
| [Knowledge Graph](#knowledge-graph-types) | Entity-relationship memory
|
|
43
|
-
| [Prompt Optimization](#prompt-optimization-types) | A/B testing, monitoring, rollback
|
|
34
|
+
| Category | Description |
|
|
35
|
+
| ------------------------------------------------- | ---------------------------------------- |
|
|
36
|
+
| [Message](#message-types) | Chat messages, tool calls, tool results |
|
|
37
|
+
| [Tool](#tool-types) | Tool definitions with Zod schemas |
|
|
38
|
+
| [Agent](#agent-types) | Agent configuration and interface |
|
|
39
|
+
| [LLM](#llm-types) | LLM backend and provider types |
|
|
40
|
+
| [Runtime](#runtime-types) | Cogitator config, run options, results |
|
|
41
|
+
| [Errors](#error-types) | Structured error handling |
|
|
42
|
+
| [Reflection](#reflection-types) | Self-analyzing agent types |
|
|
43
|
+
| [Reasoning](#reasoning-types) | Tree-of-Thought reasoning |
|
|
44
|
+
| [Learning](#learning-types) | DSPy-style optimization |
|
|
45
|
+
| [Time Travel](#time-travel-types) | Execution debugging |
|
|
46
|
+
| [Knowledge Graph](#knowledge-graph-types) | Entity-relationship memory |
|
|
47
|
+
| [Prompt Optimization](#prompt-optimization-types) | A/B testing, monitoring, rollback |
|
|
48
|
+
| [Other Modules](#other-modules) | Workflows, swarms, security, RAG, voice… |
|
|
44
49
|
|
|
45
50
|
---
|
|
46
51
|
|
|
@@ -92,6 +97,7 @@ const toolResult: ToolResultMessage = {
|
|
|
92
97
|
| ------------------- | ------------------------------------------------------------------ |
|
|
93
98
|
| `MessageRole` | `'system' \| 'user' \| 'assistant' \| 'tool'` |
|
|
94
99
|
| `Message` | Base message with role, content, optional name/toolCallId |
|
|
100
|
+
| `MessageContent` | `string` or `ContentPart[]` (text, `image_url`, `image_base64`) |
|
|
95
101
|
| `ToolCallMessage` | Assistant message containing tool calls |
|
|
96
102
|
| `ToolResultMessage` | Tool execution result |
|
|
97
103
|
| `ToolCall` | Tool invocation with id, name, arguments, thoughtSignature, replay |
|
|
@@ -104,7 +110,7 @@ const toolResult: ToolResultMessage = {
|
|
|
104
110
|
Types for defining agent tools with Zod schemas.
|
|
105
111
|
|
|
106
112
|
```typescript
|
|
107
|
-
import type {
|
|
113
|
+
import type { ToolConfig } from '@cogitator-ai/types';
|
|
108
114
|
import { z } from 'zod';
|
|
109
115
|
|
|
110
116
|
// Tool configuration
|
|
@@ -117,7 +123,7 @@ const calculatorConfig: ToolConfig<{ expression: string }, number> = {
|
|
|
117
123
|
}),
|
|
118
124
|
execute: async (params, context) => {
|
|
119
125
|
console.log(`Run ${context.runId} executing calculator`);
|
|
120
|
-
return
|
|
126
|
+
return Number(params.expression);
|
|
121
127
|
},
|
|
122
128
|
timeout: 5000,
|
|
123
129
|
sideEffects: [],
|
|
@@ -127,7 +133,11 @@ const calculatorConfig: ToolConfig<{ expression: string }, number> = {
|
|
|
127
133
|
interface ToolContext {
|
|
128
134
|
agentId: string;
|
|
129
135
|
runId: string;
|
|
130
|
-
signal: AbortSignal;
|
|
136
|
+
signal: AbortSignal; // aborted on run cancel or tool timeout
|
|
137
|
+
threadId?: string;
|
|
138
|
+
userId?: string;
|
|
139
|
+
channelType?: string;
|
|
140
|
+
channelId?: string;
|
|
131
141
|
}
|
|
132
142
|
```
|
|
133
143
|
|
|
@@ -137,22 +147,27 @@ interface ToolContext {
|
|
|
137
147
|
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
|
|
138
148
|
| `ToolConfig<TParams, TResult>` | Tool definition with execute function |
|
|
139
149
|
| `Tool<TParams, TResult>` | Full tool with toJSON() method |
|
|
140
|
-
| `ToolContext` | Execution context with agentId, runId, signal
|
|
150
|
+
| `ToolContext` | Execution context with agentId, runId, signal, threadId, userId, channel |
|
|
151
|
+
| `SideEffectType` | `'filesystem' \| 'network' \| 'database' \| 'process' \| 'external'` |
|
|
152
|
+
| `ApprovalCheck` | `(params) => boolean` form of `requiresApproval` |
|
|
141
153
|
| `ToolSchema` | JSON Schema representation for LLM |
|
|
142
154
|
| `ToolCategory` | `'math' \| 'text' \| 'file' \| 'network' \| 'system' \| 'utility' \| 'web' \| 'database' \| 'communication' \| 'development'` |
|
|
143
155
|
|
|
144
156
|
### Tool Options
|
|
145
157
|
|
|
146
158
|
```typescript
|
|
147
|
-
|
|
159
|
+
import type { ToolConfig } from '@cogitator-ai/types';
|
|
160
|
+
import { z } from 'zod';
|
|
161
|
+
|
|
162
|
+
const advancedTool: ToolConfig<{ path: string; content: string }, void> = {
|
|
148
163
|
name: 'file_write',
|
|
149
164
|
description: 'Write content to a file',
|
|
150
165
|
parameters: z.object({
|
|
151
166
|
path: z.string(),
|
|
152
167
|
content: z.string(),
|
|
153
168
|
}),
|
|
154
|
-
execute: async (
|
|
155
|
-
|
|
169
|
+
execute: async ({ path, content }) => {
|
|
170
|
+
console.log(`Writing ${content.length} chars to ${path}`);
|
|
156
171
|
},
|
|
157
172
|
|
|
158
173
|
// Optional configuration
|
|
@@ -172,7 +187,11 @@ const advancedTool: ToolConfig = {
|
|
|
172
187
|
Types for agent configuration.
|
|
173
188
|
|
|
174
189
|
```typescript
|
|
175
|
-
import type { Agent, AgentConfig, ResponseFormat } from '@cogitator-ai/types';
|
|
190
|
+
import type { Agent, AgentConfig, ResponseFormat, Tool } from '@cogitator-ai/types';
|
|
191
|
+
import { z } from 'zod';
|
|
192
|
+
|
|
193
|
+
declare const calculatorTool: Tool;
|
|
194
|
+
declare const billingAgent: Agent;
|
|
176
195
|
|
|
177
196
|
const config: AgentConfig = {
|
|
178
197
|
name: 'research-agent',
|
|
@@ -191,6 +210,15 @@ const config: AgentConfig = {
|
|
|
191
210
|
|
|
192
211
|
// Response format
|
|
193
212
|
responseFormat: { type: 'json' },
|
|
213
|
+
|
|
214
|
+
// Reasoning effort for reasoning models, in one vocabulary for every provider
|
|
215
|
+
reasoning: { effort: 'medium', summary: true },
|
|
216
|
+
|
|
217
|
+
// Agents this one can hand the conversation to (transfer_to_<name> tools)
|
|
218
|
+
handoffs: [
|
|
219
|
+
billingAgent,
|
|
220
|
+
{ agent: billingAgent, toolName: 'to_billing', description: 'Invoices' },
|
|
221
|
+
],
|
|
194
222
|
};
|
|
195
223
|
|
|
196
224
|
// Response format options
|
|
@@ -202,6 +230,8 @@ const schemaFormat: ResponseFormat = {
|
|
|
202
230
|
};
|
|
203
231
|
```
|
|
204
232
|
|
|
233
|
+
`AgentConfig` also takes `id`, `provider` (an explicit backend name) and `skills` (`Skill` bundles of tools and instructions). `AgentSnapshot` / `SerializedAgentConfig` describe the JSON form of `agent.serialize()`.
|
|
234
|
+
|
|
205
235
|
---
|
|
206
236
|
|
|
207
237
|
## LLM Types
|
|
@@ -211,6 +241,7 @@ Types for LLM backends and providers.
|
|
|
211
241
|
```typescript
|
|
212
242
|
import type {
|
|
213
243
|
LLMProvider,
|
|
244
|
+
LLMBackendProvider,
|
|
214
245
|
LLMConfig,
|
|
215
246
|
LLMBackend,
|
|
216
247
|
ChatRequest,
|
|
@@ -218,6 +249,8 @@ import type {
|
|
|
218
249
|
ChatStreamChunk,
|
|
219
250
|
ChatUsage,
|
|
220
251
|
OpenAIProviderConfig,
|
|
252
|
+
ReasoningConfig,
|
|
253
|
+
PromptCacheConfig,
|
|
221
254
|
} from '@cogitator-ai/types';
|
|
222
255
|
|
|
223
256
|
// Supported providers
|
|
@@ -234,6 +267,10 @@ type LLMProvider =
|
|
|
234
267
|
| 'together'
|
|
235
268
|
| 'deepseek';
|
|
236
269
|
|
|
270
|
+
// What LLMBackend.provider reports: a built-in provider, or the name of your
|
|
271
|
+
// own backend (llm.backends) or of a registered plugin
|
|
272
|
+
type LLMBackendProvider = LLMProvider | (string & {});
|
|
273
|
+
|
|
237
274
|
// LLM configuration
|
|
238
275
|
const llmConfig: LLMConfig = {
|
|
239
276
|
provider: 'openai',
|
|
@@ -272,8 +309,17 @@ const openaiConfig: OpenAIProviderConfig = {
|
|
|
272
309
|
apiKey: process.env.OPENAI_API_KEY!,
|
|
273
310
|
api: 'chat-completions', // force a wire API: 'responses' | 'chat-completions'
|
|
274
311
|
};
|
|
312
|
+
|
|
313
|
+
// Reasoning effort, mapped per provider (Anthropic effort / thinking, OpenAI reasoning.effort, Gemini thinking, Ollama think)
|
|
314
|
+
const reasoning: ReasoningConfig = { effort: 'high', budgetTokens: 8000, summary: true };
|
|
315
|
+
// effort: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'
|
|
316
|
+
|
|
317
|
+
// Prompt caching for agent runs (CogitatorConfig.llm.promptCache)
|
|
318
|
+
const promptCache: PromptCacheConfig = { ttl: '1h' }; // '5m' (default) | '1h'
|
|
275
319
|
```
|
|
276
320
|
|
|
321
|
+
`LLMRetryConfig` (`maxRetries`, `baseDelay`, `maxDelay`, `maxRetryAfter`, `onRetry`) types `CogitatorConfig.llm.retry`; `ModelRoute` is what `cog.route()` resolves a model string to.
|
|
322
|
+
|
|
277
323
|
`ToolCall.replay` (`ToolCallReplayState`) carries opaque provider output that must be sent back with the call on the next turn, such as OpenAI Responses reasoning items. It is JSON-serializable, so it survives memory persistence; backends that did not produce it ignore it.
|
|
278
324
|
|
|
279
325
|
---
|
|
@@ -304,15 +350,23 @@ const config: CogitatorConfig = {
|
|
|
304
350
|
memory: { adapter: 'redis', redis: { host: 'localhost' } },
|
|
305
351
|
sandbox: { defaults: { type: 'docker', image: 'node:20-alpine' } },
|
|
306
352
|
reflection: { enabled: true, reflectAfterError: true },
|
|
353
|
+
security: {
|
|
354
|
+
promptInjection: { action: 'block' },
|
|
355
|
+
pii: { mode: 'mask', custom: [{ type: 'customer_id', pattern: /CUS-\d{6}/ }] },
|
|
356
|
+
},
|
|
357
|
+
prompts: { autoDeployWinner: true }, // versioned instructions and A/B tests
|
|
307
358
|
};
|
|
308
359
|
|
|
309
360
|
// Run options with callbacks
|
|
310
361
|
const runOptions: RunOptions = {
|
|
311
362
|
input: 'Calculate 2 + 2',
|
|
312
|
-
context: {
|
|
363
|
+
context: { plan: 'pro' },
|
|
313
364
|
threadId: 'thread_abc',
|
|
365
|
+
userId: 'user_123', // owns the thread; reaches tools as context.userId
|
|
366
|
+
threadAccess: 'owner', // or 'shared'
|
|
314
367
|
timeout: 30000,
|
|
315
368
|
stream: true,
|
|
369
|
+
reasoning: { effort: 'low' },
|
|
316
370
|
|
|
317
371
|
// Callbacks
|
|
318
372
|
onToken: (token) => process.stdout.write(token),
|
|
@@ -322,17 +376,37 @@ const runOptions: RunOptions = {
|
|
|
322
376
|
onRunComplete: (result) => console.log('Done:', result.output),
|
|
323
377
|
onRunError: (error) => console.error('Error:', error),
|
|
324
378
|
onSpan: (span) => console.log('Span:', span.name),
|
|
379
|
+
onReasoning: (delta) => process.stdout.write(delta),
|
|
380
|
+
onHandoff: (handoff) => console.log(`${handoff.from} -> ${handoff.to}`),
|
|
381
|
+
onApproval: (request) => (request.toolName === 'refund' ? 'pause' : { approved: true }),
|
|
325
382
|
|
|
326
383
|
// Memory options
|
|
327
384
|
useMemory: true,
|
|
328
385
|
loadHistory: true,
|
|
329
386
|
saveHistory: true,
|
|
387
|
+
parallelToolCalls: false,
|
|
330
388
|
};
|
|
331
389
|
```
|
|
332
390
|
|
|
391
|
+
### Approvals, Handoffs and Pauses
|
|
392
|
+
|
|
393
|
+
| Type | Description |
|
|
394
|
+
| ---------------------- | ------------------------------------------------------------------------------------------------------- |
|
|
395
|
+
| `ToolApprovalRequest` | A tool call waiting for a decision: `toolCallId`, `toolName`, `arguments`, `description`, `sideEffects` |
|
|
396
|
+
| `ToolApprovalDecision` | `{ approved: true }` or `{ approved: false; reason? }` |
|
|
397
|
+
| `RunCheckpoint` | JSON snapshot of a paused run, passed to `cogitator.resume()` |
|
|
398
|
+
| `RunCheckpointStore` | `save` / `load(threadId)` / `delete` for paused runs (`CogitatorConfig.runCheckpoints`) |
|
|
399
|
+
| `ResumeOptions` | Run options for `resume()` plus `userId`, `decisions` and `defaultDecision` |
|
|
400
|
+
| `HandoffEvent` | `{ from, to, reason? }` for each handoff |
|
|
401
|
+
| `PromptsConfig` | `versions` / `abTests` stores, `score`, `autoDeployWinner` |
|
|
402
|
+
| `RunPrompt` | The instruction version or A/B variant a run used |
|
|
403
|
+
| `PiiConfig` | `mode` (`mask` \| `redact` \| `block`), `detect`, `custom`, `onDetect` |
|
|
404
|
+
|
|
333
405
|
### RunResult
|
|
334
406
|
|
|
335
407
|
```typescript
|
|
408
|
+
import type { RunResult } from '@cogitator-ai/types';
|
|
409
|
+
|
|
336
410
|
const result: RunResult = {
|
|
337
411
|
output: 'The answer is 4',
|
|
338
412
|
structured: { answer: 4 }, // if responseFormat was json_schema
|
|
@@ -347,16 +421,17 @@ const result: RunResult = {
|
|
|
347
421
|
duration: 1500,
|
|
348
422
|
},
|
|
349
423
|
toolCalls: [{ id: 'call_1', name: 'calculator', arguments: { expression: '2+2' } }],
|
|
350
|
-
messages: [
|
|
424
|
+
messages: [],
|
|
351
425
|
trace: {
|
|
352
426
|
traceId: 'trace_abc',
|
|
353
|
-
spans: [
|
|
427
|
+
spans: [],
|
|
354
428
|
},
|
|
355
|
-
|
|
356
|
-
reflectionSummary: {/* summary stats */},
|
|
429
|
+
status: 'completed', // 'paused' when tool calls wait for approval
|
|
357
430
|
};
|
|
358
431
|
```
|
|
359
432
|
|
|
433
|
+
Optional fields: `structured`, `modelUsed`, `usage.reasoningTokens` / `cachedInputTokens` / `cacheWriteTokens`, `reasoning`, `prompt`, `handoffs`, `finalAgent`, `status`, `pendingApprovals`, `checkpoint`, `reflections`, `reflectionSummary`. All fields are `readonly`.
|
|
434
|
+
|
|
360
435
|
---
|
|
361
436
|
|
|
362
437
|
## Error Types
|
|
@@ -393,23 +468,28 @@ const wrapped = CogitatorError.wrap(new Error('timeout'), ErrorCode.LLM_TIMEOUT)
|
|
|
393
468
|
|
|
394
469
|
// Check if retryable
|
|
395
470
|
if (isRetryableError(error)) {
|
|
396
|
-
const delay = getRetryDelay(error, 1000);
|
|
397
|
-
await
|
|
471
|
+
const delay = getRetryDelay(error, 1000); // retryAfter, or the default
|
|
472
|
+
await new Promise((resolve) => setTimeout(resolve, delay));
|
|
398
473
|
}
|
|
474
|
+
|
|
475
|
+
console.log(ERROR_STATUS_CODES[ErrorCode.LLM_RATE_LIMITED]); // 429
|
|
399
476
|
```
|
|
400
477
|
|
|
401
478
|
### Error Codes
|
|
402
479
|
|
|
403
|
-
| Domain | Codes
|
|
404
|
-
| -------- |
|
|
405
|
-
| LLM | `LLM_UNAVAILABLE`, `LLM_RATE_LIMITED`, `LLM_TIMEOUT`, `LLM_INVALID_RESPONSE`, `LLM_CONTEXT_LENGTH_EXCEEDED`, `LLM_CONTENT_FILTERED`
|
|
406
|
-
| Sandbox | `SANDBOX_UNAVAILABLE`, `SANDBOX_TIMEOUT`, `SANDBOX_OOM`, `SANDBOX_EXECUTION_FAILED`, `SANDBOX_INVALID_MODULE`
|
|
407
|
-
| Tool | `TOOL_NOT_FOUND`, `TOOL_INVALID_ARGS`, `TOOL_EXECUTION_FAILED`, `TOOL_TIMEOUT`
|
|
408
|
-
| Memory | `MEMORY_UNAVAILABLE`, `MEMORY_WRITE_FAILED`, `MEMORY_READ_FAILED`
|
|
409
|
-
| Agent | `AGENT_NOT_FOUND`, `AGENT_ALREADY_RUNNING`, `AGENT_MAX_ITERATIONS`
|
|
410
|
-
| Workflow | `WORKFLOW_NOT_FOUND`, `WORKFLOW_STEP_FAILED`, `WORKFLOW_CYCLE_DETECTED`
|
|
411
|
-
| Swarm | `SWARM_NO_WORKERS`, `SWARM_CONSENSUS_FAILED`
|
|
412
|
-
|
|
|
480
|
+
| Domain | Codes |
|
|
481
|
+
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
482
|
+
| LLM | `LLM_UNAVAILABLE`, `LLM_RATE_LIMITED`, `LLM_TIMEOUT`, `LLM_INVALID_RESPONSE`, `LLM_CONTEXT_LENGTH_EXCEEDED`, `LLM_CONTENT_FILTERED` |
|
|
483
|
+
| Sandbox | `SANDBOX_UNAVAILABLE`, `SANDBOX_TIMEOUT`, `SANDBOX_OOM`, `SANDBOX_EXECUTION_FAILED`, `SANDBOX_INVALID_MODULE` |
|
|
484
|
+
| Tool | `TOOL_NOT_FOUND`, `TOOL_INVALID_ARGS`, `TOOL_EXECUTION_FAILED`, `TOOL_TIMEOUT` |
|
|
485
|
+
| Memory | `MEMORY_UNAVAILABLE`, `MEMORY_WRITE_FAILED`, `MEMORY_READ_FAILED`, `THREAD_ACCESS_DENIED` |
|
|
486
|
+
| Agent | `AGENT_NOT_FOUND`, `AGENT_ALREADY_RUNNING`, `AGENT_MAX_ITERATIONS`, `RUN_TOKEN_LIMIT_EXCEEDED`, `RUN_NOT_PAUSED`, `RUN_TIMEOUT`, `BUDGET_EXCEEDED` |
|
|
487
|
+
| Workflow | `WORKFLOW_NOT_FOUND`, `WORKFLOW_STEP_FAILED`, `WORKFLOW_CYCLE_DETECTED` |
|
|
488
|
+
| Swarm | `SWARM_NO_WORKERS`, `SWARM_CONSENSUS_FAILED` |
|
|
489
|
+
| Security | `PROMPT_INJECTION_DETECTED`, `PII_DETECTED` |
|
|
490
|
+
| General | `VALIDATION_ERROR`, `CONFIGURATION_ERROR`, `INTERNAL_ERROR`, `NOT_IMPLEMENTED`, `CIRCUIT_OPEN` |
|
|
491
|
+
|
|
492
|
+
The runtime throws `RUN_TIMEOUT` (HTTP 504) for a run that hits its timeout (`Run timed out after <n>ms`), `BUDGET_EXCEEDED` (429) for a run over its cost-routing budget, and `LLM_CONTENT_FILTERED` (400) when guardrails block the input or output (`Input blocked: …` / `Output blocked: …`).
|
|
413
493
|
|
|
414
494
|
---
|
|
415
495
|
|
|
@@ -500,14 +580,14 @@ import type {
|
|
|
500
580
|
// ToT configuration
|
|
501
581
|
const totConfig: ToTConfig = {
|
|
502
582
|
branchFactor: 3, // Generate 3 candidate thoughts per step
|
|
503
|
-
beamWidth: 2, //
|
|
583
|
+
beamWidth: 2, // Queue the best 2 candidates per expanded node
|
|
504
584
|
maxDepth: 5, // Max reasoning depth
|
|
505
585
|
explorationStrategy: 'beam', // 'beam' | 'best-first' | 'dfs'
|
|
506
586
|
|
|
507
587
|
confidenceThreshold: 0.3,
|
|
508
588
|
terminationConfidence: 0.8,
|
|
509
589
|
maxTotalNodes: 50,
|
|
510
|
-
maxIterationsPerBranch: 3,
|
|
590
|
+
maxIterationsPerBranch: 3, // Iteration cap for each branch run
|
|
511
591
|
|
|
512
592
|
// Callbacks
|
|
513
593
|
onBranchGenerated: (node, branches) => console.log('Generated:', branches.length),
|
|
@@ -527,6 +607,8 @@ const branch: ThoughtBranch = {
|
|
|
527
607
|
};
|
|
528
608
|
```
|
|
529
609
|
|
|
610
|
+
`beam` runs the tree level by level, `best-first` runs the node whose own branch scored highest, and `dfs` goes deep first; candidates beyond `beamWidth` wait as pending alternatives for backtracking. `maxTotalNodes` caps executed nodes, and `maxIterationsPerBranch` caps each branch run (never above the agent's own `maxIterations`).
|
|
611
|
+
|
|
530
612
|
---
|
|
531
613
|
|
|
532
614
|
## Learning Types
|
|
@@ -547,12 +629,15 @@ import type {
|
|
|
547
629
|
const learningConfig: LearningConfig = {
|
|
548
630
|
enabled: true,
|
|
549
631
|
captureTraces: true,
|
|
550
|
-
|
|
551
|
-
optimizeAfterRuns: 10,
|
|
632
|
+
traceRetention: 1000,
|
|
552
633
|
maxDemosPerAgent: 5,
|
|
553
634
|
minScoreForDemo: 0.8,
|
|
554
635
|
defaultMetrics: ['success', 'tool_accuracy', 'efficiency'],
|
|
636
|
+
customMetrics: [
|
|
637
|
+
{ name: 'tool_accuracy', type: 'numeric', description: 'Tools worked', weight: 0.5 },
|
|
638
|
+
],
|
|
555
639
|
};
|
|
640
|
+
// autoOptimize, optimizeAfterRuns and traceStore are deprecated and not read
|
|
556
641
|
|
|
557
642
|
// Optimizer configuration
|
|
558
643
|
const optimizerConfig: OptimizerConfig = {
|
|
@@ -618,7 +703,7 @@ const checkpoint: ExecutionCheckpoint = {
|
|
|
618
703
|
runId: 'run_789',
|
|
619
704
|
agentId: 'agent_abc',
|
|
620
705
|
stepIndex: 5,
|
|
621
|
-
messages: [
|
|
706
|
+
messages: [],
|
|
622
707
|
toolResults: { call_1: 42, call_2: 'result' },
|
|
623
708
|
pendingToolCalls: [],
|
|
624
709
|
label: 'before-critical-decision',
|
|
@@ -649,18 +734,17 @@ const diff: TraceDiff = {
|
|
|
649
734
|
stepDiffs: [
|
|
650
735
|
{ index: 0, status: 'identical' },
|
|
651
736
|
{ index: 1, status: 'similar', differences: ['different tool args'] },
|
|
652
|
-
{
|
|
653
|
-
index: 2,
|
|
654
|
-
status: 'different',
|
|
655
|
-
step1: {/* ... */},
|
|
656
|
-
step2: {/* ... */},
|
|
657
|
-
},
|
|
737
|
+
{ index: 2, status: 'different' }, // step1 / step2 hold the ExecutionSteps
|
|
658
738
|
],
|
|
739
|
+
commonSteps: 2,
|
|
659
740
|
divergencePoint: 2,
|
|
741
|
+
trace1OnlySteps: 1,
|
|
742
|
+
trace2OnlySteps: 0,
|
|
660
743
|
metricsDiff: {
|
|
661
744
|
success: { trace1: true, trace2: false },
|
|
662
745
|
score: { trace1: 0.9, trace2: 0.6, delta: -0.3 },
|
|
663
|
-
|
|
746
|
+
tokens: { trace1: 1200, trace2: 1500, delta: 300 },
|
|
747
|
+
duration: { trace1: 2100, trace2: 2600, delta: 500 },
|
|
664
748
|
},
|
|
665
749
|
};
|
|
666
750
|
```
|
|
@@ -669,7 +753,7 @@ const diff: TraceDiff = {
|
|
|
669
753
|
|
|
670
754
|
## Memory Types
|
|
671
755
|
|
|
672
|
-
See [@cogitator-ai/memory](
|
|
756
|
+
See [@cogitator-ai/memory](https://www.npmjs.com/package/@cogitator-ai/memory) for detailed memory adapter types.
|
|
673
757
|
|
|
674
758
|
---
|
|
675
759
|
|
|
@@ -687,25 +771,13 @@ import type {
|
|
|
687
771
|
TraversalOptions,
|
|
688
772
|
TraversalResult,
|
|
689
773
|
GraphPath,
|
|
690
|
-
|
|
774
|
+
ExtractionResult,
|
|
691
775
|
InferredEdge,
|
|
692
776
|
} from '@cogitator-ai/types';
|
|
693
777
|
|
|
694
|
-
//
|
|
695
|
-
|
|
696
|
-
|
|
697
|
-
// Relationship types
|
|
698
|
-
type RelationType =
|
|
699
|
-
| 'knows'
|
|
700
|
-
| 'works_at'
|
|
701
|
-
| 'located_in'
|
|
702
|
-
| 'part_of'
|
|
703
|
-
| 'related_to'
|
|
704
|
-
| 'created_by'
|
|
705
|
-
| 'owns'
|
|
706
|
-
| 'member_of'
|
|
707
|
-
| 'causes'
|
|
708
|
-
| 'depends_on';
|
|
778
|
+
// EntityType: 'person' | 'organization' | 'location' | 'concept' | 'event' | 'object' | 'custom'
|
|
779
|
+
// RelationType: 'knows' | 'works_at' | 'located_in' | 'part_of' | 'related_to' | 'created_by'
|
|
780
|
+
// | 'belongs_to' | 'associated_with' | 'causes' | 'precedes' | 'custom'
|
|
709
781
|
|
|
710
782
|
// Graph node
|
|
711
783
|
const node: GraphNode = {
|
|
@@ -716,10 +788,13 @@ const node: GraphNode = {
|
|
|
716
788
|
aliases: ['alice_dev'],
|
|
717
789
|
description: 'Software engineer',
|
|
718
790
|
properties: { role: 'developer', team: 'platform' },
|
|
719
|
-
embedding: [0.1, 0.2,
|
|
791
|
+
embedding: [0.1, 0.2, 0.3],
|
|
720
792
|
confidence: 1.0,
|
|
721
|
-
source: 'extracted',
|
|
793
|
+
source: 'extracted', // 'extracted' | 'user' | 'inferred'
|
|
722
794
|
createdAt: new Date(),
|
|
795
|
+
updatedAt: new Date(),
|
|
796
|
+
lastAccessedAt: new Date(),
|
|
797
|
+
accessCount: 0,
|
|
723
798
|
};
|
|
724
799
|
|
|
725
800
|
// Graph edge
|
|
@@ -736,26 +811,28 @@ const edge: GraphEdge = {
|
|
|
736
811
|
source: 'extracted',
|
|
737
812
|
properties: { since: '2020' },
|
|
738
813
|
createdAt: new Date(),
|
|
814
|
+
updatedAt: new Date(),
|
|
739
815
|
};
|
|
740
816
|
|
|
741
817
|
// Traversal options
|
|
742
818
|
const traversalOptions: TraversalOptions = {
|
|
819
|
+
agentId: 'agent-1',
|
|
743
820
|
startNodeId: 'node_123',
|
|
744
821
|
maxDepth: 3,
|
|
745
|
-
direction: 'outgoing',
|
|
822
|
+
direction: 'outgoing', // 'outgoing' | 'incoming' | 'both'
|
|
746
823
|
edgeTypes: ['works_at', 'knows'],
|
|
747
|
-
|
|
824
|
+
minEdgeWeight: 0.5,
|
|
748
825
|
minConfidence: 0.7,
|
|
749
|
-
|
|
826
|
+
limit: 100,
|
|
750
827
|
};
|
|
751
828
|
|
|
752
829
|
// Traversal result
|
|
830
|
+
const path: GraphPath = { nodes: [node], edges: [edge], totalWeight: 1.0, length: 1 };
|
|
753
831
|
const result: TraversalResult = {
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
|
|
758
|
-
maxDepthReached: 3,
|
|
832
|
+
paths: [path],
|
|
833
|
+
visitedNodes: [node],
|
|
834
|
+
visitedEdges: [edge],
|
|
835
|
+
depth: 1,
|
|
759
836
|
};
|
|
760
837
|
```
|
|
761
838
|
|
|
@@ -785,17 +862,26 @@ const prompt: CapturedPrompt = {
|
|
|
785
862
|
id: 'prompt_123',
|
|
786
863
|
runId: 'run_456',
|
|
787
864
|
agentId: 'agent-1',
|
|
865
|
+
threadId: 'thread_789',
|
|
788
866
|
model: 'gpt-6.1-sol',
|
|
867
|
+
provider: 'openai',
|
|
868
|
+
timestamp: new Date(),
|
|
789
869
|
systemPrompt: 'You are a helpful assistant.',
|
|
790
870
|
messages: [{ role: 'user', content: 'Hello' }],
|
|
791
|
-
tools: [
|
|
871
|
+
tools: [
|
|
872
|
+
{
|
|
873
|
+
name: 'calculator',
|
|
874
|
+
description: 'Evaluate math',
|
|
875
|
+
parameters: { type: 'object', properties: {} },
|
|
876
|
+
},
|
|
877
|
+
],
|
|
792
878
|
promptTokens: 150,
|
|
793
879
|
response: {
|
|
794
880
|
content: 'Hi there!',
|
|
795
881
|
completionTokens: 10,
|
|
882
|
+
finishReason: 'stop',
|
|
796
883
|
latencyMs: 450,
|
|
797
884
|
},
|
|
798
|
-
createdAt: new Date(),
|
|
799
885
|
};
|
|
800
886
|
|
|
801
887
|
// A/B test
|
|
@@ -812,8 +898,22 @@ const abTest: ABTest = {
|
|
|
812
898
|
maxDuration: 7 * 24 * 60 * 60 * 1000,
|
|
813
899
|
confidenceLevel: 0.95,
|
|
814
900
|
metricToOptimize: 'score',
|
|
815
|
-
controlResults: {
|
|
816
|
-
|
|
901
|
+
controlResults: {
|
|
902
|
+
sampleSize: 50,
|
|
903
|
+
successRate: 0.9,
|
|
904
|
+
avgScore: 0.82,
|
|
905
|
+
avgLatency: 900,
|
|
906
|
+
totalCost: 0.4,
|
|
907
|
+
scores: [],
|
|
908
|
+
},
|
|
909
|
+
treatmentResults: {
|
|
910
|
+
sampleSize: 48,
|
|
911
|
+
successRate: 0.94,
|
|
912
|
+
avgScore: 0.87,
|
|
913
|
+
avgLatency: 850,
|
|
914
|
+
totalCost: 0.38,
|
|
915
|
+
scores: [],
|
|
916
|
+
},
|
|
817
917
|
createdAt: new Date(),
|
|
818
918
|
startedAt: new Date(),
|
|
819
919
|
};
|
|
@@ -837,7 +937,7 @@ const version: InstructionVersion = {
|
|
|
837
937
|
source: 'optimization',
|
|
838
938
|
sourceId: 'opt-run-456',
|
|
839
939
|
deployedAt: new Date(),
|
|
840
|
-
metrics: { runCount: 100, avgScore: 0.88, successRate: 0.95 },
|
|
940
|
+
metrics: { runCount: 100, avgScore: 0.88, successRate: 0.95, avgLatency: 1200, totalCost: 1.4 },
|
|
841
941
|
};
|
|
842
942
|
|
|
843
943
|
// Degradation alert
|
|
@@ -858,17 +958,26 @@ const alert: DegradationAlert = {
|
|
|
858
958
|
|
|
859
959
|
---
|
|
860
960
|
|
|
861
|
-
##
|
|
862
|
-
|
|
863
|
-
|
|
864
|
-
|
|
865
|
-
|
|
866
|
-
|
|
867
|
-
|
|
868
|
-
|
|
869
|
-
|
|
870
|
-
|
|
871
|
-
|
|
961
|
+
## Other Modules
|
|
962
|
+
|
|
963
|
+
Every module below is exported from the package root; the owning package documents how the types are used.
|
|
964
|
+
|
|
965
|
+
| Module | Main types | Used by |
|
|
966
|
+
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
|
|
967
|
+
| Memory | `MemoryAdapter`, `MemoryResult`, `Thread`, `MemoryEntry`, `Fact`, `Embedding`, `EmbeddingService`, `ContextBuilderConfig`, `MemoryConfig` | [@cogitator-ai/memory](https://www.npmjs.com/package/@cogitator-ai/memory) |
|
|
968
|
+
| Sandbox | `SandboxConfig`, `SandboxManagerConfig` (`allowNativeFallback`, default `true`: Docker-sandboxed commands run on the host when Docker is unavailable), `SandboxPoolConfig` (`reuseContainers`, default `false`: every execution gets a fresh container), `SandboxWasmConfig` (`memoryPages` caps the module's own memory), `SandboxExecutionRequest` | [@cogitator-ai/sandbox](https://www.npmjs.com/package/@cogitator-ai/sandbox) |
|
|
969
|
+
| Workflow | `WorkflowState`, `Workflow`, `CheckpointStore`, `RunStore`, `ApprovalStore`, `TimerStore` (optional `claimTtl`, `renew`, `release`), `WorkflowRunStats` | [@cogitator-ai/workflows](https://www.npmjs.com/package/@cogitator-ai/workflows) |
|
|
970
|
+
| Swarm, negotiation | `SwarmConfig`, `SwarmStrategy`, `SwarmResult`, negotiation types | [@cogitator-ai/swarms](https://www.npmjs.com/package/@cogitator-ai/swarms) |
|
|
971
|
+
| Constitutional, security | `GuardrailConfig`, `Constitution`, `PromptInjectionConfig`, `PiiConfig`, `PiiType` | `@cogitator-ai/core` |
|
|
972
|
+
| Cost routing, context, tool cache | `CostRoutingConfig`, `BudgetConfig`, `ContextManagerConfig`, `ToolCacheConfig`, `RedisClientLike` (an ioredis client fits) | `@cogitator-ai/core` |
|
|
973
|
+
| Causal | `CausalGraph`, `StructuralEquation` (`custom` type with a `customFn` expression), `InterventionQuery`, `CounterfactualQuery`, `CausalReasoningConfig` | `@cogitator-ai/core` |
|
|
974
|
+
| Neuro-symbolic | `NeuroSymbolicConfig`, `ResolvedNeuroSymbolicConfig` (every section present, returned by `getConfig()`) | [@cogitator-ai/neuro-symbolic](https://www.npmjs.com/package/@cogitator-ai/neuro-symbolic) |
|
|
975
|
+
| Self-modifying | `SelfModifyingConfig`, generated tool and architecture types | [@cogitator-ai/self-modifying](https://www.npmjs.com/package/@cogitator-ai/self-modifying) |
|
|
976
|
+
| Channel gateway | `GatewayConfig`, `ChannelMessage`, `HookRegistry`, `HookPayloads` (each hook name's payload: `MessageReceivedEvent`, `AgentErrorEvent`, `ApprovalResolvedEvent`, …) | [@cogitator-ai/channels](https://www.npmjs.com/package/@cogitator-ai/channels) |
|
|
977
|
+
| RAG, voice, browser, session, deploy | `RAGPipelineConfig`, voice/STT/TTS types, browser session types, session types, `DeployConfig` | the package of the same name |
|
|
978
|
+
| Skills, logging | `Skill`, `SkillConfig`, `LoggingConfig` (`level` up to `'silent'`, `destination: 'file'` with `filePath`) | `@cogitator-ai/core` |
|
|
979
|
+
|
|
980
|
+
`HookPayloads` types gateway hooks by name: `HookRegistry.on('agent:error', ({ error, threadId }) => …)` gets an `AgentErrorEvent` (`error` is always an `Error`), and `HookName` is `keyof HookPayloads`. A handler typed `HookHandler` (`unknown` payload) is accepted for any hook. `GatewayConfig.owner` is deprecated: owners are set on `ownerCommands({ ownerIds })` and `dmPolicy({ ownerIds })`.
|
|
872
981
|
|
|
873
982
|
---
|
|
874
983
|
|
package/dist/causal.d.ts
CHANGED
|
@@ -13,6 +13,12 @@ export interface StructuralEquation {
|
|
|
13
13
|
type: EquationType;
|
|
14
14
|
coefficients?: Record<string, number>;
|
|
15
15
|
intercept?: number;
|
|
16
|
+
/**
|
|
17
|
+
* The `custom` equation: an arithmetic expression over the parent node ids,
|
|
18
|
+
* such as `2 * price - log(demand) + max(stock, 1)`, with `+ - * / ^`,
|
|
19
|
+
* parentheses and `abs exp log sqrt pow min max tanh sigmoid`. Like the
|
|
20
|
+
* `linear` and `polynomial` types, noise is added to its value.
|
|
21
|
+
*/
|
|
16
22
|
customFn?: string;
|
|
17
23
|
noiseDistribution?: 'gaussian' | 'uniform' | 'bernoulli';
|
|
18
24
|
noiseParams?: Record<string, number>;
|