@intutic/gate 1.10.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.
Files changed (83) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +261 -0
  3. package/dist/actions.d.ts +86 -0
  4. package/dist/actions.d.ts.map +1 -0
  5. package/dist/actions.js +239 -0
  6. package/dist/actions.js.map +1 -0
  7. package/dist/client.d.ts +94 -0
  8. package/dist/client.d.ts.map +1 -0
  9. package/dist/client.js +207 -0
  10. package/dist/client.js.map +1 -0
  11. package/dist/dsh.d.ts +162 -0
  12. package/dist/dsh.d.ts.map +1 -0
  13. package/dist/dsh.js +189 -0
  14. package/dist/dsh.js.map +1 -0
  15. package/dist/errors.d.ts +41 -0
  16. package/dist/errors.d.ts.map +1 -0
  17. package/dist/errors.js +53 -0
  18. package/dist/errors.js.map +1 -0
  19. package/dist/eve.d.ts +425 -0
  20. package/dist/eve.d.ts.map +1 -0
  21. package/dist/eve.js +378 -0
  22. package/dist/eve.js.map +1 -0
  23. package/dist/gate.d.ts +113 -0
  24. package/dist/gate.d.ts.map +1 -0
  25. package/dist/gate.js +274 -0
  26. package/dist/gate.js.map +1 -0
  27. package/dist/harness.d.ts +482 -0
  28. package/dist/harness.d.ts.map +1 -0
  29. package/dist/harness.js +504 -0
  30. package/dist/harness.js.map +1 -0
  31. package/dist/headers.d.ts +26 -0
  32. package/dist/headers.d.ts.map +1 -0
  33. package/dist/headers.js +30 -0
  34. package/dist/headers.js.map +1 -0
  35. package/dist/imagecheck.d.ts +93 -0
  36. package/dist/imagecheck.d.ts.map +1 -0
  37. package/dist/imagecheck.js +286 -0
  38. package/dist/imagecheck.js.map +1 -0
  39. package/dist/index.d.ts +26 -0
  40. package/dist/index.d.ts.map +1 -0
  41. package/dist/index.js +19 -0
  42. package/dist/index.js.map +1 -0
  43. package/dist/managedAgents.d.ts +375 -0
  44. package/dist/managedAgents.d.ts.map +1 -0
  45. package/dist/managedAgents.js +446 -0
  46. package/dist/managedAgents.js.map +1 -0
  47. package/dist/mastra.d.ts +175 -0
  48. package/dist/mastra.d.ts.map +1 -0
  49. package/dist/mastra.js +161 -0
  50. package/dist/mastra.js.map +1 -0
  51. package/dist/openai.d.ts +392 -0
  52. package/dist/openai.d.ts.map +1 -0
  53. package/dist/openai.js +658 -0
  54. package/dist/openai.js.map +1 -0
  55. package/dist/shlex.d.ts +16 -0
  56. package/dist/shlex.d.ts.map +1 -0
  57. package/dist/shlex.js +78 -0
  58. package/dist/shlex.js.map +1 -0
  59. package/dist/snapshot.d.ts +111 -0
  60. package/dist/snapshot.d.ts.map +1 -0
  61. package/dist/snapshot.js +243 -0
  62. package/dist/snapshot.js.map +1 -0
  63. package/dist/soprules.d.ts +88 -0
  64. package/dist/soprules.d.ts.map +1 -0
  65. package/dist/soprules.js +176 -0
  66. package/dist/soprules.js.map +1 -0
  67. package/dist/trueforge.d.ts +191 -0
  68. package/dist/trueforge.d.ts.map +1 -0
  69. package/dist/trueforge.js +184 -0
  70. package/dist/trueforge.js.map +1 -0
  71. package/dist/vercel.d.ts +174 -0
  72. package/dist/vercel.d.ts.map +1 -0
  73. package/dist/vercel.js +157 -0
  74. package/dist/vercel.js.map +1 -0
  75. package/dist/workflow.d.ts +209 -0
  76. package/dist/workflow.d.ts.map +1 -0
  77. package/dist/workflow.js +254 -0
  78. package/dist/workflow.js.map +1 -0
  79. package/dist/wrapTools.d.ts +68 -0
  80. package/dist/wrapTools.d.ts.map +1 -0
  81. package/dist/wrapTools.js +95 -0
  82. package/dist/wrapTools.js.map +1 -0
  83. package/package.json +123 -0
package/dist/eve.d.ts ADDED
@@ -0,0 +1,425 @@
1
+ /**
2
+ * eve adapter: `intuticApproval()`, `intuticConnectionApproval()`,
3
+ * `intuticAuditHooks()`.
4
+ *
5
+ * `@intutic/gate/eve` — a framework-specific specialization of the same idea
6
+ * `wrapTools.ts` implements generically (see that file's module doc): wrap the
7
+ * framework's own veto point around this package's `Gate.guard()`.
8
+ *
9
+ * eve (npm `eve`, github.com/vercel/eve) is Vercel's filesystem-first
10
+ * framework for durable backend AI agents: an agent is a directory (`agent/`
11
+ * with `instructions.md`, `agent/tools/*.ts`, `agent/connections/*.ts`,
12
+ * `agent/hooks/*.ts`, ...) that eve builds by walking the tree. It is a
13
+ * pre-1.0 PREVIEW product (0.39.1 at the time of writing, very active) —
14
+ * see docs/TECH_DEBT.md TD-410 for the churn shield this adapter carries,
15
+ * the same posture the dsh integration established.
16
+ *
17
+ * ## The veto mechanism — CONFIRMED against a real install, not assumed
18
+ *
19
+ * `eve@0.39.1` is installed as a devDependency of this package and its
20
+ * shipped `.d.ts` files were read directly (not inferred from docs alone).
21
+ * eve's per-tool veto point is the `approval` property on a tool definition
22
+ * (`dist/src/public/definitions/tool.d.ts`), and the same `Approval` type is
23
+ * accepted per-connection by `defineMcpClientConnection` /
24
+ * `defineOpenAPIConnection` (`dist/src/public/definitions/connections/
25
+ * {mcp,openapi}.d.ts`), gating ALL of that connection's tools. There is NO
26
+ * agent-level default approval field (`agent.d.ts` carries zero approval
27
+ * fields — verified) — attaching a shared policy per tool/connection is
28
+ * eve's own documented multi-tenant pattern
29
+ * (`docs/patterns/multi-tenant-approvals.md`), and exactly the shape this
30
+ * adapter exports.
31
+ *
32
+ * The confirmed policy contract (`dist/src/public/definitions/approval.d.ts`):
33
+ *
34
+ * ```ts
35
+ * export interface ApprovalContext<TInput = Record<string, unknown>> extends SessionContext {
36
+ * readonly approvedTools: ReadonlySet<string>
37
+ * readonly callId: string
38
+ * readonly toolInput?: ApprovalToolInput<TInput> // Readonly<TInput> | TInput; CAN be undefined
39
+ * readonly toolName: string
40
+ * }
41
+ * export type ApprovalStatus = undefined | boolean
42
+ * | 'not-applicable' | 'approved' | 'denied' | 'user-approval'
43
+ * | { readonly type: 'not-applicable'; readonly reason?: never }
44
+ * | { readonly type: 'approved'; readonly reason?: string }
45
+ * | { readonly type: 'denied'; readonly reason?: string }
46
+ * | { readonly type: 'user-approval'; readonly reason?: never }
47
+ * export type ApprovalPolicy<TInput = Record<string, unknown>> =
48
+ * (ctx: ApprovalContext<TInput>) => ApprovalStatus | Promise<ApprovalStatus>
49
+ * ```
50
+ *
51
+ * These are AI SDK 7 approval statuses (eve is built on `ai` v7 — the same
52
+ * family `vercel.ts` documents). `'denied'` / `{ type: 'denied', reason }`
53
+ * vetoes the call before execution; `reason` reaches the model in place of a
54
+ * tool result. `'not-applicable'` (and `undefined`) means "continue without a
55
+ * prompt"; `'user-approval'` parks the run durably for a human. The boolean
56
+ * forms are back-compat for eve's earlier predicate shape: `true` is treated
57
+ * as `'user-approval'` and `false` as `'not-applicable'` (confirmed in
58
+ * `docs/tools/human-in-the-loop.md`) — this adapter never RETURNS booleans,
59
+ * but its structural {@link EveApprovalStatus} copy includes them so the type
60
+ * stays field-for-field faithful to the real union.
61
+ *
62
+ * ## Allow-shape: why `'not-applicable'` and not `'approved'`
63
+ *
64
+ * Unlike the Vercel AI SDK's `toolApproval` (a separate, whole-run config
65
+ * that coexists with per-tool mechanisms), eve's `approval` IS the tool's one
66
+ * approval policy — whatever this function returns is the whole decision for
67
+ * that call. On allow this adapter returns `'not-applicable'` by default:
68
+ * eve's own "no prompt needed, continue" value, matching the semantics of an
69
+ * omitted `approval` (`never()`). It deliberately does NOT return
70
+ * `'approved'`: that value asserts an affirmative approval decision this gate
71
+ * did not make (Intutic's allow is "no objection", not "signed off"), and its
72
+ * interaction with eve's `approvedTools` bookkeeping (`once()` keys off that
73
+ * set) is not something this adapter verified. Callers who want eve's human
74
+ * flow ON TOP of the governance gate set `{ onAllow: 'user-approval' }` —
75
+ * "governance has no objection; still ask a person" — or compose manually
76
+ * (see {@link intuticApproval}).
77
+ *
78
+ * ## Audit hooks — observe-only, and honestly scoped
79
+ *
80
+ * eve's hook surface (`agent/hooks/*.ts`, `dist/src/public/definitions/
81
+ * hook.d.ts`) exposes `approval.candidate` / `approval.settled` stream
82
+ * events. Handlers are OBSERVE-ONLY by eve's own contract ("fire after eve
83
+ * has accepted and durably recorded each event ... cannot inject model
84
+ * context") — {@link intuticAuditHooks} is telemetry, not enforcement; the
85
+ * enforcement surface is {@link intuticApproval}. LOAD-BEARING caveat,
86
+ * verified against `dist/src/protocol/message.d.ts`: these two events carry
87
+ * `requestId`/`responderPrincipalId`/`turnId`/`stepIndex` but NOT the tool
88
+ * name or input.
89
+ *
90
+ * TD-411 half 2, revisited: `intuticApproval()` and `intuticAuditHooks()` are
91
+ * both plain functions exported from this one module and cannot be assumed to
92
+ * run in the same process at settlement time — eve's own docs state a parked
93
+ * approval survives a process restart verbatim ("the process can restart and
94
+ * the parked turn survives", `docs/tools/human-in-the-loop.md`), so a
95
+ * `requestId -> toolName` map populated at approval-decision time and read
96
+ * back later inside the hook would silently degrade for exactly the durable,
97
+ * long-parked approvals this mechanism exists for — the worst kind of fix,
98
+ * correct in local testing and quietly wrong in the deployments that matter
99
+ * most. That map was NOT built.
100
+ *
101
+ * What WAS found and built instead needs no cross-call memory at all: eve
102
+ * ships a THIRD hookable event, `input.requested` (confirmed in the same
103
+ * `HookEventMap`, `dist/src/public/definitions/hook.d.ts`), fired once when a
104
+ * batch of human-input requests is created — including every `kind:
105
+ * 'tool-approval'` request `intuticApproval()`'s `'user-approval'` return
106
+ * value produces. Each request in that ONE event already carries
107
+ * `requestId` AND `action.toolName` TOGETHER (`InputRequest`,
108
+ * `dist/src/runtime/input/types.d.ts`'s `inputRequestSchema` — confirmed by
109
+ * the shipped zod schema, not just prose; corroborated by
110
+ * `docs/tools/human-in-the-loop.md`'s explicit statement that "`toolName` and
111
+ * `requestId` identify the action and request"). {@link intuticAuditHooks}
112
+ * now subscribes to it too: it emits a real, tool-identified `tool_flagged`
113
+ * event at REQUEST time (closing the "no tool identity" gap unconditionally,
114
+ * with no process-boundary risk — the whole payload arrives in one event),
115
+ * and best-effort caches `requestId -> toolName` in memory so the LATER
116
+ * `approval.candidate`/`approval.settled` events attribute to the real tool
117
+ * name too WHEN this cache is still warm (same-process, or a short-lived
118
+ * pause). When it is not — a genuinely long-parked, cross-restart approval —
119
+ * settlement still falls back to the synthetic {@link EVE_APPROVAL_TOOL_NAME},
120
+ * exactly the pre-existing behaviour, never worse. See TD-411 for the full
121
+ * reasoning and what a persistent (non-memory) correlation store would take
122
+ * to close that residual gap.
123
+ *
124
+ * ## LLM egress — documented honestly, not oversold
125
+ *
126
+ * eve routes models through the Vercel AI Gateway by default (a gateway model
127
+ * id string in `agent.ts`'s `defineAgent({ model })`, `AI_GATEWAY_API_KEY` /
128
+ * `VERCEL_OIDC_TOKEN` credentials — confirmed in `docs/agent-config.md` and
129
+ * `docs/getting-started.mdx`). The AI Gateway wire protocol is NOT something
130
+ * the Intutic proxy parses, so gateway-routed egress is ungoverned by the
131
+ * proxy — full stop, and TD-412 tracks it. The governable path is eve's
132
+ * other documented option: passing a provider-authored `LanguageModel`
133
+ * (`createOpenAI(...)` etc.) to `defineAgent({ model })`, where the
134
+ * `withIntuticProxy()` helper — implemented once in `vercel.ts` and
135
+ * re-exported here — applies exactly as it does for the plain Vercel AI SDK.
136
+ * As with that framework, there is no env-var base-URL override: routing is
137
+ * in-code, per provider-construction call site.
138
+ *
139
+ * @module
140
+ */
141
+ import { type Gate } from './gate.js';
142
+ import { GateClient } from './client.js';
143
+ export { intuticProxyUrl, withIntuticProxy } from './vercel.js';
144
+ /** Synthetic tool name used by {@link intuticAuditHooks} — eve's
145
+ * `approval.candidate`/`approval.settled` events do not carry the real tool
146
+ * name (verified against `dist/src/protocol/message.d.ts`; see module doc). */
147
+ export declare const EVE_APPROVAL_TOOL_NAME = "eve:approval";
148
+ /** Structural copy of eve's `ApprovalStatus` — this package does not depend
149
+ * on `eve` at runtime, so the shape is declared here rather than imported.
150
+ * Confirmed field-for-field against `eve@0.39.1`'s
151
+ * `dist/src/public/definitions/approval.d.ts` (see module doc), including
152
+ * the boolean back-compat forms this adapter itself never returns. */
153
+ export type EveApprovalStatus = undefined | boolean | 'not-applicable' | 'approved' | 'denied' | 'user-approval' | {
154
+ readonly type: 'not-applicable';
155
+ readonly reason?: never;
156
+ } | {
157
+ readonly type: 'approved';
158
+ readonly reason?: string;
159
+ } | {
160
+ readonly type: 'denied';
161
+ readonly reason?: string;
162
+ } | {
163
+ readonly type: 'user-approval';
164
+ readonly reason?: never;
165
+ };
166
+ /** Structural copy of the slice of eve's `ApprovalContext` this adapter
167
+ * reads (`toolName`, `toolInput`). The real context is wider — it extends
168
+ * `SessionContext` and also carries `approvedTools`/`callId` — so the real
169
+ * type is assignable to this one, which is what makes a policy declared
170
+ * against this slice assignable to eve's own `ApprovalPolicy`. */
171
+ export interface EveApprovalContext {
172
+ /** Final runtime tool name. Path-derived for authored tools
173
+ * (`agent/tools/refund_charge.ts` → `refund_charge`); QUALIFIED for
174
+ * connection tools (`billing__updateSubscription`) — see
175
+ * {@link intuticConnectionApproval}. */
176
+ readonly toolName: string;
177
+ /** Parsed tool input. eve documents this CAN be undefined; a non-object is
178
+ * also possible for non-record input schemas — see
179
+ * {@link renderEveToolInput}'s handling. */
180
+ readonly toolInput?: unknown;
181
+ }
182
+ /** The policy function shape this adapter returns — assignable to eve's
183
+ * `ApprovalPolicy` (and therefore to a tool definition's `approval` field
184
+ * and a connection's `approval` field, both of which accept `Approval =
185
+ * ApprovalPolicy | ApprovalConfiguration`). */
186
+ export type EveApprovalPolicy = (ctx: EveApprovalContext) => Promise<EveApprovalStatus>;
187
+ export interface IntuticApprovalOptions {
188
+ /** Overrides the process-wide installed gate (`install(new Gate(...))`). */
189
+ gate?: Gate;
190
+ /**
191
+ * Status returned when the gate ALLOWS the call.
192
+ *
193
+ * - `'not-applicable'` (default): continue without a human prompt — eve's
194
+ * own "no prompt needed" value, the same behaviour as an omitted
195
+ * `approval` (`never()`). Use when Intutic governance is the only
196
+ * approval layer this tool needs.
197
+ * - `'user-approval'`: park the run durably for a person even though
198
+ * governance has no objection — the "governance gate + human sign-off"
199
+ * stack, equivalent to composing with eve's `always()`.
200
+ *
201
+ * `'approved'` is deliberately not offered — see the module doc's
202
+ * "Allow-shape" section. For anything more conditional (e.g. eve's
203
+ * `once()`, or your own tenant policy), compose manually:
204
+ *
205
+ * ```ts
206
+ * import { once } from 'eve/tools/approval'
207
+ * const intutic = intuticApproval()
208
+ * // inside defineTool({ ... }):
209
+ * approval: async (ctx) => {
210
+ * const verdict = await intutic(ctx)
211
+ * if (typeof verdict === 'object' && verdict?.type === 'denied') return verdict
212
+ * return once()(ctx) // your own flow decides the rest
213
+ * },
214
+ * ```
215
+ */
216
+ onAllow?: 'not-applicable' | 'user-approval';
217
+ }
218
+ /**
219
+ * Builds an approval policy matching eve's `ApprovalPolicy` signature, for
220
+ * direct use as a tool definition's `approval` field:
221
+ *
222
+ * ```ts
223
+ * // agent/tools/refund_charge.ts
224
+ * import { defineTool } from 'eve/tools'
225
+ * import { z } from 'zod'
226
+ * import { intuticApproval } from '@intutic/gate/eve'
227
+ *
228
+ * export default defineTool({
229
+ * description: 'Refund a charge.',
230
+ * inputSchema: z.object({ chargeId: z.string(), amount: z.number() }),
231
+ * approval: intuticApproval(),
232
+ * async execute(input) {
233
+ * return refund(input)
234
+ * },
235
+ * })
236
+ * ```
237
+ *
238
+ * (Install the gate once, process-wide, e.g. in `agent.ts`:
239
+ * `install(new Gate({ workspaceId: process.env.INTUTIC_WORKSPACE_ID }))`.)
240
+ *
241
+ * Resolves to `'not-applicable'` on allow (or `opts.onAllow` — see
242
+ * {@link IntuticApprovalOptions.onAllow}) and to `{ type: 'denied', reason }`
243
+ * on refusal — `reason` is the `[Intutic Governance] BLOCKED: ...` message,
244
+ * handed back to the model in place of a tool result; the tool's `execute`
245
+ * never runs.
246
+ *
247
+ * Requires a `Gate` — either passed via `{ gate }` here, or installed
248
+ * process-wide with `install(new Gate(...))`. A call with neither throws,
249
+ * refusing to run the tool unguarded rather than silently skipping
250
+ * enforcement — same posture as `wrapTool`/`intuticHooks`/
251
+ * `intuticToolApproval`. A non-refusal crash inside the gate is re-thrown
252
+ * rather than mapped to a denial — eve's own approval docs direct policies to
253
+ * "throw or deny, never silently allow", and a thrown policy fails the turn
254
+ * (fail closed), matching vercel.ts's posture for the same status family.
255
+ */
256
+ export declare function intuticApproval(opts?: IntuticApprovalOptions): EveApprovalPolicy;
257
+ /**
258
+ * The same policy, shaped for a CONNECTION's `approval` field — eve's MCP and
259
+ * OpenAPI connections accept one `approval` gating ALL of that connection's
260
+ * tools (`defineMcpClientConnection`/`defineOpenAPIConnection`, confirmed at
261
+ * `dist/src/public/definitions/connections/{mcp,openapi}.d.ts` — an omitted
262
+ * `approval` means every connection tool executes without approval):
263
+ *
264
+ * ```ts
265
+ * // agent/connections/support.ts
266
+ * import { defineMcpClientConnection } from 'eve/connections'
267
+ * import { intuticConnectionApproval } from '@intutic/gate/eve'
268
+ *
269
+ * export default defineMcpClientConnection({
270
+ * url: 'https://support.example.com/mcp',
271
+ * description: 'Support tickets.',
272
+ * approval: intuticConnectionApproval(),
273
+ * })
274
+ * ```
275
+ *
276
+ * Implemented AS {@link intuticApproval} (one enforcement path, not two) —
277
+ * the separate export exists because the surface differs in one way worth
278
+ * knowing: `ctx.toolName` for a connection tool is the QUALIFIED name
279
+ * (`support__add_internal_note`, connection slug + `__` + remote tool name —
280
+ * eve's own convention, per `docs/patterns/multi-tenant-approvals.md`), and
281
+ * that qualified name is what `Gate.guard()` evaluates and what SOP rules /
282
+ * snapshot `tool:` subjects must match. This adapter deliberately does not
283
+ * strip the prefix: the qualified name is the call's real identity inside
284
+ * this eve app, and un-prefixing would let two connections' same-named remote
285
+ * tools collapse into one rule target.
286
+ */
287
+ export declare function intuticConnectionApproval(opts?: IntuticApprovalOptions): EveApprovalPolicy;
288
+ /** Structural copy of eve's `ApprovalCandidateStreamEvent` — the
289
+ * `approval.candidate` payload (`dist/src/protocol/message.d.ts`). Note:
290
+ * no tool name/input fields exist on this event (see module doc). */
291
+ export interface EveApprovalCandidateEvent {
292
+ readonly type: 'approval.candidate';
293
+ readonly data: {
294
+ readonly candidateId: string;
295
+ readonly outcome: 'pending' | 'rejected' | 'failed' | 'timed-out' | 'stale';
296
+ readonly requestId: string;
297
+ readonly responderPrincipalId: string;
298
+ readonly reason?: string;
299
+ readonly sequence: number;
300
+ readonly stepIndex: number;
301
+ readonly turnId: string;
302
+ };
303
+ }
304
+ /** Structural copy of eve's `ApprovalSettledStreamEvent` — the terminal
305
+ * durable settlement for one approval request. */
306
+ export interface EveApprovalSettledEvent {
307
+ readonly type: 'approval.settled';
308
+ readonly data: {
309
+ readonly outcome: 'approved' | 'cancelled';
310
+ readonly requestId: string;
311
+ readonly responderPrincipalId: string;
312
+ readonly sequence: number;
313
+ readonly stepIndex: number;
314
+ readonly turnId: string;
315
+ };
316
+ }
317
+ /**
318
+ * Structural copy of one element of eve's `InputRequestedStreamEvent.data.requests`
319
+ * (`InputRequest`, `dist/src/runtime/input/types.d.ts`'s `inputRequestSchema`,
320
+ * read from the shipped zod schema, not just its `.d.ts`) — narrowed to the
321
+ * fields this module reads. Unlike {@link EveApprovalCandidateEvent} /
322
+ * {@link EveApprovalSettledEvent}, this DOES carry the real tool name
323
+ * (`action.toolName`) alongside `requestId`, in the same object. See TD-411.
324
+ */
325
+ export interface EveInputRequest {
326
+ readonly requestId: string;
327
+ readonly kind: 'question' | 'session-limit' | 'tool-approval';
328
+ /** Required in the real shipped schema for every `kind`; kept optional
329
+ * here since this module only trusts it for `kind: 'tool-approval'` and
330
+ * a structural copy should not assume more than it reads. */
331
+ readonly action?: {
332
+ readonly callId: string;
333
+ readonly toolName: string;
334
+ readonly input?: unknown;
335
+ };
336
+ }
337
+ /** Structural copy of eve's `InputRequestedStreamEvent` — a REAL hookable
338
+ * `HookEventMap` key (`'input.requested'`, `dist/src/public/definitions/
339
+ * hook.d.ts`), fired once per batch of pending human-input requests. */
340
+ export interface EveInputRequestedEvent {
341
+ readonly type: 'input.requested';
342
+ readonly data: {
343
+ readonly requests: readonly EveInputRequest[];
344
+ readonly sequence: number;
345
+ readonly stepIndex: number;
346
+ readonly turnId: string;
347
+ };
348
+ }
349
+ /** Structural slice of eve's `HookContext` this adapter reads. The real
350
+ * context is wider (extends `SessionContext`, `agent.name` required) — the
351
+ * real type is assignable to this one. */
352
+ export interface EveHookContext {
353
+ readonly session: {
354
+ readonly id: string;
355
+ };
356
+ readonly agent?: {
357
+ readonly name: string;
358
+ };
359
+ }
360
+ /** The `{ events }` object {@link intuticAuditHooks} returns — structurally
361
+ * a valid eve `HookDefinition`, accepted by `defineHook` as-is. */
362
+ export interface EveAuditHookDefinition {
363
+ readonly events: {
364
+ readonly 'input.requested': (event: EveInputRequestedEvent, ctx: EveHookContext) => Promise<void>;
365
+ readonly 'approval.candidate': (event: EveApprovalCandidateEvent, ctx: EveHookContext) => Promise<void>;
366
+ readonly 'approval.settled': (event: EveApprovalSettledEvent, ctx: EveHookContext) => Promise<void>;
367
+ };
368
+ }
369
+ export interface IntuticAuditHooksOptions {
370
+ /**
371
+ * Fixed control-plane client. When omitted, one client is built per eve
372
+ * session via `GateClient.fromEnv({ harness: 'eve', sessionId })` using the
373
+ * eve session id off the hook context — eve's durable session IS the
374
+ * meaningful attribution unit here, unlike dsh (whose plugin mounts before
375
+ * any session exists and settles for one process-wide id). Passing a
376
+ * client pins every event to THAT client's own session id instead.
377
+ */
378
+ client?: GateClient;
379
+ }
380
+ /**
381
+ * Observe-only audit emitter for eve's human-approval lifecycle, shaped for
382
+ * `agent/hooks/`:
383
+ *
384
+ * ```ts
385
+ * // agent/hooks/intutic-audit.ts
386
+ * import { defineHook } from 'eve/hooks'
387
+ * import { intuticAuditHooks } from '@intutic/gate/eve'
388
+ *
389
+ * export default defineHook(intuticAuditHooks())
390
+ * ```
391
+ *
392
+ * Maps eve's approval stream events onto Intutic's gate event vocabulary
393
+ * (the same `tool_allowed`/`tool_blocked`/`tool_flagged` names `gate.ts`
394
+ * emits, so the dashboard renders both sources on one timeline):
395
+ *
396
+ * - `input.requested`, one `kind: 'tool-approval'` request → `tool_flagged`,
397
+ * under the REAL tool name (`request.action.toolName`) — a genuinely new
398
+ * signal this adapter did not emit before: a call is now pending human
399
+ * approval. See the module doc (TD-411) for why this event, not a
400
+ * process-memory map, is what closes "no tool identity" here.
401
+ * - `approval.settled` `outcome: 'approved'` → `tool_allowed` — a human
402
+ * explicitly approved the parked call.
403
+ * - `approval.settled` `outcome: 'cancelled'` → `tool_blocked` — the request
404
+ * was settled without approval; the call never ran. This is a HUMAN veto
405
+ * recorded for audit, not an Intutic-gate refusal (the reason string says
406
+ * so), and like every `tool_blocked` it creates an incident row.
407
+ * - `approval.candidate` non-`'pending'` outcomes (`rejected`/`failed`/
408
+ * `timed-out`/`stale`) → `tool_flagged` — a responder's attempt to answer
409
+ * went somewhere worth an operator's attention. `'pending'` (a candidate
410
+ * simply being created) is routine lifecycle and deliberately NOT emitted.
411
+ *
412
+ * `approval.candidate`/`approval.settled` attribute to the REAL tool name
413
+ * when this instance's in-memory `requestId -> toolName` cache (populated
414
+ * by `input.requested`) is still warm, and fall back to the synthetic
415
+ * {@link EVE_APPROVAL_TOOL_NAME} otherwise — see the module doc for why that
416
+ * fallback exists and is not itself a bug.
417
+ *
418
+ * These hooks are TELEMETRY, not enforcement: eve runs hook handlers after
419
+ * events are durably recorded, and they cannot veto anything (eve's own
420
+ * "observe-only" hook contract). The enforcement surface is
421
+ * {@link intuticApproval}. Handlers never throw — a telemetry failure must
422
+ * not break the run (`GateClient.emit`'s own never-throws contract).
423
+ */
424
+ export declare function intuticAuditHooks(opts?: IntuticAuditHooksOptions): EveAuditHookDefinition;
425
+ //# sourceMappingURL=eve.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"eve.d.ts","sourceRoot":"","sources":["../src/eve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2IG;AAEH,OAAO,EAAwB,KAAK,IAAI,EAAE,MAAM,WAAW,CAAA;AAE3D,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAMxC,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAE/D;;gFAEgF;AAChF,eAAO,MAAM,sBAAsB,iBAAiB,CAAA;AAEpD;;;;uEAIuE;AACvE,MAAM,MAAM,iBAAiB,GACzB,SAAS,GACT,OAAO,GACP,gBAAgB,GAChB,UAAU,GACV,QAAQ,GACR,eAAe,GACf;IAAE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,KAAK,CAAA;CAAE,GAC5D;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,KAAK,CAAA;CAAE,CAAA;AAE/D;;;;mEAImE;AACnE,MAAM,WAAW,kBAAkB;IACjC;;;6CAGyC;IACzC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB;;iDAE6C;IAC7C,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;CAC7B;AAED;;;gDAGgD;AAChD,MAAM,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,kBAAkB,KAAK,OAAO,CAAC,iBAAiB,CAAC,CAAA;AAEvF,MAAM,WAAW,sBAAsB;IACrC,4EAA4E;IAC5E,IAAI,CAAC,EAAE,IAAI,CAAA;IACX;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,OAAO,CAAC,EAAE,gBAAgB,GAAG,eAAe,CAAA;CAC7C;AAqBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,eAAe,CAAC,IAAI,GAAE,sBAA2B,GAAG,iBAAiB,CAmBpF;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,GAAE,sBAA2B,GAAG,iBAAiB,CAE9F;AAMD;;sEAEsE;AACtE,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAA;IACnC,QAAQ,CAAC,IAAI,EAAE;QACb,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;QAC5B,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,UAAU,GAAG,QAAQ,GAAG,WAAW,GAAG,OAAO,CAAA;QAC3E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;QAC1B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAA;QACrC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;QACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;QACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;QAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KACxB,CAAA;CACF;AAED;mDACmD;AACnD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAA;IACjC,QAAQ,CAAC,IAAI,EAAE;QACb,QAAQ,CAAC,OAAO,EAAE,UAAU,GAAG,WAAW,CAAA;QAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;QAC1B,QAAQ,CAAC,oBAAoB,EAAE,MAAM,CAAA;QACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;QACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;QAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KACxB,CAAA;CACF;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,IAAI,EAAE,UAAU,GAAG,eAAe,GAAG,eAAe,CAAA;IAC7D;;kEAE8D;IAC9D,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;QACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;QACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KACzB,CAAA;CACF;AAED;;yEAEyE;AACzE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;IAChC,QAAQ,CAAC,IAAI,EAAE;QACb,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAA;QAC7C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;QACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;QAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KACxB,CAAA;CACF;AAED;;2CAE2C;AAC3C,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAA;IACzC,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;CAC3C;AAED;oEACoE;AACpE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,iBAAiB,EAAE,CAC1B,KAAK,EAAE,sBAAsB,EAC7B,GAAG,EAAE,cAAc,KAChB,OAAO,CAAC,IAAI,CAAC,CAAA;QAClB,QAAQ,CAAC,oBAAoB,EAAE,CAC7B,KAAK,EAAE,yBAAyB,EAChC,GAAG,EAAE,cAAc,KAChB,OAAO,CAAC,IAAI,CAAC,CAAA;QAClB,QAAQ,CAAC,kBAAkB,EAAE,CAC3B,KAAK,EAAE,uBAAuB,EAC9B,GAAG,EAAE,cAAc,KAChB,OAAO,CAAC,IAAI,CAAC,CAAA;KACnB,CAAA;CACF;AAED,MAAM,WAAW,wBAAwB;IACvC;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,UAAU,CAAA;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,wBAA6B,GAAG,sBAAsB,CAwF7F"}