@astratra/ai 1.1.0 → 1.3.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 +152 -0
- package/package.json +1 -1
- package/src/fallback.js +71 -0
- package/src/formatInstructions.js +99 -0
- package/src/index.d.ts +167 -0
- package/src/index.js +5 -1
- package/src/pendingActions.js +216 -0
- package/src/responseCleaner.js +337 -0
package/README.md
CHANGED
|
@@ -108,3 +108,155 @@ construire dans votre propre boucle, ou à couvrir dans un futur spec.
|
|
|
108
108
|
```bash
|
|
109
109
|
npm test --workspace @astratra/ai
|
|
110
110
|
```
|
|
111
|
+
|
|
112
|
+
## Le sas : un agent propose, un humain dispose
|
|
113
|
+
|
|
114
|
+
Un agent autorisé à écrire est dangereux d'une façon qu'un agent qui répond
|
|
115
|
+
n'est pas. Le mode de panne n'est pas la malveillance, c'est l'assurance : le
|
|
116
|
+
modèle appelle `send_email` avec un destinataire plausible et un corps
|
|
117
|
+
plausible, et une vraie famille reçoit un vrai message que personne n'a
|
|
118
|
+
approuvé.
|
|
119
|
+
|
|
120
|
+
```js
|
|
121
|
+
const { createPendingActions } = require('@astratra/ai');
|
|
122
|
+
|
|
123
|
+
const sas = createPendingActions({
|
|
124
|
+
store,
|
|
125
|
+
// Seul ce qui figure ici peut JAMAIS s'exécuter.
|
|
126
|
+
tools: {
|
|
127
|
+
send_email: async (payload) => mailer.send(payload),
|
|
128
|
+
send_fee_reminders: async (payload) => finance.remind(payload),
|
|
129
|
+
},
|
|
130
|
+
onPending: (action) => notifier.tell(action), // « quelque chose attend »
|
|
131
|
+
});
|
|
132
|
+
|
|
133
|
+
// L'agent propose — rien ne part.
|
|
134
|
+
await sas.propose({ action: 'send_email', payload, proposedBy: 'agent', dedupeKey });
|
|
135
|
+
|
|
136
|
+
// Un humain tranche.
|
|
137
|
+
await sas.approve(id, { approvedBy: userId, amend: { to: 'bonne-adresse@x.cd' } });
|
|
138
|
+
await sas.reject(id, { rejectedBy: userId, note: 'mauvais destinataire' });
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
`createMemoryActionStore()` fournit un store en mémoire pour les tests et le
|
|
142
|
+
développement — non persistant, donc à remplacer par une vraie table dès qu'il
|
|
143
|
+
y a plusieurs instances : la revendication atomique n'a de sens que partagée.
|
|
144
|
+
|
|
145
|
+
Ce que le cycle garantit :
|
|
146
|
+
|
|
147
|
+
- **une exécution, jamais deux** — la transition vers `executing` est une
|
|
148
|
+
revendication atomique : deux approbations simultanées produisent un envoi ;
|
|
149
|
+
- **`dedupeKey`** empêche un modèle insistant d'empiler cinq propositions
|
|
150
|
+
identiques ;
|
|
151
|
+
- **`amend`** : l'humain corrige le brouillon du modèle — destinataire, liste —
|
|
152
|
+
et la correction est consignée ;
|
|
153
|
+
- un outil qui **retourne** une erreur est marqué `failed`, jamais `executed` :
|
|
154
|
+
« Envoyé » à l'écran pour un message jamais parti est le mensonge que ce sas
|
|
155
|
+
existe pour empêcher ;
|
|
156
|
+
- un canal de notification mort ne fait pas échouer l'agent — l'action reste
|
|
157
|
+
visible dans sa liste.
|
|
158
|
+
|
|
159
|
+
## Le repli déterministe : répondre quand tout est tombé
|
|
160
|
+
|
|
161
|
+
La norme, quand le dernier fournisseur de la chaîne échoue, est un message
|
|
162
|
+
d'erreur. L'alternative est une réponse calculée SANS modèle, depuis les données
|
|
163
|
+
qu'on a déjà. Ce n'est pas aussi bien — et ce n'est jamais un écran vide.
|
|
164
|
+
|
|
165
|
+
```js
|
|
166
|
+
const { createDeterministicFallback } = require('@astratra/ai');
|
|
167
|
+
|
|
168
|
+
const repli = createDeterministicFallback({
|
|
169
|
+
responders: {
|
|
170
|
+
average: async ({ grades }) => ({ text: `La moyenne est de ${mean(grades)}/20.` }),
|
|
171
|
+
},
|
|
172
|
+
classify: (input) => input.question.includes('moyenne') ? 'average' : null,
|
|
173
|
+
});
|
|
174
|
+
|
|
175
|
+
const { degraded, answer, providerError } = await repli.withFallback(
|
|
176
|
+
(input) => router.ask(input),
|
|
177
|
+
input,
|
|
178
|
+
);
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
La règle d'honnêteté est la partie qui compte : une réponse de repli **dit**
|
|
182
|
+
qu'elle en est une (`degraded: true`). Servir une réponse dégradée comme si de
|
|
183
|
+
rien n'était apprend aux utilisateurs à se méfier des bonnes.
|
|
184
|
+
|
|
185
|
+
Et l'erreur du fournisseur est **transportée**, pas avalée : la gober en
|
|
186
|
+
silence cacherait la panne à ta propre supervision. Une question sans réponse
|
|
187
|
+
déterministe est déclinée, pas inventée.
|
|
188
|
+
|
|
189
|
+
## Nettoyer une réponse avant qu'un humain la lise
|
|
190
|
+
|
|
191
|
+
Une règle écrite dans l'invite n'est qu'un vœu : le modèle la suit quand ça
|
|
192
|
+
l'arrange. Trois fuites arrivaient quand même à l'écran — du JSON brut, les
|
|
193
|
+
étiquettes d'une structure que le modèle s'est inventée (`**introduction** :`),
|
|
194
|
+
et des brouillons de raisonnement ou des relances robotiques en fin de réponse.
|
|
195
|
+
`createResponseCleaner` les retire de façon déterministe.
|
|
196
|
+
|
|
197
|
+
```js
|
|
198
|
+
const { createResponseCleaner } = require('@astratra/ai');
|
|
199
|
+
|
|
200
|
+
const nettoyeur = createResponseCleaner({
|
|
201
|
+
shared: { // appliqué quelle que soit la langue
|
|
202
|
+
payloadKeys: ['response', 'message', 'answer'],
|
|
203
|
+
titleKeys: ['title', 'name'],
|
|
204
|
+
lineLabels: ['title', 'introduction', 'features', /key[ _]features/],
|
|
205
|
+
reasoningStarters: ['Wait', 'Actually'],
|
|
206
|
+
finalMarkers: [/Final\s*answer/],
|
|
207
|
+
},
|
|
208
|
+
languages: {
|
|
209
|
+
fr: {
|
|
210
|
+
payloadKeys: ['réponse'],
|
|
211
|
+
closingPhrases: [/Besoin d'autre chose[^.?!]*[.?!]?/],
|
|
212
|
+
},
|
|
213
|
+
},
|
|
214
|
+
fallbackLanguage: 'fr',
|
|
215
|
+
});
|
|
216
|
+
|
|
217
|
+
nettoyeur.clean(texteDuModele, { language: 'fr' });
|
|
218
|
+
```
|
|
219
|
+
|
|
220
|
+
**Aucune clé JSON à l'écran, jamais.** Un ancien convertisseur écrivait
|
|
221
|
+
« title : … », « features : … » : les clés restaient visibles. Ici un titre
|
|
222
|
+
devient une ligne en gras, un texte un paragraphe, une liste des puces, un
|
|
223
|
+
élément nommé « **Nom** — description ». Quand le modèle enveloppe sa réponse
|
|
224
|
+
(`{"role": "...", "response": "..."}`), le champ utile EST la réponse.
|
|
225
|
+
|
|
226
|
+
Les étiquettes de ligne ne sont retirées **qu'en début de ligne** : le même mot
|
|
227
|
+
au milieu d'une phrase n'est jamais touché. Pour un brouillon, seul ce qui suit
|
|
228
|
+
la **dernière** ligne de raisonnement est gardé. Les relances empilées en fin de
|
|
229
|
+
réponse sont retirées en plusieurs passes, bornées (`maxClosingPasses`, 3 par
|
|
230
|
+
défaut).
|
|
231
|
+
|
|
232
|
+
Le paquet ne contient **aucun mot** : chaque entrée est un mot littéral
|
|
233
|
+
(échappé) ou une `RegExp`, fournie par l'appelant, par langue. Sans vocabulaire,
|
|
234
|
+
seul le nettoyage structurel tourne (blocs `<think>`, JSON, espaces).
|
|
235
|
+
|
|
236
|
+
## Dire au modèle où part sa réponse
|
|
237
|
+
|
|
238
|
+
```js
|
|
239
|
+
const { createFormatInstructions } = require('@astratra/ai');
|
|
240
|
+
|
|
241
|
+
const forme = createFormatInstructions({
|
|
242
|
+
languages: {
|
|
243
|
+
fr: {
|
|
244
|
+
heading: '## Où part ta réponse',
|
|
245
|
+
intro: "Ta réponse s'affiche sur {surface}.",
|
|
246
|
+
surfaceNames: { phone: 'un téléphone', tablet: 'une tablette', desktop: 'un navigateur' },
|
|
247
|
+
table: 'Un tableau tient au maximum {columns} colonnes courtes.',
|
|
248
|
+
narrow: "Sur un téléphone, préfère la liste au moindre doute.",
|
|
249
|
+
wide: 'Le tableau reste réservé aux données réellement tabulaires.',
|
|
250
|
+
paragraphs: 'Écris en paragraphes : une idée chacun, des phrases complètes, jamais de trait (---).',
|
|
251
|
+
},
|
|
252
|
+
},
|
|
253
|
+
});
|
|
254
|
+
|
|
255
|
+
forme.build(req.headers['x-surface'], 'fr');
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
Surfaces par défaut : téléphone 3 colonnes, tablette 4, bureau 6. Une surface
|
|
259
|
+
absente ou inconnue vaut **téléphone** : se tromper vers le petit coûte une liste
|
|
260
|
+
là où un tableau tenait, se tromper vers le grand coûte un tableau illisible.
|
|
261
|
+
La règle `paragraphs` est **obligatoire** : un pack de langue qui ne l'a pas est
|
|
262
|
+
refusé à la création, pas découvert sur un écran.
|
package/package.json
CHANGED
package/src/fallback.js
ADDED
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Answering when every provider is down.
|
|
3
|
+
*
|
|
4
|
+
* The norm, when the last AI provider in the chain fails, is an error message.
|
|
5
|
+
* The alternative is a DETERMINISTIC answer: computed without any model, from
|
|
6
|
+
* the data you already have. It is not as good — and it is never a blank
|
|
7
|
+
* screen. A parent asking about their child's average gets the average and a
|
|
8
|
+
* plain sentence, not "service unavailable, try later".
|
|
9
|
+
*
|
|
10
|
+
* The honesty rule is the part that matters: a fallback answer SAYS it is one.
|
|
11
|
+
* Serving a degraded answer as if nothing happened teaches users to distrust
|
|
12
|
+
* the good ones.
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* @param {object} options
|
|
17
|
+
* @param {Record<string, Function>} options.responders intent -> async (input) => answer.
|
|
18
|
+
* Each one is plain code: a template over data, no model anywhere.
|
|
19
|
+
* @param {Function} [options.classify] (input) => intent. Defaults to reading
|
|
20
|
+
* `input.intent`. Keyword matching is the usual implementation — crude, and
|
|
21
|
+
* crude is fine here: this path only runs when everything better is down.
|
|
22
|
+
* @param {Function} [options.markDegraded] (answer) => answer, applied to every
|
|
23
|
+
* fallback response so the caller — and the user — can tell.
|
|
24
|
+
*/
|
|
25
|
+
function createDeterministicFallback(options = {}) {
|
|
26
|
+
const responders = options.responders || {};
|
|
27
|
+
if (!Object.keys(responders).length) {
|
|
28
|
+
throw new Error('createDeterministicFallback requires at least one responder.');
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
const classify = options.classify || ((input) => input && input.intent);
|
|
32
|
+
const markDegraded = options.markDegraded
|
|
33
|
+
|| ((answer) => ({ ...answer, degraded: true }));
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* @returns {Promise<{handled: boolean, answer?: object}>}
|
|
37
|
+
* handled: false means "no deterministic answer exists for this" — the
|
|
38
|
+
* caller then apologises honestly instead of inventing.
|
|
39
|
+
*/
|
|
40
|
+
async function answer(input) {
|
|
41
|
+
const intent = classify(input);
|
|
42
|
+
const responder = intent && responders[intent];
|
|
43
|
+
if (!responder) return { handled: false };
|
|
44
|
+
|
|
45
|
+
const produced = await responder(input);
|
|
46
|
+
if (produced === null || produced === undefined) return { handled: false };
|
|
47
|
+
|
|
48
|
+
const shaped = typeof produced === 'object' ? produced : { text: String(produced) };
|
|
49
|
+
return { handled: true, answer: markDegraded(shaped) };
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/**
|
|
53
|
+
* Wrap a provider call: try it, fall back when it throws.
|
|
54
|
+
*
|
|
55
|
+
* The provider error is carried alongside the fallback answer — silently
|
|
56
|
+
* eating it would hide the outage from your own monitoring.
|
|
57
|
+
*/
|
|
58
|
+
async function withFallback(ask, input) {
|
|
59
|
+
try {
|
|
60
|
+
return { degraded: false, answer: await ask(input) };
|
|
61
|
+
} catch (error) {
|
|
62
|
+
const fallen = await answer(input);
|
|
63
|
+
if (fallen.handled) return { degraded: true, answer: fallen.answer, providerError: error };
|
|
64
|
+
throw error;
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
return { answer, withFallback, intents: Object.keys(responders) };
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
module.exports = { createDeterministicFallback };
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Telling the model where its reply will be displayed.
|
|
3
|
+
*
|
|
4
|
+
* The same answer goes to a 1,400-pixel desktop console and to a 390-point
|
|
5
|
+
* phone. A model that is not told writes for the screen it imagines, and ships
|
|
6
|
+
* five-column tables that a phone renders as crushed columns or a horizontal
|
|
7
|
+
* scroll nobody finds.
|
|
8
|
+
*
|
|
9
|
+
* Why the default surface is the PHONE: guessing small wrongly costs a list
|
|
10
|
+
* where a table would have fit — still readable. Guessing large wrongly costs an
|
|
11
|
+
* unreadable table on the phone. The risk is not symmetric.
|
|
12
|
+
*
|
|
13
|
+
* Why the paragraph rule is mandatory: without it models start a sentence and
|
|
14
|
+
* leave it hanging, or pack a compact block with no breathing room, and put
|
|
15
|
+
* horizontal rules (---) between ideas. The rule must reach EVERY surface — so a
|
|
16
|
+
* language pack without it is refused at creation, not discovered on a screen.
|
|
17
|
+
*
|
|
18
|
+
* All wording is supplied by the caller, per language. Templates may use
|
|
19
|
+
* {surface} (that language's name for the surface) and {columns}.
|
|
20
|
+
*/
|
|
21
|
+
|
|
22
|
+
const DEFAULT_SURFACES = {
|
|
23
|
+
phone: { columns: 3, narrow: true, aliases: ['mobile', 'ios', 'android'] },
|
|
24
|
+
tablet: { columns: 4, narrow: false, aliases: ['ipad'] },
|
|
25
|
+
desktop: { columns: 6, narrow: false, aliases: ['web', 'browser'] }
|
|
26
|
+
};
|
|
27
|
+
|
|
28
|
+
function fill(template, values) {
|
|
29
|
+
return String(template).replace(/\{(\w+)\}/g, (whole, name) => (
|
|
30
|
+
Object.prototype.hasOwnProperty.call(values, name) ? String(values[name]) : whole
|
|
31
|
+
));
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/**
|
|
35
|
+
* @param {object} options
|
|
36
|
+
* @param {Record<string, object>} options.languages language -> pack:
|
|
37
|
+
* { paragraphs (required), heading?, intro?, table?, narrow?, wide?,
|
|
38
|
+
* rules?: string[], surfaceNames?: Record<surfaceId, string> }
|
|
39
|
+
* @param {Record<string, {columns: number, narrow?: boolean, aliases?: string[]}>} [options.surfaces]
|
|
40
|
+
* @param {string} [options.defaultSurface='phone']
|
|
41
|
+
* @param {string} [options.fallbackLanguage]
|
|
42
|
+
*/
|
|
43
|
+
function createFormatInstructions(options = {}) {
|
|
44
|
+
const surfaces = options.surfaces || DEFAULT_SURFACES;
|
|
45
|
+
const defaultSurface = options.defaultSurface || 'phone';
|
|
46
|
+
if (!surfaces[defaultSurface]) {
|
|
47
|
+
throw new Error(`createFormatInstructions: unknown defaultSurface "${defaultSurface}".`);
|
|
48
|
+
}
|
|
49
|
+
const languages = options.languages || {};
|
|
50
|
+
const names = Object.keys(languages);
|
|
51
|
+
if (!names.length) throw new Error('createFormatInstructions requires at least one language pack.');
|
|
52
|
+
for (const name of names) {
|
|
53
|
+
const pack = languages[name];
|
|
54
|
+
if (!pack || typeof pack.paragraphs !== 'string' || !pack.paragraphs.trim()) {
|
|
55
|
+
throw new Error(`createFormatInstructions: language "${name}" has no paragraphs rule.`);
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
const fallbackLanguage = options.fallbackLanguage && languages[options.fallbackLanguage]
|
|
59
|
+
? options.fallbackLanguage
|
|
60
|
+
: names[0];
|
|
61
|
+
|
|
62
|
+
const aliasIndex = new Map();
|
|
63
|
+
for (const [id, surface] of Object.entries(surfaces)) {
|
|
64
|
+
aliasIndex.set(id.toLowerCase(), id);
|
|
65
|
+
for (const alias of surface.aliases || []) aliasIndex.set(String(alias).toLowerCase(), id);
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/** Any client-sent value maps to a known surface; missing or unknown means the default. */
|
|
69
|
+
function normalizeSurface(value) {
|
|
70
|
+
if (typeof value !== 'string') return defaultSurface;
|
|
71
|
+
return aliasIndex.get(value.trim().toLowerCase()) || defaultSurface;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
function build(surfaceValue, language) {
|
|
75
|
+
const id = normalizeSurface(surfaceValue);
|
|
76
|
+
const surface = surfaces[id];
|
|
77
|
+
const pack = languages[language] || languages[fallbackLanguage];
|
|
78
|
+
const values = {
|
|
79
|
+
surface: (pack.surfaceNames && pack.surfaceNames[id]) || id,
|
|
80
|
+
columns: surface.columns
|
|
81
|
+
};
|
|
82
|
+
|
|
83
|
+
const lines = [];
|
|
84
|
+
if (pack.intro) lines.push(fill(pack.intro, values));
|
|
85
|
+
const bullets = [];
|
|
86
|
+
if (pack.table) bullets.push(pack.table);
|
|
87
|
+
const sizeRule = surface.narrow ? pack.narrow : pack.wide;
|
|
88
|
+
if (sizeRule) bullets.push(sizeRule);
|
|
89
|
+
bullets.push(pack.paragraphs);
|
|
90
|
+
for (const rule of pack.rules || []) bullets.push(rule);
|
|
91
|
+
lines.push(bullets.map((b) => `- ${fill(b, values)}`).join('\n'));
|
|
92
|
+
|
|
93
|
+
return (pack.heading ? `${fill(pack.heading, values)}\n` : '') + lines.join('\n\n');
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
return { build, normalizeSurface, surfaces: Object.keys(surfaces), languages: names };
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
module.exports = { createFormatInstructions, DEFAULT_SURFACES };
|
package/src/index.d.ts
CHANGED
|
@@ -118,3 +118,170 @@ export interface AgentLoopOptions {
|
|
|
118
118
|
}
|
|
119
119
|
|
|
120
120
|
export function runAgentLoop(options: AgentLoopOptions): Promise<string>;
|
|
121
|
+
|
|
122
|
+
export type ActionStatus = 'proposed' | 'approved' | 'rejected' | 'executing' | 'executed' | 'failed';
|
|
123
|
+
|
|
124
|
+
export interface PendingAction {
|
|
125
|
+
id: string;
|
|
126
|
+
action: string;
|
|
127
|
+
payload: Record<string, unknown>;
|
|
128
|
+
description: string | null;
|
|
129
|
+
proposedBy: unknown;
|
|
130
|
+
tenant: unknown;
|
|
131
|
+
dedupeKey: string | null;
|
|
132
|
+
status: ActionStatus;
|
|
133
|
+
proposedAt: Date;
|
|
134
|
+
approvedBy?: unknown;
|
|
135
|
+
approvedAt?: Date;
|
|
136
|
+
rejectedBy?: unknown;
|
|
137
|
+
rejectedAt?: Date;
|
|
138
|
+
executedAt?: Date;
|
|
139
|
+
failedAt?: Date;
|
|
140
|
+
lastError?: string;
|
|
141
|
+
amendedWith?: Record<string, unknown> | null;
|
|
142
|
+
reviewNote?: string | null;
|
|
143
|
+
[key: string]: unknown;
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
export interface ActionStore {
|
|
147
|
+
create(data: Record<string, unknown>): Awaitable<PendingAction>;
|
|
148
|
+
find(id: string): Awaitable<PendingAction | null>;
|
|
149
|
+
/** Atomic status transition: returns null when the record was not in `from`. */
|
|
150
|
+
claim(id: string, from: ActionStatus[], patch: Record<string, unknown>): Awaitable<PendingAction | null>;
|
|
151
|
+
update(id: string, patch: Record<string, unknown>): Awaitable<PendingAction | null>;
|
|
152
|
+
findOpenByKey?(dedupeKey: string, statuses: ActionStatus[]): Awaitable<PendingAction | null>;
|
|
153
|
+
list?(filter?: Record<string, unknown>): Awaitable<PendingAction[]>;
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
export type ActionTool = (
|
|
157
|
+
payload: Record<string, unknown>,
|
|
158
|
+
context: { action: PendingAction; approvedBy: unknown }
|
|
159
|
+
) => Awaitable<unknown>;
|
|
160
|
+
|
|
161
|
+
export interface PendingActions {
|
|
162
|
+
/** The agent proposes a write. Nothing runs yet. */
|
|
163
|
+
propose(input: {
|
|
164
|
+
action: string;
|
|
165
|
+
payload?: Record<string, unknown>;
|
|
166
|
+
description?: string;
|
|
167
|
+
proposedBy?: unknown;
|
|
168
|
+
tenant?: unknown;
|
|
169
|
+
dedupeKey?: string;
|
|
170
|
+
}): Promise<{ created: boolean; action: PendingAction }>;
|
|
171
|
+
/** A human says yes — the tool runs once, atomically claimed. */
|
|
172
|
+
approve(id: string, review: { approvedBy: unknown; amend?: Record<string, unknown> }): Promise<
|
|
173
|
+
| { executed: true; action: PendingAction; result: unknown }
|
|
174
|
+
| { executed: false; reason: 'already-handled' | 'failed'; error?: string }
|
|
175
|
+
>;
|
|
176
|
+
reject(id: string, review: { rejectedBy: unknown; note?: string }): Promise<PendingAction>;
|
|
177
|
+
pending(filter?: Record<string, unknown>): Promise<PendingAction[]>;
|
|
178
|
+
tools: string[];
|
|
179
|
+
OPEN_STATUSES: ActionStatus[];
|
|
180
|
+
}
|
|
181
|
+
|
|
182
|
+
export function createPendingActions(options: {
|
|
183
|
+
store: ActionStore;
|
|
184
|
+
tools: Record<string, ActionTool>;
|
|
185
|
+
onPending?: (action: PendingAction) => Awaitable<void>;
|
|
186
|
+
now?: () => Date;
|
|
187
|
+
logger?: { info?(m: string): void; warn?(m: string): void; error?(m: string): void };
|
|
188
|
+
}): PendingActions;
|
|
189
|
+
|
|
190
|
+
export function createMemoryActionStore(): ActionStore & {
|
|
191
|
+
findOpenByKey(dedupeKey: string, statuses: ActionStatus[]): Promise<PendingAction | null>;
|
|
192
|
+
list(filter?: Record<string, unknown>): Promise<PendingAction[]>;
|
|
193
|
+
size(): number;
|
|
194
|
+
};
|
|
195
|
+
|
|
196
|
+
export interface FallbackAnswer {
|
|
197
|
+
handled: boolean;
|
|
198
|
+
answer?: Record<string, unknown> & { degraded?: boolean };
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
export interface DeterministicFallback<Input = Record<string, unknown>> {
|
|
202
|
+
answer(input: Input): Promise<FallbackAnswer>;
|
|
203
|
+
/** Try the provider; serve the deterministic answer when it throws, carrying the provider error. */
|
|
204
|
+
withFallback<T>(ask: (input: Input) => Awaitable<T>, input: Input): Promise<
|
|
205
|
+
| { degraded: false; answer: T }
|
|
206
|
+
| { degraded: true; answer: Record<string, unknown>; providerError: unknown }
|
|
207
|
+
>;
|
|
208
|
+
intents: string[];
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
export function createDeterministicFallback<Input = Record<string, unknown>>(options: {
|
|
212
|
+
responders: Record<string, (input: Input) => Awaitable<unknown>>;
|
|
213
|
+
classify?: (input: Input) => string | null | undefined;
|
|
214
|
+
markDegraded?: (answer: Record<string, unknown>) => Record<string, unknown>;
|
|
215
|
+
}): DeterministicFallback<Input>;
|
|
216
|
+
|
|
217
|
+
/** A literal word (escaped) or a RegExp whose source is used as-is. */
|
|
218
|
+
export type VocabularyEntry = string | RegExp;
|
|
219
|
+
|
|
220
|
+
export interface CleanerVocabulary {
|
|
221
|
+
/** Wrapper keys whose string value IS the answer ({"response": "..."}). */
|
|
222
|
+
payloadKeys?: VocabularyEntry[];
|
|
223
|
+
/** Object keys rendered as a bold heading when JSON becomes prose. */
|
|
224
|
+
titleKeys?: string[];
|
|
225
|
+
/** Labels removed at the start of a line only ("**introduction** : ..."). */
|
|
226
|
+
lineLabels?: VocabularyEntry[];
|
|
227
|
+
/** Form-like labels removed anywhere they are followed by ":", "-" or "—". */
|
|
228
|
+
inlineLabels?: VocabularyEntry[];
|
|
229
|
+
/** Labels removed when alone on a line or leading one, bold or not, colon or not. */
|
|
230
|
+
headingLabels?: VocabularyEntry[];
|
|
231
|
+
reasoningLabels?: VocabularyEntry[];
|
|
232
|
+
reasoningStarters?: VocabularyEntry[];
|
|
233
|
+
finalMarkers?: VocabularyEntry[];
|
|
234
|
+
planningStarters?: VocabularyEntry[];
|
|
235
|
+
leadingFillers?: VocabularyEntry[];
|
|
236
|
+
annotationMarkers?: VocabularyEntry[];
|
|
237
|
+
/** Robotic closings, removed only at the very end of the reply. */
|
|
238
|
+
closingPhrases?: VocabularyEntry[];
|
|
239
|
+
openers?: VocabularyEntry[];
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
export interface ResponseCleaner {
|
|
243
|
+
clean(text: string | null | undefined, options?: { language?: string }): string;
|
|
244
|
+
jsonToProse(value: unknown, language?: string): string;
|
|
245
|
+
languages: string[];
|
|
246
|
+
}
|
|
247
|
+
|
|
248
|
+
export function createResponseCleaner(options?: {
|
|
249
|
+
shared?: CleanerVocabulary;
|
|
250
|
+
languages?: Record<string, CleanerVocabulary>;
|
|
251
|
+
fallbackLanguage?: string;
|
|
252
|
+
maxClosingPasses?: number;
|
|
253
|
+
}): ResponseCleaner;
|
|
254
|
+
|
|
255
|
+
export interface FormatSurface {
|
|
256
|
+
columns: number;
|
|
257
|
+
narrow?: boolean;
|
|
258
|
+
aliases?: string[];
|
|
259
|
+
}
|
|
260
|
+
|
|
261
|
+
export interface FormatLanguagePack {
|
|
262
|
+
/** Mandatory: the paragraph rule reaches every surface. */
|
|
263
|
+
paragraphs: string;
|
|
264
|
+
heading?: string;
|
|
265
|
+
intro?: string;
|
|
266
|
+
table?: string;
|
|
267
|
+
narrow?: string;
|
|
268
|
+
wide?: string;
|
|
269
|
+
rules?: string[];
|
|
270
|
+
surfaceNames?: Record<string, string>;
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
export interface FormatInstructions {
|
|
274
|
+
build(surface: unknown, language?: string): string;
|
|
275
|
+
normalizeSurface(surface: unknown): string;
|
|
276
|
+
surfaces: string[];
|
|
277
|
+
languages: string[];
|
|
278
|
+
}
|
|
279
|
+
|
|
280
|
+
export const DEFAULT_SURFACES: Record<'phone' | 'tablet' | 'desktop', FormatSurface>;
|
|
281
|
+
|
|
282
|
+
export function createFormatInstructions(options: {
|
|
283
|
+
languages: Record<string, FormatLanguagePack>;
|
|
284
|
+
surfaces?: Record<string, FormatSurface>;
|
|
285
|
+
defaultSurface?: string;
|
|
286
|
+
fallbackLanguage?: string;
|
|
287
|
+
}): FormatInstructions;
|
package/src/index.js
CHANGED
|
@@ -1,5 +1,9 @@
|
|
|
1
1
|
module.exports = {
|
|
2
2
|
...require('./providerRouter'),
|
|
3
3
|
...require('./toolRegistry'),
|
|
4
|
-
...require('./agentLoop')
|
|
4
|
+
...require('./agentLoop'),
|
|
5
|
+
...require('./pendingActions'),
|
|
6
|
+
...require('./fallback'),
|
|
7
|
+
...require('./responseCleaner'),
|
|
8
|
+
...require('./formatInstructions')
|
|
5
9
|
};
|
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The airlock between an agent that proposes and a human who decides.
|
|
3
|
+
*
|
|
4
|
+
* An agent allowed to write is dangerous in a way an agent that answers is not.
|
|
5
|
+
* The failure is not malice, it is confidence: the model calls send_email with
|
|
6
|
+
* a plausible recipient and a plausible body, and a real family receives a real
|
|
7
|
+
* message nobody approved.
|
|
8
|
+
*
|
|
9
|
+
* So a write is never executed on the model's say-so. It becomes a PENDING
|
|
10
|
+
* ACTION: recorded, visible, waiting. A person approves it, and only then does
|
|
11
|
+
* it run — through a lifecycle that also guarantees it cannot run twice.
|
|
12
|
+
*
|
|
13
|
+
* proposed -> approved -> executing -> executed
|
|
14
|
+
* \-> rejected \-> failed
|
|
15
|
+
*
|
|
16
|
+
* The `executing` step is not decoration. The transition INTO it is atomic
|
|
17
|
+
* (one findOneAndUpdate-style claim in the store): two people clicking
|
|
18
|
+
* "approve" at the same moment produce one send, not two.
|
|
19
|
+
*/
|
|
20
|
+
const { AppError } = require('@astratra/core');
|
|
21
|
+
|
|
22
|
+
const PROPOSED = 'proposed';
|
|
23
|
+
const APPROVED = 'approved';
|
|
24
|
+
const REJECTED = 'rejected';
|
|
25
|
+
const EXECUTING = 'executing';
|
|
26
|
+
const EXECUTED = 'executed';
|
|
27
|
+
const FAILED = 'failed';
|
|
28
|
+
|
|
29
|
+
const OPEN_STATUSES = [PROPOSED, APPROVED, EXECUTING];
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* @param {object} options
|
|
33
|
+
* @param {object} options.store adapter:
|
|
34
|
+
* create(data), find(id), claim(id, from[], patch) — atomic status change,
|
|
35
|
+
* update(id, patch), findOpenByKey(dedupeKey), list(filter).
|
|
36
|
+
* @param {Record<string, Function>} options.tools action name -> executor.
|
|
37
|
+
* Only what is listed here can EVER run. An action recorded with a name this
|
|
38
|
+
* map does not carry is refused at execution, however it got approved.
|
|
39
|
+
* @param {Function} [options.onPending] async (action) => void — tell the
|
|
40
|
+
* humans something waits. Failures are swallowed: the action stays visible
|
|
41
|
+
* in its list even if the notification channel is down.
|
|
42
|
+
* @param {Function} [options.now]
|
|
43
|
+
* @param {object} [options.logger]
|
|
44
|
+
*/
|
|
45
|
+
function createPendingActions(options = {}) {
|
|
46
|
+
const store = options.store;
|
|
47
|
+
for (const method of ['create', 'find', 'claim', 'update']) {
|
|
48
|
+
if (!store || typeof store[method] !== 'function') {
|
|
49
|
+
throw new Error(`createPendingActions requires options.store.${method}().`);
|
|
50
|
+
}
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
const tools = options.tools || {};
|
|
54
|
+
if (!Object.keys(tools).length) {
|
|
55
|
+
throw new Error('createPendingActions requires at least one tool in options.tools.');
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
const onPending = options.onPending || null;
|
|
59
|
+
const now = options.now || (() => new Date());
|
|
60
|
+
const logger = options.logger || { info() {}, warn() {}, error() {} };
|
|
61
|
+
|
|
62
|
+
/**
|
|
63
|
+
* The agent proposes a write. Nothing happens yet.
|
|
64
|
+
*
|
|
65
|
+
* `dedupeKey` is what stops an insistent model from stacking five identical
|
|
66
|
+
* proposals: the same open action is returned instead of a new one.
|
|
67
|
+
*/
|
|
68
|
+
async function propose({ action, payload = {}, description, proposedBy, tenant, dedupeKey } = {}) {
|
|
69
|
+
if (!action || !tools[action]) {
|
|
70
|
+
throw new AppError(`"${action}" is not a tool this airlock knows.`, 400);
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
if (dedupeKey && typeof store.findOpenByKey === 'function') {
|
|
74
|
+
const existing = await store.findOpenByKey(dedupeKey, OPEN_STATUSES);
|
|
75
|
+
if (existing) return { created: false, action: existing };
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
const record = await store.create({
|
|
79
|
+
action, payload, description: description || null,
|
|
80
|
+
proposedBy: proposedBy || null, tenant: tenant || null,
|
|
81
|
+
dedupeKey: dedupeKey || null,
|
|
82
|
+
status: PROPOSED, proposedAt: now()
|
|
83
|
+
});
|
|
84
|
+
|
|
85
|
+
if (onPending) {
|
|
86
|
+
try {
|
|
87
|
+
await onPending(record);
|
|
88
|
+
} catch (error) {
|
|
89
|
+
/* The action stays visible in its list either way. The agent must not
|
|
90
|
+
fail because the notification backend blinked. */
|
|
91
|
+
logger.warn(`[pending-actions] notification failed: ${error.message}`);
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
return { created: true, action: record };
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* A human says yes — and the action runs, once.
|
|
100
|
+
*/
|
|
101
|
+
async function approve(id, { approvedBy, amend } = {}) {
|
|
102
|
+
if (approvedBy === undefined || approvedBy === null) {
|
|
103
|
+
throw new AppError('An approval must record who approved it.', 400);
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
const pending = await store.find(id);
|
|
107
|
+
if (!pending) throw new AppError('This action could not be found.', 404);
|
|
108
|
+
if (pending.status !== PROPOSED) {
|
|
109
|
+
throw new AppError(`This action has already been ${pending.status}.`, 409);
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
const tool = tools[pending.action];
|
|
113
|
+
if (!tool) {
|
|
114
|
+
/* Recorded under one catalogue, approved under another — a deploy
|
|
115
|
+
between the two, or a tampered record. Refuse. */
|
|
116
|
+
throw new AppError(`Tool "${pending.action}" is not available any more.`, 400);
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/* The atomic claim. Whoever loses this race gets a clean "already
|
|
120
|
+
handled", not a second execution. */
|
|
121
|
+
const claimed = await store.claim(id, [PROPOSED], {
|
|
122
|
+
status: EXECUTING, approvedBy, approvedAt: now()
|
|
123
|
+
});
|
|
124
|
+
if (!claimed) return { executed: false, reason: 'already-handled' };
|
|
125
|
+
|
|
126
|
+
/* An amendment comes from the HUMAN — correcting a recipient, trimming a
|
|
127
|
+
list. The model's payload is never silently replaced; the two are
|
|
128
|
+
merged with the human's values on top, and the amendment is recorded. */
|
|
129
|
+
const payload = amend ? { ...claimed.payload, ...amend } : claimed.payload;
|
|
130
|
+
|
|
131
|
+
try {
|
|
132
|
+
const result = await tool(payload, { action: claimed, approvedBy });
|
|
133
|
+
/* A tool that RETURNS an error has not succeeded, even though it did not
|
|
134
|
+
throw. Marking it executed would show "sent" for a message that never
|
|
135
|
+
left. */
|
|
136
|
+
if (result && result.error) throw new AppError(String(result.error), 502);
|
|
137
|
+
|
|
138
|
+
const done = await store.update(id, { status: EXECUTED, executedAt: now(), amendedWith: amend || null });
|
|
139
|
+
logger.info(`[pending-actions] "${claimed.action}" executed (approved by ${approvedBy})`);
|
|
140
|
+
return { executed: true, action: done, result };
|
|
141
|
+
} catch (error) {
|
|
142
|
+
await store.update(id, { status: FAILED, failedAt: now(), lastError: error.message });
|
|
143
|
+
logger.error(`[pending-actions] "${claimed.action}" failed: ${error.message}`);
|
|
144
|
+
return { executed: false, reason: 'failed', error: error.message };
|
|
145
|
+
}
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/** A human says no. The record stays — a refused proposal is information. */
|
|
149
|
+
async function reject(id, { rejectedBy, note } = {}) {
|
|
150
|
+
if (rejectedBy === undefined || rejectedBy === null) {
|
|
151
|
+
throw new AppError('A rejection must record who rejected it.', 400);
|
|
152
|
+
}
|
|
153
|
+
const pending = await store.find(id);
|
|
154
|
+
if (!pending) throw new AppError('This action could not be found.', 404);
|
|
155
|
+
if (pending.status !== PROPOSED) {
|
|
156
|
+
throw new AppError(`This action has already been ${pending.status}.`, 409);
|
|
157
|
+
}
|
|
158
|
+
return store.update(id, { status: REJECTED, rejectedBy, rejectedAt: now(), reviewNote: note || null });
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
/** What waits for a human. */
|
|
162
|
+
async function pending(filter = {}) {
|
|
163
|
+
if (typeof store.list !== 'function') {
|
|
164
|
+
throw new Error('createPendingActions: options.store.list is required to list.');
|
|
165
|
+
}
|
|
166
|
+
return store.list({ ...filter, status: PROPOSED });
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
return {
|
|
170
|
+
propose, approve, reject, pending,
|
|
171
|
+
tools: Object.keys(tools),
|
|
172
|
+
PROPOSED, APPROVED, REJECTED, EXECUTING, EXECUTED, FAILED, OPEN_STATUSES
|
|
173
|
+
};
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
/** In-process store for tests and development. Not persistent. */
|
|
177
|
+
function createMemoryActionStore() {
|
|
178
|
+
const records = new Map();
|
|
179
|
+
let sequence = 0;
|
|
180
|
+
const clone = (r) => (r ? JSON.parse(JSON.stringify(r)) : r);
|
|
181
|
+
|
|
182
|
+
return {
|
|
183
|
+
async create(data) {
|
|
184
|
+
const id = String(++sequence);
|
|
185
|
+
records.set(id, { id, ...data });
|
|
186
|
+
return clone(records.get(id));
|
|
187
|
+
},
|
|
188
|
+
async find(id) { return clone(records.get(String(id))) || null; },
|
|
189
|
+
async claim(id, fromStatuses, patch) {
|
|
190
|
+
const record = records.get(String(id));
|
|
191
|
+
if (!record || !fromStatuses.includes(record.status)) return null;
|
|
192
|
+
Object.assign(record, patch);
|
|
193
|
+
return clone(record);
|
|
194
|
+
},
|
|
195
|
+
async update(id, patch) {
|
|
196
|
+
const record = records.get(String(id));
|
|
197
|
+
if (!record) return null;
|
|
198
|
+
Object.assign(record, patch);
|
|
199
|
+
return clone(record);
|
|
200
|
+
},
|
|
201
|
+
async findOpenByKey(dedupeKey, statuses) {
|
|
202
|
+
for (const record of records.values()) {
|
|
203
|
+
if (record.dedupeKey === dedupeKey && statuses.includes(record.status)) return clone(record);
|
|
204
|
+
}
|
|
205
|
+
return null;
|
|
206
|
+
},
|
|
207
|
+
async list(filter = {}) {
|
|
208
|
+
return [...records.values()]
|
|
209
|
+
.filter((r) => Object.entries(filter).every(([k, v]) => r[k] === v))
|
|
210
|
+
.map(clone);
|
|
211
|
+
},
|
|
212
|
+
size: () => records.size
|
|
213
|
+
};
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
module.exports = { createPendingActions, createMemoryActionStore };
|
|
@@ -0,0 +1,337 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Cleaning a model's reply before a human reads it.
|
|
3
|
+
*
|
|
4
|
+
* A rule written in the system prompt is a wish: the model follows it when it
|
|
5
|
+
* suits it. Three leaks kept reaching real screens despite explicit
|
|
6
|
+
* instructions, so this cleaner removes them deterministically:
|
|
7
|
+
*
|
|
8
|
+
* 1. Raw JSON. The model answers `{"title": "...", "features": [...]}` or wraps
|
|
9
|
+
* its real answer as `{"role": "...", "response": "..."}`. An earlier
|
|
10
|
+
* converter turned JSON into "title: ...", "features: ..." — the KEYS were
|
|
11
|
+
* still on screen. A JSON key is not a word for the user, even translated,
|
|
12
|
+
* so none is ever shown: a title becomes a bold line, text a paragraph, a
|
|
13
|
+
* list bullets, a named item "**Name** — description".
|
|
14
|
+
* 2. Labels copied from a structure the model invented for itself
|
|
15
|
+
* ("**introduction** : ..."). Removed at the start of a line only — the same
|
|
16
|
+
* word inside a sentence is never touched.
|
|
17
|
+
* 3. Reasoning drafts and robotic closings ("Wait, ...", "Final answer:",
|
|
18
|
+
* "Let me know if you need anything else.").
|
|
19
|
+
*
|
|
20
|
+
* The structural part (think blocks, JSON detection, prose conversion,
|
|
21
|
+
* whitespace) is language-neutral and built in. Every WORD — which keys carry
|
|
22
|
+
* the answer, which labels to drop, which closings are robotic — belongs to a
|
|
23
|
+
* language and is supplied by the caller, per language.
|
|
24
|
+
*/
|
|
25
|
+
|
|
26
|
+
const ESCAPE = /[.*+?^${}()|[\]\\]/g;
|
|
27
|
+
|
|
28
|
+
/** A vocabulary entry is a literal word (escaped) or a RegExp (its source is used as-is). */
|
|
29
|
+
function toSource(entry) {
|
|
30
|
+
if (entry instanceof RegExp) return entry.source;
|
|
31
|
+
return String(entry).replace(ESCAPE, '\\$&');
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
function alternation(entries) {
|
|
35
|
+
return entries.map(toSource).join('|');
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
const VOCABULARY_FIELDS = [
|
|
39
|
+
'payloadKeys', 'titleKeys', 'lineLabels', 'inlineLabels', 'headingLabels',
|
|
40
|
+
'reasoningLabels', 'reasoningStarters', 'finalMarkers', 'planningStarters',
|
|
41
|
+
'leadingFillers', 'annotationMarkers', 'closingPhrases', 'openers'
|
|
42
|
+
];
|
|
43
|
+
|
|
44
|
+
function mergeVocabularies(parts) {
|
|
45
|
+
const merged = {};
|
|
46
|
+
for (const field of VOCABULARY_FIELDS) {
|
|
47
|
+
const seen = new Set();
|
|
48
|
+
merged[field] = [];
|
|
49
|
+
for (const part of parts) {
|
|
50
|
+
for (const entry of (part && part[field]) || []) {
|
|
51
|
+
const key = entry instanceof RegExp ? `re:${entry.source}` : `s:${entry}`;
|
|
52
|
+
if (seen.has(key)) continue;
|
|
53
|
+
seen.add(key);
|
|
54
|
+
merged[field].push(entry);
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
return merged;
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/* Lenient parse: models emit trailing commas, single quotes and unquoted keys.
|
|
62
|
+
A strict JSON.parse alone let those through to the screen untouched. */
|
|
63
|
+
function lenientParse(str) {
|
|
64
|
+
try { return JSON.parse(str); } catch (_e) { /* try the repaired form */ }
|
|
65
|
+
try {
|
|
66
|
+
const fixed = str
|
|
67
|
+
.replace(/,\s*([}\]])/g, '$1')
|
|
68
|
+
.replace(/'/g, '"')
|
|
69
|
+
// Unquoted keys, only right after { or , so text values are not rewritten.
|
|
70
|
+
.replace(/([{,]\s*)(\w+)\s*:/g, '$1"$2":')
|
|
71
|
+
.replace(/""+/g, '"');
|
|
72
|
+
return JSON.parse(fixed);
|
|
73
|
+
} catch (_e) {
|
|
74
|
+
return null;
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
function inlineValue(value) {
|
|
79
|
+
if (value === null || value === undefined) return '';
|
|
80
|
+
if (typeof value !== 'object') return String(value).trim();
|
|
81
|
+
if (Array.isArray(value)) return value.map(inlineValue).filter(Boolean).join(', ');
|
|
82
|
+
return Object.values(value).map(inlineValue).filter(Boolean).join(' — ');
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
function makeJsonToProse(titleKeys) {
|
|
86
|
+
const titles = titleKeys.map((k) => String(k).toLowerCase());
|
|
87
|
+
|
|
88
|
+
function jsonToProse(value, depth = 0) {
|
|
89
|
+
const indent = ' '.repeat(depth);
|
|
90
|
+
if (value === null || value === undefined) return '';
|
|
91
|
+
if (typeof value !== 'object') return String(value).trim();
|
|
92
|
+
|
|
93
|
+
if (Array.isArray(value)) {
|
|
94
|
+
return value.map((item) => {
|
|
95
|
+
if (item && typeof item === 'object' && !Array.isArray(item)) {
|
|
96
|
+
const nameKey = Object.keys(item).find((k) => titles.includes(k.toLowerCase())
|
|
97
|
+
&& typeof item[k] === 'string' && item[k].trim());
|
|
98
|
+
const rest = Object.entries(item)
|
|
99
|
+
.filter(([k]) => k !== nameKey)
|
|
100
|
+
.map(([, v]) => inlineValue(v))
|
|
101
|
+
.filter(Boolean)
|
|
102
|
+
.join(' — ');
|
|
103
|
+
const head = nameKey ? `**${item[nameKey].trim()}**` : '';
|
|
104
|
+
return `${indent}- ${head && rest ? `${head} — ${rest}` : head || rest}`;
|
|
105
|
+
}
|
|
106
|
+
return `${indent}- ${inlineValue(item)}`;
|
|
107
|
+
}).filter((line) => line.trim() !== '-').join('\n');
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
// An object: its values in order, WITHOUT their keys. A title opens in bold.
|
|
111
|
+
const blocks = [];
|
|
112
|
+
for (const [key, v] of Object.entries(value)) {
|
|
113
|
+
if (v === null || v === undefined || v === '') continue;
|
|
114
|
+
if (typeof v !== 'object') {
|
|
115
|
+
const text = String(v).trim();
|
|
116
|
+
if (!text) continue;
|
|
117
|
+
blocks.push(titles.includes(key.toLowerCase()) ? `**${text}**` : text);
|
|
118
|
+
} else {
|
|
119
|
+
const prose = jsonToProse(v, Array.isArray(v) ? depth : depth + 1);
|
|
120
|
+
if (prose) blocks.push(prose);
|
|
121
|
+
}
|
|
122
|
+
}
|
|
123
|
+
return blocks.join('\n\n');
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
return jsonToProse;
|
|
127
|
+
}
|
|
128
|
+
|
|
129
|
+
function makeJsonConverter(vocabulary) {
|
|
130
|
+
const jsonToProse = makeJsonToProse(vocabulary.titleKeys);
|
|
131
|
+
|
|
132
|
+
/* When the model wraps its answer ({"role": "...", "response": "..."}), the
|
|
133
|
+
payload field IS the answer; listing role/name alongside it is noise. */
|
|
134
|
+
function payloadOf(parsed) {
|
|
135
|
+
if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return null;
|
|
136
|
+
const key = vocabulary.payloadKeys.find((k) => typeof parsed[k] === 'string' && parsed[k].trim());
|
|
137
|
+
return key ? parsed[key] : null;
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
function render(parsed) {
|
|
141
|
+
return payloadOf(parsed) || jsonToProse(parsed, 0);
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
function convertRawJson(text) {
|
|
145
|
+
let trimmed = text.trim();
|
|
146
|
+
const fence = trimmed.match(/^```(?:json)?\s*\n([\s\S]*?)\n\s*```\s*$/);
|
|
147
|
+
if (fence) trimmed = fence[1].trim();
|
|
148
|
+
|
|
149
|
+
// The whole reply is JSON — only when it has at least one quoted key, so a
|
|
150
|
+
// reply that merely starts with "[" is left alone.
|
|
151
|
+
if ((trimmed.startsWith('{') || trimmed.startsWith('[')) && /"[\wÀ-ÿ_]+"\s*:/.test(trimmed)) {
|
|
152
|
+
const parsed = lenientParse(trimmed);
|
|
153
|
+
if (parsed) return render(parsed) || text;
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
// A short preamble, then a JSON block.
|
|
157
|
+
const jsonStart = trimmed.search(/\n\s*[{[]/);
|
|
158
|
+
if (jsonStart > 0 && jsonStart < 200) {
|
|
159
|
+
const preamble = trimmed.slice(0, jsonStart).trim();
|
|
160
|
+
const parsed = lenientParse(trimmed.slice(jsonStart).trim());
|
|
161
|
+
if (parsed) {
|
|
162
|
+
const body = render(parsed);
|
|
163
|
+
if (body) return (preamble ? `${preamble}\n\n` : '') + body;
|
|
164
|
+
}
|
|
165
|
+
}
|
|
166
|
+
|
|
167
|
+
// Unparseable but clearly structured (3+ quoted keys): keep the values only.
|
|
168
|
+
// Keys are erased here too — this path used to be the last place they leaked.
|
|
169
|
+
const quotedKeys = (trimmed.match(/"[\wÀ-ÿ_]+"\s*:/g) || []).length;
|
|
170
|
+
if (quotedKeys >= 3 && /^\s*\{/.test(trimmed)) {
|
|
171
|
+
return trimmed
|
|
172
|
+
.replace(/^\s*\{/, '').replace(/\}\s*$/, '')
|
|
173
|
+
.replace(/"([\wÀ-ÿ_ ]+)"\s*:\s*/g, '')
|
|
174
|
+
.replace(/[[\]{}]/g, '')
|
|
175
|
+
.replace(/",?\s*/g, '\n')
|
|
176
|
+
.replace(/"/g, '')
|
|
177
|
+
.replace(/\n{3,}/g, '\n\n')
|
|
178
|
+
.trim();
|
|
179
|
+
}
|
|
180
|
+
return text;
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
/* JSON fragments pasted in the middle of prose (a tool result copied back). */
|
|
184
|
+
function convertInlineJson(text) {
|
|
185
|
+
return text.replace(
|
|
186
|
+
/\{(?:\s*"[\wÀ-ÿ_]+"\s*:\s*(?:"[^"]*"|[\d.]+|true|false|null|\[.*?\]|\{[^}]*\})\s*,?\s*){2,}\}/g,
|
|
187
|
+
(match) => {
|
|
188
|
+
const parsed = lenientParse(match);
|
|
189
|
+
if (!parsed) return match;
|
|
190
|
+
return render(parsed) || match;
|
|
191
|
+
}
|
|
192
|
+
);
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
return { convertRawJson, convertInlineJson, jsonToProse };
|
|
196
|
+
}
|
|
197
|
+
|
|
198
|
+
function compile(vocabulary) {
|
|
199
|
+
const v = vocabulary;
|
|
200
|
+
const any = (list) => list.length > 0;
|
|
201
|
+
const rx = {};
|
|
202
|
+
|
|
203
|
+
if (any(v.payloadKeys)) {
|
|
204
|
+
rx.payloadLabel = new RegExp(`^\\s*(?:\\*\\*)?(?:${alternation(v.payloadKeys)})(?:\\*\\*)?\\s*[:\\-—]\\s*`, 'i');
|
|
205
|
+
}
|
|
206
|
+
if (any(v.inlineLabels)) {
|
|
207
|
+
rx.inlineLabels = new RegExp(`(?:^|\\s)(?:\\*\\*)?(?:${alternation(v.inlineLabels)})(?:\\*\\*)?\\s*[:\\-—]\\s*`, 'gi');
|
|
208
|
+
}
|
|
209
|
+
if (any(v.lineLabels)) {
|
|
210
|
+
// Replaced by a paragraph break: the content stays, split as it was.
|
|
211
|
+
rx.lineLabels = new RegExp(`(^|\\n)[ \\t]*(?:\\*\\*)?(?:${alternation(v.lineLabels)})(?:\\*\\*)?[ \\t]*:[ \\t]*`, 'gi');
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
/* Drafts chain corrections with no fixed marker ("Wait, ...", "Actually, ...",
|
|
215
|
+
"Final answer:"). Patching word by word never ends, so the LAST line that
|
|
216
|
+
looks like reasoning is found and only what follows it is kept: the model
|
|
217
|
+
writes its last meta comment right before the real answer. */
|
|
218
|
+
const boundary = [];
|
|
219
|
+
if (any(v.finalMarkers)) {
|
|
220
|
+
// The answer often follows on the same line after the colon: consume up to ':' only.
|
|
221
|
+
boundary.push(`^[ \\t]*(?:${alternation(v.finalMarkers)})\\s*(?:\\([^)]*\\))?\\s*[:\\-—]`);
|
|
222
|
+
}
|
|
223
|
+
const labelBlock = any(v.reasoningLabels)
|
|
224
|
+
? `^[ \\t]*\\(?(?:${alternation(v.reasoningLabels)})(?:[\\s-]+\\w+){0,6}(?:\\s*\\([^)]*\\))?\\)?\\s*[:\\-—]`
|
|
225
|
+
: null;
|
|
226
|
+
if (labelBlock) boundary.push(`${labelBlock}.*$`);
|
|
227
|
+
if (any(v.reasoningStarters)) boundary.push(`^[ \\t]*(?:${alternation(v.reasoningStarters)})\\b.*$`);
|
|
228
|
+
if (boundary.length) rx.boundary = new RegExp(boundary.join('|'), 'gim');
|
|
229
|
+
// Safety net: a labelled block still left (label + paragraph up to a blank line).
|
|
230
|
+
if (labelBlock) rx.labelledBlock = new RegExp(`${labelBlock}.*(?:\\n(?!\\s*\\n).*)*`, 'gim');
|
|
231
|
+
|
|
232
|
+
if (any(v.planningStarters)) {
|
|
233
|
+
rx.planning = new RegExp(`^[\\s]*[*\\-•]\\s*(?:${alternation(v.planningStarters)}).*$`, 'gim');
|
|
234
|
+
}
|
|
235
|
+
if (any(v.leadingFillers)) {
|
|
236
|
+
// Punctuation is required after the filler: "Bon" must not eat "Bonjour".
|
|
237
|
+
rx.filler = new RegExp(`^(?:${alternation(v.leadingFillers)})\\s*[.,!]+\\s*`, 'i');
|
|
238
|
+
}
|
|
239
|
+
if (any(v.annotationMarkers)) {
|
|
240
|
+
rx.annotation = new RegExp(`^.*\\((?:${alternation(v.annotationMarkers)}).*\\).*$`, 'gim');
|
|
241
|
+
}
|
|
242
|
+
if (any(v.headingLabels)) {
|
|
243
|
+
/* Bold may wrap the label, and the colon is absent when the label holds its
|
|
244
|
+
own line: an expression requiring "^label:" saw neither case. */
|
|
245
|
+
const h = alternation(v.headingLabels);
|
|
246
|
+
rx.headingAlone = new RegExp(`^\\s*(?:\\*\\*)?\\s*(?:${h})\\s*(?:\\*\\*)?\\s*:?\\s*(?:\\*\\*)?\\s*$`, 'gim');
|
|
247
|
+
rx.headingLead = new RegExp(`^\\s*(?:\\*\\*)?\\s*(?:${h})\\s*(?:\\*\\*)?\\s*:\\s*`, 'gim');
|
|
248
|
+
}
|
|
249
|
+
if (any(v.closingPhrases)) {
|
|
250
|
+
rx.closing = new RegExp(`\\s*(?:${alternation(v.closingPhrases)})\\s*$`, 'i');
|
|
251
|
+
}
|
|
252
|
+
if (any(v.openers)) {
|
|
253
|
+
rx.openers = new RegExp(`(?:^|\\n)\\s*(?:${alternation(v.openers)})\\s*[.!?]?\\s*`, 'gi');
|
|
254
|
+
}
|
|
255
|
+
return rx;
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
/**
|
|
259
|
+
* @param {object} [options]
|
|
260
|
+
* @param {object} [options.shared] vocabulary applied whatever the language
|
|
261
|
+
* (JSON keys are usually English whatever language the user speaks).
|
|
262
|
+
* @param {Record<string, object>} [options.languages] vocabulary per language.
|
|
263
|
+
* @param {string} [options.fallbackLanguage] used when clean() gets an unknown language.
|
|
264
|
+
* @param {number} [options.maxClosingPasses=3] successive robotic closings removed.
|
|
265
|
+
*/
|
|
266
|
+
function createResponseCleaner(options = {}) {
|
|
267
|
+
const shared = options.shared || {};
|
|
268
|
+
const languages = options.languages || {};
|
|
269
|
+
const fallbackLanguage = options.fallbackLanguage || null;
|
|
270
|
+
const maxClosingPasses = options.maxClosingPasses ?? 3;
|
|
271
|
+
const cache = new Map();
|
|
272
|
+
|
|
273
|
+
function forLanguage(language) {
|
|
274
|
+
const lang = language && languages[language] ? language : fallbackLanguage;
|
|
275
|
+
const key = lang || '';
|
|
276
|
+
if (!cache.has(key)) {
|
|
277
|
+
const vocabulary = mergeVocabularies([shared, lang ? languages[lang] : null]);
|
|
278
|
+
cache.set(key, { vocabulary, rx: compile(vocabulary), json: makeJsonConverter(vocabulary) });
|
|
279
|
+
}
|
|
280
|
+
return cache.get(key);
|
|
281
|
+
}
|
|
282
|
+
|
|
283
|
+
function clean(text, cleanOptions = {}) {
|
|
284
|
+
if (text === null || text === undefined) return '';
|
|
285
|
+
const { rx, json } = forLanguage(cleanOptions.language);
|
|
286
|
+
let out = String(text);
|
|
287
|
+
|
|
288
|
+
// Reasoning blocks, closed or cut off mid-stream.
|
|
289
|
+
out = out.replace(/<think>[\s\S]*?<\/think>/gi, '');
|
|
290
|
+
out = out.replace(/<think>[\s\S]*/gi, '');
|
|
291
|
+
|
|
292
|
+
out = json.convertRawJson(out);
|
|
293
|
+
if (rx.payloadLabel) out = out.replace(rx.payloadLabel, '');
|
|
294
|
+
if (rx.inlineLabels) out = out.replace(rx.inlineLabels, ' ');
|
|
295
|
+
if (rx.lineLabels) out = out.replace(rx.lineLabels, '$1\n');
|
|
296
|
+
out = json.convertInlineJson(out);
|
|
297
|
+
|
|
298
|
+
if (rx.boundary) {
|
|
299
|
+
const matches = [...out.matchAll(rx.boundary)];
|
|
300
|
+
if (matches.length) {
|
|
301
|
+
const last = matches[matches.length - 1];
|
|
302
|
+
out = out.slice(last.index + last[0].length);
|
|
303
|
+
}
|
|
304
|
+
}
|
|
305
|
+
if (rx.labelledBlock) out = out.replace(rx.labelledBlock, '');
|
|
306
|
+
if (rx.planning) out = out.replace(rx.planning, '');
|
|
307
|
+
if (rx.filler) out = out.replace(rx.filler, '');
|
|
308
|
+
if (rx.annotation) out = out.replace(rx.annotation, '');
|
|
309
|
+
if (rx.headingAlone) out = out.replace(rx.headingAlone, '');
|
|
310
|
+
if (rx.headingLead) out = out.replace(rx.headingLead, '');
|
|
311
|
+
|
|
312
|
+
/* Closings stack ("Need anything else? Don't hesitate to ask."): one pass
|
|
313
|
+
left the first one standing. Bounded, so a reply made only of phrases
|
|
314
|
+
that look robotic cannot be eaten whole by a loop. */
|
|
315
|
+
if (rx.closing) {
|
|
316
|
+
for (let i = 0; i < maxClosingPasses; i += 1) {
|
|
317
|
+
const next = out.replace(rx.closing, '');
|
|
318
|
+
if (next === out) break;
|
|
319
|
+
out = next;
|
|
320
|
+
}
|
|
321
|
+
}
|
|
322
|
+
if (rx.openers) out = out.replace(rx.openers, '\n');
|
|
323
|
+
|
|
324
|
+
out = out.replace(/\n{3,}/g, '\n\n');
|
|
325
|
+
out = out.replace(/[ \t]{2,}/g, ' ');
|
|
326
|
+
return out.trim();
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
return {
|
|
330
|
+
clean,
|
|
331
|
+
/** Converts a parsed JSON value to prose without any key (for tool results shown as text). */
|
|
332
|
+
jsonToProse: (value, language) => forLanguage(language).json.jsonToProse(value, 0),
|
|
333
|
+
languages: Object.keys(languages)
|
|
334
|
+
};
|
|
335
|
+
}
|
|
336
|
+
|
|
337
|
+
module.exports = { createResponseCleaner };
|