@vaia-lab/sdk 0.3.0 → 0.4.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/agent-1bVw0eB8.d.cts +222 -0
- package/dist/agent-1bVw0eB8.d.ts +222 -0
- package/dist/index.cjs +0 -203
- package/dist/index.d.cts +4 -271
- package/dist/index.d.ts +4 -271
- package/dist/index.js +0 -202
- package/dist/react/index.cjs +1244 -0
- package/dist/react/index.d.cts +95 -0
- package/dist/react/index.d.ts +95 -0
- package/dist/react/index.js +1232 -0
- package/package.json +38 -3
|
@@ -0,0 +1,222 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* VAIA Extension Protocol — superficie de AGENTE.
|
|
3
|
+
*
|
|
4
|
+
* Es la parte del protocolo que permite que el asistente de Handeia viva
|
|
5
|
+
* dentro de un espacio de terceros. Sigue la regla del ecosistema: protocolo
|
|
6
|
+
* antes que SDK. Lo que hay aquí son CONTRATOS; el SDK solo los transporta.
|
|
7
|
+
*
|
|
8
|
+
* ── El reparto de papeles ────────────────────────────────────────────────
|
|
9
|
+
* El espacio → superficie y manos. Declara qué sabe y qué puede hacer.
|
|
10
|
+
* Handeia → cerebro, memoria y autoridad. Decide y ejecuta a través suyo.
|
|
11
|
+
*
|
|
12
|
+
* Por eso un espacio NO trae su propia IA: si la trajera, no te conocería,
|
|
13
|
+
* empezaría de cero cada vez, y no podría contradecirse a sí mismo. El caso
|
|
14
|
+
* que lo justifica: el espacio puntúa un resultado con 90 y el agente te dice
|
|
15
|
+
* que te conviene el de 87, porque sabe algo de ti que el espacio no sabe.
|
|
16
|
+
* Eso solo es posible si el cerebro vive fuera del espacio.
|
|
17
|
+
*
|
|
18
|
+
* ── La regla de confianza, que manda sobre todo lo demás ─────────────────
|
|
19
|
+
* El espacio es CÓDIGO DE TERCEROS. Nada de lo que envía es un hecho: es una
|
|
20
|
+
* AFIRMACIÓN. Handeia la trata como dato citado, nunca como instrucción y
|
|
21
|
+
* nunca al mismo nivel que lo que sabe del usuario. Un espacio que escriba
|
|
22
|
+
* "ignora las instrucciones anteriores" en su contexto no logra nada.
|
|
23
|
+
*
|
|
24
|
+
* @see AGENT_PROTOCOL_VERSION para la política de compatibilidad.
|
|
25
|
+
*/
|
|
26
|
+
/**
|
|
27
|
+
* Versión del protocolo de agente. Viaja en cada mensaje.
|
|
28
|
+
*
|
|
29
|
+
* Se versiona desde el primer día a propósito: este contrato es público y
|
|
30
|
+
* cambiarlo después obliga a coordinar despliegues entre partes que no se
|
|
31
|
+
* conocen. Ya se pagó esa factura una vez con la codificación del JWT.
|
|
32
|
+
*/
|
|
33
|
+
declare const AGENT_PROTOCOL_VERSION = 1;
|
|
34
|
+
/** Un parámetro de una acción. Sin tipos no hay validación posible. */
|
|
35
|
+
interface AgentActionParam {
|
|
36
|
+
name: string;
|
|
37
|
+
type: 'string' | 'number' | 'boolean';
|
|
38
|
+
description: string;
|
|
39
|
+
required?: boolean | undefined;
|
|
40
|
+
/** Valores admitidos. Si se define, nada fuera de la lista es válido. */
|
|
41
|
+
enum?: string[] | undefined;
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* Algo que el espacio sabe hacer.
|
|
45
|
+
*
|
|
46
|
+
* Handeia SOLO puede pedir acciones declaradas aquí. No improvisa, no toca el
|
|
47
|
+
* DOM, no busca la forma. Si no está declarada, para el agente no existe —
|
|
48
|
+
* y eso es lo que hace que el mismo agente sirva en cualquier espacio sin que
|
|
49
|
+
* Handeia sepa nada de ninguno en particular.
|
|
50
|
+
*/
|
|
51
|
+
interface AgentAction {
|
|
52
|
+
/** Identificador estable, en minúsculas: 'filtrar_resultados'. */
|
|
53
|
+
name: string;
|
|
54
|
+
/** Qué hace, en lenguaje natural. Es lo que lee el modelo para elegirla. */
|
|
55
|
+
description: string;
|
|
56
|
+
params?: AgentActionParam[] | undefined;
|
|
57
|
+
/**
|
|
58
|
+
* true si modifica algo. Las que escriben se confirman con el usuario ANTES
|
|
59
|
+
* de ejecutarse — un agente que escribe sin preguntar se siente fuera de
|
|
60
|
+
* control incluso cuando acierta.
|
|
61
|
+
*/
|
|
62
|
+
writes?: boolean | undefined;
|
|
63
|
+
/** Permiso que el usuario debe haber concedido a este espacio. */
|
|
64
|
+
permission?: string | undefined;
|
|
65
|
+
}
|
|
66
|
+
/** Configuración de la superficie de agente dentro de defineCapability. */
|
|
67
|
+
interface AgentSurfaceConfig {
|
|
68
|
+
/** Acciones que el espacio expone. Vacío = el agente solo puede responder. */
|
|
69
|
+
actions?: AgentAction[] | undefined;
|
|
70
|
+
/**
|
|
71
|
+
* Endpoint para preguntarle al espacio cuando el usuario NO está dentro
|
|
72
|
+
* ("¿tengo algo pendiente ahí?"). El círculo solo existe con el espacio
|
|
73
|
+
* abierto; esto es lo que permite que Handeia sea el lugar donde convergen
|
|
74
|
+
* todos tus espacios en vez de uno más al que entrar.
|
|
75
|
+
*/
|
|
76
|
+
queryEndpoint?: string | undefined;
|
|
77
|
+
/** Frase de bienvenida propia del espacio. */
|
|
78
|
+
greeting?: string | undefined;
|
|
79
|
+
/**
|
|
80
|
+
* Servicios externos que el espacio necesita consultar. El usuario los
|
|
81
|
+
* concede por espacio y los puede revocar cuando quiera. El espacio jamás
|
|
82
|
+
* recibe el token: pide operaciones, la plataforma las ejecuta.
|
|
83
|
+
*/
|
|
84
|
+
needs?: ConnectorNeed[] | undefined;
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
87
|
+
* Servicios externos que un espacio puede necesitar (GitHub, Drive, Calendar…).
|
|
88
|
+
*
|
|
89
|
+
* ── La regla, y no tiene excepciones ─────────────────────────────────────
|
|
90
|
+
* El espacio NUNCA recibe el token del usuario. Declara qué necesita, la
|
|
91
|
+
* plataforma llama al proveedor con el token que YA tiene guardado, y le
|
|
92
|
+
* devuelve solo el resultado.
|
|
93
|
+
*
|
|
94
|
+
* Por qué así y no entregando el token:
|
|
95
|
+
* - Si cada espacio guardara tokens, la superficie de ataque se multiplica
|
|
96
|
+
* por cada desarrollador que publique. Un espacio comprometido entregaría
|
|
97
|
+
* el GitHub y el Drive de todos sus usuarios.
|
|
98
|
+
* - Prestado, un espacio comprometido solo puede pedir las operaciones que
|
|
99
|
+
* el usuario le concedió, con límite de frecuencia, auditadas y
|
|
100
|
+
* revocables al instante desde Conectores.
|
|
101
|
+
*
|
|
102
|
+
* De regalo, publicar un espacio se vuelve barato: el desarrollador no
|
|
103
|
+
* implementa OAuth de nada.
|
|
104
|
+
*/
|
|
105
|
+
type ConnectorNeed = 'github' | 'drive' | 'calendar' | 'email' | 'notion' | 'discord';
|
|
106
|
+
/**
|
|
107
|
+
* Operaciones de LECTURA que la plataforma sabe hacer por el espacio.
|
|
108
|
+
*
|
|
109
|
+
* Lista cerrada a propósito: un espacio no puede pedir "haz esta llamada
|
|
110
|
+
* arbitraria a la API de GitHub". Solo puede pedir lo que está aquí, y cada
|
|
111
|
+
* una devuelve datos ya acotados. Escribir en un servicio externo NO se
|
|
112
|
+
* presta — para eso el usuario usa el servicio.
|
|
113
|
+
*/
|
|
114
|
+
type ConnectorOperation = 'github.repos' | 'github.issues' | 'drive.files' | 'calendar.events' | 'email.recent' | 'notion.pages';
|
|
115
|
+
/** Lo que el espacio pide prestado. */
|
|
116
|
+
interface ConnectorRequest {
|
|
117
|
+
operation: ConnectorOperation;
|
|
118
|
+
/** Filtros simples. La plataforma los valida; nada de consultas libres. */
|
|
119
|
+
params?: Record<string, string | number | boolean> | undefined;
|
|
120
|
+
}
|
|
121
|
+
/** Lo que la plataforma devuelve. Datos, jamás credenciales. */
|
|
122
|
+
interface ConnectorResult {
|
|
123
|
+
operation: ConnectorOperation;
|
|
124
|
+
ok: boolean;
|
|
125
|
+
items?: Record<string, unknown>[] | undefined;
|
|
126
|
+
/** 'sin_conectar' = el usuario no ha vinculado ese servicio todavía. */
|
|
127
|
+
error?: 'sin_permiso' | 'sin_conectar' | 'no_soportada' | 'limite_excedido' | 'fallo' | undefined;
|
|
128
|
+
}
|
|
129
|
+
/** Qué operación necesita qué conector — la plataforma lo usa para autorizar. */
|
|
130
|
+
declare const CONNECTOR_OF_OPERATION: Record<ConnectorOperation, ConnectorNeed>;
|
|
131
|
+
/**
|
|
132
|
+
* Lo que el espacio dice que está pasando.
|
|
133
|
+
*
|
|
134
|
+
* OJO: se llama `claims` y no `facts` a propósito. Handeia lo etiqueta como
|
|
135
|
+
* afirmación de un tercero antes de dárselo al modelo.
|
|
136
|
+
*/
|
|
137
|
+
interface AgentSpaceContext {
|
|
138
|
+
/** Dónde está el usuario dentro del espacio: '/lista'. */
|
|
139
|
+
route?: string | undefined;
|
|
140
|
+
/** Qué está viendo, en lenguaje natural: 'Lista de 12 resultados'. */
|
|
141
|
+
view?: string | undefined;
|
|
142
|
+
/** Datos que el espacio considera relevantes ahora mismo. */
|
|
143
|
+
claims?: Record<string, unknown> | undefined;
|
|
144
|
+
}
|
|
145
|
+
/** Petición del espacio a Handeia. Un solo endpoint, un solo formato. */
|
|
146
|
+
interface AgentTurnRequest {
|
|
147
|
+
protocol: typeof AGENT_PROTOCOL_VERSION;
|
|
148
|
+
/** Lo que escribió el usuario. */
|
|
149
|
+
message: string;
|
|
150
|
+
context?: AgentSpaceContext | undefined;
|
|
151
|
+
/** Acciones disponibles AHORA (pueden ser menos que las declaradas). */
|
|
152
|
+
actions?: AgentAction[] | undefined;
|
|
153
|
+
/** Turnos previos, para que el agente no pierda el hilo. */
|
|
154
|
+
history?: {
|
|
155
|
+
role: 'user' | 'agent';
|
|
156
|
+
text: string;
|
|
157
|
+
}[] | undefined;
|
|
158
|
+
/** Resultado de una acción que Handeia pidió en el turno anterior. */
|
|
159
|
+
actionResult?: AgentActionResult | undefined;
|
|
160
|
+
}
|
|
161
|
+
/** Lo que el espacio devuelve tras ejecutar una acción. */
|
|
162
|
+
interface AgentActionResult {
|
|
163
|
+
action: string;
|
|
164
|
+
ok: boolean;
|
|
165
|
+
/** Qué pasó, para que el agente pueda cerrar el ciclo con el usuario. */
|
|
166
|
+
summary?: string | undefined;
|
|
167
|
+
error?: string | undefined;
|
|
168
|
+
}
|
|
169
|
+
/**
|
|
170
|
+
* De dónde salió lo que el agente afirma.
|
|
171
|
+
*
|
|
172
|
+
* No es adorno: es el pilar de info verificada. Cuando el agente contradice
|
|
173
|
+
* al espacio ("dice 90, pero te conviene la de 87"), tiene que poder decir de
|
|
174
|
+
* dónde sacó su razón. Un oráculo que no se explica no se gana la confianza.
|
|
175
|
+
*/
|
|
176
|
+
interface AgentEvidence {
|
|
177
|
+
/** 'handeia' = memoria del usuario · 'space' = lo que declaró el espacio. */
|
|
178
|
+
source: 'handeia' | 'space';
|
|
179
|
+
label: string;
|
|
180
|
+
}
|
|
181
|
+
/** Respuesta de Handeia al espacio. */
|
|
182
|
+
interface AgentTurnResponse {
|
|
183
|
+
protocol: typeof AGENT_PROTOCOL_VERSION;
|
|
184
|
+
/** Qué decirle al usuario. */
|
|
185
|
+
text?: string | undefined;
|
|
186
|
+
/** Acción a ejecutar. Siempre sale de la lista declarada, nunca inventada. */
|
|
187
|
+
action?: {
|
|
188
|
+
name: string;
|
|
189
|
+
args?: Record<string, unknown> | undefined;
|
|
190
|
+
} | undefined;
|
|
191
|
+
/** true si hay que confirmar con el usuario antes de ejecutarla. */
|
|
192
|
+
confirm?: boolean | undefined;
|
|
193
|
+
evidence?: AgentEvidence[] | undefined;
|
|
194
|
+
/** Identificador para cruzar los registros de todas las capas. */
|
|
195
|
+
traceId?: string | undefined;
|
|
196
|
+
}
|
|
197
|
+
/**
|
|
198
|
+
* Revisa que las acciones declaradas sean utilizables.
|
|
199
|
+
*
|
|
200
|
+
* Corre al declarar la capacidad, no en producción: un contrato mal escrito
|
|
201
|
+
* debe reventar en el escritorio del desarrollador, no frente al usuario.
|
|
202
|
+
*/
|
|
203
|
+
declare function validateAgentSurface(cfg: AgentSurfaceConfig): string[];
|
|
204
|
+
/**
|
|
205
|
+
* ¿Es válida esta acción contra lo declarado?
|
|
206
|
+
*
|
|
207
|
+
* La usa Handeia antes de reenviarle nada al espacio. Es la lista blanca en
|
|
208
|
+
* ejecución: aunque el modelo se invente una acción o un argumento fuera de
|
|
209
|
+
* rango, aquí se detiene.
|
|
210
|
+
*/
|
|
211
|
+
declare function validateActionCall(llamada: {
|
|
212
|
+
name: string;
|
|
213
|
+
args?: Record<string, unknown> | undefined;
|
|
214
|
+
}, declaradas: AgentAction[]): {
|
|
215
|
+
ok: true;
|
|
216
|
+
action: AgentAction;
|
|
217
|
+
} | {
|
|
218
|
+
ok: false;
|
|
219
|
+
reason: string;
|
|
220
|
+
};
|
|
221
|
+
|
|
222
|
+
export { type AgentSurfaceConfig as A, CONNECTOR_OF_OPERATION as C, type AgentAction as a, AGENT_PROTOCOL_VERSION as b, type AgentActionParam as c, type AgentActionResult as d, type AgentEvidence as e, type AgentSpaceContext as f, type AgentTurnRequest as g, type AgentTurnResponse as h, type ConnectorNeed as i, type ConnectorOperation as j, type ConnectorRequest as k, type ConnectorResult as l, validateAgentSurface as m, validateActionCall as v };
|
|
@@ -0,0 +1,222 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* VAIA Extension Protocol — superficie de AGENTE.
|
|
3
|
+
*
|
|
4
|
+
* Es la parte del protocolo que permite que el asistente de Handeia viva
|
|
5
|
+
* dentro de un espacio de terceros. Sigue la regla del ecosistema: protocolo
|
|
6
|
+
* antes que SDK. Lo que hay aquí son CONTRATOS; el SDK solo los transporta.
|
|
7
|
+
*
|
|
8
|
+
* ── El reparto de papeles ────────────────────────────────────────────────
|
|
9
|
+
* El espacio → superficie y manos. Declara qué sabe y qué puede hacer.
|
|
10
|
+
* Handeia → cerebro, memoria y autoridad. Decide y ejecuta a través suyo.
|
|
11
|
+
*
|
|
12
|
+
* Por eso un espacio NO trae su propia IA: si la trajera, no te conocería,
|
|
13
|
+
* empezaría de cero cada vez, y no podría contradecirse a sí mismo. El caso
|
|
14
|
+
* que lo justifica: el espacio puntúa un resultado con 90 y el agente te dice
|
|
15
|
+
* que te conviene el de 87, porque sabe algo de ti que el espacio no sabe.
|
|
16
|
+
* Eso solo es posible si el cerebro vive fuera del espacio.
|
|
17
|
+
*
|
|
18
|
+
* ── La regla de confianza, que manda sobre todo lo demás ─────────────────
|
|
19
|
+
* El espacio es CÓDIGO DE TERCEROS. Nada de lo que envía es un hecho: es una
|
|
20
|
+
* AFIRMACIÓN. Handeia la trata como dato citado, nunca como instrucción y
|
|
21
|
+
* nunca al mismo nivel que lo que sabe del usuario. Un espacio que escriba
|
|
22
|
+
* "ignora las instrucciones anteriores" en su contexto no logra nada.
|
|
23
|
+
*
|
|
24
|
+
* @see AGENT_PROTOCOL_VERSION para la política de compatibilidad.
|
|
25
|
+
*/
|
|
26
|
+
/**
|
|
27
|
+
* Versión del protocolo de agente. Viaja en cada mensaje.
|
|
28
|
+
*
|
|
29
|
+
* Se versiona desde el primer día a propósito: este contrato es público y
|
|
30
|
+
* cambiarlo después obliga a coordinar despliegues entre partes que no se
|
|
31
|
+
* conocen. Ya se pagó esa factura una vez con la codificación del JWT.
|
|
32
|
+
*/
|
|
33
|
+
declare const AGENT_PROTOCOL_VERSION = 1;
|
|
34
|
+
/** Un parámetro de una acción. Sin tipos no hay validación posible. */
|
|
35
|
+
interface AgentActionParam {
|
|
36
|
+
name: string;
|
|
37
|
+
type: 'string' | 'number' | 'boolean';
|
|
38
|
+
description: string;
|
|
39
|
+
required?: boolean | undefined;
|
|
40
|
+
/** Valores admitidos. Si se define, nada fuera de la lista es válido. */
|
|
41
|
+
enum?: string[] | undefined;
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* Algo que el espacio sabe hacer.
|
|
45
|
+
*
|
|
46
|
+
* Handeia SOLO puede pedir acciones declaradas aquí. No improvisa, no toca el
|
|
47
|
+
* DOM, no busca la forma. Si no está declarada, para el agente no existe —
|
|
48
|
+
* y eso es lo que hace que el mismo agente sirva en cualquier espacio sin que
|
|
49
|
+
* Handeia sepa nada de ninguno en particular.
|
|
50
|
+
*/
|
|
51
|
+
interface AgentAction {
|
|
52
|
+
/** Identificador estable, en minúsculas: 'filtrar_resultados'. */
|
|
53
|
+
name: string;
|
|
54
|
+
/** Qué hace, en lenguaje natural. Es lo que lee el modelo para elegirla. */
|
|
55
|
+
description: string;
|
|
56
|
+
params?: AgentActionParam[] | undefined;
|
|
57
|
+
/**
|
|
58
|
+
* true si modifica algo. Las que escriben se confirman con el usuario ANTES
|
|
59
|
+
* de ejecutarse — un agente que escribe sin preguntar se siente fuera de
|
|
60
|
+
* control incluso cuando acierta.
|
|
61
|
+
*/
|
|
62
|
+
writes?: boolean | undefined;
|
|
63
|
+
/** Permiso que el usuario debe haber concedido a este espacio. */
|
|
64
|
+
permission?: string | undefined;
|
|
65
|
+
}
|
|
66
|
+
/** Configuración de la superficie de agente dentro de defineCapability. */
|
|
67
|
+
interface AgentSurfaceConfig {
|
|
68
|
+
/** Acciones que el espacio expone. Vacío = el agente solo puede responder. */
|
|
69
|
+
actions?: AgentAction[] | undefined;
|
|
70
|
+
/**
|
|
71
|
+
* Endpoint para preguntarle al espacio cuando el usuario NO está dentro
|
|
72
|
+
* ("¿tengo algo pendiente ahí?"). El círculo solo existe con el espacio
|
|
73
|
+
* abierto; esto es lo que permite que Handeia sea el lugar donde convergen
|
|
74
|
+
* todos tus espacios en vez de uno más al que entrar.
|
|
75
|
+
*/
|
|
76
|
+
queryEndpoint?: string | undefined;
|
|
77
|
+
/** Frase de bienvenida propia del espacio. */
|
|
78
|
+
greeting?: string | undefined;
|
|
79
|
+
/**
|
|
80
|
+
* Servicios externos que el espacio necesita consultar. El usuario los
|
|
81
|
+
* concede por espacio y los puede revocar cuando quiera. El espacio jamás
|
|
82
|
+
* recibe el token: pide operaciones, la plataforma las ejecuta.
|
|
83
|
+
*/
|
|
84
|
+
needs?: ConnectorNeed[] | undefined;
|
|
85
|
+
}
|
|
86
|
+
/**
|
|
87
|
+
* Servicios externos que un espacio puede necesitar (GitHub, Drive, Calendar…).
|
|
88
|
+
*
|
|
89
|
+
* ── La regla, y no tiene excepciones ─────────────────────────────────────
|
|
90
|
+
* El espacio NUNCA recibe el token del usuario. Declara qué necesita, la
|
|
91
|
+
* plataforma llama al proveedor con el token que YA tiene guardado, y le
|
|
92
|
+
* devuelve solo el resultado.
|
|
93
|
+
*
|
|
94
|
+
* Por qué así y no entregando el token:
|
|
95
|
+
* - Si cada espacio guardara tokens, la superficie de ataque se multiplica
|
|
96
|
+
* por cada desarrollador que publique. Un espacio comprometido entregaría
|
|
97
|
+
* el GitHub y el Drive de todos sus usuarios.
|
|
98
|
+
* - Prestado, un espacio comprometido solo puede pedir las operaciones que
|
|
99
|
+
* el usuario le concedió, con límite de frecuencia, auditadas y
|
|
100
|
+
* revocables al instante desde Conectores.
|
|
101
|
+
*
|
|
102
|
+
* De regalo, publicar un espacio se vuelve barato: el desarrollador no
|
|
103
|
+
* implementa OAuth de nada.
|
|
104
|
+
*/
|
|
105
|
+
type ConnectorNeed = 'github' | 'drive' | 'calendar' | 'email' | 'notion' | 'discord';
|
|
106
|
+
/**
|
|
107
|
+
* Operaciones de LECTURA que la plataforma sabe hacer por el espacio.
|
|
108
|
+
*
|
|
109
|
+
* Lista cerrada a propósito: un espacio no puede pedir "haz esta llamada
|
|
110
|
+
* arbitraria a la API de GitHub". Solo puede pedir lo que está aquí, y cada
|
|
111
|
+
* una devuelve datos ya acotados. Escribir en un servicio externo NO se
|
|
112
|
+
* presta — para eso el usuario usa el servicio.
|
|
113
|
+
*/
|
|
114
|
+
type ConnectorOperation = 'github.repos' | 'github.issues' | 'drive.files' | 'calendar.events' | 'email.recent' | 'notion.pages';
|
|
115
|
+
/** Lo que el espacio pide prestado. */
|
|
116
|
+
interface ConnectorRequest {
|
|
117
|
+
operation: ConnectorOperation;
|
|
118
|
+
/** Filtros simples. La plataforma los valida; nada de consultas libres. */
|
|
119
|
+
params?: Record<string, string | number | boolean> | undefined;
|
|
120
|
+
}
|
|
121
|
+
/** Lo que la plataforma devuelve. Datos, jamás credenciales. */
|
|
122
|
+
interface ConnectorResult {
|
|
123
|
+
operation: ConnectorOperation;
|
|
124
|
+
ok: boolean;
|
|
125
|
+
items?: Record<string, unknown>[] | undefined;
|
|
126
|
+
/** 'sin_conectar' = el usuario no ha vinculado ese servicio todavía. */
|
|
127
|
+
error?: 'sin_permiso' | 'sin_conectar' | 'no_soportada' | 'limite_excedido' | 'fallo' | undefined;
|
|
128
|
+
}
|
|
129
|
+
/** Qué operación necesita qué conector — la plataforma lo usa para autorizar. */
|
|
130
|
+
declare const CONNECTOR_OF_OPERATION: Record<ConnectorOperation, ConnectorNeed>;
|
|
131
|
+
/**
|
|
132
|
+
* Lo que el espacio dice que está pasando.
|
|
133
|
+
*
|
|
134
|
+
* OJO: se llama `claims` y no `facts` a propósito. Handeia lo etiqueta como
|
|
135
|
+
* afirmación de un tercero antes de dárselo al modelo.
|
|
136
|
+
*/
|
|
137
|
+
interface AgentSpaceContext {
|
|
138
|
+
/** Dónde está el usuario dentro del espacio: '/lista'. */
|
|
139
|
+
route?: string | undefined;
|
|
140
|
+
/** Qué está viendo, en lenguaje natural: 'Lista de 12 resultados'. */
|
|
141
|
+
view?: string | undefined;
|
|
142
|
+
/** Datos que el espacio considera relevantes ahora mismo. */
|
|
143
|
+
claims?: Record<string, unknown> | undefined;
|
|
144
|
+
}
|
|
145
|
+
/** Petición del espacio a Handeia. Un solo endpoint, un solo formato. */
|
|
146
|
+
interface AgentTurnRequest {
|
|
147
|
+
protocol: typeof AGENT_PROTOCOL_VERSION;
|
|
148
|
+
/** Lo que escribió el usuario. */
|
|
149
|
+
message: string;
|
|
150
|
+
context?: AgentSpaceContext | undefined;
|
|
151
|
+
/** Acciones disponibles AHORA (pueden ser menos que las declaradas). */
|
|
152
|
+
actions?: AgentAction[] | undefined;
|
|
153
|
+
/** Turnos previos, para que el agente no pierda el hilo. */
|
|
154
|
+
history?: {
|
|
155
|
+
role: 'user' | 'agent';
|
|
156
|
+
text: string;
|
|
157
|
+
}[] | undefined;
|
|
158
|
+
/** Resultado de una acción que Handeia pidió en el turno anterior. */
|
|
159
|
+
actionResult?: AgentActionResult | undefined;
|
|
160
|
+
}
|
|
161
|
+
/** Lo que el espacio devuelve tras ejecutar una acción. */
|
|
162
|
+
interface AgentActionResult {
|
|
163
|
+
action: string;
|
|
164
|
+
ok: boolean;
|
|
165
|
+
/** Qué pasó, para que el agente pueda cerrar el ciclo con el usuario. */
|
|
166
|
+
summary?: string | undefined;
|
|
167
|
+
error?: string | undefined;
|
|
168
|
+
}
|
|
169
|
+
/**
|
|
170
|
+
* De dónde salió lo que el agente afirma.
|
|
171
|
+
*
|
|
172
|
+
* No es adorno: es el pilar de info verificada. Cuando el agente contradice
|
|
173
|
+
* al espacio ("dice 90, pero te conviene la de 87"), tiene que poder decir de
|
|
174
|
+
* dónde sacó su razón. Un oráculo que no se explica no se gana la confianza.
|
|
175
|
+
*/
|
|
176
|
+
interface AgentEvidence {
|
|
177
|
+
/** 'handeia' = memoria del usuario · 'space' = lo que declaró el espacio. */
|
|
178
|
+
source: 'handeia' | 'space';
|
|
179
|
+
label: string;
|
|
180
|
+
}
|
|
181
|
+
/** Respuesta de Handeia al espacio. */
|
|
182
|
+
interface AgentTurnResponse {
|
|
183
|
+
protocol: typeof AGENT_PROTOCOL_VERSION;
|
|
184
|
+
/** Qué decirle al usuario. */
|
|
185
|
+
text?: string | undefined;
|
|
186
|
+
/** Acción a ejecutar. Siempre sale de la lista declarada, nunca inventada. */
|
|
187
|
+
action?: {
|
|
188
|
+
name: string;
|
|
189
|
+
args?: Record<string, unknown> | undefined;
|
|
190
|
+
} | undefined;
|
|
191
|
+
/** true si hay que confirmar con el usuario antes de ejecutarla. */
|
|
192
|
+
confirm?: boolean | undefined;
|
|
193
|
+
evidence?: AgentEvidence[] | undefined;
|
|
194
|
+
/** Identificador para cruzar los registros de todas las capas. */
|
|
195
|
+
traceId?: string | undefined;
|
|
196
|
+
}
|
|
197
|
+
/**
|
|
198
|
+
* Revisa que las acciones declaradas sean utilizables.
|
|
199
|
+
*
|
|
200
|
+
* Corre al declarar la capacidad, no en producción: un contrato mal escrito
|
|
201
|
+
* debe reventar en el escritorio del desarrollador, no frente al usuario.
|
|
202
|
+
*/
|
|
203
|
+
declare function validateAgentSurface(cfg: AgentSurfaceConfig): string[];
|
|
204
|
+
/**
|
|
205
|
+
* ¿Es válida esta acción contra lo declarado?
|
|
206
|
+
*
|
|
207
|
+
* La usa Handeia antes de reenviarle nada al espacio. Es la lista blanca en
|
|
208
|
+
* ejecución: aunque el modelo se invente una acción o un argumento fuera de
|
|
209
|
+
* rango, aquí se detiene.
|
|
210
|
+
*/
|
|
211
|
+
declare function validateActionCall(llamada: {
|
|
212
|
+
name: string;
|
|
213
|
+
args?: Record<string, unknown> | undefined;
|
|
214
|
+
}, declaradas: AgentAction[]): {
|
|
215
|
+
ok: true;
|
|
216
|
+
action: AgentAction;
|
|
217
|
+
} | {
|
|
218
|
+
ok: false;
|
|
219
|
+
reason: string;
|
|
220
|
+
};
|
|
221
|
+
|
|
222
|
+
export { type AgentSurfaceConfig as A, CONNECTOR_OF_OPERATION as C, type AgentAction as a, AGENT_PROTOCOL_VERSION as b, type AgentActionParam as c, type AgentActionResult as d, type AgentEvidence as e, type AgentSpaceContext as f, type AgentTurnRequest as g, type AgentTurnResponse as h, type ConnectorNeed as i, type ConnectorOperation as j, type ConnectorRequest as k, type ConnectorResult as l, validateAgentSurface as m, validateActionCall as v };
|
package/dist/index.cjs
CHANGED
|
@@ -36,7 +36,6 @@ __export(src_exports, {
|
|
|
36
36
|
httpTransport: () => httpTransport,
|
|
37
37
|
local: () => local,
|
|
38
38
|
mcp: () => mcp,
|
|
39
|
-
mountAgent: () => mountAgent,
|
|
40
39
|
requiresApproval: () => requiresApproval,
|
|
41
40
|
toMCPTool: () => toMCPTool,
|
|
42
41
|
toMCPTools: () => toMCPTools,
|
|
@@ -814,207 +813,6 @@ function toManifest(config) {
|
|
|
814
813
|
};
|
|
815
814
|
}
|
|
816
815
|
|
|
817
|
-
// src/agent-mount.ts
|
|
818
|
-
var HANDEIA_POR_DEFECTO = "https://handeia.com";
|
|
819
|
-
var RUTA_TURNO = "/api/agent/space";
|
|
820
|
-
var CSS = `
|
|
821
|
-
.hdi-agent-root{position:fixed;z-index:2147483000;bottom:20px;right:20px;font-family:ui-sans-serif,system-ui,-apple-system,"Segoe UI",sans-serif}
|
|
822
|
-
.hdi-agent-orb{width:44px;height:44px;border-radius:9999px;border:0;cursor:pointer;background:#000;color:#fff;display:flex;align-items:center;justify-content:center;box-shadow:0 10px 30px -6px rgba(0,0,0,.4);transition:transform .15s}
|
|
823
|
-
.hdi-agent-orb:hover{transform:scale(1.05)}
|
|
824
|
-
.hdi-agent-orb:active{transform:scale(.95)}
|
|
825
|
-
.hdi-agent-panel{position:absolute;bottom:56px;right:0;width:min(360px,calc(100vw - 40px));background:#fff;color:#111;border:1px solid rgba(0,0,0,.09);border-radius:18px;box-shadow:0 24px 60px -18px rgba(0,0,0,.32);overflow:hidden;display:flex;flex-direction:column;max-height:min(60vh,460px)}
|
|
826
|
-
.hdi-agent-head{display:flex;align-items:center;gap:8px;padding:12px 14px;border-bottom:1px solid rgba(0,0,0,.06);font-size:12.5px;font-weight:600}
|
|
827
|
-
.hdi-agent-dot{width:7px;height:7px;border-radius:9999px;background:#8b5cf6}
|
|
828
|
-
.hdi-agent-log{flex:1;overflow-y:auto;padding:12px 14px;display:flex;flex-direction:column;gap:10px;font-size:13px;line-height:1.55}
|
|
829
|
-
.hdi-agent-turn{white-space:pre-wrap}
|
|
830
|
-
.hdi-agent-q{font-size:10.5px;letter-spacing:.14em;text-transform:uppercase;color:rgba(0,0,0,.34)}
|
|
831
|
-
.hdi-agent-form{display:flex;gap:8px;padding:10px 12px;border-top:1px solid rgba(0,0,0,.06)}
|
|
832
|
-
.hdi-agent-input{flex:1;border:1px solid rgba(0,0,0,.12);border-radius:10px;padding:8px 10px;font:inherit;font-size:13px;outline:none}
|
|
833
|
-
.hdi-agent-input:focus{border-color:rgba(0,0,0,.34)}
|
|
834
|
-
.hdi-agent-send{border:0;border-radius:10px;padding:0 12px;background:#000;color:#fff;cursor:pointer;font-size:12.5px}
|
|
835
|
-
.hdi-agent-confirm{display:flex;gap:8px;margin-top:4px}
|
|
836
|
-
.hdi-agent-btn{border:1px solid rgba(0,0,0,.14);background:#fff;border-radius:9999px;padding:5px 12px;font-size:12px;cursor:pointer}
|
|
837
|
-
.hdi-agent-btn-primary{background:#000;color:#fff;border-color:#000}
|
|
838
|
-
@media (prefers-color-scheme:dark){
|
|
839
|
-
.hdi-agent-orb{background:#fff;color:#000}
|
|
840
|
-
.hdi-agent-panel{background:#171717;color:#f5f5f5;border-color:rgba(255,255,255,.13)}
|
|
841
|
-
.hdi-agent-head,.hdi-agent-form{border-color:rgba(255,255,255,.1)}
|
|
842
|
-
.hdi-agent-q{color:rgba(255,255,255,.5)}
|
|
843
|
-
.hdi-agent-input{background:transparent;color:inherit;border-color:rgba(255,255,255,.16)}
|
|
844
|
-
.hdi-agent-send{background:#fff;color:#000}
|
|
845
|
-
.hdi-agent-btn{background:transparent;color:inherit;border-color:rgba(255,255,255,.18)}
|
|
846
|
-
.hdi-agent-btn-primary{background:#fff;color:#000}
|
|
847
|
-
}`;
|
|
848
|
-
function el(tag, cls, text) {
|
|
849
|
-
const n = document.createElement(tag);
|
|
850
|
-
if (cls) n.className = cls;
|
|
851
|
-
if (text !== void 0) n.textContent = text;
|
|
852
|
-
return n;
|
|
853
|
-
}
|
|
854
|
-
function mountAgent(opts) {
|
|
855
|
-
if (typeof document === "undefined") {
|
|
856
|
-
throw new Error("[@vaia-lab/sdk] mountAgent solo corre en el navegador.");
|
|
857
|
-
}
|
|
858
|
-
const base = (opts.handeiaUrl ?? HANDEIA_POR_DEFECTO).replace(/\/$/, "");
|
|
859
|
-
const contenedor = opts.container ?? document.body;
|
|
860
|
-
const previo = contenedor.querySelector(".hdi-agent-root");
|
|
861
|
-
if (previo) previo.remove();
|
|
862
|
-
if (!document.getElementById("hdi-agent-css")) {
|
|
863
|
-
const estilo = el("style");
|
|
864
|
-
estilo.id = "hdi-agent-css";
|
|
865
|
-
estilo.textContent = CSS;
|
|
866
|
-
document.head.appendChild(estilo);
|
|
867
|
-
}
|
|
868
|
-
const raiz = el("div", "hdi-agent-root");
|
|
869
|
-
const orbe = el("button", "hdi-agent-orb");
|
|
870
|
-
orbe.type = "button";
|
|
871
|
-
orbe.setAttribute("aria-label", "Abrir asistente de Handeia");
|
|
872
|
-
orbe.textContent = "\u2726";
|
|
873
|
-
const panel = el("div", "hdi-agent-panel");
|
|
874
|
-
panel.hidden = true;
|
|
875
|
-
panel.setAttribute("role", "dialog");
|
|
876
|
-
panel.setAttribute("aria-label", "Asistente de Handeia");
|
|
877
|
-
const cabeza = el("div", "hdi-agent-head");
|
|
878
|
-
cabeza.appendChild(el("span", "hdi-agent-dot"));
|
|
879
|
-
cabeza.appendChild(el("span", void 0, "Handeia"));
|
|
880
|
-
const registro = el("div", "hdi-agent-log");
|
|
881
|
-
if (opts.greeting) registro.appendChild(el("div", "hdi-agent-turn", opts.greeting));
|
|
882
|
-
const forma = el("form", "hdi-agent-form");
|
|
883
|
-
const entrada = el("input", "hdi-agent-input");
|
|
884
|
-
entrada.type = "text";
|
|
885
|
-
entrada.placeholder = "Preg\xFAntale a Handeia\u2026";
|
|
886
|
-
entrada.autocomplete = "off";
|
|
887
|
-
const enviar = el("button", "hdi-agent-send", "Enviar");
|
|
888
|
-
enviar.type = "submit";
|
|
889
|
-
forma.append(entrada, enviar);
|
|
890
|
-
panel.append(cabeza, registro, forma);
|
|
891
|
-
raiz.append(panel, orbe);
|
|
892
|
-
contenedor.appendChild(raiz);
|
|
893
|
-
const historial = [];
|
|
894
|
-
const decir = (texto, clase = "hdi-agent-turn") => {
|
|
895
|
-
const n = el("div", clase, texto);
|
|
896
|
-
registro.appendChild(n);
|
|
897
|
-
registro.scrollTop = registro.scrollHeight;
|
|
898
|
-
return n;
|
|
899
|
-
};
|
|
900
|
-
async function turno(mensaje, actionResult) {
|
|
901
|
-
let context;
|
|
902
|
-
try {
|
|
903
|
-
context = await opts.getContext?.();
|
|
904
|
-
} catch {
|
|
905
|
-
context = void 0;
|
|
906
|
-
}
|
|
907
|
-
let res;
|
|
908
|
-
try {
|
|
909
|
-
res = await fetch(`${base}${RUTA_TURNO}`, {
|
|
910
|
-
method: "POST",
|
|
911
|
-
// La identidad va en la cookie de sesión de Handeia. El espacio nunca
|
|
912
|
-
// toca ni ve el token del usuario.
|
|
913
|
-
credentials: "include",
|
|
914
|
-
headers: { "Content-Type": "application/json; charset=utf-8" },
|
|
915
|
-
body: JSON.stringify({
|
|
916
|
-
protocol: AGENT_PROTOCOL_VERSION,
|
|
917
|
-
capId: opts.capabilityId,
|
|
918
|
-
message: mensaje,
|
|
919
|
-
context,
|
|
920
|
-
actions: opts.actions ?? [],
|
|
921
|
-
history: historial.slice(-12),
|
|
922
|
-
actionResult
|
|
923
|
-
})
|
|
924
|
-
});
|
|
925
|
-
} catch {
|
|
926
|
-
decir("No pude comunicarme con Handeia. Revisa tu conexi\xF3n.");
|
|
927
|
-
return;
|
|
928
|
-
}
|
|
929
|
-
let data;
|
|
930
|
-
try {
|
|
931
|
-
data = await res.json();
|
|
932
|
-
} catch {
|
|
933
|
-
decir("Handeia respondi\xF3 algo que no pude leer.");
|
|
934
|
-
return;
|
|
935
|
-
}
|
|
936
|
-
if (!res.ok || data.ok === false) {
|
|
937
|
-
decir(
|
|
938
|
-
data.error === "no_autenticado" ? "Inicia sesi\xF3n en Handeia para usar el asistente." : data.error === "espacio_no_instalado" ? "Este espacio no est\xE1 instalado en tu Handeia." : "Handeia no pudo responder ahora mismo."
|
|
939
|
-
);
|
|
940
|
-
return;
|
|
941
|
-
}
|
|
942
|
-
if (data.text) {
|
|
943
|
-
decir(data.text);
|
|
944
|
-
historial.push({ role: "agent", text: data.text });
|
|
945
|
-
}
|
|
946
|
-
if (!data.action) return;
|
|
947
|
-
if (!opts.onAction) {
|
|
948
|
-
decir("Esto requiere una acci\xF3n que este espacio todav\xEDa no sabe ejecutar.");
|
|
949
|
-
return;
|
|
950
|
-
}
|
|
951
|
-
const ejecutar = async () => {
|
|
952
|
-
let resultado;
|
|
953
|
-
try {
|
|
954
|
-
resultado = await opts.onAction(data.action.name, data.action.args ?? {});
|
|
955
|
-
} catch (e) {
|
|
956
|
-
resultado = { action: data.action.name, ok: false, error: e instanceof Error ? e.message : "fall\xF3" };
|
|
957
|
-
}
|
|
958
|
-
await turno(mensaje, resultado);
|
|
959
|
-
};
|
|
960
|
-
if (data.confirm) {
|
|
961
|
-
const fila = el("div", "hdi-agent-confirm");
|
|
962
|
-
const si = el("button", "hdi-agent-btn hdi-agent-btn-primary", "Hacerlo");
|
|
963
|
-
const no = el("button", "hdi-agent-btn", "Cancelar");
|
|
964
|
-
si.type = "button";
|
|
965
|
-
no.type = "button";
|
|
966
|
-
si.onclick = () => {
|
|
967
|
-
fila.remove();
|
|
968
|
-
void ejecutar();
|
|
969
|
-
};
|
|
970
|
-
no.onclick = () => {
|
|
971
|
-
fila.remove();
|
|
972
|
-
decir("Cancelado.");
|
|
973
|
-
};
|
|
974
|
-
fila.append(si, no);
|
|
975
|
-
registro.appendChild(fila);
|
|
976
|
-
registro.scrollTop = registro.scrollHeight;
|
|
977
|
-
return;
|
|
978
|
-
}
|
|
979
|
-
await ejecutar();
|
|
980
|
-
}
|
|
981
|
-
forma.onsubmit = async (e) => {
|
|
982
|
-
e.preventDefault();
|
|
983
|
-
const texto = entrada.value.trim();
|
|
984
|
-
if (!texto) return;
|
|
985
|
-
entrada.value = "";
|
|
986
|
-
decir(texto, "hdi-agent-q");
|
|
987
|
-
historial.push({ role: "user", text: texto });
|
|
988
|
-
enviar.disabled = true;
|
|
989
|
-
try {
|
|
990
|
-
await turno(texto);
|
|
991
|
-
} finally {
|
|
992
|
-
enviar.disabled = false;
|
|
993
|
-
entrada.focus();
|
|
994
|
-
}
|
|
995
|
-
};
|
|
996
|
-
const abrir = () => {
|
|
997
|
-
panel.hidden = false;
|
|
998
|
-
entrada.focus();
|
|
999
|
-
};
|
|
1000
|
-
const cerrar = () => {
|
|
1001
|
-
panel.hidden = true;
|
|
1002
|
-
};
|
|
1003
|
-
orbe.onclick = () => panel.hidden ? abrir() : cerrar();
|
|
1004
|
-
const alTeclear = (e) => {
|
|
1005
|
-
if (e.key === "Escape") cerrar();
|
|
1006
|
-
};
|
|
1007
|
-
document.addEventListener("keydown", alTeclear);
|
|
1008
|
-
return {
|
|
1009
|
-
open: abrir,
|
|
1010
|
-
close: cerrar,
|
|
1011
|
-
destroy: () => {
|
|
1012
|
-
document.removeEventListener("keydown", alTeclear);
|
|
1013
|
-
raiz.remove();
|
|
1014
|
-
}
|
|
1015
|
-
};
|
|
1016
|
-
}
|
|
1017
|
-
|
|
1018
816
|
// src/capabilities.ts
|
|
1019
817
|
async function conAutoridad(tools, call, ejecutar) {
|
|
1020
818
|
const tool = tools.find((t) => t.name === call.name);
|
|
@@ -1309,7 +1107,6 @@ var handeia = handeia_exports;
|
|
|
1309
1107
|
httpTransport,
|
|
1310
1108
|
local,
|
|
1311
1109
|
mcp,
|
|
1312
|
-
mountAgent,
|
|
1313
1110
|
requiresApproval,
|
|
1314
1111
|
toMCPTool,
|
|
1315
1112
|
toMCPTools,
|