@laburen/delta-sdk 1.0.0 → 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/CHANGELOG.md +38 -0
- package/README.md +13 -3
- package/dist/core/constantes.d.ts +1 -1
- package/dist/core/constantes.js +1 -1
- package/dist/telemetry/captura.d.ts +5 -0
- package/dist/telemetry/captura.d.ts.map +1 -1
- package/dist/telemetry/captura.js +4 -2
- package/dist/telemetry/captura.js.map +1 -1
- package/dist/telemetry/with-telemetry.d.ts +9 -1
- package/dist/telemetry/with-telemetry.d.ts.map +1 -1
- package/dist/telemetry/with-telemetry.js +10 -4
- package/dist/telemetry/with-telemetry.js.map +1 -1
- package/docs/telemetria.md +41 -1
- package/package.json +1 -1
- package/src/core/constantes.ts +1 -1
- package/src/telemetry/captura.ts +4 -2
- package/src/telemetry/with-telemetry.ts +39 -9
package/CHANGELOG.md
CHANGED
|
@@ -4,6 +4,44 @@ Formato: [Keep a Changelog](https://keepachangelog.com/es-ES/1.1.0/).
|
|
|
4
4
|
El paquete es **additive-only**: se agregan funciones y campos opcionales, nunca se renombra ni se
|
|
5
5
|
saca nada. Un worker que se queda en una versión vieja sigue funcionando.
|
|
6
6
|
|
|
7
|
+
## [1.1.0] — 2026-08-04
|
|
8
|
+
|
|
9
|
+
`withTelemetry` ahora le pasa el cliente de telemetría al handler. Es aditivo: no rompe ningún
|
|
10
|
+
handler existente.
|
|
11
|
+
|
|
12
|
+
### Agregado
|
|
13
|
+
|
|
14
|
+
- `withTelemetry` invoca el handler con el cliente como **cuarto argumento**:
|
|
15
|
+
`(primero, env, ctx, telemetry)`. Un handler que declara solo tres parámetros lo ignora y sigue
|
|
16
|
+
funcionando igual. Ese cuarto argumento **nunca es `null` ni `undefined`**: si `configFn` lanzó y
|
|
17
|
+
no se pudo armar el cliente real, llega el mismo cliente inerte que devuelve `createTelemetry`
|
|
18
|
+
con una config inválida — descarta todo, no lanza, y su `withTool` igual corre la tool y
|
|
19
|
+
re-lanza.
|
|
20
|
+
|
|
21
|
+
### Hay que hacer algo
|
|
22
|
+
|
|
23
|
+
Nada, es opcional. Pero si tu handler ya suma `captureException`/`captureEvent` a mano dentro de
|
|
24
|
+
un `catch` propio, podés declarar el cuarto parámetro y borrar el `createTelemetry` duplicado: el
|
|
25
|
+
cliente que te pasa `withTelemetry` es el mismo que usa el wrapper para su propia captura. Ver
|
|
26
|
+
`docs/telemetria.md`, sección 1.
|
|
27
|
+
|
|
28
|
+
## [1.0.1] — 2026-08-04
|
|
29
|
+
|
|
30
|
+
Solo documentación. **El código no cambió**: si ya estás en `1.0.0`, actualizar es opcional.
|
|
31
|
+
|
|
32
|
+
### Cambiado
|
|
33
|
+
|
|
34
|
+
- `docs/telemetria.md` y el README ahora dicen explícitamente **qué va y qué no en un MCP sobre
|
|
35
|
+
Durable Object**: va `createTelemetry` dentro de `init()` más `withTool` en las tools, y **no** va
|
|
36
|
+
`withTelemetry` sobre el `export default`, porque el framework de MCP convierte el error de la
|
|
37
|
+
tool en un resultado con `isError: true` antes de que pueda escapar al `fetch` del worker.
|
|
38
|
+
Envolver ahí no reporta nada.
|
|
39
|
+
|
|
40
|
+
### Hay que hacer algo
|
|
41
|
+
|
|
42
|
+
Nada. Pero si instrumentaste un MCP y envolviste el `export default` con `withTelemetry`, sacalo:
|
|
43
|
+
no está reportando nada y solo duplica la config.
|
|
44
|
+
|
|
7
45
|
## [1.0.0] — 2026-08-03
|
|
8
46
|
|
|
9
47
|
Primera versión.
|
package/README.md
CHANGED
|
@@ -69,6 +69,12 @@ export class MiAgenteMCP extends McpAgent<Env> {
|
|
|
69
69
|
> en el scope global hace fallar el deploy con *"Disallowed operation called within global scope"*,
|
|
70
70
|
> y `wrangler dev` local **no lo detecta**.
|
|
71
71
|
|
|
72
|
+
> **Y no envuelvas el `export default` con `withTelemetry` en un MCP.** Aunque el worker tenga un
|
|
73
|
+
> `fetch` que rutea hacia el Durable Object, el framework de MCP atrapa el error de la tool y lo
|
|
74
|
+
> convierte en un resultado con `isError: true` antes de que llegue ahí: envolver el `export default`
|
|
75
|
+
> no reportaría nada. Acá va `createTelemetry` + `withTool`, y nada más. Ver
|
|
76
|
+
> [docs/telemetria.md](docs/telemetria.md).
|
|
77
|
+
|
|
72
78
|
## Caso 2 — Worker plano, cola y cron
|
|
73
79
|
|
|
74
80
|
```ts
|
|
@@ -84,15 +90,19 @@ export default withTelemetry(
|
|
|
84
90
|
queueMaxRetries: 3, // el MISMO número del wrangler.jsonc, sin sumarle 1
|
|
85
91
|
}),
|
|
86
92
|
{
|
|
87
|
-
async fetch(req, env, ctx)
|
|
88
|
-
async queue(batch, env, ctx)
|
|
89
|
-
async scheduled(ctrl, env, ctx)
|
|
93
|
+
async fetch(req, env, ctx, telemetry) { /* ... */ }, // → surface "worker"
|
|
94
|
+
async queue(batch, env, ctx) { /* ... */ }, // → surface "queue"
|
|
95
|
+
async scheduled(ctrl, env, ctx) { /* ... */ }, // → surface "cron"
|
|
90
96
|
},
|
|
91
97
|
);
|
|
92
98
|
```
|
|
93
99
|
|
|
94
100
|
La config **no lleva `surface`**: se deduce del nombre del handler, y pasarla no compila.
|
|
95
101
|
|
|
102
|
+
**El cuarto argumento (`telemetry`) es el mismo cliente que usa el wrapper.** Un handler que
|
|
103
|
+
declara solo tres lo ignora y sigue andando igual; uno que lo declara puede usarlo en su propio
|
|
104
|
+
`catch` sin llamar a `createTelemetry` de nuevo. Ver [docs/telemetria.md](docs/telemetria.md).
|
|
105
|
+
|
|
96
106
|
> **Los nombres de las env var no están estandarizados entre proyectos.** Abrí tu `env.d.ts` antes
|
|
97
107
|
> de copiar los nombres: no asumas que son los mismos que en otro worker.
|
|
98
108
|
|
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
export declare const INGEST_URL = "https://telemetry.laburen.com/events";
|
|
4
4
|
export declare const SDK_NAME = "@laburen/delta-sdk";
|
|
5
5
|
/** Tiene que coincidir con `version` del package.json; lo verifica `npm run version:check`. */
|
|
6
|
-
export declare const SDK_VERSION = "1.
|
|
6
|
+
export declare const SDK_VERSION = "1.1.0";
|
|
7
7
|
/** Los mismos topes que aplica la ingesta. El cliente los aplica para no perder el sobre entero;
|
|
8
8
|
* la ingesta, para no confiar en el cliente. */
|
|
9
9
|
export declare const LIMITES: {
|
package/dist/core/constantes.js
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
export const INGEST_URL = "https://telemetry.laburen.com/events";
|
|
4
4
|
export const SDK_NAME = "@laburen/delta-sdk";
|
|
5
5
|
/** Tiene que coincidir con `version` del package.json; lo verifica `npm run version:check`. */
|
|
6
|
-
export const SDK_VERSION = "1.
|
|
6
|
+
export const SDK_VERSION = "1.1.0";
|
|
7
7
|
/** Los mismos topes que aplica la ingesta. El cliente los aplica para no perder el sobre entero;
|
|
8
8
|
* la ingesta, para no confiar en el cliente. */
|
|
9
9
|
export const LIMITES = {
|
|
@@ -1,4 +1,9 @@
|
|
|
1
1
|
import type { TelemetryClient, TelemetryConfig } from "../core/tipos.js";
|
|
2
|
+
/** Descarta todo, pero `withTool` sigue corriendo la tool y re-lanzando: un cliente inerte no
|
|
3
|
+
* puede cambiar el comportamiento de la app. Exportado (pero no re-exportado por ninguna puerta
|
|
4
|
+
* del `exports` map) para que `with-telemetry.ts` lo use como el cuarto argumento del handler
|
|
5
|
+
* cuando `configFn` lanza: el invariante es que ese argumento nunca es `null`/`undefined`. */
|
|
6
|
+
export declare function clienteInerte(): TelemetryClient;
|
|
2
7
|
/** El núcleo explícito, y el camino principal: los dos wrappers se construyen sobre esto y
|
|
3
8
|
* ninguno puede hacer nada que esto no permita.
|
|
4
9
|
*
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"captura.d.ts","sourceRoot":"","sources":["../../src/telemetry/captura.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAIX,eAAe,EACf,eAAe,EAEf,MAAM,kBAAkB,CAAC;
|
|
1
|
+
{"version":3,"file":"captura.d.ts","sourceRoot":"","sources":["../../src/telemetry/captura.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAIX,eAAe,EACf,eAAe,EAEf,MAAM,kBAAkB,CAAC;AAI1B;;;+FAG+F;AAC/F,wBAAgB,aAAa,IAAI,eAAe,CAM/C;AAeD;;;;oFAIoF;AACpF,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAqHxE"}
|
|
@@ -5,8 +5,10 @@ import { armarEvento, armarSobre, extraerException, serializarAcotado } from "..
|
|
|
5
5
|
import { AVISO_CTX_ROTO, enviar, probarCtx } from "../core/transporte.js";
|
|
6
6
|
import { crearWithTool } from "./with-tool.js";
|
|
7
7
|
/** Descarta todo, pero `withTool` sigue corriendo la tool y re-lanzando: un cliente inerte no
|
|
8
|
-
* puede cambiar el comportamiento de la app.
|
|
9
|
-
|
|
8
|
+
* puede cambiar el comportamiento de la app. Exportado (pero no re-exportado por ninguna puerta
|
|
9
|
+
* del `exports` map) para que `with-telemetry.ts` lo use como el cuarto argumento del handler
|
|
10
|
+
* cuando `configFn` lanza: el invariante es que ese argumento nunca es `null`/`undefined`. */
|
|
11
|
+
export function clienteInerte() {
|
|
10
12
|
return {
|
|
11
13
|
captureException() { },
|
|
12
14
|
captureEvent() { },
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"captura.js","sourceRoot":"","sources":["../../src/telemetry/captura.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACtE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAShG,OAAO,EAAE,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C;
|
|
1
|
+
{"version":3,"file":"captura.js","sourceRoot":"","sources":["../../src/telemetry/captura.ts"],"names":[],"mappings":"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"}
|
|
@@ -7,12 +7,20 @@ export interface Handlers {
|
|
|
7
7
|
queue?: HandlerCualquiera;
|
|
8
8
|
scheduled?: HandlerCualquiera;
|
|
9
9
|
}
|
|
10
|
+
/** Recorta el tipo de un handler a sus primeros tres parámetros, preservando el resto: es lo
|
|
11
|
+
* único que un caller externo puede llegar a pasar. Sin esto, un handler que declara el cuarto
|
|
12
|
+
* parámetro (`telemetry`) haría que `withTelemetry` devolviera un tipo que exige ESE cuarto
|
|
13
|
+
* argumento también al invocarlo desde afuera — cuando en realidad lo agrega el wrapper. */
|
|
14
|
+
type SoloLosPrimerosTres<F> = F extends (...args: infer Args) => infer R ? Args extends [infer P1, infer P2, infer P3, ...unknown[]] ? (p1: P1, p2: P2, p3: P3) => R : F : F;
|
|
15
|
+
type HandlersEnvueltos<H extends Handlers> = {
|
|
16
|
+
[K in keyof H]: SoloLosPrimerosTres<H[K]>;
|
|
17
|
+
};
|
|
10
18
|
/** Envuelve el `export default` de un worker. Recibe la config como FUNCIÓN de `env` y no como
|
|
11
19
|
* objeto ya armado, porque el `env` no existe a nivel de módulo y evaluar la config ahí sería
|
|
12
20
|
* el mismo error que genera ids en el scope global.
|
|
13
21
|
*
|
|
14
22
|
* Solo ve lo que ESCAPA del handler: un `catch` que loguea y devuelve un valor no deja escapar
|
|
15
23
|
* nada, y el wrapper no se entera. Envolver no reemplaza revisar los `catch` que ya existen. */
|
|
16
|
-
export declare function withTelemetry<Env, H extends Handlers>(configFn: (env: Env) => HandlerTelemetryConfig, handlers: H): H
|
|
24
|
+
export declare function withTelemetry<Env, H extends Handlers>(configFn: (env: Env) => HandlerTelemetryConfig, handlers: H): HandlersEnvueltos<H>;
|
|
17
25
|
export {};
|
|
18
26
|
//# sourceMappingURL=with-telemetry.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"with-telemetry.d.ts","sourceRoot":"","sources":["../../src/telemetry/with-telemetry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAGX,sBAAsB,EAGtB,MAAM,kBAAkB,CAAC;AAG1B;2FAC2F;AAC3F,KAAK,iBAAiB,GAAG,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC;AAEvD,MAAM,WAAW,QAAQ;IACxB,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,SAAS,CAAC,EAAE,iBAAiB,CAAC;CAC9B;
|
|
1
|
+
{"version":3,"file":"with-telemetry.d.ts","sourceRoot":"","sources":["../../src/telemetry/with-telemetry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAGX,sBAAsB,EAGtB,MAAM,kBAAkB,CAAC;AAG1B;2FAC2F;AAC3F,KAAK,iBAAiB,GAAG,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,OAAO,CAAC;AAEvD,MAAM,WAAW,QAAQ;IACxB,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,KAAK,CAAC,EAAE,iBAAiB,CAAC;IAC1B,SAAS,CAAC,EAAE,iBAAiB,CAAC;CAC9B;AA6BD;;;6FAG6F;AAC7F,KAAK,mBAAmB,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,IAAI,KAAK,MAAM,CAAC,GACrE,IAAI,SAAS,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,EAAE,GAAG,OAAO,EAAE,CAAC,GACxD,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,KAAK,CAAC,GAC7B,CAAC,GACF,CAAC,CAAC;AAEL,KAAK,iBAAiB,CAAC,CAAC,SAAS,QAAQ,IAAI;KAAG,CAAC,IAAI,MAAM,CAAC,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAAE,CAAC;AA6E3F;;;;;iGAKiG;AACjG,wBAAgB,aAAa,CAAC,GAAG,EAAE,CAAC,SAAS,QAAQ,EACpD,QAAQ,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,sBAAsB,EAC9C,QAAQ,EAAE,CAAC,GACT,iBAAiB,CAAC,CAAC,CAAC,CActB"}
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { queueMaxRetriesUsable } from "../core/config.js";
|
|
2
|
-
import { createTelemetry } from "./captura.js";
|
|
2
|
+
import { clienteInerte, createTelemetry } from "./captura.js";
|
|
3
3
|
/** El nombre del handler ES la superficie. No hay nada que el implementador pueda escribir mal,
|
|
4
4
|
* y a diferencia de los comentarios del repo, el nombre del handler no miente. */
|
|
5
5
|
const SUPERFICIE_POR_HANDLER = {
|
|
@@ -30,7 +30,10 @@ function opcionesDelHandler(surface, primero, queueMaxRetries) {
|
|
|
30
30
|
}
|
|
31
31
|
function envolver(surface, configFn, handler) {
|
|
32
32
|
return async (primero, env, ctx) => {
|
|
33
|
-
|
|
33
|
+
// Nunca queda en `null`: si `configFn` lanza, el handler recibe igual el cliente inerte
|
|
34
|
+
// como cuarto argumento. Pasar `null` obligaría a `telemetry?.captureException(...)` en
|
|
35
|
+
// cada consumidor, y el que se olvide del `?.` se rompería solo con un TypeError.
|
|
36
|
+
let cliente;
|
|
34
37
|
let cfg = null;
|
|
35
38
|
try {
|
|
36
39
|
cfg = configFn(env);
|
|
@@ -42,9 +45,12 @@ function envolver(surface, configFn, handler) {
|
|
|
42
45
|
catch (error) {
|
|
43
46
|
// Si la telemetría no arranca, el handler del cliente corre igual.
|
|
44
47
|
console.error("[delta-sdk] no se pudo inicializar la telemetría; el handler sigue igual", error);
|
|
48
|
+
cliente = clienteInerte();
|
|
45
49
|
}
|
|
46
50
|
try {
|
|
47
|
-
|
|
51
|
+
// El cliente como cuarto argumento: el implementador puede usarlo en su propio catch
|
|
52
|
+
// sin llamar a createTelemetry de nuevo ni duplicar la config.
|
|
53
|
+
return await handler(primero, env, ctx, cliente);
|
|
48
54
|
}
|
|
49
55
|
catch (error) {
|
|
50
56
|
// `cfg` es la config CRUDA que devolvió `configFn`, no la `ConfigValidada` de
|
|
@@ -55,7 +61,7 @@ function envolver(surface, configFn, handler) {
|
|
|
55
61
|
const queueMaxRetries = queueMaxRetriesUsable(queueMaxRetriesCrudo)
|
|
56
62
|
? queueMaxRetriesCrudo
|
|
57
63
|
: undefined;
|
|
58
|
-
cliente
|
|
64
|
+
cliente.captureException(error, opcionesDelHandler(surface, primero, queueMaxRetries));
|
|
59
65
|
// Se re-lanza igual que en withTool: el runtime tiene que ver el mismo error para
|
|
60
66
|
// decidir el 500 o el reintento del batch.
|
|
61
67
|
throw error;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"with-telemetry.js","sourceRoot":"","sources":["../../src/telemetry/with-telemetry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AAQ1D,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;
|
|
1
|
+
{"version":3,"file":"with-telemetry.js","sourceRoot":"","sources":["../../src/telemetry/with-telemetry.ts"],"names":[],"mappings":"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"}
|
package/docs/telemetria.md
CHANGED
|
@@ -11,7 +11,7 @@ el [README](../README.md). Para qué cambia según dónde corre tu worker, ver
|
|
|
11
11
|
| Forma | Cuándo | Qué resuelve |
|
|
12
12
|
|---|---|---|
|
|
13
13
|
| **`createTelemetry(config)` + `captureException`/`captureEvent`** | **cualquier situación — es el camino principal** | el núcleo explícito. Devuelve el **cliente**, y las otras dos formas se construyen sobre esto |
|
|
14
|
-
| `withTelemetry(configFn, handlers)` | worker plano, `queue`, `cron` | envuelve el `export default`; provee `env` y
|
|
14
|
+
| `withTelemetry(configFn, handlers)` | worker plano, `queue`, `cron` | envuelve el `export default`; provee `env`, `ctx` y el **cliente como cuarto argumento**; deduce la superficie por el nombre del handler; captura lo que **escapa** del handler |
|
|
15
15
|
| `telemetry.withTool(nombre, fn)` | tools de MCP que **hoy no atrapan su error** | envuelve una tool; captura y **re-lanza**; ahorra escribir el `try/catch` |
|
|
16
16
|
|
|
17
17
|
**`createTelemetry` es el camino principal.** Los dos wrappers son atajos que se arman encima: ni
|
|
@@ -24,6 +24,46 @@ entera. En la práctica, el grueso del trabajo de instrumentar un worker existen
|
|
|
24
24
|
con estos wrappers: es sumar `captureException`/`captureEvent` a mano dentro de los `catch` que ya
|
|
25
25
|
existen. Ver la sección 5.
|
|
26
26
|
|
|
27
|
+
**`withTelemetry` le pasa el cliente al handler como cuarto argumento**, así que ese trabajo de
|
|
28
|
+
sumar `captureException`/`captureEvent` a mano **no** requiere llamar a `createTelemetry` de nuevo
|
|
29
|
+
ni duplicar la config: el cliente ya armado está ahí, en el cuarto parámetro. Un handler que
|
|
30
|
+
declara solo tres sigue andando igual — es aditivo.
|
|
31
|
+
|
|
32
|
+
```ts
|
|
33
|
+
export default withTelemetry(configFn, {
|
|
34
|
+
async fetch(req, env, ctx, telemetry) {
|
|
35
|
+
try {
|
|
36
|
+
return await manejarRequest(req);
|
|
37
|
+
} catch (error) {
|
|
38
|
+
// el MISMO cliente que arma el wrapper, sin volver a llamar a createTelemetry
|
|
39
|
+
telemetry.captureException(error, { workUnit: "manejar-request" });
|
|
40
|
+
return new Response("Ocurrió un error", { status: 500 });
|
|
41
|
+
}
|
|
42
|
+
},
|
|
43
|
+
});
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Ese cuarto argumento **nunca es `null` ni `undefined`**: si `configFn` lanzó y no se pudo armar el
|
|
47
|
+
cliente real, llega el mismo cliente inerte que devuelve `createTelemetry` con una config inválida
|
|
48
|
+
— descarta todo, no lanza, y su `withTool` igual corre la tool y re-lanza. Así ningún consumidor
|
|
49
|
+
necesita escribir `telemetry?.captureException(...)`.
|
|
50
|
+
|
|
51
|
+
### Un MCP sobre Durable Object: qué va y qué no
|
|
52
|
+
|
|
53
|
+
Un MCP hecho con `McpAgent` tiene las dos formas a la vez: un `export default { fetch }` que rutea
|
|
54
|
+
hacia el Durable Object, y adentro las tools. **No son capas que se sumen** — una de las dos no
|
|
55
|
+
sirve acá:
|
|
56
|
+
|
|
57
|
+
- **Va:** `createTelemetry` **dentro de `init()`**, con `surface: "durable_object"` y el `ctx` del
|
|
58
|
+
agente (`ctx: this.ctx`, el original y nunca una copia), más `withTool` en cada tool que hoy no
|
|
59
|
+
atrapa su propio error.
|
|
60
|
+
- **No va:** `withTelemetry` sobre el `export default`. El framework de MCP **atrapa cualquier error
|
|
61
|
+
que lance una tool y lo convierte en un resultado con `isError: true`** antes de que pueda escapar
|
|
62
|
+
al `fetch` del worker. Envolver ahí no reportaría nunca nada, y solo duplicaría la config.
|
|
63
|
+
|
|
64
|
+
Es la misma razón por la que las tools que **sí** atrapan su propio error necesitan
|
|
65
|
+
`captureException` a mano: ese error no escapa a ningún lado, así que ningún wrapper puede verlo.
|
|
66
|
+
|
|
27
67
|
## 2. La config, campo por campo
|
|
28
68
|
|
|
29
69
|
Esta es la config que recibe `createTelemetry`. `withTelemetry` recibe la misma forma **menos**
|
package/package.json
CHANGED
package/src/core/constantes.ts
CHANGED
|
@@ -5,7 +5,7 @@ export const INGEST_URL = "https://telemetry.laburen.com/events";
|
|
|
5
5
|
export const SDK_NAME = "@laburen/delta-sdk";
|
|
6
6
|
|
|
7
7
|
/** Tiene que coincidir con `version` del package.json; lo verifica `npm run version:check`. */
|
|
8
|
-
export const SDK_VERSION = "1.
|
|
8
|
+
export const SDK_VERSION = "1.1.0";
|
|
9
9
|
|
|
10
10
|
/** Los mismos topes que aplica la ingesta. El cliente los aplica para no perder el sobre entero;
|
|
11
11
|
* la ingesta, para no confiar en el cliente. */
|
package/src/telemetry/captura.ts
CHANGED
|
@@ -14,8 +14,10 @@ import { AVISO_CTX_ROTO, enviar, probarCtx } from "../core/transporte.js";
|
|
|
14
14
|
import { crearWithTool } from "./with-tool.js";
|
|
15
15
|
|
|
16
16
|
/** Descarta todo, pero `withTool` sigue corriendo la tool y re-lanzando: un cliente inerte no
|
|
17
|
-
* puede cambiar el comportamiento de la app.
|
|
18
|
-
|
|
17
|
+
* puede cambiar el comportamiento de la app. Exportado (pero no re-exportado por ninguna puerta
|
|
18
|
+
* del `exports` map) para que `with-telemetry.ts` lo use como el cuarto argumento del handler
|
|
19
|
+
* cuando `configFn` lanza: el invariante es que ese argumento nunca es `null`/`undefined`. */
|
|
20
|
+
export function clienteInerte(): TelemetryClient {
|
|
19
21
|
return {
|
|
20
22
|
captureException() {},
|
|
21
23
|
captureEvent() {},
|
|
@@ -6,7 +6,7 @@ import type {
|
|
|
6
6
|
Surface,
|
|
7
7
|
TelemetryClient,
|
|
8
8
|
} from "../core/tipos.js";
|
|
9
|
-
import { createTelemetry } from "./captura.js";
|
|
9
|
+
import { clienteInerte, createTelemetry } from "./captura.js";
|
|
10
10
|
|
|
11
11
|
/** `(...args: never[]) => unknown` es el supertipo de cualquier función, sin usar `any`: deja
|
|
12
12
|
* pasar el handler tal como lo escribió el implementador, con SUS tipos de Cloudflare. */
|
|
@@ -31,8 +31,32 @@ interface MensajeCola {
|
|
|
31
31
|
attempts?: number;
|
|
32
32
|
}
|
|
33
33
|
|
|
34
|
+
// El handler tal como lo escribe el implementador: el wrapper lo llama SIEMPRE con el cliente
|
|
35
|
+
// como cuarto argumento. Un handler que declara solo tres lo ignora y sigue andando igual.
|
|
36
|
+
type HandlerInterno = (
|
|
37
|
+
primero: unknown,
|
|
38
|
+
env: unknown,
|
|
39
|
+
ctx: CtxLike,
|
|
40
|
+
telemetry: TelemetryClient,
|
|
41
|
+
) => Promise<unknown>;
|
|
42
|
+
|
|
43
|
+
// Lo que expone `withTelemetry`: solo los tres parámetros que el runtime (Cloudflare, o quien
|
|
44
|
+
// invoque el `export default`) puede llegar a pasar. El cuarto lo agrega `envolver` puertas
|
|
45
|
+
// adentro, nunca el caller externo, así que el tipo expuesto no puede exigirlo.
|
|
34
46
|
type Envuelto = (primero: unknown, env: unknown, ctx: CtxLike) => Promise<unknown>;
|
|
35
47
|
|
|
48
|
+
/** Recorta el tipo de un handler a sus primeros tres parámetros, preservando el resto: es lo
|
|
49
|
+
* único que un caller externo puede llegar a pasar. Sin esto, un handler que declara el cuarto
|
|
50
|
+
* parámetro (`telemetry`) haría que `withTelemetry` devolviera un tipo que exige ESE cuarto
|
|
51
|
+
* argumento también al invocarlo desde afuera — cuando en realidad lo agrega el wrapper. */
|
|
52
|
+
type SoloLosPrimerosTres<F> = F extends (...args: infer Args) => infer R
|
|
53
|
+
? Args extends [infer P1, infer P2, infer P3, ...unknown[]]
|
|
54
|
+
? (p1: P1, p2: P2, p3: P3) => R
|
|
55
|
+
: F
|
|
56
|
+
: F;
|
|
57
|
+
|
|
58
|
+
type HandlersEnvueltos<H extends Handlers> = { [K in keyof H]: SoloLosPrimerosTres<H[K]> };
|
|
59
|
+
|
|
36
60
|
/** Los números del reintento que el SDK puede leer del runtime. En `queue` salen del batch; en
|
|
37
61
|
* las otras dos superficies los pone el default de la superficie. */
|
|
38
62
|
function opcionesDelHandler(
|
|
@@ -63,10 +87,13 @@ function opcionesDelHandler(
|
|
|
63
87
|
function envolver<Env>(
|
|
64
88
|
surface: Surface,
|
|
65
89
|
configFn: (env: Env) => HandlerTelemetryConfig,
|
|
66
|
-
handler:
|
|
90
|
+
handler: HandlerInterno,
|
|
67
91
|
): Envuelto {
|
|
68
92
|
return async (primero, env, ctx) => {
|
|
69
|
-
|
|
93
|
+
// Nunca queda en `null`: si `configFn` lanza, el handler recibe igual el cliente inerte
|
|
94
|
+
// como cuarto argumento. Pasar `null` obligaría a `telemetry?.captureException(...)` en
|
|
95
|
+
// cada consumidor, y el que se olvide del `?.` se rompería solo con un TypeError.
|
|
96
|
+
let cliente: TelemetryClient;
|
|
70
97
|
let cfg: HandlerTelemetryConfig | null = null;
|
|
71
98
|
|
|
72
99
|
try {
|
|
@@ -81,10 +108,13 @@ function envolver<Env>(
|
|
|
81
108
|
"[delta-sdk] no se pudo inicializar la telemetría; el handler sigue igual",
|
|
82
109
|
error,
|
|
83
110
|
);
|
|
111
|
+
cliente = clienteInerte();
|
|
84
112
|
}
|
|
85
113
|
|
|
86
114
|
try {
|
|
87
|
-
|
|
115
|
+
// El cliente como cuarto argumento: el implementador puede usarlo en su propio catch
|
|
116
|
+
// sin llamar a createTelemetry de nuevo ni duplicar la config.
|
|
117
|
+
return await handler(primero, env, ctx, cliente);
|
|
88
118
|
} catch (error) {
|
|
89
119
|
// `cfg` es la config CRUDA que devolvió `configFn`, no la `ConfigValidada` de
|
|
90
120
|
// `createTelemetry`: este camino no pasa por `validar`, así que hay que sanearlo acá
|
|
@@ -94,7 +124,7 @@ function envolver<Env>(
|
|
|
94
124
|
const queueMaxRetries = queueMaxRetriesUsable(queueMaxRetriesCrudo)
|
|
95
125
|
? queueMaxRetriesCrudo
|
|
96
126
|
: undefined;
|
|
97
|
-
cliente
|
|
127
|
+
cliente.captureException(error, opcionesDelHandler(surface, primero, queueMaxRetries));
|
|
98
128
|
// Se re-lanza igual que en withTool: el runtime tiene que ver el mismo error para
|
|
99
129
|
// decidir el 500 o el reintento del batch.
|
|
100
130
|
throw error;
|
|
@@ -111,8 +141,8 @@ function envolver<Env>(
|
|
|
111
141
|
export function withTelemetry<Env, H extends Handlers>(
|
|
112
142
|
configFn: (env: Env) => HandlerTelemetryConfig,
|
|
113
143
|
handlers: H,
|
|
114
|
-
): H {
|
|
115
|
-
const salida = { ...handlers } as H
|
|
144
|
+
): HandlersEnvueltos<H> {
|
|
145
|
+
const salida = { ...handlers } as unknown as HandlersEnvueltos<H>;
|
|
116
146
|
|
|
117
147
|
for (const nombre of ["fetch", "queue", "scheduled"] as const) {
|
|
118
148
|
const handler = handlers[nombre];
|
|
@@ -120,8 +150,8 @@ export function withTelemetry<Env, H extends Handlers>(
|
|
|
120
150
|
salida[nombre] = envolver(
|
|
121
151
|
SUPERFICIE_POR_HANDLER[nombre],
|
|
122
152
|
configFn,
|
|
123
|
-
handler as unknown as
|
|
124
|
-
) as H[typeof nombre];
|
|
153
|
+
handler as unknown as HandlerInterno,
|
|
154
|
+
) as HandlersEnvueltos<H>[typeof nombre];
|
|
125
155
|
}
|
|
126
156
|
|
|
127
157
|
return salida;
|