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

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 +184 -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 +88 -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 +5181 -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 +661 -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 +225 -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 +84 -0
  125. package/src/platform/generated/types.ts +5181 -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,661 @@
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
+ Este primer ejemplo es un worker de Cloudflare Workers: `Env` es el tipo que genera `wrangler types` con tus variables. Para Node, ver [En un script de Node](#en-un-script-de-node) más abajo.
17
+
18
+ ```ts
19
+ import { createPlatform } from "@laburen/delta-sdk/platform";
20
+
21
+ export default {
22
+ async fetch(request: Request, env: Env): Promise<Response> {
23
+ // Crealo adentro del handler: no hace ningún pedido al crearse, pero no va en el scope global.
24
+ const platform = createPlatform({ token: env.LABUREN_PLATFORM_TOKEN });
25
+
26
+ const agent = await platform.agents.get("agt_123");
27
+ return Response.json(agent);
28
+ },
29
+ };
30
+ ```
31
+
32
+ El `token` puede ser un texto o una función `async` que lo devuelve (útil si lo renovás). Los
33
+ métodos están agrupados por recurso (`agents`, `skills`, `tokens`, `models`, `me`,
34
+ `knowledge.projects`, `mcp.connections`), y los de versiones cuelgan del recurso (`agents.versions.list(...)`). Cada método
35
+ recibe primero los ids de la ruta, después los parámetros y al final las `options` de la llamada. Un método sin
36
+ parámetros es `(…ids, options?)`: `platform.agents.get(id, { signal })`, `platform.me.get({ signal })`. Uno con parámetros
37
+ (`list`, `create`, `update`...) es `(…ids, params, options?)`: `platform.agents.list({}, { signal })`.
38
+
39
+ 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
40
+ tu código llamaba `platform.agents.get(id, undefined, { signal })` o `platform.me.get({}, { signal })`, sacá ese argumento.
41
+
42
+ Opciones del cliente (todas menos `token` son opcionales): `organization`, `baseUrl`, `timeout`
43
+ (milisegundos, 30 000 por default), `maxRetries` (2 por default) y `fetch`.
44
+
45
+ `baseUrl` es producción por default (`https://dashboard.laburen.com/api/platform/v1`). Pasalo solo
46
+ para apuntar a otro ambiente.
47
+
48
+ ### En un script de Node
49
+
50
+ 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`).
51
+
52
+ Para un script local, sacá un token con la CLI y guardalo en una variable de entorno. El valor
53
+ sale una sola vez, en el campo `value` de la respuesta:
54
+
55
+ ```bash
56
+ laburen orgs list # copiá el id de la organización
57
+ laburen tokens create --org <organization_id> --name mi-script --kind personal \
58
+ --permissions '["read","write","query"]' --json
59
+ export LABUREN_TOKEN=<el valor>
60
+ ```
61
+
62
+ La sesión de la CLI suele abarcar todas tus organizaciones, así que el comando necesita `--org <organization_id>`.
63
+ 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`;
64
+ con `--all-organizations` el token sirve en todas y cada llamada lleva la organización (sección 2).
65
+
66
+ ```ts
67
+ import { createPlatform } from "@laburen/delta-sdk/platform";
68
+
69
+ const platform = createPlatform({ token: process.env.LABUREN_TOKEN! });
70
+ const me = await platform.me.get();
71
+ ```
72
+
73
+ Cada operación pide un permiso (tabla completa en la sección 12). Un token sin el permiso recibe un `PermissionError`.
74
+ Si preferís no guardar una clave, ver el login por device code (sección 7).
75
+
76
+ ## 2. Organización
77
+
78
+ Si tu token da acceso a más de una organización, decile con cuál trabajar. Se manda en el header
79
+ `x-laburen-organization`.
80
+
81
+ ```ts
82
+ // Para todo el cliente
83
+ const platform = createPlatform({ token, organization: "org_123" });
84
+
85
+ // O solo para una llamada
86
+ await platform.agents.list({}, { organization: "org_456" });
87
+ ```
88
+
89
+ `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.
90
+
91
+ ## 3. Errores
92
+
93
+ Todo lo que falla lanza una clase propia. Si la API contestó con un error, es un
94
+ `LaburenApiError`, y su subclase sale del `type` del cuerpo de error (no del status):
95
+ `InvalidRequestError`, `AuthenticationError`, `BillingError`, `PermissionError`, `NotFoundError`, `ConflictError`, `RateLimitError`, `ApiError` y
96
+ `OverloadedError`. Si el cuerpo no es el del catálogo (por ejemplo, el HTML de un proxy con un 5xx),
97
+ es el `LaburenApiError` base. Por eso conviene preguntar con `isLaburenApiError` y mirar `e.type` y
98
+ `e.status`, en vez de `instanceof` sobre cada subclase. Si no hubo respuesta, es un
99
+ `LaburenConnectionError` (o `LaburenTimeoutError`, que es un caso del anterior).
100
+
101
+ ```ts
102
+ import {
103
+ isLaburenApiError,
104
+ isLaburenConnectionError,
105
+ } from "@laburen/delta-sdk/platform";
106
+
107
+ try {
108
+ await platform.agents.get("agt_123");
109
+ } catch (error) {
110
+ if (isLaburenApiError(error) && error.type === "not_found_error") {
111
+ // el agente no existe
112
+ } else if (isLaburenApiError(error)) {
113
+ console.error(error.status, error.type, error.code, error.message, error.requestId);
114
+ } else if (isLaburenConnectionError(error)) {
115
+ console.error("no hubo respuesta", error.message);
116
+ } else {
117
+ throw error;
118
+ }
119
+ }
120
+ ```
121
+
122
+ Los `is...` sirven también si el error cruzó un límite entre dos copias del paquete, donde
123
+ `instanceof` falla. `requestId` es lo que tenés que pasarle a soporte.
124
+
125
+ Un `LaburenApiError` trae además tres campos para decidir qué hacer:
126
+
127
+ - `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 `[]`).
128
+ - `e.details`: datos extra según el `code`, por ejemplo `details.latest_version_id` en `base_version_mismatch`. Si no hay, es `{}`.
129
+ - `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.
130
+
131
+ Un argumento que no sirve lanza `LaburenArgumentError` (se pregunta con `isLaburenArgumentError`) **antes de mandar nada**: un id de ruta
132
+ vacío, `null`, `undefined`, `.` o `..`, o un `token` vacío. Los demás ids (`"0"`, con `/`) se mandan, codificados.
133
+
134
+ El token vacío falla en dos momentos distintos, siempre con el mensaje `The token must not be empty.`:
135
+ - `createPlatform({ token: "" })` lanza **al crear el cliente**, no en la primera llamada.
136
+ - Un `token` que no es texto (por ejemplo `process.env.LABUREN_TOKEN!` sin la variable definida) o una función que devuelve
137
+ `""` pasan la creación y lanzan en **cada llamada**, sin mandar el pedido.
138
+
139
+ Todos los códigos. El status sale de la familia (`type`); `shouldRetry` es `true` solo donde dice "reintentable":
140
+
141
+ | `code` | Status | Qué significa y qué hacer |
142
+ |---|---|---|
143
+ | `invalid_request` | 400 | El path, la query o el body no cumplen el esquema; `issues` lista cada campo inválido |
144
+ | `invalid_agent_config` | 400 | La config del agente no es válida o no puede correr (tools, historial, versión, proveedor); mirá `issues` |
145
+ | `invalid_skill` | 400 | La skill no sigue el formato; `details.reason` dice la regla (`forbidden_path`, `invalid_character`, `invalid_frontmatter`, `missing_skill_md`, `name_mismatch`, `limit_exceeded`, `no_active_version`) y `issues` dice qué archivo |
146
+ | `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 |
147
+ | `tool_execution_failed` | 400 | Una tool que llama a un sistema del cliente recibió un error o ninguna respuesta |
148
+ | `legacy_agent_not_supported` | 400 | Esa operación de la API nueva se pidió sobre un agente legacy |
149
+ | `conversational_mode_not_supported` | 400 | El agente usa el modo conversacional, que este endpoint todavía no soporta |
150
+ | `unsupported_trigger` | 400 | El harness recibió un tipo de disparo que no sabe correr |
151
+ | `invalid_token` | 401 | La credencial falta, no existe, venció o fue revocada |
152
+ | `credits_exhausted` | 402 | La organización no tiene créditos para correr el agente |
153
+ | `insufficient_permissions` | 403 | La credencial o el rol no alcanzan. Cuando falta un permiso, `details.required` trae cuál; en los otros casos no viene `required` y `details` dice qué campo chocó (por ejemplo `details.field: "all_organizations"`, sección 12) |
154
+ | `organization_access_denied` | 403 | No tenés membresía activa en esa organización, o el header no coincide con la credencial |
155
+ | `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) |
156
+ | `thread_resource_mismatch` | 403 | `memory.resource` no es el dueño de `memory.thread` (sección 8) |
157
+ | `agent_not_found` | 404 | El agente no existe o no es de la organización |
158
+ | `config_version_not_found` | 404 | La versión de config no existe o no es de ese agente |
159
+ | `skill_not_found` | 404 | La skill no existe o no es de la organización |
160
+ | `skill_version_not_found` | 404 | La versión de skill no existe o no es de una skill de la organización |
161
+ | `mcp_connection_not_found` | 404 | La conexión MCP no existe o no es de la organización |
162
+ | `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 |
163
+ | `token_not_found` | 404 | Revocar o leer un token que no existe o no es tuyo |
164
+ | `conversation_not_found` | 404 | `memory.thread` no existe, o es de otra organización u otro agente (mismo error en los dos casos) |
165
+ | `resource_in_use` | 409 | Borrar una skill, una conexión MCP o una versión suya que usan versiones de agentes. Receta abajo |
166
+ | `version_in_use` | 409 | Borrar la versión activa; activá otra primero |
167
+ | `base_version_mismatch` | 409 | `base_version_id` ya no es la última; `details.latest_version_id` dice cuál es |
168
+ | `skill_name_taken` | 409 | Ya hay una skill con ese nombre en la organización |
169
+ | `mcp_connection_name_taken` | 409 | Ya hay una conexión MCP con ese nombre (se compara como prefijo de tool) |
170
+ | `idempotency_key_reused` | 409 | La misma `Idempotency-Key` con otro body: usá una key nueva |
171
+ | `idempotency_key_in_progress` | 409 | La misma key y el mismo body mientras el primer pedido sigue corriendo; reintentable: esperá unos segundos y repetí |
172
+ | `ai_disabled_for_conversation` | 409 | La IA está apagada en la conversación (la tomó una persona): el turno no corre |
173
+ | `version_number_conflict` | 409 | Otro borrador tomó el número de versión y se acabaron los reintentos; reintentable |
174
+ | `model_provider_rate_limited` | 529 | El proveedor del modelo limitó por tasa o cuota (429); reintentable |
175
+ | `model_provider_unavailable` | 529 | El proveedor del modelo no respondió bien (5xx, red o timeout); reintentable |
176
+ | `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 |
177
+ | `turn_deadline_exceeded` | 500 | El turno pasó el tiempo máximo del server y se cortó |
178
+ | `model_response_malformed` | 500 | A la respuesta del modelo le falta algo que el turno necesita (por ejemplo una tool call sin resultado) |
179
+ | `invalid_history` | 500 | El historial armado para el modelo está mal formado: bug de la plataforma |
180
+ | `tool_source_failed` | 500 | Falló el origen de una tool; hereda el `shouldRetry` de ese error |
181
+ | `delivery_failed` | 500 | Falló la entrega al canal después de sus propios reintentos |
182
+ | `internal_invariant_violation` | 500 | Se rompió algo que nuestro código garantiza: es un bug, pasale el `requestId` a soporte |
183
+
184
+ `resource_in_use` trae `details.resource`, `details.versions_count`, `details.agent_ids` (ids de los agentes, sin repetidos) y
185
+ `details.agent_versions`: `[{ agent_id, version_id, is_active }]`, las versiones de agente que bloquean el borrado (sin repetidos;
186
+ `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.
187
+ Receta: (1) por cada agente con una versión `is_active`, `agents.update(agentId, { skills: [], activate: true })` (o `mcp_connections: []`,
188
+ 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
189
+ de `agent_versions` (la que era activa ya no lo es después del paso 1); (3) reintentá el borrado. O borrá el agente.
190
+
191
+ ```ts
192
+ import { isLaburenApiError, resourceInUseVersions } from "@laburen/delta-sdk/platform";
193
+
194
+ if (isLaburenApiError(err) && err.code === "resource_in_use") {
195
+ // Lista tipada `{ agent_id, version_id, is_active }[]`; vacía si el error no trae `agent_versions`.
196
+ const blocking = resourceInUseVersions(err);
197
+ for (const v of blocking) {
198
+ if (v.is_active) await platform.agents.update(v.agent_id, { skills: [], activate: true });
199
+ }
200
+ for (const v of blocking) {
201
+ await platform.agents.versions.delete(v.agent_id, v.version_id);
202
+ }
203
+ await platform.skills.delete(skillId);
204
+ }
205
+ ```
206
+
207
+ `resourceInUseVersions(err)` acepta cualquier valor y devuelve `[]` si no es un `resource_in_use`: no hace falta casteo ni comprobar `details` a mano.
208
+
209
+ `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.
210
+
211
+ Si cortás una llamada con un `signal`, lanza `LaburenAbortError` (mensaje `Request was aborted.`, el motivo del abort queda
212
+ en `error.cause`). No es un `LaburenTimeoutError`: se pregunta con `isLaburenAbortError`. Lo mismo vale para `stream.chunks` y `stream.result`.
213
+
214
+ `LaburenOAuthError.description` puede ser `null` (el server no siempre manda `error_description`): no la uses sin comprobarla.
215
+
216
+ 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. Todo `invalid_skill` trae `details.field` y, por eso, `issues[]`: la ruta del archivo con el problema (`files["notes.txt"]`) cuando es de un archivo puntual (`forbidden_path`, `invalid_character`), y `files["SKILL.md"]` en el resto (frontmatter, límites, `SKILL.md` faltante, `name` distinto).
217
+
218
+ Los esquemas del cuerpo de error se exportan como tipos con los nombres `ApiErrorBody` (el error de
219
+ la API) y `OAuthErrorBody` (el del login, ver la sección 7).
220
+
221
+ ## 4. Reintentos y timeout
222
+
223
+ El cliente reintenta solo los errores transitorios (408, 429, 5xx, y los fallos de conexión), con
224
+ espera creciente, y respeta el header `retry-after` cuando es razonable.
225
+
226
+ - **Solo se reintenta un pedido `GET` o uno con `Idempotency-Key`.** Los métodos que crean o
227
+ cambian cosas mandan una key automática (un UUID, el mismo en cada reintento); si querés fijarla
228
+ vos, pasá `idempotencyKey`. Una operación que no admite key se manda una sola vez.
229
+ - **El `timeout` es por intento, no por llamada.** El peor caso es `(maxRetries + 1) × timeout`
230
+ más las esperas entre reintentos.
231
+
232
+ ```ts
233
+ const agent = await platform.agents.create(
234
+ { harness_type: "mastra", name: "Soporte" },
235
+ { idempotencyKey: "alta-soporte-001", maxRetries: 4, timeout: 10_000 },
236
+ );
237
+ ```
238
+
239
+ Para cortar una llamada desde afuera, pasá un `signal` en las options; se corta con `LaburenAbortError` (sección 3).
240
+
241
+ ## 5. Paginación
242
+
243
+ Los métodos `list` devuelven un `PagePromise`. Con `await` te da la primera página; con `for await`
244
+ recorre todos los items, pidiendo las páginas que falten.
245
+
246
+ ```ts
247
+ // Una página
248
+ const page = await platform.agents.list({ limit: 20 });
249
+ console.log(page.data.length, page.has_more);
250
+
251
+ // Todos los items
252
+ for await (const agent of platform.agents.list({ limit: 100 })) {
253
+ console.log(agent.id);
254
+ }
255
+ ```
256
+
257
+ Para seguir a mano usá `after_id` (hacia adelante, con el `last_id` de la página) o `before_id`
258
+ (hacia atrás, con el `first_id`).
259
+
260
+ ## 6. Más rutas
261
+
262
+ Una línea por ruta, todas con la forma de siempre (ver el tipo de cada una en el cliente):
263
+
264
+ - `platform.models.list()`: los modelos que un agente puede usar (el `model` de la config sale de acá).
265
+ - `platform.me.get()`: quién es el token que estás usando.
266
+ - `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í.
267
+ - `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.
268
+ - `platform.meta.schemas.agentConfig()`: el JSON Schema de la config del agente.
269
+ - `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.
270
+ - `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.
271
+ - `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).
272
+
273
+ ```ts
274
+ const models = await platform.models.list();
275
+ const page = await platform.agents.list({ search: "soporte" });
276
+ const gpt = await platform.models.list({ search: "gpt" });
277
+ ```
278
+
279
+ `models.list()` es un `list` como cualquier otro: con `await` trae solo la primera página (20 modelos por default). Para
280
+ recorrerlos todos usá `for await` (sección 5). `reasoning` es `null` en un modelo sin esfuerzo configurable; si no,
281
+ trae los `levels` que acepta y el `default`:
282
+
283
+ ```ts
284
+ import type { Model } from "@laburen/delta-sdk/platform";
285
+
286
+ const all: Model[] = [];
287
+ for await (const model of platform.models.list({ limit: 100 })) all.push(model);
288
+
289
+ // Los modelos que aceptan `reasoning_effort: "high"`.
290
+ const highReasoning = all.filter((m) => m.reasoning?.levels.includes("high"));
291
+ console.log(highReasoning.map((m) => m.id));
292
+ ```
293
+
294
+ ## 7. Login por device code
295
+
296
+ Para una herramienta que corre en la máquina de una persona (por ejemplo una CLI), el login no
297
+ necesita guardar una clave: la persona aprueba en el navegador. Estas funciones no usan token ni
298
+ reintentan.
299
+
300
+ ```ts
301
+ import {
302
+ createPlatform,
303
+ isLaburenOAuthError,
304
+ startDeviceLogin,
305
+ waitForDeviceToken,
306
+ } from "@laburen/delta-sdk/platform";
307
+
308
+ const device = await startDeviceLogin({ clientInfo: "mi-cli en mi-laptop" });
309
+ console.log(`Abrí ${device.verification_uri_complete} y confirmá el código ${device.user_code}`);
310
+
311
+ try {
312
+ const tokens = await waitForDeviceToken({
313
+ deviceCode: device.device_code,
314
+ interval: device.interval,
315
+ expiresIn: device.expires_in,
316
+ });
317
+ const platform = createPlatform({ token: tokens.access_token });
318
+ // guardá tokens.refresh_token para renovar el acceso más adelante
319
+ } catch (error) {
320
+ if (isLaburenOAuthError(error)) {
321
+ // `error.error` es "expired_token" si venció el código, o "invalid_grant" si ya se usó o se rechazó
322
+ console.error(error.error, error.description);
323
+ } else {
324
+ throw error;
325
+ }
326
+ }
327
+ ```
328
+
329
+ Las cuatro funciones (`startDeviceLogin`, `waitForDeviceToken`, `refreshToken`, `revokeToken`) aceptan `baseUrl` (default producción). **El SDK no lee
330
+ 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`.
331
+
332
+ `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,
333
+ `refreshToken({ refreshToken })` cambia un refresh token por un access token nuevo, y
334
+ `revokeToken({ token })` revoca uno cuando ya no se necesita. Los errores de estas funciones son
335
+ `LaburenOAuthError`.
336
+
337
+ ## 8. Correr un turno de un agente
338
+
339
+ Dos métodos, los dos con el mismo body (`AgentGenerateParams`; `AgentStreamParams` es igual):
340
+
341
+ | Campo | Qué es | Permiso |
342
+ |---|---|---|
343
+ | `messages` | Obligatorio. Un texto, o `[{ role: "user", parts: [...] }]` (`role` acepta solo `"user"`: no se mandan mensajes del asistente ni de sistema; el historial lo pone el `thread`) con partes `{ type: "text", text }` y `{ type: "file", url, media_type, filename? }` (url `https` pública, hasta 20 MB) | `query` |
344
+ | `memory` | `{ thread?, resource? }`: conversación y usuario final (ver abajo) | `query` |
345
+ | `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` |
346
+ | `contact` | `{ first_name?, last_name?, email?, phone_number? }`: perfil del usuario final; solo cuenta si `memory.resource` crea un contacto nuevo. El modelo no lo ve: para darle datos del usuario, usá `context` | `query` |
347
+ | `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` |
348
+ | `instructions` | Reemplaza el prompt del agente solo en este turno | `write` |
349
+ | `model` | Reemplaza el modelo solo en este turno: un id **en texto** de `models.list()` (no un objeto) | `write` |
350
+ | `model_settings` | `{ reasoning: "off" \| "low" \| "medium" \| "high" \| "max" }`; no admite otra clave y el modelo tiene que soportar ese nivel | `write` |
351
+ | `max_steps` | Tope de pasos del modelo, 1 a 200 (default 80) | `write` |
352
+
353
+ ```ts
354
+ const run = await platform.agents.generate(agentId, {
355
+ 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" }] }],
356
+ context: ["El cliente es VIP."],
357
+ contact: { first_name: "Ana", email: "ana@acme.com" },
358
+ memory: { resource: "cliente-42" },
359
+ versions: { agents: { [agentId]: { version_id: "ver_123" /* placeholder: un id real de versión */ } } },
360
+ model: "gpt_4o_mini",
361
+ max_steps: 20,
362
+ });
363
+ ```
364
+
365
+ `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.
366
+
367
+ Los métodos:
368
+
369
+ - `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`...); su tipo es `AgentRun`.
370
+ - `platform.agents.stream(agentId, body, options?)`: devuelve el turno en vivo, a medida que el agente lo arma.
371
+
372
+ ```ts
373
+ const run = await platform.agents.stream(agentId, { messages: "Hola", memory: { thread } });
374
+ for await (const chunk of run.chunks) {
375
+ if (chunk.type === "text-delta") process.stdout.write(chunk.delta);
376
+ }
377
+ const { text, memory, cost } = await run.result;
378
+ ```
379
+
380
+ `memory` dice a qué conversación pertenece el turno y quién es el usuario final: `thread` es el id de una
381
+ conversación anterior (sin él, arranca una nueva) y `resource` es tu propio id del usuario final (por ejemplo el id de cliente).
382
+ Para seguir una conversación, pasá el `thread` que devolvió el turno anterior en `memory.thread`.
383
+
384
+ - Si mandás `thread` sin `resource`, se usa el usuario dueño de ese thread, y la respuesta lo devuelve en `memory.resource`.
385
+ - 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`.
386
+
387
+ ```ts
388
+ import type { AgentGenerateParams } from "@laburen/delta-sdk/platform";
389
+
390
+ const body: AgentGenerateParams = { messages: "Hola", memory: { resource: "cliente-42" } };
391
+ const first = await platform.agents.generate(agentId, body);
392
+ const next = await platform.agents.generate(agentId, {
393
+ messages: "¿Qué te pedí recién?",
394
+ memory: { thread: first.memory.thread }, // sin resource: usa cliente-42
395
+ });
396
+ ```
397
+
398
+ - `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.
399
+ - `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`.
400
+ - 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`.
401
+ - **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:
402
+ `{ type: "tool-input-available", toolCallId, toolName, input }`, `{ type: "tool-output-available", toolCallId, output }`, `{ type: "text-delta", id, delta }`,
403
+ `{ type: "source-url", sourceId, url, title }`, `{ type: "finish", finishReason, messageMetadata }`. Con `stream`, las tool calls llegan solo como esos chunks.
404
+ `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`.
405
+ 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`.
406
+ - `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"`.
407
+ - Seguir ese thread no le devuelve al modelo lo que dieron las tools del turno cortado: por defecto el agente no guarda tool calls en el historial (`config.history.tool_calls.mode` es `"off"`), así que el modelo puede volver a llamarlas. Para guardarlas, cambialo en el agente: `platform.agents.update(agentId, { config: { history: { tool_calls: { mode: "all" } } }, activate: true })` (o `{ mode: "recent", turns: n }`; `exclude_tools` deja tools afuera). `history` se reemplaza entero: mandá también `exchanges` y `reasoning` si los habías cambiado.
408
+ - `reasoning_text` (solo en `generate`) viene cuando el proveedor del modelo devuelve el texto del razonamiento; si no, es `null`, aunque `total_usage` traiga `reasoning_tokens`: hay proveedores que cobran el razonamiento sin mostrarlo.
409
+ - Un chunk de un tipo que este SDK todavía no conoce se saltea: actualizá el SDK para verlo.
410
+ - El timeout de estas dos rutas viene del contrato (630 s por intento), no del `timeout` del cliente. Para cortar antes, pasá un `signal`.
411
+ - 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.
412
+
413
+ ## 9. Bodies de ejemplo por recurso
414
+
415
+ Los tipos de cada body se exportan con el nombre `<Recurso><Verbo>Params` (`AgentCreateParams`,
416
+ `AgentVersionCreateParams`, `SkillCreateParams`, `McpConnectionCreateParams`, `AgentGenerateParams`...). Lo que
417
+ devuelve cada recurso se llama como el recurso (`Agent`, `Skill`, `McpConnection`, `Token`, `Model`; un turno de
418
+ `agents.generate`, `AgentRun`) y las páginas
419
+ `AgentsPage`, `SkillsPage`, etc. Los ids de modelo salen de `platform.models.list()`.
420
+
421
+ **Agente con config, tools, skills y conexión MCP.** Se crea con la primera versión y queda activa (salvo `activate: false`):
422
+
423
+ ```ts
424
+ import type { AgentCreateParams } from "@laburen/delta-sdk/platform";
425
+
426
+ const body: AgentCreateParams = {
427
+ harness_type: "mastra",
428
+ name: "Soporte",
429
+ config: {
430
+ model: { id: "gpt_4o_mini" },
431
+ prompt: [{ type: "text", content: "Sos el agente de soporte de Acme. Respondé corto." }],
432
+ tools: [
433
+ { type: "http", id: "clima", name: "clima", url: "https://api.acme.com/clima", method: "GET" },
434
+ { type: "send_files", id: "archivos" },
435
+ ],
436
+ knowledge: { mode: "vector", project_ids: ["kp_123"] },
437
+ },
438
+ skills: [{ skill_id: "skl_123", strategy: "latest" }],
439
+ mcp_connections: [{ connection_id: "mcp_123", strategy: "latest", tools: ["buscar_pedido"] }],
440
+ };
441
+ const res = await platform.agents.create(body);
442
+ // `agents.create` y `agents.update` devuelven el agente con la versión creada adentro (`AgentWithVersion`),
443
+ // no un `{ agent, version }`: el id del agente es `res.id` y el de la versión es `res.version?.id`.
444
+ console.log(res.id, res.version?.id);
445
+ ```
446
+
447
+ `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).
448
+
449
+ **Tools de un agente** (`config.tools`). Son cuatro tipos; cada uno que no sea `http` va como mucho una vez:
450
+
451
+ | `type` | Para qué | Campos |
452
+ |---|---|---|
453
+ | `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` |
454
+ | `thinking` | El modelo escribe su razonamiento antes de responder | `id?`, `instructions?`, `max_thoughts?` |
455
+ | `send_files` | El modelo manda archivos al usuario | `id?` |
456
+ | `request_human` | El modelo pasa la conversación a una persona | `id?` |
457
+
458
+ `headers`, `body`, `query_parameters` y `path_variables` son **listas** de `{ key, value?, description?, is_user_provided?, required?, accepted_values?, type? }`, no objetos ni textos.
459
+ `value` es un valor fijo en cada llamada; con `is_user_provided: true` lo completa el modelo en cada llamada.
460
+
461
+ ```ts
462
+ const tool = {
463
+ type: "http" as const,
464
+ name: "clima",
465
+ description: "Consulta el clima de una ciudad",
466
+ url: "https://api.acme.com/clima/{country}",
467
+ method: "GET" as const,
468
+ headers: [{ key: "Authorization", value: "Bearer <clave>" }],
469
+ path_variables: [{ key: "country", is_user_provided: true, required: true, description: "Código de país" }],
470
+ query_parameters: [{ key: "city", is_user_provided: true, required: true, accepted_values: ["Madrid", "Lima"] }],
471
+ };
472
+ ```
473
+
474
+ 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 } } }`).
475
+
476
+ **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.
477
+
478
+ **Skill con archivos.** `files` es un objeto `ruta: contenido`. Solo se aceptan `SKILL.md` (obligatorio) y archivos
479
+ bajo `references/`. `SKILL.md` empieza con un frontmatter con `name` (igual al `name` de la skill) y `description`:
480
+
481
+ ```ts
482
+ import type { SkillCreateParams } from "@laburen/delta-sdk/platform";
483
+
484
+ const body: SkillCreateParams = {
485
+ name: "devoluciones",
486
+ files: {
487
+ "SKILL.md": "---\nname: devoluciones\ndescription: Cómo procesar una devolución.\n---\n\nSeguí los pasos de references/pasos.md.",
488
+ "references/pasos.md": "1. Pedí el número de pedido.\n2. ...",
489
+ },
490
+ };
491
+ const skill = await platform.skills.create(body);
492
+ ```
493
+
494
+ `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.`
495
+
496
+ Igual que los agentes y las conexiones MCP, la skill activa su primera versión al crearse; pasá `activate: false` para que
497
+ quede sin versión activa.
498
+
499
+ `skills.versions.create(skillId, { files, change_message? })` **no acepta `activate`**: el tipo no lo tiene y la API rechaza
500
+ claves de más con `invalid_request`. La versión siempre se crea inactiva; se activa aparte con
501
+ `platform.skills.versions.activate(skillId, versionId)`.
502
+
503
+ La skill (`skills.get`, `skills.list`, `skills.create`, `skills.versions.activate`) trae `description: string | null`: la del
504
+ frontmatter de `SKILL.md` de la versión activa o, si no hay activa, de la última; `null` si la skill no tiene versiones.
505
+
506
+ **Conexión MCP:**
507
+
508
+ ```ts
509
+ import type { McpConnectionCreateParams } from "@laburen/delta-sdk/platform";
510
+
511
+ const body: McpConnectionCreateParams = {
512
+ name: "pedidos",
513
+ url: "https://mcp.acme.com/mcp",
514
+ headers: { Authorization: "Bearer <clave>" },
515
+ };
516
+ const connection = await platform.mcp.connections.create(body);
517
+ ```
518
+
519
+ **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`.
520
+
521
+ `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.
522
+
523
+ ## 10. Editar: `update` y `versions.create`
524
+
525
+ Los dos crean una versión nueva del agente, pero no son lo mismo:
526
+
527
+ - `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
528
+ (por ejemplo `config: { prompt }` deja el modelo y las tools como estaban, pero mandar `tools` reemplaza la lista completa). No activa
529
+ la versión nueva salvo que pases `activate: true`.
530
+ - `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
531
+ `skills` o `mcp_connections` la versión queda sin ninguna. Nunca activa; para eso, `platform.agents.versions.activate(...)`.
532
+
533
+ 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.
534
+ `skills` y `mcp_connections` en `update` reemplazan la lista entera de asignadas (mandá la lista completa, no solo lo nuevo).
535
+
536
+ ### Secretos de las tools http: `[REDACTED]`
537
+
538
+ Al leer una versión (`versions.get`, `versions.list`, la `version` de `create`/`update`), la API tapa con el texto
539
+ `[REDACTED]` los valores secretos de cada tool `http`:
540
+
541
+ - el `value` de **todo** header que tenga valor fijo;
542
+ - el `value` de un campo de `body`, `query_parameters` o `path_variables` con valor fijo **solo si su `key` es de credencial**
543
+ (`token`, `key`, `api_key`, `secret`, `password`, `authorization`, `signature`, todo lo que termina en `token`, etc.);
544
+ - la `url` entera si lleva una credencial (usuario y contraseña, o un parámetro del query con esos nombres).
545
+
546
+ Mandar `[REDACTED]` de vuelta en `update` o `versions.create` significa "conservá el valor que ya había": la API lo busca
547
+ en la tool con el mismo `id` y, adentro, en el campo con el mismo `key`. Así se puede leer una config, cambiar otra cosa y
548
+ mandarla entera sin conocer los secretos. Para cambiar un secreto, mandá el valor real en su lugar.
549
+
550
+ El valor se recupera de la **última** versión del agente, no de la versión de la que leíste la config. Si leíste una versión
551
+ vieja y la última no tiene esa tool (mismo `id`) o ese campo (mismo `key`), la API rechaza con `invalid_request` y
552
+ `details.field` apunta al campo (por ejemplo `config.tools[0].headers[0].value`). Hay dos salidas: mandar el valor real, o
553
+ primero `versions.restore` de la versión de la que salió la config (crea una versión nueva con su contenido, que pasa a ser
554
+ la última) y después editar.
555
+
556
+ ### La forma de una versión
557
+
558
+ `versions.get`, `versions.list` (cada item), `versions.create` y `versions.restore` devuelven una versión (`versions.activate`
559
+ devuelve el recurso, no la versión). Su tipo se exporta: `AgentVersion`, `SkillVersion` y `McpConnectionVersion`
560
+ (`skills.versions.create` devuelve `SkillVersionCreated`, la versión con `warnings`).
561
+
562
+ ```ts
563
+ import type { AgentVersion } from "@laburen/delta-sdk/platform";
564
+
565
+ const v: AgentVersion = await platform.agents.versions.get(agentId, versionId);
566
+ v.type; // "agent_version"
567
+ v.id; // id de la versión
568
+ v.agent_id; // agente al que pertenece
569
+ v.version_number; // 1, 2, 3... por agente
570
+ v.is_active; // true si es la que corre
571
+ v.harness_type; // "legacy" | "mastra"
572
+ v.config; // la config (con los secretos como "[REDACTED]")
573
+ v.skills; // [{ skill_id, strategy, pinned_version_id }]
574
+ v.mcp_connections; // [{ connection_id, strategy, pinned_version_id, tools }]
575
+ v.changed_fields; // claves de primer nivel que cambiaron contra la versión anterior: "tools", "model", "skills"...
576
+ v.change_message; // nota de quien la creó, o null
577
+ v.created_at; // RFC 3339
578
+ v.created_by; // usuario o credencial que la creó
579
+ v.warnings; // solo en la respuesta del llamado que la creó y si hay algo que avisar (ver "Avisos de la versión")
580
+ ```
581
+
582
+ En la primera versión, `changed_fields` trae las claves que tienen valor. `SkillVersion` y `McpConnectionVersion` comparten
583
+ `id`, `version_number`, `is_active`, `changed_fields`, `change_message`, `created_at` y `created_by`, y cambian el resto
584
+ (`skill_id`, `files`, `name`... en una; `connection_id`, `url`, `headers`... en la otra).
585
+
586
+ ## 11. Conexiones MCP: renombrar
587
+
588
+ `platform.mcp.connections.update(id, { name })` solo renombra. Para cambiar la url o los headers se crea otra versión con
589
+ `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
590
+ **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
591
+ viejo, hay que actualizarlo.
592
+
593
+ ### Versiones, respuestas y skills: tres datos
594
+
595
+ Datos sueltos que conviene saber:
596
+
597
+ - El body de `agents.versions.create` **no lleva `harness_type`** (ese campo es solo de `agents.create`): la versión usa el del agente.
598
+ - 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)`.
599
+ - Los threads y las conversaciones no se pueden borrar por la API.
600
+ - 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`).
601
+
602
+ ## 12. Permisos por operación
603
+
604
+ 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` por un permiso que falta trae `details.required` con ese permiso (el de `all_organizations` no: ver abajo).
605
+
606
+ | Permiso | Operaciones |
607
+ |---|---|
608
+ | 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) |
609
+ | `read` | todos los `get`, `list` y `versions.compare` de agentes, skills y conexiones MCP; `mcp.connections.tools.list`; `knowledge.projects.list`; `models.list` |
610
+ | `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`) |
611
+ | `admin` | `agents.delete`, `skills.delete`, `mcp.connections.delete` |
612
+ | `query` | `agents.generate`, `agents.stream` (más `write` si el body trae `instructions`, `model`, `model_settings` o `max_steps`) |
613
+
614
+ `tokens.create` crea el token para la organización con la que trabaja la llamada: la `organization` del cliente o de
615
+ la llamada (header `x-laburen-organization`; sección 2). El body no tiene `organization_id`: mandarlo da un error de
616
+ validación (`Unrecognized key`). Para un token personal que sirva en todas tus organizaciones, mandá
617
+ `all_organizations: true`; después cada llamada con ese token tiene que decir la organización. Para eso, el token con
618
+ el que llamás ya tiene que ser de todas las organizaciones (la sesión de la CLI suele serlo, o un token creado con
619
+ `all_organizations: true`): uno de una sola organización da 403 `insufficient_permissions` con
620
+ `details.field: "all_organizations"` y sin `details.required`, porque no falta un permiso.
621
+
622
+ ```ts
623
+ // Token para org_123: la organización sale del cliente, no del body.
624
+ const created = await platform.tokens.create(
625
+ { name: "mi-script", kind: "personal", permissions: ["read", "write"] },
626
+ { organization: "org_123" },
627
+ );
628
+ console.log(created.value); // sale una sola vez
629
+
630
+ // Token personal para todas tus organizaciones (con un token que ya sea de todas).
631
+ await platform.tokens.create({
632
+ name: "multi",
633
+ kind: "personal",
634
+ permissions: ["read"],
635
+ all_organizations: true,
636
+ });
637
+ ```
638
+
639
+ 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.
640
+ Borrar una versión (`versions.delete`) pide solo `write`, pero borrar el recurso entero pide `admin`.
641
+
642
+ ## 13. Índice de métodos
643
+
644
+ Ids como parámetros posicionales, después `params`, después `options`. `list` devuelve `PagePromise` (sección 5). Cada método está en `platform.<ruta>`.
645
+
646
+ | Recurso | Métodos |
647
+ |---|---|
648
+ | `agents` | `create(params)` · `get(id)` · `list(params?)` · `update(id, params)` · `delete(id)` · `generate(id, params)` · `stream(id, params)` |
649
+ | `agents.versions` | `create(id, params)` · `get(id, versionId)` · `list(id, params?)` · `compare(id, params)` · `activate(id, versionId)` · `restore(id, versionId, params?)` · `delete(id, versionId)` |
650
+ | `skills` | `create(params)` · `get(id)` · `list(params?)` · `delete(id)` (sin `update`) |
651
+ | `skills.versions` | `create` · `get` · `list` · `compare` · `activate` · `restore` · `delete` (igual que `agents.versions`) |
652
+ | `mcp.connections` | `create(params)` · `get(id)` · `list(params?)` · `update(id, { name })` · `delete(id)` |
653
+ | `mcp.connections.tools` | `list(connectionId, params?)` |
654
+ | `mcp.connections.versions` | `create` · `get` · `list` · `compare` · `activate` · `restore` · `delete` (igual que `agents.versions`) |
655
+ | `knowledge.projects` | `list(params?)` |
656
+ | `models` | `list(params?)` |
657
+ | `tokens` | `create(params)` · `list(params?)` · `update(id, params)` · `revoke(id)` |
658
+ | `me` | `get()` · `organizations.list(params?)` |
659
+ | `meta.schemas` | `agentConfig()` |
660
+
661
+ `compare` pide `params` `{ from, to }` (ids de versión); el tipo es `<Recurso>VersionCompareParams`.