@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.
- package/LICENSE +21 -0
- package/README.md +261 -0
- package/dist/actions.d.ts +86 -0
- package/dist/actions.d.ts.map +1 -0
- package/dist/actions.js +239 -0
- package/dist/actions.js.map +1 -0
- package/dist/client.d.ts +94 -0
- package/dist/client.d.ts.map +1 -0
- package/dist/client.js +207 -0
- package/dist/client.js.map +1 -0
- package/dist/dsh.d.ts +162 -0
- package/dist/dsh.d.ts.map +1 -0
- package/dist/dsh.js +189 -0
- package/dist/dsh.js.map +1 -0
- package/dist/errors.d.ts +41 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +53 -0
- package/dist/errors.js.map +1 -0
- package/dist/eve.d.ts +425 -0
- package/dist/eve.d.ts.map +1 -0
- package/dist/eve.js +378 -0
- package/dist/eve.js.map +1 -0
- package/dist/gate.d.ts +113 -0
- package/dist/gate.d.ts.map +1 -0
- package/dist/gate.js +274 -0
- package/dist/gate.js.map +1 -0
- package/dist/harness.d.ts +482 -0
- package/dist/harness.d.ts.map +1 -0
- package/dist/harness.js +504 -0
- package/dist/harness.js.map +1 -0
- package/dist/headers.d.ts +26 -0
- package/dist/headers.d.ts.map +1 -0
- package/dist/headers.js +30 -0
- package/dist/headers.js.map +1 -0
- package/dist/imagecheck.d.ts +93 -0
- package/dist/imagecheck.d.ts.map +1 -0
- package/dist/imagecheck.js +286 -0
- package/dist/imagecheck.js.map +1 -0
- package/dist/index.d.ts +26 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +19 -0
- package/dist/index.js.map +1 -0
- package/dist/managedAgents.d.ts +375 -0
- package/dist/managedAgents.d.ts.map +1 -0
- package/dist/managedAgents.js +446 -0
- package/dist/managedAgents.js.map +1 -0
- package/dist/mastra.d.ts +175 -0
- package/dist/mastra.d.ts.map +1 -0
- package/dist/mastra.js +161 -0
- package/dist/mastra.js.map +1 -0
- package/dist/openai.d.ts +392 -0
- package/dist/openai.d.ts.map +1 -0
- package/dist/openai.js +658 -0
- package/dist/openai.js.map +1 -0
- package/dist/shlex.d.ts +16 -0
- package/dist/shlex.d.ts.map +1 -0
- package/dist/shlex.js +78 -0
- package/dist/shlex.js.map +1 -0
- package/dist/snapshot.d.ts +111 -0
- package/dist/snapshot.d.ts.map +1 -0
- package/dist/snapshot.js +243 -0
- package/dist/snapshot.js.map +1 -0
- package/dist/soprules.d.ts +88 -0
- package/dist/soprules.d.ts.map +1 -0
- package/dist/soprules.js +176 -0
- package/dist/soprules.js.map +1 -0
- package/dist/trueforge.d.ts +191 -0
- package/dist/trueforge.d.ts.map +1 -0
- package/dist/trueforge.js +184 -0
- package/dist/trueforge.js.map +1 -0
- package/dist/vercel.d.ts +174 -0
- package/dist/vercel.d.ts.map +1 -0
- package/dist/vercel.js +157 -0
- package/dist/vercel.js.map +1 -0
- package/dist/workflow.d.ts +209 -0
- package/dist/workflow.d.ts.map +1 -0
- package/dist/workflow.js +254 -0
- package/dist/workflow.js.map +1 -0
- package/dist/wrapTools.d.ts +68 -0
- package/dist/wrapTools.d.ts.map +1 -0
- package/dist/wrapTools.js +95 -0
- package/dist/wrapTools.js.map +1 -0
- 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":"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"}
|