@astratra/ai 1.0.1 → 1.1.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 CHANGED
@@ -74,7 +74,9 @@ const reponse = await runAgentLoop({
74
74
  registry,
75
75
  router,
76
76
  userRole: 'doctor',
77
- maxSteps: 5
77
+ maxSteps: 5,
78
+ onChunk: (chunk) => res.write(chunk), // streaming token par token, optionnel
79
+ confirmTool: async (toolCall) => askUser(toolCall) // confirmation avant exécution, optionnel
78
80
  });
79
81
  ```
80
82
 
@@ -83,12 +85,23 @@ modèle, exécute l'outil correspondant enregistré (refuse si le rôle n'y a
83
85
  pas accès), réinjecte le résultat sous forme de `<tool_result>`, et boucle
84
86
  jusqu'à une réponse finale ou `maxSteps` atteint.
85
87
 
86
- **Périmètre V0 — volontairement exclu :** streaming token par token,
87
- gestion d'images/vision, et confirmation humaine avant l'exécution d'un
88
- outil sensible. Ce sont de vraies fonctionnalités non triviales dont une
89
- boucle d'agent de production a besoin, mais les porter fidèlement a été
90
- jugé trop ambitieux pour cette première version du package. À construire
91
- dans votre propre boucle, ou à couvrir dans un futur spec.
88
+ `onChunk(chunk)` est appelé pour chaque morceau reçu si `router.ask()`
89
+ retourne un flux (async iterable) — un vrai passthrough token par token vers
90
+ ton UI. La boucle continue d'accumuler le texte complet en interne (elle en
91
+ a besoin pour détecter un `<tool_call>`), donc le fournir ne change rien au
92
+ comportement, juste un point d'observation en plus.
93
+
94
+ `confirmTool(toolCall, ctx)` est attendu avant l'exécution d'un appel d'outil
95
+ détecté. Retourne `false` (ou une promesse résolue en `false`) pour refuser
96
+ — la boucle ne plante pas, elle informe le modèle (`{"denied": true, ...}`
97
+ comme résultat d'outil) et continue, il peut réagir (expliquer, proposer
98
+ autre chose, s'arrêter). Omis, chaque outil autorisé s'exécute automatiquement,
99
+ comme avant.
100
+
101
+ **Périmètre V0 — toujours volontairement exclu :** gestion d'images/vision.
102
+ Fonctionnalité non triviale dont une boucle d'agent de production a besoin,
103
+ mais dont le portage fidèle reste jugé trop ambitieux pour ce package. À
104
+ construire dans votre propre boucle, ou à couvrir dans un futur spec.
92
105
 
93
106
  ## Tests
94
107
 
package/package.json CHANGED
@@ -1,7 +1,10 @@
1
1
  {
2
2
  "name": "@astratra/ai",
3
- "version": "1.0.1",
3
+ "version": "1.1.0",
4
4
  "description": "Generic AI provider routing, tool registry, and agent loop utilities for Astratra.",
5
+ "engines": {
6
+ "node": ">=20"
7
+ },
5
8
  "main": "src/index.js",
6
9
  "types": "src/index.d.ts",
7
10
  "type": "commonjs",
package/src/agentLoop.js CHANGED
@@ -9,7 +9,9 @@ async function runAgentLoop({
9
9
  registry,
10
10
  router,
11
11
  userRole,
12
- maxSteps = DEFAULT_MAX_STEPS
12
+ maxSteps = DEFAULT_MAX_STEPS,
13
+ onChunk,
14
+ confirmTool
13
15
  }) {
14
16
  if (!registry) throw new AppError('agentLoop requires a registry', 500);
15
17
  if (!router || typeof router.ask !== 'function') throw new AppError('agentLoop requires a router', 500);
@@ -19,11 +21,15 @@ async function runAgentLoop({
19
21
 
20
22
  for (let step = 0; step < maxSteps; step += 1) {
21
23
  const modelPrompt = buildPrompt(registry, userRole, messages);
24
+ // onChunk, when provided, is called with each chunk AS IT ARRIVES if
25
+ // router.ask() returns a stream — real token-by-token streaming to the
26
+ // caller. The loop itself still needs the fully-assembled text to
27
+ // detect a <tool_call>, so it accumulates in parallel regardless.
22
28
  const response = await stringifyModelResponse(await router.ask(modelPrompt, {
23
29
  complexity: 'agent',
24
30
  intent: 'agent_loop',
25
31
  estimatedTokens: estimateTokens(modelPrompt)
26
- }, ctx));
32
+ }, ctx), onChunk);
27
33
  const toolCall = parseToolCall(response);
28
34
 
29
35
  if (!toolCall) {
@@ -38,6 +44,23 @@ async function runAgentLoop({
38
44
  throw new AppError(`Tool "${toolCall.name}" is not allowed for role "${userRole}"`, 403);
39
45
  }
40
46
 
47
+ // confirmTool, when provided, gates execution — e.g. a human approval
48
+ // step surfaced by the calling app before a write/delete tool actually
49
+ // runs. Denying doesn't crash the loop: the model gets told and can
50
+ // adjust course (ask something else, explain, stop), same as it would
51
+ // handle any other tool result.
52
+ if (typeof confirmTool === 'function') {
53
+ const approved = await confirmTool(toolCall, ctx);
54
+ if (!approved) {
55
+ messages.push({ role: 'assistant', content: response });
56
+ messages.push({
57
+ role: 'tool',
58
+ content: `<tool_result name="${tool.name}">${JSON.stringify({ denied: true, reason: 'Execution was not approved.' })}</tool_result>`
59
+ });
60
+ continue;
61
+ }
62
+ }
63
+
41
64
  const result = await tool.handler(toolCall.params, ctx);
42
65
  messages.push({ role: 'assistant', content: response });
43
66
  messages.push({
@@ -76,15 +99,19 @@ function parseToolCall(text) {
76
99
  }
77
100
  }
78
101
 
79
- async function stringifyModelResponse(value) {
102
+ async function stringifyModelResponse(value, onChunk) {
80
103
  if (isAsyncIterable(value)) {
81
104
  let output = '';
82
105
  for await (const chunk of value) {
83
- output += String(chunk);
106
+ const text = String(chunk);
107
+ output += text;
108
+ if (typeof onChunk === 'function') onChunk(text);
84
109
  }
85
110
  return output;
86
111
  }
87
- return String(value ?? '');
112
+ const text = String(value ?? '');
113
+ if (typeof onChunk === 'function') onChunk(text);
114
+ return text;
88
115
  }
89
116
 
90
117
  function isAsyncIterable(value) {
package/src/index.d.ts CHANGED
@@ -88,6 +88,11 @@ export interface AgentRouter {
88
88
  ask(prompt: string, request?: ProviderRequest, ctx?: Record<string, unknown>): Awaitable<string | AsyncIterable<unknown> | null | undefined>;
89
89
  }
90
90
 
91
+ export interface ToolCall {
92
+ name: string;
93
+ params: Record<string, unknown>;
94
+ }
95
+
91
96
  export interface AgentLoopOptions {
92
97
  prompt: string;
93
98
  ctx?: Record<string, unknown>;
@@ -96,6 +101,20 @@ export interface AgentLoopOptions {
96
101
  router: AgentRouter;
97
102
  userRole: string;
98
103
  maxSteps?: number;
104
+ /**
105
+ * Called with each text chunk as it arrives, when router.ask() returns a
106
+ * stream — real token-by-token passthrough to your UI. The loop still
107
+ * needs the fully-assembled text to detect a tool call, so it keeps
108
+ * accumulating internally regardless of whether you pass this.
109
+ */
110
+ onChunk?: (chunk: string) => void;
111
+ /**
112
+ * Awaited before a detected tool call actually executes. Return (or
113
+ * resolve to) false to deny — the loop tells the model the call was not
114
+ * approved and continues, rather than crashing. Omit to auto-execute
115
+ * every allowed tool call, unchanged from before.
116
+ */
117
+ confirmTool?: (toolCall: ToolCall, ctx: Record<string, unknown>) => Awaitable<boolean>;
99
118
  }
100
119
 
101
120
  export function runAgentLoop(options: AgentLoopOptions): Promise<string>;