@cogitator-ai/core 0.10.0 → 0.11.1

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.
Files changed (41) hide show
  1. package/dist/agent.d.ts +52 -2
  2. package/dist/agent.d.ts.map +1 -1
  3. package/dist/agent.js +52 -2
  4. package/dist/agent.js.map +1 -1
  5. package/dist/cogitator/index.d.ts +6 -0
  6. package/dist/cogitator/index.d.ts.map +1 -0
  7. package/dist/cogitator/index.js +6 -0
  8. package/dist/cogitator/index.js.map +1 -0
  9. package/dist/cogitator/initializers.d.ts +54 -0
  10. package/dist/cogitator/initializers.d.ts.map +1 -0
  11. package/dist/cogitator/initializers.js +126 -0
  12. package/dist/cogitator/initializers.js.map +1 -0
  13. package/dist/cogitator/message-builder.d.ts +10 -0
  14. package/dist/cogitator/message-builder.d.ts.map +1 -0
  15. package/dist/cogitator/message-builder.js +72 -0
  16. package/dist/cogitator/message-builder.js.map +1 -0
  17. package/dist/cogitator/span-factory.d.ts +4 -0
  18. package/dist/cogitator/span-factory.d.ts.map +1 -0
  19. package/dist/cogitator/span-factory.js +27 -0
  20. package/dist/cogitator/span-factory.js.map +1 -0
  21. package/dist/cogitator/streaming.d.ts +16 -0
  22. package/dist/cogitator/streaming.d.ts.map +1 -0
  23. package/dist/cogitator/streaming.js +52 -0
  24. package/dist/cogitator/streaming.js.map +1 -0
  25. package/dist/cogitator/tool-executor.d.ts +7 -0
  26. package/dist/cogitator/tool-executor.d.ts.map +1 -0
  27. package/dist/cogitator/tool-executor.js +146 -0
  28. package/dist/cogitator/tool-executor.js.map +1 -0
  29. package/dist/cogitator.d.ts +142 -82
  30. package/dist/cogitator.d.ts.map +1 -1
  31. package/dist/cogitator.js +205 -513
  32. package/dist/cogitator.js.map +1 -1
  33. package/dist/registry.d.ts +64 -2
  34. package/dist/registry.d.ts.map +1 -1
  35. package/dist/registry.js +64 -2
  36. package/dist/registry.js.map +1 -1
  37. package/dist/tool.d.ts +48 -5
  38. package/dist/tool.d.ts.map +1 -1
  39. package/dist/tool.js +48 -5
  40. package/dist/tool.js.map +1 -1
  41. package/package.json +2 -2
@@ -0,0 +1,146 @@
1
+ import { getLogger } from '../logger';
2
+ export async function executeTool(registry, toolCall, runId, agentId, sandboxManager, constitutionalAI, filterToolCalls, initializeSandbox, signal) {
3
+ const tool = registry.get(toolCall.name);
4
+ if (!tool) {
5
+ return {
6
+ callId: toolCall.id,
7
+ name: toolCall.name,
8
+ result: null,
9
+ error: `Tool not found: ${toolCall.name}`,
10
+ };
11
+ }
12
+ const parseResult = tool.parameters.safeParse(toolCall.arguments);
13
+ if (!parseResult.success) {
14
+ return {
15
+ callId: toolCall.id,
16
+ name: toolCall.name,
17
+ result: null,
18
+ error: `Invalid arguments: ${parseResult.error.message}`,
19
+ };
20
+ }
21
+ if (constitutionalAI && filterToolCalls) {
22
+ const context = {
23
+ agentId,
24
+ runId,
25
+ signal: signal ?? new AbortController().signal,
26
+ };
27
+ const guardResult = await constitutionalAI.guardTool(tool, toolCall.arguments, context);
28
+ if (!guardResult.approved) {
29
+ return {
30
+ callId: toolCall.id,
31
+ name: toolCall.name,
32
+ result: null,
33
+ error: `Tool blocked: ${guardResult.reason ?? 'Policy violation'}`,
34
+ };
35
+ }
36
+ }
37
+ if (tool.sandbox?.type === 'docker' || tool.sandbox?.type === 'wasm') {
38
+ return executeInSandbox(tool, toolCall, runId, agentId, sandboxManager, initializeSandbox);
39
+ }
40
+ const context = {
41
+ agentId,
42
+ runId,
43
+ signal: signal ?? new AbortController().signal,
44
+ };
45
+ try {
46
+ const result = await tool.execute(parseResult.data, context);
47
+ return {
48
+ callId: toolCall.id,
49
+ name: toolCall.name,
50
+ result,
51
+ };
52
+ }
53
+ catch (error) {
54
+ return {
55
+ callId: toolCall.id,
56
+ name: toolCall.name,
57
+ result: null,
58
+ error: error instanceof Error ? error.message : String(error),
59
+ };
60
+ }
61
+ }
62
+ async function executeInSandbox(tool, toolCall, runId, agentId, sandboxManager, initializeSandbox) {
63
+ await initializeSandbox();
64
+ if (!sandboxManager) {
65
+ getLogger().warn('Sandbox unavailable, executing natively', { tool: tool.name });
66
+ const context = {
67
+ agentId,
68
+ runId,
69
+ signal: new AbortController().signal,
70
+ };
71
+ try {
72
+ const result = await tool.execute(toolCall.arguments, context);
73
+ return { callId: toolCall.id, name: toolCall.name, result };
74
+ }
75
+ catch (error) {
76
+ return {
77
+ callId: toolCall.id,
78
+ name: toolCall.name,
79
+ result: null,
80
+ error: error instanceof Error ? error.message : String(error),
81
+ };
82
+ }
83
+ }
84
+ const args = toolCall.arguments;
85
+ const sandboxConfig = tool.sandbox;
86
+ const isWasm = sandboxConfig.type === 'wasm';
87
+ const request = isWasm
88
+ ? {
89
+ command: [],
90
+ stdin: JSON.stringify(args),
91
+ timeout: tool.timeout,
92
+ }
93
+ : {
94
+ command: ['sh', '-c', String(args.command ?? '')],
95
+ cwd: args.cwd,
96
+ env: args.env,
97
+ timeout: tool.timeout,
98
+ };
99
+ const result = await sandboxManager.execute(request, sandboxConfig);
100
+ if (!result.success) {
101
+ return {
102
+ callId: toolCall.id,
103
+ name: toolCall.name,
104
+ result: null,
105
+ error: result.error,
106
+ };
107
+ }
108
+ if (isWasm) {
109
+ try {
110
+ const parsed = JSON.parse(result.data.stdout);
111
+ return {
112
+ callId: toolCall.id,
113
+ name: toolCall.name,
114
+ result: parsed,
115
+ };
116
+ }
117
+ catch {
118
+ return {
119
+ callId: toolCall.id,
120
+ name: toolCall.name,
121
+ result: result.data.stdout,
122
+ };
123
+ }
124
+ }
125
+ return {
126
+ callId: toolCall.id,
127
+ name: toolCall.name,
128
+ result: {
129
+ stdout: result.data.stdout,
130
+ stderr: result.data.stderr,
131
+ exitCode: result.data.exitCode,
132
+ timedOut: result.data.timedOut,
133
+ duration: result.data.duration,
134
+ command: args.command,
135
+ },
136
+ };
137
+ }
138
+ export function createToolMessage(toolCall, result) {
139
+ return {
140
+ role: 'tool',
141
+ content: JSON.stringify(result.result),
142
+ toolCallId: toolCall.id,
143
+ name: toolCall.name,
144
+ };
145
+ }
146
+ //# sourceMappingURL=tool-executor.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tool-executor.js","sourceRoot":"","sources":["../../src/cogitator/tool-executor.ts"],"names":[],"mappings":"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"}
@@ -1,113 +1,173 @@
1
- /**
2
- * Cogitator - Main runtime class
3
- */
4
1
  import type { CogitatorConfig, RunOptions, RunResult, Constitution, CostSummary } from '@cogitator-ai/types';
5
2
  import { type Agent } from './agent';
6
3
  import { ToolRegistry } from './registry';
7
- import { ConstitutionalAI } from './constitutional/index';
8
- import { CostAwareRouter } from './cost-routing/index';
4
+ /**
5
+ * Main runtime for executing AI agents.
6
+ *
7
+ * Cogitator orchestrates agent execution with support for:
8
+ * - Multiple LLM providers (OpenAI, Anthropic, Ollama, Google, Azure, etc.)
9
+ * - Memory persistence (Redis, PostgreSQL, in-memory)
10
+ * - Sandboxed tool execution (Docker, WASM)
11
+ * - Reflection and learning from past runs
12
+ * - Constitutional AI guardrails
13
+ * - Cost-aware model routing
14
+ *
15
+ * @example Basic usage
16
+ * ```ts
17
+ * import { Cogitator, Agent } from '@cogitator-ai/core';
18
+ *
19
+ * const cog = new Cogitator({
20
+ * llm: { defaultProvider: 'anthropic' },
21
+ * });
22
+ *
23
+ * const agent = new Agent({
24
+ * name: 'assistant',
25
+ * model: 'anthropic/claude-sonnet-4-20250514',
26
+ * instructions: 'You are a helpful assistant.',
27
+ * });
28
+ *
29
+ * const result = await cog.run(agent, { input: 'Hello!' });
30
+ * console.log(result.output);
31
+ *
32
+ * await cog.close();
33
+ * ```
34
+ *
35
+ * @example With memory and streaming
36
+ * ```ts
37
+ * const cog = new Cogitator({
38
+ * memory: {
39
+ * adapter: 'redis',
40
+ * redis: { url: 'redis://localhost:6379' },
41
+ * },
42
+ * });
43
+ *
44
+ * const result = await cog.run(agent, {
45
+ * input: 'Remember my name is Alice',
46
+ * threadId: 'conversation-123',
47
+ * stream: true,
48
+ * onToken: (token) => process.stdout.write(token),
49
+ * });
50
+ * ```
51
+ */
9
52
  export declare class Cogitator {
10
53
  private config;
11
54
  private backends;
55
+ /** Global tool registry shared across all runs */
12
56
  readonly tools: ToolRegistry;
13
- private memoryAdapter?;
14
- private contextBuilder?;
15
- private memoryInitialized;
16
- private sandboxManager?;
17
- private sandboxInitialized;
18
- private reflectionEngine?;
19
- private insightStore?;
20
- private reflectionInitialized;
21
- private constitutionalAI?;
22
- private guardrailsInitialized;
23
- private costRouter?;
24
- private costRoutingInitialized;
25
- constructor(config?: CogitatorConfig);
26
- /**
27
- * Initialize memory adapter and context builder (lazy, on first run)
28
- */
29
- private initializeMemory;
30
- /**
31
- * Initialize sandbox manager (lazy, on first sandboxed tool execution)
57
+ private state;
58
+ /**
59
+ * Create a new Cogitator runtime.
60
+ *
61
+ * @param config - Runtime configuration
62
+ * @param config.llm - LLM provider settings (API keys, base URLs)
63
+ * @param config.memory - Memory adapter configuration
64
+ * @param config.sandbox - Sandbox execution settings
65
+ * @param config.reflection - Reflection engine settings
66
+ * @param config.guardrails - Constitutional AI settings
67
+ * @param config.costRouting - Cost-aware routing settings
32
68
  */
33
- private initializeSandbox;
34
- /**
35
- * Initialize reflection engine (lazy, on first run with reflection enabled)
36
- */
37
- private initializeReflection;
38
- /**
39
- * Initialize constitutional AI guardrails (lazy, on first run with guardrails enabled)
40
- */
41
- private initializeGuardrails;
42
- /**
43
- * Initialize cost-aware routing (lazy, on first run with cost routing enabled)
44
- */
45
- private initializeCostRouting;
46
- /**
47
- * Build initial messages for a run, loading history if memory is enabled
48
- */
49
- private buildInitialMessages;
50
- /**
51
- * Save a message entry to memory (non-blocking, won't crash on failure)
52
- */
53
- private saveEntry;
54
- /**
55
- * Create a span with proper IDs and emit callback
56
- */
57
- private createSpan;
69
+ constructor(config?: CogitatorConfig);
58
70
  /**
59
- * Run an agent with the given input
71
+ * Run an agent with the given input.
72
+ *
73
+ * Executes the agent's task, handling LLM calls, tool execution,
74
+ * memory persistence, and observability callbacks.
75
+ *
76
+ * @param agent - Agent to execute
77
+ * @param options - Run configuration
78
+ * @param options.input - User input/prompt for the agent
79
+ * @param options.threadId - Thread ID for memory persistence
80
+ * @param options.context - Additional context to include in system prompt
81
+ * @param options.stream - Enable streaming responses
82
+ * @param options.onToken - Callback for each streamed token
83
+ * @param options.onToolCall - Callback when a tool is called
84
+ * @param options.onToolResult - Callback when a tool returns a result
85
+ * @param options.onSpan - Callback for observability spans
86
+ * @param options.timeout - Override agent timeout
87
+ * @returns Run result with output, usage stats, and trace
88
+ *
89
+ * @example
90
+ * ```ts
91
+ * const result = await cog.run(agent, {
92
+ * input: 'Search for TypeScript tutorials',
93
+ * threadId: 'session-123',
94
+ * stream: true,
95
+ * onToken: (token) => process.stdout.write(token),
96
+ * onToolCall: (call) => console.log('Tool:', call.name),
97
+ * });
98
+ *
99
+ * console.log('Output:', result.output);
100
+ * console.log('Tokens:', result.usage.totalTokens);
101
+ * console.log('Cost:', result.usage.cost);
102
+ * ```
60
103
  */
61
104
  run(agent: Agent, options: RunOptions): Promise<RunResult>;
62
- /**
63
- * Stream chat with token callback
64
- */
65
- private streamChat;
66
- /**
67
- * Execute a tool
68
- */
69
- private executeTool;
70
- /**
71
- * Execute a tool in sandbox (Docker or WASM)
72
- */
73
- private executeInSandbox;
74
- /**
75
- * Get or create an LLM backend
76
- * @param modelString - Model string (e.g., "x-ai/grok-4.1-fast")
77
- * @param explicitProvider - Explicit provider override (e.g., 'openai' for OpenRouter)
78
- */
105
+ private initializeAll;
79
106
  private getBackend;
80
- /**
81
- * Calculate cost based on model and tokens using dynamic model registry
82
- */
83
107
  private calculateCost;
84
108
  /**
85
- * Get accumulated insights for an agent
109
+ * Get accumulated insights from reflection for an agent.
110
+ *
111
+ * Insights are learnings derived from past runs that can help
112
+ * improve future agent performance.
113
+ *
114
+ * @param agentId - ID of the agent to get insights for
115
+ * @returns Array of insights, empty if reflection is not enabled
86
116
  */
87
117
  getInsights(agentId: string): Promise<import("@cogitator-ai/types").Insight[]>;
88
118
  /**
89
- * Get reflection summary for an agent
119
+ * Get reflection summary for an agent.
120
+ *
121
+ * Summary includes statistics about total runs, successful tool calls,
122
+ * common patterns, and accumulated learnings.
123
+ *
124
+ * @param agentId - ID of the agent to get summary for
125
+ * @returns Reflection summary, null if reflection is not enabled
90
126
  */
91
127
  getReflectionSummary(agentId: string): Promise<import("@cogitator-ai/types").ReflectionSummary | null>;
92
128
  /**
93
- * Get the constitutional AI guardrails instance
129
+ * Get the constitutional AI guardrails instance.
130
+ *
131
+ * @returns ConstitutionalAI instance, undefined if guardrails not enabled
94
132
  */
95
- getGuardrails(): ConstitutionalAI | undefined;
133
+ getGuardrails(): import("./constitutional").ConstitutionalAI | undefined;
96
134
  /**
97
- * Set the constitution for guardrails
135
+ * Set or update the constitution for guardrails.
136
+ *
137
+ * The constitution defines principles and rules that the agent
138
+ * must follow, filtering both input and output.
139
+ *
140
+ * @param constitution - New constitution to apply
98
141
  */
99
142
  setConstitution(constitution: Constitution): void;
100
143
  /**
101
- * Get cost-aware routing summary
144
+ * Get cost tracking summary across all runs.
145
+ *
146
+ * @returns Cost summary with total spent, runs count, and per-model breakdown
102
147
  */
103
148
  getCostSummary(): CostSummary | undefined;
104
149
  /**
105
- * Get the cost-aware router instance
106
- */
107
- getCostRouter(): CostAwareRouter | undefined;
108
- private getTextContent;
109
- /**
110
- * Close all connections
150
+ * Get the cost-aware router instance for advanced cost management.
151
+ *
152
+ * @returns CostAwareRouter instance, undefined if cost routing not enabled
153
+ */
154
+ getCostRouter(): import("./cost-routing").CostAwareRouter | undefined;
155
+ /**
156
+ * Close all connections and release resources.
157
+ *
158
+ * Should be called when done using the Cogitator instance to properly
159
+ * disconnect from memory adapters, shut down sandbox containers, and
160
+ * clean up internal state.
161
+ *
162
+ * @example
163
+ * ```ts
164
+ * const cog = new Cogitator({ ... });
165
+ * try {
166
+ * await cog.run(agent, { input: 'Hello' });
167
+ * } finally {
168
+ * await cog.close();
169
+ * }
170
+ * ```
111
171
  */
112
172
  close(): Promise<void>;
113
173
  }
@@ -1 +1 @@
1
- {"version":3,"file":"cogitator.d.ts","sourceRoot":"","sources":["../src/cogitator.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EACV,eAAe,EACf,UAAU,EACV,SAAS,EAeT,YAAY,EACZ,WAAW,EACZ,MAAM,qBAAqB,CAAC;AAW7B,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAI1C,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AA4BvD,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,QAAQ,CAAsC;IACtD,SAAgB,KAAK,EAAE,YAAY,CAAsB;IAEzD,OAAO,CAAC,aAAa,CAAC,CAAgB;IACtC,OAAO,CAAC,cAAc,CAAC,CAAiB;IACxC,OAAO,CAAC,iBAAiB,CAAS;IAElC,OAAO,CAAC,cAAc,CAAC,CAAiB;IACxC,OAAO,CAAC,kBAAkB,CAAS;IAEnC,OAAO,CAAC,gBAAgB,CAAC,CAAmB;IAC5C,OAAO,CAAC,YAAY,CAAC,CAAe;IACpC,OAAO,CAAC,qBAAqB,CAAS;IAEtC,OAAO,CAAC,gBAAgB,CAAC,CAAmB;IAC5C,OAAO,CAAC,qBAAqB,CAAS;IAEtC,OAAO,CAAC,UAAU,CAAC,CAAkB;IACrC,OAAO,CAAC,sBAAsB,CAAS;gBAE3B,MAAM,GAAE,eAAoB;IAIxC;;OAEG;YACW,gBAAgB;IA6D9B;;OAEG;YACW,iBAAiB;IAa/B;;OAEG;YACW,oBAAoB;IAelC;;OAEG;IACH,OAAO,CAAC,oBAAoB;IAc5B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAO7B;;OAEG;YACW,oBAAoB;IA0ClC;;OAEG;YACW,SAAS;IA8BvB;;OAEG;IACH,OAAO,CAAC,UAAU;IA2BlB;;OAEG;IACG,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC;IA0bhE;;OAEG;YACW,UAAU;IA6DxB;;OAEG;YACW,WAAW;IAwEzB;;OAEG;YACW,gBAAgB;IAuF9B;;;;OAIG;IACH,OAAO,CAAC,UAAU;IAiBlB;;OAEG;IACH,OAAO,CAAC,aAAa;IAWrB;;OAEG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM;IAKjC;;OAEG;IACG,oBAAoB,CAAC,OAAO,EAAE,MAAM;IAK1C;;OAEG;IACH,aAAa,IAAI,gBAAgB,GAAG,SAAS;IAI7C;;OAEG;IACH,eAAe,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI;IAIjD;;OAEG;IACH,cAAc,IAAI,WAAW,GAAG,SAAS;IAIzC;;OAEG;IACH,aAAa,IAAI,eAAe,GAAG,SAAS;IAI5C,OAAO,CAAC,cAAc;IAUtB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAqB7B"}
1
+ {"version":3,"file":"cogitator.d.ts","sourceRoot":"","sources":["../src/cogitator.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EACf,UAAU,EACV,SAAS,EAST,YAAY,EACZ,WAAW,EACZ,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAsB1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,QAAQ,CAAsC;IACtD,kDAAkD;IAClD,SAAgB,KAAK,EAAE,YAAY,CAAsB;IAEzD,OAAO,CAAC,KAAK,CAMX;IAEF;;;;;;;;;;OAUG;gBACS,MAAM,GAAE,eAAoB;IAIxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACG,GAAG,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC;YA+alD,aAAa;IAkB3B,OAAO,CAAC,UAAU;IAiBlB,OAAO,CAAC,aAAa;IAWrB;;;;;;;;OAQG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM;IAKjC;;;;;;;;OAQG;IACG,oBAAoB,CAAC,OAAO,EAAE,MAAM;IAK1C;;;;OAIG;IACH,aAAa;IAIb;;;;;;;OAOG;IACH,eAAe,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI;IAIjD;;;;OAIG;IACH,cAAc,IAAI,WAAW,GAAG,SAAS;IAIzC;;;;OAIG;IACH,aAAa;IAIb;;;;;;;;;;;;;;;;OAgBG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7B"}