@laburen/delta-sdk 1.3.0 → 1.5.0-canary.10

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 (150) hide show
  1. package/CHANGELOG.md +24 -0
  2. package/README.md +3 -0
  3. package/dist/core/config.d.ts +12 -12
  4. package/dist/core/config.d.ts.map +1 -1
  5. package/dist/core/config.js +88 -88
  6. package/dist/core/config.js.map +1 -1
  7. package/dist/core/{constantes.d.ts → constants.d.ts} +3 -3
  8. package/dist/core/constants.d.ts.map +1 -0
  9. package/dist/core/{constantes.js → constants.js} +3 -3
  10. package/dist/core/constants.js.map +1 -0
  11. package/dist/core/{contadores.d.ts → counters.d.ts} +12 -11
  12. package/dist/core/counters.d.ts.map +1 -0
  13. package/dist/core/counters.js +53 -0
  14. package/dist/core/counters.js.map +1 -0
  15. package/dist/core/{sobre.d.ts → envelope.d.ts} +17 -17
  16. package/dist/core/envelope.d.ts.map +1 -0
  17. package/dist/core/envelope.js +198 -0
  18. package/dist/core/envelope.js.map +1 -0
  19. package/dist/core/scrubbing.d.ts +4 -4
  20. package/dist/core/scrubbing.d.ts.map +1 -1
  21. package/dist/core/scrubbing.js +38 -38
  22. package/dist/core/scrubbing.js.map +1 -1
  23. package/dist/core/{sesion.d.ts → session.d.ts} +2 -2
  24. package/dist/core/session.d.ts.map +1 -0
  25. package/dist/core/{sesion.js → session.js} +2 -2
  26. package/dist/core/session.js.map +1 -0
  27. package/dist/core/{transporte.d.ts → transport.d.ts} +9 -9
  28. package/dist/core/transport.d.ts.map +1 -0
  29. package/dist/core/{transporte.js → transport.js} +15 -15
  30. package/dist/core/transport.js.map +1 -0
  31. package/dist/core/{tipos.d.ts → types.d.ts} +4 -4
  32. package/dist/core/{tipos.d.ts.map → types.d.ts.map} +1 -1
  33. package/dist/core/{tipos.js → types.js} +1 -1
  34. package/dist/core/{tipos.js.map → types.js.map} +1 -1
  35. package/dist/index.d.ts +1 -1
  36. package/dist/platform/client.d.ts +8 -0
  37. package/dist/platform/client.d.ts.map +1 -0
  38. package/dist/platform/client.js +30 -0
  39. package/dist/platform/client.js.map +1 -0
  40. package/dist/platform/core/errors.d.ts +150 -0
  41. package/dist/platform/core/errors.d.ts.map +1 -0
  42. package/dist/platform/core/errors.js +265 -0
  43. package/dist/platform/core/errors.js.map +1 -0
  44. package/dist/platform/core/oauth.d.ts +37 -0
  45. package/dist/platform/core/oauth.d.ts.map +1 -0
  46. package/dist/platform/core/oauth.js +144 -0
  47. package/dist/platform/core/oauth.js.map +1 -0
  48. package/dist/platform/core/pagination.d.ts +30 -0
  49. package/dist/platform/core/pagination.d.ts.map +1 -0
  50. package/dist/platform/core/pagination.js +44 -0
  51. package/dist/platform/core/pagination.js.map +1 -0
  52. package/dist/platform/core/request.d.ts +6 -0
  53. package/dist/platform/core/request.d.ts.map +1 -0
  54. package/dist/platform/core/request.js +24 -0
  55. package/dist/platform/core/request.js.map +1 -0
  56. package/dist/platform/core/send.d.ts +36 -0
  57. package/dist/platform/core/send.d.ts.map +1 -0
  58. package/dist/platform/core/send.js +171 -0
  59. package/dist/platform/core/send.js.map +1 -0
  60. package/dist/platform/core/sse.d.ts +8 -0
  61. package/dist/platform/core/sse.d.ts.map +1 -0
  62. package/dist/platform/core/sse.js +72 -0
  63. package/dist/platform/core/sse.js.map +1 -0
  64. package/dist/platform/core/stream.d.ts +21 -0
  65. package/dist/platform/core/stream.d.ts.map +1 -0
  66. package/dist/platform/core/stream.js +268 -0
  67. package/dist/platform/core/stream.js.map +1 -0
  68. package/dist/platform/generated/resources.d.ts +120 -0
  69. package/dist/platform/generated/resources.d.ts.map +1 -0
  70. package/dist/platform/generated/resources.js +65 -0
  71. package/dist/platform/generated/resources.js.map +1 -0
  72. package/dist/platform/generated/schemas.d.ts +78 -0
  73. package/dist/platform/generated/schemas.d.ts.map +1 -0
  74. package/dist/platform/generated/schemas.js +2 -0
  75. package/dist/platform/generated/schemas.js.map +1 -0
  76. package/dist/platform/generated/types.d.ts +5167 -0
  77. package/dist/platform/generated/types.d.ts.map +1 -0
  78. package/dist/platform/generated/types.js +6 -0
  79. package/dist/platform/generated/types.js.map +1 -0
  80. package/dist/platform/index.d.ts +9 -0
  81. package/dist/platform/index.d.ts.map +1 -0
  82. package/dist/platform/index.js +7 -0
  83. package/dist/platform/index.js.map +1 -0
  84. package/dist/telemetry/{captura.d.ts → capture.d.ts} +3 -3
  85. package/dist/telemetry/capture.d.ts.map +1 -0
  86. package/dist/telemetry/{captura.js → capture.js} +54 -54
  87. package/dist/telemetry/capture.js.map +1 -0
  88. package/dist/telemetry/index.d.ts +2 -2
  89. package/dist/telemetry/index.js +1 -1
  90. package/dist/telemetry/{tipos.d.ts → types.d.ts} +2 -2
  91. package/dist/telemetry/types.d.ts.map +1 -0
  92. package/dist/telemetry/types.js +2 -0
  93. package/dist/telemetry/types.js.map +1 -0
  94. package/dist/telemetry/with-telemetry.d.ts +9 -9
  95. package/dist/telemetry/with-telemetry.d.ts.map +1 -1
  96. package/dist/telemetry/with-telemetry.js +31 -31
  97. package/dist/telemetry/with-telemetry.js.map +1 -1
  98. package/dist/telemetry/with-tool.d.ts +2 -2
  99. package/dist/telemetry/with-tool.d.ts.map +1 -1
  100. package/dist/telemetry/with-tool.js +3 -3
  101. package/dist/telemetry/with-tool.js.map +1 -1
  102. package/docs/platform/guide.md +554 -0
  103. package/docs/telemetry/que-se-manda.md +2 -2
  104. package/docs/telemetry/troubleshooting.md +1 -1
  105. package/package.json +15 -5
  106. package/src/core/config.ts +81 -83
  107. package/src/core/{constantes.ts → constants.ts} +2 -2
  108. package/src/core/counters.ts +72 -0
  109. package/src/core/envelope.ts +234 -0
  110. package/src/core/scrubbing.ts +41 -41
  111. package/src/core/{sesion.ts → session.ts} +1 -1
  112. package/src/core/{transporte.ts → transport.ts} +20 -20
  113. package/src/core/{tipos.ts → types.ts} +3 -3
  114. package/src/index.ts +1 -1
  115. package/src/platform/client.ts +32 -0
  116. package/src/platform/core/errors.ts +348 -0
  117. package/src/platform/core/oauth.ts +201 -0
  118. package/src/platform/core/pagination.ts +67 -0
  119. package/src/platform/core/request.ts +27 -0
  120. package/src/platform/core/send.ts +212 -0
  121. package/src/platform/core/sse.ts +68 -0
  122. package/src/platform/core/stream.ts +314 -0
  123. package/src/platform/generated/resources.ts +192 -0
  124. package/src/platform/generated/schemas.ts +79 -0
  125. package/src/platform/generated/types.ts +5167 -0
  126. package/src/platform/index.ts +45 -0
  127. package/src/telemetry/{captura.ts → capture.ts} +57 -57
  128. package/src/telemetry/index.ts +2 -2
  129. package/src/telemetry/{tipos.ts → types.ts} +1 -1
  130. package/src/telemetry/with-telemetry.ts +51 -54
  131. package/src/telemetry/with-tool.ts +5 -5
  132. package/dist/core/constantes.d.ts.map +0 -1
  133. package/dist/core/constantes.js.map +0 -1
  134. package/dist/core/contadores.d.ts.map +0 -1
  135. package/dist/core/contadores.js +0 -53
  136. package/dist/core/contadores.js.map +0 -1
  137. package/dist/core/sesion.d.ts.map +0 -1
  138. package/dist/core/sesion.js.map +0 -1
  139. package/dist/core/sobre.d.ts.map +0 -1
  140. package/dist/core/sobre.js +0 -200
  141. package/dist/core/sobre.js.map +0 -1
  142. package/dist/core/transporte.d.ts.map +0 -1
  143. package/dist/core/transporte.js.map +0 -1
  144. package/dist/telemetry/captura.d.ts.map +0 -1
  145. package/dist/telemetry/captura.js.map +0 -1
  146. package/dist/telemetry/tipos.d.ts.map +0 -1
  147. package/dist/telemetry/tipos.js +0 -2
  148. package/dist/telemetry/tipos.js.map +0 -1
  149. package/src/core/contadores.ts +0 -71
  150. package/src/core/sobre.ts +0 -236
@@ -0,0 +1,554 @@
1
+ # La puerta `/platform`, guía
2
+
3
+ Esta es la guía de `@laburen/delta-sdk/platform`: un cliente tipado de la API de plataforma de
4
+ Laburen (`https://dashboard.laburen.com/api/platform/v1`). Con él manejás agentes, skills,
5
+ conexiones MCP y tokens desde código. Para instalar el paquete, ver [docs/empezar.md](../empezar.md).
6
+
7
+ La puerta no depende de la de `/telemetry`: se pueden usar por separado.
8
+
9
+ ## 1. Crear el cliente
10
+
11
+ Para apuntar a un ambiente que no es producción (development, staging), pasá `baseUrl` al crear el cliente:
12
+ `createPlatform({ token, baseUrl: "https://<tu-ambiente>/api/platform/v1" })`. Sin `baseUrl`, todo va a producción.
13
+
14
+ Los ids de los ejemplos (`agt_123`, `org_123`, `ver_123`) son placeholders: los ids reales son cuid (`cmviigyjv000a13bs5ut17tzf`).
15
+
16
+ ```ts
17
+ import { createPlatform } from "@laburen/delta-sdk/platform";
18
+
19
+ export default {
20
+ async fetch(request: Request, env: Env): Promise<Response> {
21
+ // Crealo adentro del handler: no hace ningún pedido al crearse, pero no va en el scope global.
22
+ const platform = createPlatform({ token: env.LABUREN_PLATFORM_TOKEN });
23
+
24
+ const agent = await platform.agents.get("agt_123");
25
+ return Response.json(agent);
26
+ },
27
+ };
28
+ ```
29
+
30
+ El `token` puede ser un texto o una función `async` que lo devuelve (útil si lo renovás). Los
31
+ métodos están agrupados por recurso (`agents`, `skills`, `tokens`, `models`, `me`,
32
+ `knowledge.projects`, `mcp.connections`), y los de versiones cuelgan del recurso (`agents.versions.list(...)`). Cada método
33
+ recibe primero los ids de la ruta, después los parámetros y al final las `options` de la llamada. Un método sin
34
+ parámetros es `(…ids, options?)`: `platform.agents.get(id, { signal })`, `platform.me.get({ signal })`. Uno con parámetros
35
+ (`list`, `create`, `update`...) es `(…ids, params, options?)`: `platform.agents.list({}, { signal })`.
36
+
37
+ Desde la 1.5, los métodos sin parámetros pasaron a `(…ids, options?)`: antes recibían un `params` vacío en ese lugar. Si
38
+ tu código llamaba `platform.agents.get(id, undefined, { signal })` o `platform.me.get({}, { signal })`, sacá ese argumento.
39
+
40
+ Opciones del cliente (todas menos `token` son opcionales): `organization`, `baseUrl`, `timeout`
41
+ (milisegundos, 30 000 por default), `maxRetries` (2 por default) y `fetch`.
42
+
43
+ `baseUrl` es producción por default (`https://dashboard.laburen.com/api/platform/v1`). Pasalo solo
44
+ para apuntar a otro ambiente.
45
+
46
+ ### En un script de Node
47
+
48
+ El snippet usa `await` a nivel de módulo: el `package.json` necesita `"type": "module"` (o ponés el código dentro de una función `async`).
49
+
50
+ Para un script local, sacá un token con la CLI y guardalo en una variable de entorno. El valor
51
+ sale una sola vez, en el campo `value` de la respuesta:
52
+
53
+ ```bash
54
+ laburen orgs list # copiá el id de la organización
55
+ laburen tokens create --org <organization_id> --name mi-script --kind personal \
56
+ --permissions '["read","write","query"]' --json
57
+ export LABUREN_TOKEN=<el valor>
58
+ ```
59
+
60
+ La sesión de la CLI suele abarcar todas tus organizaciones, así que el comando necesita `--org <organization_id>`.
61
+ Si el script va a borrar recursos, sumá `"admin"` a los permisos. Un token sin acceso a la organización que usás da `organization_access_denied`;
62
+ con `--all-organizations` el token sirve en todas y cada llamada lleva la organización (sección 2).
63
+
64
+ ```ts
65
+ import { createPlatform } from "@laburen/delta-sdk/platform";
66
+
67
+ const platform = createPlatform({ token: process.env.LABUREN_TOKEN! });
68
+ const me = await platform.me.get();
69
+ ```
70
+
71
+ Cada operación pide un permiso (tabla completa en la sección 12). Un token sin el permiso recibe un `PermissionError`.
72
+ Si preferís no guardar una clave, ver el login por device code (sección 7).
73
+
74
+ ## 2. Organización
75
+
76
+ Si tu token da acceso a más de una organización, decile con cuál trabajar. Se manda en el header
77
+ `x-laburen-organization`.
78
+
79
+ ```ts
80
+ // Para todo el cliente
81
+ const platform = createPlatform({ token, organization: "org_123" });
82
+
83
+ // O solo para una llamada
84
+ await platform.agents.list({}, { organization: "org_456" });
85
+ ```
86
+
87
+ `platform.me.organizations.list()` te devuelve las organizaciones a las que tenés acceso. Con un token de una sola organización devuelve solo esa.
88
+
89
+ ## 3. Errores
90
+
91
+ Todo lo que falla lanza una clase propia. Si la API contestó con un error, es un
92
+ `LaburenApiError`, y su subclase sale del `type` del cuerpo de error (no del status):
93
+ `InvalidRequestError`, `AuthenticationError`, `BillingError`, `PermissionError`, `NotFoundError`, `ConflictError`, `RateLimitError`, `ApiError` y
94
+ `OverloadedError`. Si el cuerpo no es el del catálogo (por ejemplo, el HTML de un proxy con un 5xx),
95
+ es el `LaburenApiError` base. Por eso conviene preguntar con `isLaburenApiError` y mirar `e.type` y
96
+ `e.status`, en vez de `instanceof` sobre cada subclase. Si no hubo respuesta, es un
97
+ `LaburenConnectionError` (o `LaburenTimeoutError`, que es un caso del anterior).
98
+
99
+ ```ts
100
+ import {
101
+ isLaburenApiError,
102
+ isLaburenConnectionError,
103
+ } from "@laburen/delta-sdk/platform";
104
+
105
+ try {
106
+ await platform.agents.get("agt_123");
107
+ } catch (error) {
108
+ if (isLaburenApiError(error) && error.type === "not_found_error") {
109
+ // el agente no existe
110
+ } else if (isLaburenApiError(error)) {
111
+ console.error(error.status, error.type, error.code, error.message, error.requestId);
112
+ } else if (isLaburenConnectionError(error)) {
113
+ console.error("no hubo respuesta", error.message);
114
+ } else {
115
+ throw error;
116
+ }
117
+ }
118
+ ```
119
+
120
+ Los `is...` sirven también si el error cruzó un límite entre dos copias del paquete, donde
121
+ `instanceof` falla. `requestId` es lo que tenés que pasarle a soporte.
122
+
123
+ Un `LaburenApiError` trae además tres campos para decidir qué hacer:
124
+
125
+ - `e.issues`: una lista `{ field, message }` con lo que estaba mal (cuando el error nombra un campo, `details.field`, `issues` lo trae también; si no, es `[]`).
126
+ - `e.details`: datos extra según el `code`, por ejemplo `details.latest_version_id` en `base_version_mismatch`. Si no hay, es `{}`.
127
+ - `e.shouldRetry`: `true` si la API dice que repetir el mismo pedido puede funcionar, `false` si no; `null` si el error no vino del catálogo.
128
+
129
+ Un argumento que no sirve lanza `LaburenArgumentError` (se pregunta con `isLaburenArgumentError`) **antes de mandar nada**: un id de ruta
130
+ vacío, `null`, `undefined`, `.` o `..`, o un `token` vacío. Los demás ids (`"0"`, con `/`) se mandan, codificados.
131
+
132
+ Todos los códigos. El status sale de la familia (`type`); `shouldRetry` es `true` solo donde dice "reintentable":
133
+
134
+ | `code` | Status | Qué significa y qué hacer |
135
+ |---|---|---|
136
+ | `invalid_request` | 400 | El path, la query o el body no cumplen el esquema; `issues` lista cada campo inválido |
137
+ | `invalid_agent_config` | 400 | La config del agente no es válida o no puede correr (tools, historial, versión, proveedor); mirá `issues` |
138
+ | `invalid_skill` | 400 | La skill no sigue el formato; `details.reason` dice la regla (`forbidden_path`, `invalid_character`, `invalid_frontmatter`, `name_mismatch`, `limit_exceeded`, `no_active_version`) |
139
+ | `mcp_server_unreachable` | 400 | `mcp.connections.tools.list` no pudo hablar con el servidor MCP; `details.connection_id` dice cuál. Revisá la url y los headers de la conexión (`mcp.connections.versions.list` muestra el host de cada versión). Guardar un filtro `tools` de un agente con un MCP caído no falla con este código: se guarda y la versión creada trae el aviso `mcp_tools_unverified` (ver sección 9). No es reintentable. Solo pasa en la API de gestión; un turno con un MCP caído no devuelve este error |
140
+ | `tool_execution_failed` | 400 | Una tool que llama a un sistema del cliente recibió un error o ninguna respuesta |
141
+ | `legacy_agent_not_supported` | 400 | Esa operación de la API nueva se pidió sobre un agente legacy |
142
+ | `conversational_mode_not_supported` | 400 | El agente usa el modo conversacional, que este endpoint todavía no soporta |
143
+ | `unsupported_trigger` | 400 | El harness recibió un tipo de disparo que no sabe correr |
144
+ | `invalid_token` | 401 | La credencial falta, no existe, venció o fue revocada |
145
+ | `credits_exhausted` | 402 | La organización no tiene créditos para correr el agente |
146
+ | `insufficient_permissions` | 403 | La credencial o el rol no alcanzan; `details.required` trae el permiso que faltó |
147
+ | `organization_access_denied` | 403 | No tenés membresía activa en esa organización, o el header no coincide con la credencial |
148
+ | `invalid_origin` | 403 | Pedido que cambia datos con cookie de sesión y un `Origin` que no es el nuestro (no pasa con un token) |
149
+ | `thread_resource_mismatch` | 403 | `memory.resource` no es el dueño de `memory.thread` (sección 8) |
150
+ | `agent_not_found` | 404 | El agente no existe o no es de la organización |
151
+ | `config_version_not_found` | 404 | La versión de config no existe o no es de ese agente |
152
+ | `skill_not_found` | 404 | La skill no existe o no es de la organización |
153
+ | `skill_version_not_found` | 404 | La versión de skill no existe o no es de una skill de la organización |
154
+ | `mcp_connection_not_found` | 404 | La conexión MCP no existe o no es de la organización |
155
+ | `mcp_connection_version_not_found` | 404 | La versión de conexión MCP no existe o no es de una conexión de la organización |
156
+ | `token_not_found` | 404 | Revocar o leer un token que no existe o no es tuyo |
157
+ | `conversation_not_found` | 404 | `memory.thread` no existe, o es de otra organización u otro agente (mismo error en los dos casos) |
158
+ | `resource_in_use` | 409 | Borrar una skill, una conexión MCP o una versión suya que usan versiones de agentes. Receta abajo |
159
+ | `version_in_use` | 409 | Borrar la versión activa; activá otra primero |
160
+ | `base_version_mismatch` | 409 | `base_version_id` ya no es la última; `details.latest_version_id` dice cuál es |
161
+ | `skill_name_taken` | 409 | Ya hay una skill con ese nombre en la organización |
162
+ | `mcp_connection_name_taken` | 409 | Ya hay una conexión MCP con ese nombre (se compara como prefijo de tool) |
163
+ | `idempotency_key_reused` | 409 | La misma `Idempotency-Key` con otro body: usá una key nueva |
164
+ | `idempotency_key_in_progress` | 409 | La misma key y el mismo body mientras el primer pedido sigue corriendo; reintentable: esperá unos segundos y repetí |
165
+ | `ai_disabled_for_conversation` | 409 | La IA está apagada en la conversación (la tomó una persona): el turno no corre |
166
+ | `version_number_conflict` | 409 | Otro borrador tomó el número de versión y se acabaron los reintentos; reintentable |
167
+ | `model_provider_rate_limited` | 529 | El proveedor del modelo limitó por tasa o cuota (429); reintentable |
168
+ | `model_provider_unavailable` | 529 | El proveedor del modelo no respondió bien (5xx, red o timeout); reintentable |
169
+ | `model_provider_auth_failed` | 500 | El proveedor rechazó nuestras credenciales (401/403), incluso después de probar los modelos de respaldo. Es un problema de la plataforma: si persiste, pasale el `requestId` a soporte |
170
+ | `turn_deadline_exceeded` | 500 | El turno pasó el tiempo máximo del server y se cortó |
171
+ | `model_response_malformed` | 500 | A la respuesta del modelo le falta algo que el turno necesita (por ejemplo una tool call sin resultado) |
172
+ | `invalid_history` | 500 | El historial armado para el modelo está mal formado: bug de la plataforma |
173
+ | `tool_source_failed` | 500 | Falló el origen de una tool; hereda el `shouldRetry` de ese error |
174
+ | `delivery_failed` | 500 | Falló la entrega al canal después de sus propios reintentos |
175
+ | `internal_invariant_violation` | 500 | Se rompió algo que nuestro código garantiza: es un bug, pasale el `requestId` a soporte |
176
+
177
+ `resource_in_use` trae `details.resource`, `details.versions_count`, `details.agent_ids` (ids de los agentes, sin repetidos) y
178
+ `details.agent_versions`: `[{ agent_id, version_id, is_active }]`, las versiones de agente que bloquean el borrado (sin repetidos;
179
+ `is_active` marca la que está activa). Esas versiones asignan la skill o la conexión (o fijan una versión suya) y no se editan.
180
+ Receta: (1) por cada agente con una versión `is_active`, `agents.update(agentId, { skills: [], activate: true })` (o `mcp_connections: []`,
181
+ o la lista sin ese recurso) para que la versión activa ya no lo use; (2) `agents.versions.delete(agentId, versionId)` por cada versión
182
+ de `agent_versions` (la que era activa ya no lo es después del paso 1); (3) reintentá el borrado. O borrá el agente.
183
+
184
+ ```ts
185
+ import { isLaburenApiError, resourceInUseVersions } from "@laburen/delta-sdk/platform";
186
+
187
+ if (isLaburenApiError(err) && err.code === "resource_in_use") {
188
+ // Lista tipada `{ agent_id, version_id, is_active }[]`; vacía si el error no trae `agent_versions`.
189
+ const blocking = resourceInUseVersions(err);
190
+ for (const v of blocking) {
191
+ if (v.is_active) await platform.agents.update(v.agent_id, { skills: [], activate: true });
192
+ }
193
+ for (const v of blocking) {
194
+ await platform.agents.versions.delete(v.agent_id, v.version_id);
195
+ }
196
+ await platform.skills.delete(skillId);
197
+ }
198
+ ```
199
+
200
+ `resourceInUseVersions(err)` acepta cualquier valor y devuelve `[]` si no es un `resource_in_use`: no hace falta casteo ni comprobar `details` a mano.
201
+
202
+ `e.issues[].field` es la ruta del campo dentro del body, con el índice entre corchetes: `config.model.id`, `config.tools[3]`, `config.tools[0].url`. Una clave que el body no admite sale con una issue por clave y su nombre en `field` (por ejemplo `harness_type` en `agents.versions.create`). Un adjunto de `messages` que la API no pudo bajar dice por qué (el status o el error de red, y el host) y que la url tiene que ser pública y bajarse sin login.
203
+
204
+ Si cortás una llamada con un `signal`, lanza `LaburenAbortError` (mensaje `Request was aborted.`, el motivo del abort queda
205
+ en `error.cause`). No es un `LaburenTimeoutError`: se pregunta con `isLaburenAbortError`. Lo mismo vale para `stream.chunks` y `stream.result`.
206
+
207
+ `LaburenOAuthError.description` puede ser `null` (el server no siempre manda `error_description`): no la uses sin comprobarla.
208
+
209
+ Una clave que el body de `agents.generate` o `agents.stream` no admite (por ejemplo `max_step` en vez de `max_steps`) da 400 `invalid_request`, con una issue por clave en `issues[]`: el turno no corre. En un `invalid_skill` por un archivo con una ruta no permitida o un carácter NUL (`forbidden_path`, `invalid_character`), `details.field` trae su ruta como `files["notes.txt"]` y `issues[]` la nombra; otros errores de archivo no la traen.
210
+
211
+ Los esquemas del cuerpo de error se exportan como tipos con los nombres `ApiErrorBody` (el error de
212
+ la API) y `OAuthErrorBody` (el del login, ver la sección 7).
213
+
214
+ ## 4. Reintentos y timeout
215
+
216
+ El cliente reintenta solo los errores transitorios (408, 429, 5xx, y los fallos de conexión), con
217
+ espera creciente, y respeta el header `retry-after` cuando es razonable.
218
+
219
+ - **Solo se reintenta un pedido `GET` o uno con `Idempotency-Key`.** Los métodos que crean o
220
+ cambian cosas mandan una key automática (un UUID, el mismo en cada reintento); si querés fijarla
221
+ vos, pasá `idempotencyKey`. Una operación que no admite key se manda una sola vez.
222
+ - **El `timeout` es por intento, no por llamada.** El peor caso es `(maxRetries + 1) × timeout`
223
+ más las esperas entre reintentos.
224
+
225
+ ```ts
226
+ const agent = await platform.agents.create(
227
+ { harness_type: "mastra", name: "Soporte" },
228
+ { idempotencyKey: "alta-soporte-001", maxRetries: 4, timeout: 10_000 },
229
+ );
230
+ ```
231
+
232
+ Para cortar una llamada desde afuera, pasá un `signal` en las options; se corta con `LaburenAbortError` (sección 3).
233
+
234
+ ## 5. Paginación
235
+
236
+ Los métodos `list` devuelven un `PagePromise`. Con `await` te da la primera página; con `for await`
237
+ recorre todos los items, pidiendo las páginas que falten.
238
+
239
+ ```ts
240
+ // Una página
241
+ const page = await platform.agents.list({ limit: 20 });
242
+ console.log(page.data.length, page.has_more);
243
+
244
+ // Todos los items
245
+ for await (const agent of platform.agents.list({ limit: 100 })) {
246
+ console.log(agent.id);
247
+ }
248
+ ```
249
+
250
+ Para seguir a mano usá `after_id` (hacia adelante, con el `last_id` de la página) o `before_id`
251
+ (hacia atrás, con el `first_id`).
252
+
253
+ ## 6. Más rutas
254
+
255
+ Una línea por ruta, todas con la forma de siempre (ver el tipo de cada una en el cliente):
256
+
257
+ - `platform.models.list()`: los modelos que un agente puede usar (el `model` de la config sale de acá).
258
+ - `platform.me.get()`: quién es el token que estás usando.
259
+ - `platform.knowledge.projects.list()`: los proyectos de conocimiento; sus ids van en `config.knowledge.project_ids`. La API solo los lista: los proyectos de conocimiento se crean y se cargan en el dashboard, y las apps de Composio también se conectan ahí.
260
+ - `platform.mcp.connections.tools.list(connectionId, params?)`: las tools que ofrece el servidor MCP, consultándolo en vivo; `version_id` es opcional y por default usa la versión activa.
261
+ - `platform.meta.schemas.agentConfig()`: el JSON Schema de la config del agente.
262
+ - `search`: los `list` de agentes, skills, conexiones MCP, tokens, proyectos de conocimiento y modelos (`models.list({ search })`, por id o nombre) aceptan `search` para filtrar por texto.
263
+ - `base_version_id`: `agents.update`, `agents.versions.create` y `mcp.connections.versions.create` lo aceptan; si la versión base ya no es la última, la API contesta 409 `base_version_mismatch` y `details.latest_version_id` dice cuál es.
264
+ - `agents.versions.restore`, `mcp.connections.versions.restore` y `skills.versions.restore` aceptan `{ activate? }` en el body: por default es `true` (la restauración activa la versión) salvo que pases `activate: false`. `compare` devuelve los `diffs`; en una conexión MCP, una url distinta se ve como `url_host` (si solo cambió el path, los dos lados muestran el mismo host, porque el path es secreto).
265
+
266
+ ```ts
267
+ const models = await platform.models.list();
268
+ const page = await platform.agents.list({ search: "soporte" });
269
+ const gpt = await platform.models.list({ search: "gpt" });
270
+ ```
271
+
272
+ ## 7. Login por device code
273
+
274
+ Para una herramienta que corre en la máquina de una persona (por ejemplo una CLI), el login no
275
+ necesita guardar una clave: la persona aprueba en el navegador. Estas funciones no usan token ni
276
+ reintentan.
277
+
278
+ ```ts
279
+ import {
280
+ createPlatform,
281
+ isLaburenOAuthError,
282
+ startDeviceLogin,
283
+ waitForDeviceToken,
284
+ } from "@laburen/delta-sdk/platform";
285
+
286
+ const device = await startDeviceLogin({ clientInfo: "mi-cli en mi-laptop" });
287
+ console.log(`Abrí ${device.verification_uri_complete} y confirmá el código ${device.user_code}`);
288
+
289
+ try {
290
+ const tokens = await waitForDeviceToken({
291
+ deviceCode: device.device_code,
292
+ interval: device.interval,
293
+ expiresIn: device.expires_in,
294
+ });
295
+ const platform = createPlatform({ token: tokens.access_token });
296
+ // guardá tokens.refresh_token para renovar el acceso más adelante
297
+ } catch (error) {
298
+ if (isLaburenOAuthError(error)) {
299
+ // `error.error` es "expired_token" si venció el código, o "invalid_grant" si ya se usó o se rechazó
300
+ console.error(error.error, error.description);
301
+ } else {
302
+ throw error;
303
+ }
304
+ }
305
+ ```
306
+
307
+ Las cuatro funciones (`startDeviceLogin`, `waitForDeviceToken`, `refreshToken`, `revokeToken`) aceptan `baseUrl` (default producción). **El SDK no lee
308
+ ninguna variable de entorno** (tampoco `LABUREN_API_URL`, que es de la CLI): para otro ambiente pasá `baseUrl` a las funciones de login y a `createPlatform`.
309
+
310
+ `waitForDeviceToken` consulta cada `interval` segundos y espera a que la persona apruebe. Todas las funciones de login aceptan `timeout` (milisegundos por pedido, 30 000 por default) y `signal`. Después,
311
+ `refreshToken({ refreshToken })` cambia un refresh token por un access token nuevo, y
312
+ `revokeToken({ token })` revoca uno cuando ya no se necesita. Los errores de estas funciones son
313
+ `LaburenOAuthError`.
314
+
315
+ ## 8. Correr un turno de un agente
316
+
317
+ Dos métodos, los dos con el mismo body (`AgentGenerateParams`; `AgentStreamParams` es igual):
318
+
319
+ | Campo | Qué es | Permiso |
320
+ |---|---|---|
321
+ | `messages` | Obligatorio. Un texto, o `[{ role: "user", parts: [...] }]` con partes `{ type: "text", text }` y `{ type: "file", url, media_type, filename? }` (url `https` pública, hasta 20 MB) | `query` |
322
+ | `memory` | `{ thread?, resource? }`: conversación y usuario final (ver abajo) | `query` |
323
+ | `context` | `string[]`: textos extra que el modelo debe conocer en este turno; se unen con una línea en blanco y van antes del mensaje | `query` |
324
+ | `contact` | `{ first_name?, last_name?, email?, phone_number? }`: perfil del usuario final; solo cuenta si `memory.resource` crea un contacto nuevo | `query` |
325
+ | `versions` | `{ agents: { [agentId]: { version_id } } }`: corre esa versión en vez de la activa. La única clave permitida es el agente que llamás | `query` |
326
+ | `instructions` | Reemplaza el prompt del agente solo en este turno | `write` |
327
+ | `model` | Reemplaza el modelo solo en este turno: un id **en texto** de `models.list()` (no un objeto) | `write` |
328
+ | `model_settings` | `{ reasoning: "off" \| "low" \| "medium" \| "high" \| "max" }`; no admite otra clave y el modelo tiene que soportar ese nivel | `write` |
329
+ | `max_steps` | Tope de pasos del modelo, 1 a 200 (default 80) | `write` |
330
+
331
+ ```ts
332
+ const run = await platform.agents.generate(agentId, {
333
+ messages: [{ role: "user", parts: [{ type: "text", text: "Resumí este PDF" }, { type: "file", url: "https://acme.com/a.pdf" /* placeholder: una URL tuya */, media_type: "application/pdf" }] }],
334
+ context: ["El cliente es VIP."],
335
+ contact: { first_name: "Ana", email: "ana@acme.com" },
336
+ memory: { resource: "cliente-42" },
337
+ versions: { agents: { [agentId]: { version_id: "ver_123" /* placeholder: un id real de versión */ } } },
338
+ model: "gpt_4o_mini",
339
+ max_steps: 20,
340
+ });
341
+ ```
342
+
343
+ `model_settings: { reasoning: "low" }` solo se puede mandar si el modelo lo admite: `models.list()` trae `reasoning.levels` (y `reasoning: null` si no tiene esfuerzo configurable). En un modelo sin reasoning, la API contesta un error de validación.
344
+
345
+ Los métodos:
346
+
347
+ - `platform.agents.generate(agentId, body, options?)`: espera a que termine el turno y devuelve el JSON entero (`text`, `memory`, `cost`, `total_usage`, `tool_calls`, `sources`, `handoff`...).
348
+ - `platform.agents.stream(agentId, body, options?)`: devuelve el turno en vivo, a medida que el agente lo arma.
349
+
350
+ ```ts
351
+ const run = await platform.agents.stream(agentId, { messages: "Hola", memory: { thread } });
352
+ for await (const chunk of run.chunks) {
353
+ if (chunk.type === "text-delta") process.stdout.write(chunk.delta);
354
+ }
355
+ const { text, memory, cost } = await run.result;
356
+ ```
357
+
358
+ `memory` dice a qué conversación pertenece el turno y quién es el usuario final: `thread` es el id de una
359
+ conversación anterior (sin él, arranca una nueva) y `resource` es tu propio id del usuario final (por ejemplo el id de cliente).
360
+ Para seguir una conversación, pasá el `thread` que devolvió el turno anterior en `memory.thread`.
361
+
362
+ - Si mandás `thread` sin `resource`, se usa el usuario dueño de ese thread, y la respuesta lo devuelve en `memory.resource`.
363
+ - Si mandás un `resource` distinto al dueño del thread, la API contesta 403 `thread_resource_mismatch`. Un thread sin usuario conocido acepta cualquier `resource`.
364
+
365
+ ```ts
366
+ import type { AgentGenerateParams } from "@laburen/delta-sdk/platform";
367
+
368
+ const body: AgentGenerateParams = { messages: "Hola", memory: { resource: "cliente-42" } };
369
+ const first = await platform.agents.generate(agentId, body);
370
+ const next = await platform.agents.generate(agentId, {
371
+ messages: "¿Qué te pedí recién?",
372
+ memory: { thread: first.memory.thread }, // sin resource: usa cliente-42
373
+ });
374
+ ```
375
+
376
+ - `chunks` entrega cada pedazo del turno (`text-delta`, `reasoning-delta`, `tool-input-available`, `tool-output-available`, `source-url`...; los tipos están en `AgentRunChunk`). Cada acceso arranca desde el primer pedazo; leerlo no es obligatorio.
377
+ - `result` se resuelve con los datos del `finish` (`AgentRunMetadata`: `memory`, `cost`, `total_usage`, `handoff`...) más `text`, la unión de todos los `text-delta`. Se puede pedir sin leer `chunks`.
378
+ - Un 4xx antes de que empiece el stream lanza el error tipado al hacer `await platform.agents.stream(...)`. Un error durante el turno (`data-error` o `error`) sale como error tipado de `chunks` y de `result`; no se entrega como pedazo. Trae el status de su familia (por ejemplo 529 en `model_provider_unavailable`) y `shouldRetry` igual que un error del JSON; un `type` que el SDK no conoce cae a status 500 y `shouldRetry: null`. Si el stream se corta sin `finish`, es un `LaburenConnectionError` que trae el `thread` si ya se conocía; pasados 45 s sin recibir bytes, un `LaburenTimeoutError`.
379
+ - **La forma de los chunks no es la del JSON de `generate`.** Los chunks de `stream` siguen el protocolo de UI messages de AI SDK, en camelCase:
380
+ `{ type: "tool-input-available", toolCallId, toolName, input }`, `{ type: "tool-output-available", toolCallId, output }`, `{ type: "text-delta", id, delta }`,
381
+ `{ type: "source-url", sourceId, url, title }`, `{ type: "finish", finishReason, messageMetadata }`. Con `stream`, las tool calls llegan solo como esos chunks.
382
+ `await run.result` (`AgentRunMetadata`) trae solo `memory`, `message_id`, `cost`, `handoff`, `total_usage`, `trace_id`, `run_id` y `finish_reason` (snake_case), más `text`; no trae `tool_calls` ni `tool_results`.
383
+ Esos dos (`tool_calls[].tool_call_id`, `tool_calls[].tool_name`, `tool_calls[].args`, `tool_results`) existen solo en la respuesta JSON de `agents.generate`, en snake_case, junto con `finish_reason`, `total_usage`, `sources`, `files` y `reasoning_text`.
384
+ - `finish_reason: "tool-calls"` quiere decir que el turno cortó por `max_steps` antes de dar una respuesta final: `text` puede venir vacío. Subí `max_steps` (pide `write`) o simplificá el agente. Un turno que terminó con texto trae `"stop"`.
385
+ - Un chunk de un tipo que este SDK todavía no conoce se saltea: actualizá el SDK para verlo.
386
+ - El timeout de estas dos rutas viene del contrato (630 s por intento), no del `timeout` del cliente. Para cortar antes, pasá un `signal`.
387
+ - Se reintenta solo antes de que lleguen los headers y con la misma `Idempotency-Key`; después de eso no, porque el turno ya corre en el server y cobra.
388
+
389
+ ## 9. Bodies de ejemplo por recurso
390
+
391
+ Los tipos de cada body se exportan con el nombre `<Recurso><Verbo>Params` (`AgentCreateParams`,
392
+ `AgentVersionCreateParams`, `SkillCreateParams`, `McpConnectionCreateParams`, `AgentGenerateParams`...). Lo que
393
+ devuelve cada recurso se llama como el recurso (`Agent`, `Skill`, `McpConnection`, `Token`, `Model`) y las páginas
394
+ `AgentsPage`, `SkillsPage`, etc. Los ids de modelo salen de `platform.models.list()`.
395
+
396
+ **Agente con config, tools, skills y conexión MCP.** Se crea con la primera versión y queda activa (salvo `activate: false`):
397
+
398
+ ```ts
399
+ import type { AgentCreateParams } from "@laburen/delta-sdk/platform";
400
+
401
+ const body: AgentCreateParams = {
402
+ harness_type: "mastra",
403
+ name: "Soporte",
404
+ config: {
405
+ model: { id: "gpt_4o_mini" },
406
+ prompt: [{ type: "text", content: "Sos el agente de soporte de Acme. Respondé corto." }],
407
+ tools: [
408
+ { type: "http", id: "clima", name: "clima", url: "https://api.acme.com/clima", method: "GET" },
409
+ { type: "send_files", id: "archivos" },
410
+ ],
411
+ knowledge: { mode: "vector", project_ids: ["kp_123"] },
412
+ },
413
+ skills: [{ skill_id: "skl_123", strategy: "latest" }],
414
+ mcp_connections: [{ connection_id: "mcp_123", strategy: "latest", tools: ["buscar_pedido"] }],
415
+ };
416
+ const res = await platform.agents.create(body);
417
+ // `agents.create` y `agents.update` devuelven el agente con la versión creada adentro (`AgentWithVersion`),
418
+ // no un `{ agent, version }`: el id del agente es `res.id` y el de la versión es `res.version?.id`.
419
+ console.log(res.id, res.version?.id);
420
+ ```
421
+
422
+ `skills` y `mcp_connections` piden `config`. Con `strategy: "pin"` y `version_id` se fija una versión; con `latest` se sigue la activa. `strategy: "pin"` sin `version_id` fija, al guardar, la versión activa del recurso (o la última si no hay ninguna activa).
423
+
424
+ **Tools de un agente** (`config.tools`). Son cuatro tipos; cada uno que no sea `http` va como mucho una vez:
425
+
426
+ | `type` | Para qué | Campos |
427
+ |---|---|---|
428
+ | `http` | Llama a un endpoint | Obligatorios `type` y `url` (las variables de ruta van como `{nombre}`). Opcionales: `id` (lo asigna el server si falta), `name`, `description` (cuándo usarla), `method` (`GET` por default; `POST`, `PUT`, `DELETE`, `PATCH`), `headers`, `body`, `query_parameters`, `path_variables`, `with_approval` |
429
+ | `thinking` | El modelo escribe su razonamiento antes de responder | `id?`, `instructions?`, `max_thoughts?` |
430
+ | `send_files` | El modelo manda archivos al usuario | `id?` |
431
+ | `request_human` | El modelo pasa la conversación a una persona | `id?` |
432
+
433
+ `headers`, `body`, `query_parameters` y `path_variables` son **listas** de `{ key, value?, description?, is_user_provided?, required?, accepted_values?, type? }`, no objetos ni textos.
434
+ `value` es un valor fijo en cada llamada; con `is_user_provided: true` lo completa el modelo en cada llamada.
435
+
436
+ ```ts
437
+ const tool = {
438
+ type: "http" as const,
439
+ name: "clima",
440
+ description: "Consulta el clima de una ciudad",
441
+ url: "https://api.acme.com/clima/{country}",
442
+ method: "GET" as const,
443
+ headers: [{ key: "Authorization", value: "Bearer <clave>" }],
444
+ path_variables: [{ key: "country", is_user_provided: true, required: true, description: "Código de país" }],
445
+ query_parameters: [{ key: "city", is_user_provided: true, required: true, accepted_values: ["Madrid", "Lima"] }],
446
+ };
447
+ ```
448
+
449
+ Regla de `thinking`: solo va con un modelo que no razona, o con `model.reasoning_effort: "off"`. Con un modelo que razona (esfuerzo distinto de `off`) la API la rechaza con `invalid_agent_config`. Para pasar a un modelo que razona, mandá `model` y la lista `tools` completa sin `thinking` en un solo `agents.update`. Lo mismo vale al correr: una versión con `thinking` y una corrida con un modelo que razona falla con `invalid_request` (`details.field` = `model_settings.reasoning`); se arregla con `model_settings: { reasoning: "off" }` en esa corrida (si el modelo puede apagarlo) o corriendo otra versión sin `thinking` (`versions: { agents: { [agentId]: { version_id } } }`).
450
+
451
+ **Avisos de la versión.** La respuesta de un llamado que crea una versión puede traer `warnings[]`: en `version.warnings` con `agents.create` y `agents.update` (devuelven el agente con la versión creada en `version`), y en `warnings` de primer nivel con `agents.versions.create` (devuelve la versión misma; `agents.versions.restore` no trae ninguno); `code` es uno de dos: `mcp_tools_unverified` (el servidor MCP no contestó y los nombres de tools del filtro se guardaron sin verificar) o `no_changes` (la versión nueva es idéntica a la última; se crea igual). `connection_id` es opcional: solo viene con `mcp_tools_unverified`. Un `get` posterior no lo trae.
452
+
453
+ **Skill con archivos.** `files` es un objeto `ruta: contenido`. Solo se aceptan `SKILL.md` (obligatorio) y archivos
454
+ bajo `references/`. `SKILL.md` empieza con un frontmatter con `name` (igual al `name` de la skill) y `description`:
455
+
456
+ ```ts
457
+ import type { SkillCreateParams } from "@laburen/delta-sdk/platform";
458
+
459
+ const body: SkillCreateParams = {
460
+ name: "devoluciones",
461
+ files: {
462
+ "SKILL.md": "---\nname: devoluciones\ndescription: Cómo procesar una devolución.\n---\n\nSeguí los pasos de references/pasos.md.",
463
+ "references/pasos.md": "1. Pedí el número de pedido.\n2. ...",
464
+ },
465
+ };
466
+ const skill = await platform.skills.create(body);
467
+ ```
468
+
469
+ `skills.create` y `skills.versions.create` devuelven también `warnings`: una lista de textos con problemas que la API encontró al leer `SKILL.md` y que no frenaron el guardado. Si la versión nueva es idéntica a la última, la lista trae el texto `The new version is identical to the latest one.`
470
+
471
+ Igual que los agentes y las conexiones MCP, la skill activa su primera versión al crearse; pasá `activate: false` para que
472
+ quede sin versión activa.
473
+
474
+ **Conexión MCP:**
475
+
476
+ ```ts
477
+ import type { McpConnectionCreateParams } from "@laburen/delta-sdk/platform";
478
+
479
+ const body: McpConnectionCreateParams = {
480
+ name: "pedidos",
481
+ url: "https://mcp.acme.com/mcp",
482
+ headers: { Authorization: "Bearer <clave>" },
483
+ };
484
+ const connection = await platform.mcp.connections.create(body);
485
+ ```
486
+
487
+ **Qué devuelven `delete`, `restore` y `revoke`.** Los `delete` devuelven `{ type, id }` con el tipo del objeto borrado (`agent_deleted`, `skill_deleted`, `mcp_connection_deleted`, `agent_version_deleted`, `skill_version_deleted`, `mcp_connection_version_deleted`) y el id. `tokens.revoke(id)` devuelve el token con `revoked_at`; revocar dos veces no falla. `versions.restore` crea una versión **nueva** con el contenido de la elegida (su `change_message` es "Restored from version N") y la activa, salvo que pases `activate: false`.
488
+
489
+ `platform.me.get()` trae `user: null` cuando el token es de una organización (no hay una persona detrás). El `limit` de los `list` va de 1 a 100.
490
+
491
+ ## 10. Editar: `update` y `versions.create`
492
+
493
+ Los dos crean una versión nueva del agente, pero no son lo mismo:
494
+
495
+ - `platform.agents.update(id, { config })` parte de la **última** versión y cambia solo las claves de `config` que mandás; cada una se reemplaza entera
496
+ (por ejemplo `config: { prompt }` deja el modelo y las tools como estaban, pero mandar `tools` reemplaza la lista completa). No activa
497
+ la versión nueva salvo que pases `activate: true`.
498
+ - `platform.agents.versions.create(id, body)` escribe la versión **entera**: lo que no mandás vuelve a su default, y si no mandás
499
+ `skills` o `mcp_connections` la versión queda sin ninguna. Nunca activa; para eso, `platform.agents.versions.activate(...)`.
500
+
501
+ Para cambiar un detalle usá `update`; para reemplazar todo, `versions.create`. Un `update` que solo cambia `name` o `description` no crea versión; con `config`, `skills` o `mcp_connections` sí la crea.
502
+ `skills` y `mcp_connections` en `update` reemplazan la lista entera de asignadas (mandá la lista completa, no solo lo nuevo).
503
+
504
+ ## 11. Conexiones MCP: renombrar
505
+
506
+ `platform.mcp.connections.update(id, { name })` solo renombra. Para cambiar la url o los headers se crea otra versión con
507
+ `platform.mcp.connections.versions.create(...)`; sin `url` conserva la de la última versión, y sin `headers` conserva sus headers (`headers: {}` los quita). La url siempre vuelve como `[REDACTED]`, así que así se cambian solo los headers. Ojo: las tools que ve el agente llevan el nombre de la conexión como prefijo, así que
508
+ **renombrar una conexión cambia el nombre de sus tools**. La API no avisa; si un prompt o un `config` nombra una tool por su nombre
509
+ viejo, hay que actualizarlo.
510
+
511
+ ### Versiones, respuestas y skills: tres datos
512
+
513
+ Datos sueltos que conviene saber:
514
+
515
+ - El body de `agents.versions.create` **no lleva `harness_type`** (ese campo es solo de `agents.create`): la versión usa el del agente.
516
+ - Las respuestas de `create` (`agents.create` con `config`, `skills.create`, `mcp.connections.create`) traen la primera `version` incrustada (en `agents.create` el tipo admite `null` porque un `create` sin `config` no crea versión; con `config` siempre viene); `get` **no**: devuelve el recurso con `active_version_id`, y la config se lee con `versions.get(id, active_version_id)`.
517
+ - Los threads y las conversaciones no se pueden borrar por la API.
518
+ - Una skill **no se renombra**: no existe `skills.update`. Para otro nombre, creá otra skill y borrá la vieja (el `name` del frontmatter de `SKILL.md` tiene que coincidir con el `name`).
519
+
520
+ ## 12. Permisos por operación
521
+
522
+ Del contrato (`security` de cada operación). Los permisos son independientes, no una escalera: un token con solo `admin` no puede leer. Para un script que borra, pedí `read`, `write` y `admin` (y `query` si corre turnos). Un `PermissionError` trae `details.required` con el permiso que faltó.
523
+
524
+ | Permiso | Operaciones |
525
+ |---|---|
526
+ | ninguno (cualquier credencial válida) | `me.get`, `tokens.list`, `tokens.create`, `tokens.update`, `tokens.revoke`; `me.organizations.list` anda con una sesión de usuario o con cualquier credencial y ignora el header de organización; `meta.schemas.agentConfig` es público (sin token) |
527
+ | `read` | todos los `get`, `list` y `versions.compare` de agentes, skills y conexiones MCP; `mcp.connections.tools.list`; `knowledge.projects.list`; `models.list` |
528
+ | `write` | `agents.create`, `agents.update`, `agents.versions.create/activate/restore/delete`; lo mismo de `skills` y `mcp.connections` (`create`, `update` en MCP, `versions.create/activate/restore/delete`) |
529
+ | `admin` | `agents.delete`, `skills.delete`, `mcp.connections.delete` |
530
+ | `query` | `agents.generate`, `agents.stream` (más `write` si el body trae `instructions`, `model`, `model_settings` o `max_steps`) |
531
+
532
+ Crear un token de `kind: "organization"` pide `admin`, y los permisos de un token nuevo no pueden superar los tuyos. `tokens.update(id, params)` solo acepta `name` y `description` (`null` la borra); los permisos, el tipo y la organización de un token no se cambian: creá otro. `tokens.list` muestra tus tokens personales y, con `admin`, también los de la organización.
533
+ Borrar una versión (`versions.delete`) pide solo `write`, pero borrar el recurso entero pide `admin`.
534
+
535
+ ## 13. Índice de métodos
536
+
537
+ Ids como parámetros posicionales, después `params`, después `options`. `list` devuelve `PagePromise` (sección 5). Cada método está en `platform.<ruta>`.
538
+
539
+ | Recurso | Métodos |
540
+ |---|---|
541
+ | `agents` | `create(params)` · `get(id)` · `list(params?)` · `update(id, params)` · `delete(id)` · `generate(id, params)` · `stream(id, params)` |
542
+ | `agents.versions` | `create(id, params)` · `get(id, versionId)` · `list(id, params?)` · `compare(id, params)` · `activate(id, versionId)` · `restore(id, versionId, params?)` · `delete(id, versionId)` |
543
+ | `skills` | `create(params)` · `get(id)` · `list(params?)` · `delete(id)` (sin `update`) |
544
+ | `skills.versions` | `create` · `get` · `list` · `compare` · `activate` · `restore` · `delete` (igual que `agents.versions`) |
545
+ | `mcp.connections` | `create(params)` · `get(id)` · `list(params?)` · `update(id, { name })` · `delete(id)` |
546
+ | `mcp.connections.tools` | `list(connectionId, params?)` |
547
+ | `mcp.connections.versions` | `create` · `get` · `list` · `compare` · `activate` · `restore` · `delete` (igual que `agents.versions`) |
548
+ | `knowledge.projects` | `list(params?)` |
549
+ | `models` | `list(params?)` |
550
+ | `tokens` | `create(params)` · `list(params?)` · `update(id, params)` · `revoke(id)` |
551
+ | `me` | `get()` · `organizations.list(params?)` |
552
+ | `meta.schemas` | `agentConfig()` |
553
+
554
+ `compare` pide `params` `{ from, to }` (ids de versión); el tipo es `<Recurso>VersionCompareParams`.
@@ -77,8 +77,8 @@ perdió al final.
77
77
  | `internos` | eventos que se perdieron porque algo entre armar el evento y mandarlo lanzó una excepción (por ejemplo, un `attributes` con un getter roto) — la única razón sin una causa de negocio detrás |
78
78
 
79
79
  **El límite honesto de `incompletos`: mezcla "en vuelo" con "perdido", y en un sobre suelto no se
80
- puede leer como pérdida.** El `drops` de un sobre es un snapshot tomado en `armarSobre`, **antes**
81
- de que el `enviar` de ESE MISMO evento termine. Con varias capturas seguidas en la misma invocación,
80
+ puede leer como pérdida.** El `drops` de un sobre es un snapshot tomado en `buildEnvelope`, **antes**
81
+ de que el `send` de ESE MISMO evento termine. Con varias capturas seguidas en la misma invocación,
82
82
  cada sobre ve los envíos anteriores todavía pendientes: `incompletos` sube de 0 a 1 a 2 sin que se
83
83
  haya perdido nada, porque esos POST siguen en vuelo, no fallaron. **Por eso `incompletos` solo sirve
84
84
  agregado sobre muchos isolates**, donde ese sesgo del último evento en vuelo se promedia y lo que
@@ -17,7 +17,7 @@ es un bug: es el límite documentado en [guia.md](./guia.md). La solución es su
17
17
  ## `413`
18
18
 
19
19
  Cuerpo de la request > 512 KB. Esto **no debería pasar en el uso normal**: el orden real del
20
- pipeline es `scrubEvento` → `aplicarBeforeSend` → `armarSobre` → `serializarAcotado` — **el recorte
20
+ pipeline es `scrubEvent` → `applyBeforeSend` → `buildEnvelope` → `serializeCapped` — **el recorte
21
21
  corre DESPUÉS de `beforeSend`, no antes**. Un `beforeSend` que agranda el evento (por ejemplo,
22
22
  concatenando datos extra en `attributes` o en `message`) **también pasa por el recorte**: esa no es
23
23
  una causa posible del `413`.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@laburen/delta-sdk",
3
- "version": "1.3.0",
4
- "description": "Instrumentación para los workers de Laburen en Cloudflare, sin dependencias de runtime. Puerta /telemetry: errores y eventos a la ingesta",
3
+ "version": "1.5.0-canary.10",
4
+ "description": "Instrumentación para los workers de Laburen en Cloudflare, sin dependencias de runtime. Puertas: /telemetry (errores y eventos a la ingesta) y /platform (cliente de la API de plataforma)",
5
5
  "type": "module",
6
6
  "sideEffects": false,
7
7
  "license": "MIT",
@@ -14,19 +14,25 @@
14
14
  "types": "./dist/telemetry/index.d.ts",
15
15
  "import": "./dist/telemetry/index.js"
16
16
  },
17
+ "./platform": {
18
+ "types": "./dist/platform/index.d.ts",
19
+ "import": "./dist/platform/index.js"
20
+ },
17
21
  "./package.json": "./package.json"
18
22
  },
19
23
  "files": [
20
24
  "dist",
21
25
  "src",
22
26
  "docs",
27
+ "!docs/superpowers",
28
+ "!docs/claude-rules",
23
29
  "README.md",
24
30
  "CHANGELOG.md",
25
31
  "LICENSE"
26
32
  ],
27
33
  "scripts": {
28
34
  "prepack": "npm run build",
29
- "build": "rm -rf dist && tsc -p tsconfig.build.json",
35
+ "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
30
36
  "typecheck": "tsc --noEmit && tsc --noEmit -p test/tsconfig.json",
31
37
  "lint": "biome check .",
32
38
  "lint:fix": "biome check --write .",
@@ -34,14 +40,18 @@
34
40
  "test:watch": "vitest",
35
41
  "version:check": "node scripts/check-version.mjs",
36
42
  "check:publicable": "node scripts/check-publicable.mjs",
37
- "check": "npm run build && publint && attw --pack . && npm run check:publicable && npm run version:check",
38
- "smoke": "node scripts/smoke.mjs"
43
+ "check": "npm run build && publint && attw --pack . && npm run check:publicable && npm run version:check && node scripts/check-boundaries.mjs",
44
+ "smoke": "node scripts/smoke.mjs",
45
+ "contract:pull": "node scripts/contract-pull.mjs",
46
+ "generate": "openapi-typescript contract/openapi.json --default-non-nullable false -o src/platform/generated/types.ts && node scripts/generate-resources.mjs",
47
+ "check:generated": "npm run generate && node scripts/check-generated.mjs"
39
48
  },
40
49
  "dependencies": {},
41
50
  "devDependencies": {
42
51
  "@arethetypeswrong/cli": "^0.18.5",
43
52
  "@biomejs/biome": "^2.5.6",
44
53
  "@cloudflare/vitest-pool-workers": "^0.12.21",
54
+ "openapi-typescript": "7.13.0",
45
55
  "publint": "^0.3.22",
46
56
  "typescript": "^5.9.3",
47
57
  "vitest": "~3.2.0",