@withgateway/sdk 0.2.3 → 0.2.5
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/cli.js +13267 -5869
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +13272 -5874
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.js +83 -31
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +79 -28
- package/dist/files/index.mjs.map +1 -1
- package/dist/hooks/index.d.mts +1 -0
- package/dist/hooks/index.d.ts +1 -0
- package/dist/hooks/index.js +4355 -0
- package/dist/hooks/index.js.map +1 -0
- package/dist/hooks/index.mjs +4243 -0
- package/dist/hooks/index.mjs.map +1 -0
- package/dist/{index-Dpo-t8iO.d.ts → index-1xnxt0Cc.d.ts} +58 -2
- package/dist/index-B0R3IgsV.d.mts +1279 -0
- package/dist/index-B0R3IgsV.d.ts +1279 -0
- package/dist/{index-B5HUQQDE.d.mts → index-C1wDEwH4.d.mts} +58 -2
- package/dist/index.d.mts +4 -3
- package/dist/index.d.ts +4 -3
- package/dist/index.js +6698 -1606
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +6793 -1713
- package/dist/index.mjs.map +1 -1
- package/dist/traces/index.js +72 -20
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +68 -17
- package/dist/traces/index.mjs.map +1 -1
- package/dist/tracing/index.d.mts +1 -1
- package/dist/tracing/index.d.ts +1 -1
- package/dist/tracing/index.js +47 -3
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +42 -2
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +390 -27
- package/dist/worlds/index.d.ts +390 -27
- package/dist/worlds/index.js +2291 -366
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +2281 -356
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +7 -1
- package/runtime/gatewaysdk/environment/_bundle.py +14 -24
- package/runtime/gatewaysdk/environment/_materialize.py +3 -3
- package/runtime/gatewaysdk/environment/schema/api.py +153 -20
- package/runtime/gatewaysdk/environment/schema/compiler.py +14 -0
- package/runtime/gatewaysdk/environment/schema/data.py +21 -19
- package/runtime/gatewaysdk/environment/schema/grading.py +225 -0
- package/runtime/gatewaysdk/environment/schema/host.py +171 -535
- package/runtime/gatewaysdk/environment/schema/ingest.py +3 -11
- package/runtime/gatewaysdk/environment/schema/local.py +32 -126
- package/runtime/gatewaysdk/environment/schema/platform.py +14 -22
- package/runtime/gatewaysdk/environment/schema/proof.py +237 -0
- package/runtime/gatewaysdk/environment/schema/runtime.py +686 -0
- package/runtime/gatewaysdk/environment/schema/skill.py +1 -0
- package/runtime/gatewaysdk/environment/schema/skills/hooks-getting-started/SKILL.md +156 -0
- package/runtime/gatewaysdk/environment/schema/snapshot.py +6 -5
- package/runtime/gatewaysdk/environment/schema/tasks.py +12 -2
- package/runtime/gatewaysdk/environment/schema/tools_world.py +75 -23
- package/runtime/gatewaysdk/environment/schema/verbs.py +136 -0
- package/runtime/gatewaysdk/environment/schema/workers.py +44 -13
- package/runtime/gatewaysdk/environment/world.py +391 -0
- package/skills/hooks-getting-started/SKILL.md +156 -0
|
@@ -0,0 +1,1279 @@
|
|
|
1
|
+
/** The kinds with a dedicated derivation; any other kind gets a `REF-nnnn` stand-in. */
|
|
2
|
+
declare const KINDS: readonly ["person_name", "email", "username", "phone", "company", "domain", "ip", "account", "machine", "log"];
|
|
3
|
+
type Pair = [real: string, alias: string];
|
|
4
|
+
/** The kinds a pattern finds in free text safely enough to act on sight — mint a
|
|
5
|
+
* persona for (`[alias] mint_inbound`) or redact (a `redact` handler): an address, a
|
|
6
|
+
* formatted number, a public IP. A name or a handle is not one: a title-case pair or
|
|
7
|
+
* a short word is as often a place, a product or a common noun, so those stay seeded. */
|
|
8
|
+
declare const INBOUND_KINDS: readonly ["email", "phone", "ip"];
|
|
9
|
+
type InboundKind = (typeof INBOUND_KINDS)[number];
|
|
10
|
+
/** Python's `ipaddress.ip_address(v).is_global` for a dotted quad: not private,
|
|
11
|
+
* loopback, link-local, shared, documentation (203.0.113.0/24 is where personas
|
|
12
|
+
* live), benchmarking, multicast or reserved space. */
|
|
13
|
+
declare function isGlobalIpv4(text: string): boolean;
|
|
14
|
+
/** Every value of one inbound kind in `text`, in order of first appearance, each
|
|
15
|
+
* once. A phone needs 10 to 15 digits; an IP must parse and be global. */
|
|
16
|
+
declare function findKind(kind: string, text: string): string[];
|
|
17
|
+
type Finding$1 = {
|
|
18
|
+
check: string;
|
|
19
|
+
detail?: string;
|
|
20
|
+
where: string;
|
|
21
|
+
kind?: string;
|
|
22
|
+
alias?: string;
|
|
23
|
+
variant?: string;
|
|
24
|
+
};
|
|
25
|
+
/** One run key per evaluation run: 32 random bytes as hex. Shared with the seeding
|
|
26
|
+
* and the grader, never stored beside the data, never reused. */
|
|
27
|
+
declare function newRunKey(): string;
|
|
28
|
+
/** One entity is one alias: NFKC, trim, lower-case for names, emails, usernames,
|
|
29
|
+
* domains and companies; digits only for phones; exploded form for IP addresses. */
|
|
30
|
+
declare function canonical(kind: string, value: unknown): string;
|
|
31
|
+
/** Python's `ipaddress.ip_address(text).exploded`: a dotted quad as it is, an IPv6
|
|
32
|
+
* address as eight zero-padded groups (an embedded IPv4 tail becomes two groups). */
|
|
33
|
+
declare function explodeIp(text: string): string | null;
|
|
34
|
+
/** Every spelling of a person's name a page or a record plausibly carries, paired
|
|
35
|
+
* with the same spelling of the alias. The bare surname is included deliberately: it
|
|
36
|
+
* is the commonest leak. */
|
|
37
|
+
declare function namePairs(real: string, fake: string): Pair[];
|
|
38
|
+
declare function emailPairs(real: string, fake: string): Pair[];
|
|
39
|
+
declare function phonePairs(real: string, fake: string): Pair[];
|
|
40
|
+
/** Python's `urllib.parse.quote(v, safe="")`: everything but `A-Za-z0-9_.-~` percent-encoded. */
|
|
41
|
+
declare function pyQuote(value: string): string;
|
|
42
|
+
declare function genericPairs(real: string, fake: string): Pair[];
|
|
43
|
+
/** One real value and its stand-in. */
|
|
44
|
+
type Alias = {
|
|
45
|
+
kind: string;
|
|
46
|
+
canonical: string;
|
|
47
|
+
real: string;
|
|
48
|
+
display: string;
|
|
49
|
+
/** The identity this attribute belongs to. */
|
|
50
|
+
identity: string | null;
|
|
51
|
+
/** `public` is never replaced. */
|
|
52
|
+
role: "private" | "public";
|
|
53
|
+
/** (real spelling, the SAME spelling of the alias), paired by form. */
|
|
54
|
+
variants: Pair[];
|
|
55
|
+
/** `found`: minted on sight by `mint_inbound`. */
|
|
56
|
+
provenance: "seed" | "world" | "web" | "found";
|
|
57
|
+
hitsIn: number;
|
|
58
|
+
hitsOut: number;
|
|
59
|
+
};
|
|
60
|
+
/** One private person, and every stand-in attribute derived from them. */
|
|
61
|
+
type Identity = {
|
|
62
|
+
key: string;
|
|
63
|
+
given: string;
|
|
64
|
+
surname: string;
|
|
65
|
+
company: string;
|
|
66
|
+
domain: string;
|
|
67
|
+
};
|
|
68
|
+
type SeedEntity = {
|
|
69
|
+
type: string;
|
|
70
|
+
value: unknown;
|
|
71
|
+
role?: "private" | "public";
|
|
72
|
+
identity?: string;
|
|
73
|
+
};
|
|
74
|
+
type SeedRow = {
|
|
75
|
+
type: string;
|
|
76
|
+
real: string;
|
|
77
|
+
alias: string;
|
|
78
|
+
role: string;
|
|
79
|
+
identity: string | null;
|
|
80
|
+
};
|
|
81
|
+
type LegendRow = {
|
|
82
|
+
kind: string;
|
|
83
|
+
role: string;
|
|
84
|
+
real: string;
|
|
85
|
+
alias: string;
|
|
86
|
+
identity: string | null;
|
|
87
|
+
provenance: string;
|
|
88
|
+
hits_in: number;
|
|
89
|
+
hits_out: number;
|
|
90
|
+
};
|
|
91
|
+
type Leak = {
|
|
92
|
+
where: string;
|
|
93
|
+
kind: string;
|
|
94
|
+
variant: string;
|
|
95
|
+
alias: string;
|
|
96
|
+
check?: string;
|
|
97
|
+
};
|
|
98
|
+
/**
|
|
99
|
+
* The run's map: every alias minted, the identities behind them, and the meters.
|
|
100
|
+
*
|
|
101
|
+
* `slugs` are the connector slugs whose worlds store personal fields as
|
|
102
|
+
* `sha256:<slug>:<value>`; seeding registers those digests as variants so a hashed
|
|
103
|
+
* field rewrites like a plaintext one.
|
|
104
|
+
*/
|
|
105
|
+
declare class AliasMap {
|
|
106
|
+
readonly runKey: string;
|
|
107
|
+
readonly slugs: readonly string[];
|
|
108
|
+
readonly aliases: Map<string, Alias>;
|
|
109
|
+
readonly identities: Map<string, Identity>;
|
|
110
|
+
readonly taken: Set<string>;
|
|
111
|
+
/** Digests that are ALREADY an alias's stand-in: never re-mint over one. */
|
|
112
|
+
readonly aliasDigests: Set<string>;
|
|
113
|
+
readonly leaksIn: Leak[];
|
|
114
|
+
readonly leaksOut: Leak[];
|
|
115
|
+
readonly unresolvedOut: Finding$1[];
|
|
116
|
+
/** Every value minted on sight: `{where, kind, alias}`. */
|
|
117
|
+
readonly found: {
|
|
118
|
+
where: string;
|
|
119
|
+
kind: string;
|
|
120
|
+
alias: string;
|
|
121
|
+
}[];
|
|
122
|
+
/** Every value a `redact` handler removed: `{where, kind}`. */
|
|
123
|
+
readonly redactions: {
|
|
124
|
+
where: string;
|
|
125
|
+
kind: string;
|
|
126
|
+
value?: string;
|
|
127
|
+
}[];
|
|
128
|
+
private readonly displays;
|
|
129
|
+
private pairsCache;
|
|
130
|
+
/** A value seeded `role: "public"` is never rewritten, even where a private
|
|
131
|
+
* entity's derived variants reach it (the domain of a private email that is a
|
|
132
|
+
* state company's). Off, the private entity's variants apply as derived. */
|
|
133
|
+
readonly publicLayerWins: boolean;
|
|
134
|
+
/** Mail domains kept real inside an email persona ("a gmail address" stays a
|
|
135
|
+
* fact without naming anyone). `null` is the built-in free-mail list; `[]`
|
|
136
|
+
* keeps none real; any other list replaces the built-in one. */
|
|
137
|
+
readonly publicMailboxDomains: readonly string[] | null;
|
|
138
|
+
/** Kinds (of `INBOUND_KINDS`) minted ON SIGHT: a value of one of them that arrives
|
|
139
|
+
* in a tool result or a page and was never seeded gets a persona there and then, so
|
|
140
|
+
* a third party found on the web is aliased in and resolved out like a seeded
|
|
141
|
+
* subject. Off (the default) such a value reaches the agent as it is — the seed
|
|
142
|
+
* list is the whole map. */
|
|
143
|
+
readonly mintInbound: readonly string[];
|
|
144
|
+
constructor(runKey: string, slugs?: readonly string[], options?: {
|
|
145
|
+
publicLayerWins?: boolean;
|
|
146
|
+
publicMailboxDomains?: readonly string[] | null;
|
|
147
|
+
mintInbound?: readonly string[];
|
|
148
|
+
});
|
|
149
|
+
private mailboxDomains;
|
|
150
|
+
private isPublic;
|
|
151
|
+
private static key;
|
|
152
|
+
identityFor(key: string): Identity;
|
|
153
|
+
/** The alias for one value. `identityKey` ties an attribute to its person, so
|
|
154
|
+
* every attribute of one identity stays consistent (the relationship rule). */
|
|
155
|
+
mint(kind: string, value: unknown, opts?: {
|
|
156
|
+
identityKey?: string;
|
|
157
|
+
role?: "private" | "public";
|
|
158
|
+
provenance?: "seed" | "world" | "web" | "found";
|
|
159
|
+
}): Alias;
|
|
160
|
+
/** A value of an inbound kind met in a result and never seeded: minted there and
|
|
161
|
+
* then (`provenance: "found"`), its variants spliced into the live pair lists so
|
|
162
|
+
* the rest of this walk and every later call see it, and recorded in `found`. The
|
|
163
|
+
* spelling the text carried is a variant too — a mixed-case address that canonical
|
|
164
|
+
* form alone would miss. */
|
|
165
|
+
mintFound(kind: string, value: string, where: string): Alias;
|
|
166
|
+
private known;
|
|
167
|
+
/** `mint_inbound` over a whole tree BEFORE it is rewritten: every unseeded value of
|
|
168
|
+
* a listed kind, in any string of it, gets its persona now. `walk` does this first so
|
|
169
|
+
* a spelling that sits in an earlier field than the one that reveals the value (a
|
|
170
|
+
* profile URL carrying the address percent-encoded, above the snippet that spells it
|
|
171
|
+
* out) is rewritten too — string order in a page is not the order the door learns
|
|
172
|
+
* things in. Returns how many were minted. */
|
|
173
|
+
discover(node: unknown, where?: string): number;
|
|
174
|
+
/** `mint_inbound` on one string: every unseeded value of a listed kind in `text`
|
|
175
|
+
* gets a persona and is rewritten here, before the leak meter looks. */
|
|
176
|
+
private mintFoundIn;
|
|
177
|
+
/** A `redact` handler: every value of the listed kinds, and every match of the
|
|
178
|
+
* listed patterns, becomes `token` — removed, not aliased. A persona's own spelling
|
|
179
|
+
* is left alone, so redaction after the door keeps the door's work. */
|
|
180
|
+
redactText<T>(text: T, opts?: {
|
|
181
|
+
kinds?: readonly string[];
|
|
182
|
+
/** Literal strings removed wherever they appear, any case, any run of whitespace. */
|
|
183
|
+
values?: readonly string[];
|
|
184
|
+
patterns?: readonly RegExp[];
|
|
185
|
+
token?: string;
|
|
186
|
+
where?: string;
|
|
187
|
+
}): T;
|
|
188
|
+
private derive;
|
|
189
|
+
/** A world serves hashed personal fields as `sha256:<hex>`. If the plaintext is
|
|
190
|
+
* one we know, the digest is that alias's; otherwise it is an identity we have no
|
|
191
|
+
* plaintext for, and it gets its own stable stand-in digest so records still join. */
|
|
192
|
+
mintDigest(digest: string, provenance?: "seed" | "world" | "web"): string;
|
|
193
|
+
/** Mint aliases for a task's known entities before the run starts, so the
|
|
194
|
+
* instruction the agent reads is already in alias space. `identity` groups the
|
|
195
|
+
* attributes of one person; `role: "public"` marks the public layer, never replaced. */
|
|
196
|
+
seed(entities: readonly SeedEntity[]): SeedRow[];
|
|
197
|
+
/** (needle, replacement, alias) for every variant, longest first, so a full name
|
|
198
|
+
* is replaced before its bare surname. */
|
|
199
|
+
/** The public layer, folded: what is never replaced — and never counted as a
|
|
200
|
+
* leak either. A found email whose local part IS a public handle (the subject's
|
|
201
|
+
* own `oni-sensei`, seeded public) derives that handle as a bare variant; with
|
|
202
|
+
* `publicLayerWins` the handle stays real in both directions and the meters agree,
|
|
203
|
+
* or every mention of the subject would read as a leak. */
|
|
204
|
+
private publicFolded;
|
|
205
|
+
private pairs;
|
|
206
|
+
/** Inbound. Every real value and variant becomes its alias, then what slipped
|
|
207
|
+
* through is counted. `meter: false` rewrites text that is being RECORDED, not
|
|
208
|
+
* shown to the agent, so it is not counted as leak-through. */
|
|
209
|
+
toAgent<T>(text: T, where?: string, meter?: boolean): T;
|
|
210
|
+
/** Outbound. Every alias variant becomes the real value, for a live API or for a
|
|
211
|
+
* fidelity world. An alias that leaves unresolved would make the agent fold a
|
|
212
|
+
* stranger into the case, so anything left over is recorded as a run-failing bug;
|
|
213
|
+
* a `sha256:` digest is a stored form, never a selector. */
|
|
214
|
+
toWorld<T>(text: T, where?: string): [T, Finding$1[]];
|
|
215
|
+
/** `toAgent` / `toWorld` over a whole JSON structure. */
|
|
216
|
+
walk(node: unknown, direction: "in", where?: string, meter?: boolean): unknown;
|
|
217
|
+
walk(node: unknown, direction: "out", where?: string): [unknown, Finding$1[]];
|
|
218
|
+
/** Requirement 3: count what slipped, do not assume nothing did. */
|
|
219
|
+
/** Requirement 3: count what slipped, do not assume nothing did. The scan is
|
|
220
|
+
* case-folded with whitespace collapsed and walks EVERY variant of every alias,
|
|
221
|
+
* not only the pairs the rewriter used. */
|
|
222
|
+
private meter;
|
|
223
|
+
/** Requirement 4: the report and the artifacts must contain no real value. */
|
|
224
|
+
scanOutgoing(text: unknown, where: string): Leak[];
|
|
225
|
+
/** The task the agent is given, in alias space. */
|
|
226
|
+
rewriteInstruction(text: string): string;
|
|
227
|
+
/** The run key's map. Kept WITH THE RUN KEY, never with the world data. */
|
|
228
|
+
/** Outbound without the meters: every persona spelling back to the real value.
|
|
229
|
+
* What `gateway hooks reveal` does to a run's files for an owner holding the
|
|
230
|
+
* legend. A `[redacted …]` token has nothing behind it: redaction removed the
|
|
231
|
+
* value; the raw copy is a `record` sink placed before the `redact` rule. */
|
|
232
|
+
revealText<T>(text: T): T;
|
|
233
|
+
/** `revealText` over a whole JSON structure. */
|
|
234
|
+
reveal(node: unknown): unknown;
|
|
235
|
+
/** The map a legend describes, rebuilt: every persona derives from the run key and
|
|
236
|
+
* its real value alone, so minting the rows again — the public layer first, then the
|
|
237
|
+
* rest in the legend's order — reproduces the same stand-ins, found ones included.
|
|
238
|
+
* This is how an owner's `gateway hooks legend` / `reveal` read a run that ended in
|
|
239
|
+
* another process. */
|
|
240
|
+
static fromLegend(legend: {
|
|
241
|
+
run_key: string;
|
|
242
|
+
aliases: readonly Partial<LegendRow>[];
|
|
243
|
+
}, options?: {
|
|
244
|
+
slugs?: readonly string[];
|
|
245
|
+
publicLayerWins?: boolean;
|
|
246
|
+
publicMailboxDomains?: readonly string[] | null;
|
|
247
|
+
}): AliasMap;
|
|
248
|
+
legend(): LegendRow[];
|
|
249
|
+
summary(): Record<string, unknown>;
|
|
250
|
+
/** The alias minted for a kind and value, if any. */
|
|
251
|
+
get(kind: string, value: unknown): Alias | undefined;
|
|
252
|
+
}
|
|
253
|
+
/** Case-folded, whitespace collapsed: how the leak meter and the outgoing scan look. */
|
|
254
|
+
declare const folded: (text: string) => string;
|
|
255
|
+
/** Give the alias a handle with the SAME morphology as the real one, so
|
|
256
|
+
* `mnowell` -> `jdoe` and `matthew.nowell` -> `john.doe`: the shape of the identity
|
|
257
|
+
* survives the substitution. */
|
|
258
|
+
declare function mirrorHandle(handle: string, identity: Identity): string;
|
|
259
|
+
|
|
260
|
+
/**
|
|
261
|
+
* The events a hook sees and the result it answers — the contract every handler
|
|
262
|
+
* (a command, an HTTP endpoint, a function, a built-in) implements. The same
|
|
263
|
+
* shapes as the Python SDK's `gatewaysdk.hooks.events`.
|
|
264
|
+
*
|
|
265
|
+
* pre_tool_call before the tool runs allow · deny (with reason) · rewrite tool_input
|
|
266
|
+
* post_tool_call after the tool returns rewrite tool_result (or the error text) · add findings
|
|
267
|
+
* pre_request before one HTTP request rewrite request {method, path, query, body} · deny
|
|
268
|
+
* post_response after one HTTP response rewrite response {status, body}
|
|
269
|
+
* run_end once, with the report fail the run with findings
|
|
270
|
+
*
|
|
271
|
+
* Claude Code's names are accepted as aliases (`PreToolUse`, `PostToolUse`,
|
|
272
|
+
* `Stop` / `SessionEnd` -> `run_end`).
|
|
273
|
+
*
|
|
274
|
+
* stdin {hook_event_name, run_id, tool_name, tool_input, tool_result?, error?,
|
|
275
|
+
* request?, response?, report?, artifacts?, matcher, vendor?, cwd}
|
|
276
|
+
* stdout {decision: "allow"|"deny"|"rewrite", reason?, updated_input?, updated_result?,
|
|
277
|
+
* updated_error?, updated_request?, updated_response?, additional_context?, findings?: []}
|
|
278
|
+
*
|
|
279
|
+
* The run key is never in the stdin JSON: only the built-in alias handler holds it.
|
|
280
|
+
*/
|
|
281
|
+
declare const EVENTS: readonly ["pre_tool_call", "post_tool_call", "pre_request", "post_response", "run_end"];
|
|
282
|
+
type HookEventName = (typeof EVENTS)[number];
|
|
283
|
+
declare const EVENT_ALIASES: Record<string, HookEventName>;
|
|
284
|
+
declare const DECISIONS: readonly ["allow", "deny", "rewrite"];
|
|
285
|
+
type Decision = (typeof DECISIONS)[number];
|
|
286
|
+
/** `pre_tool_call` for a snake_case name or a Claude Code alias; null otherwise. */
|
|
287
|
+
declare function normalizeEvent(name: string): HookEventName | null;
|
|
288
|
+
type Finding = Record<string, unknown> & {
|
|
289
|
+
check?: string;
|
|
290
|
+
where?: string;
|
|
291
|
+
};
|
|
292
|
+
type HookRequest = {
|
|
293
|
+
method: string;
|
|
294
|
+
path: string;
|
|
295
|
+
query?: Record<string, unknown>;
|
|
296
|
+
body?: unknown;
|
|
297
|
+
};
|
|
298
|
+
type HookResponse = {
|
|
299
|
+
/** null when the request never got an answer (see `error`). */
|
|
300
|
+
status: number | null;
|
|
301
|
+
body: unknown;
|
|
302
|
+
headers?: Record<string, string>;
|
|
303
|
+
/** Seconds the request took, set by `HookedSession.request`. */
|
|
304
|
+
elapsed?: number;
|
|
305
|
+
/** The network failure's text, when there was one, instead of a lost exception. */
|
|
306
|
+
error?: string;
|
|
307
|
+
};
|
|
308
|
+
/** One occurrence of an event. Every handler of one matcher sees the same event;
|
|
309
|
+
* the dispatcher merges their answers and applies the one rewrite before the next
|
|
310
|
+
* matcher's handlers run. */
|
|
311
|
+
type HookEvent = {
|
|
312
|
+
event: HookEventName;
|
|
313
|
+
runId: string;
|
|
314
|
+
/** The tool's name; for `pre_request` / `post_response` the request path. */
|
|
315
|
+
toolName: string;
|
|
316
|
+
toolInput?: unknown;
|
|
317
|
+
toolResult?: unknown;
|
|
318
|
+
/** Set on `post_tool_call` when the tool threw or the call was denied: the text. */
|
|
319
|
+
error?: string;
|
|
320
|
+
request?: HookRequest;
|
|
321
|
+
response?: HookResponse;
|
|
322
|
+
/** The final report on `run_end`. */
|
|
323
|
+
report?: string;
|
|
324
|
+
/** `{name: text}` on `run_end`. */
|
|
325
|
+
artifacts?: Record<string, string>;
|
|
326
|
+
vendor?: string;
|
|
327
|
+
/** The matcher text of the rule being applied. */
|
|
328
|
+
matcher: string;
|
|
329
|
+
cwd: string;
|
|
330
|
+
/** `[hook <name>] text` lines the handlers so far added for the agent. */
|
|
331
|
+
context: string[];
|
|
332
|
+
};
|
|
333
|
+
/** What a command handler reads on stdin and an HTTP handler is POSTed. */
|
|
334
|
+
declare function eventToJson(event: HookEvent): Record<string, unknown>;
|
|
335
|
+
/** What a handler answers. `decision` is `allow` (default), `deny` (with `reason`)
|
|
336
|
+
* or `rewrite` (with one or more `updated_*`, present only when set); `additional_context`
|
|
337
|
+
* reaches the agent labelled with the handler's name; `findings` travel with the run. */
|
|
338
|
+
type HookResult = {
|
|
339
|
+
decision: Decision;
|
|
340
|
+
reason?: string;
|
|
341
|
+
updated_input?: unknown;
|
|
342
|
+
updated_result?: unknown;
|
|
343
|
+
updated_error?: string;
|
|
344
|
+
updated_request?: HookRequest;
|
|
345
|
+
updated_response?: HookResponse;
|
|
346
|
+
additional_context?: string;
|
|
347
|
+
findings: Finding[];
|
|
348
|
+
};
|
|
349
|
+
declare class HookDenied extends Error {
|
|
350
|
+
readonly event: HookEventName;
|
|
351
|
+
readonly toolName: string;
|
|
352
|
+
readonly reason: string;
|
|
353
|
+
readonly findings: Finding[];
|
|
354
|
+
handler: string;
|
|
355
|
+
constructor(event: HookEventName, toolName: string, reason: string, findings?: Finding[], handler?: string);
|
|
356
|
+
}
|
|
357
|
+
/** A rule could not be applied: two handlers of one matcher both rewrote, or a
|
|
358
|
+
* handler failed on an event where a failure blocks (`pre_*`, `run_end`). Recorded
|
|
359
|
+
* on the run before it propagates — never silent. */
|
|
360
|
+
declare class HookError extends Error {
|
|
361
|
+
readonly event: HookEventName;
|
|
362
|
+
readonly toolName: string;
|
|
363
|
+
readonly handler: string;
|
|
364
|
+
readonly detail: string;
|
|
365
|
+
constructor(event: HookEventName, toolName: string, handler: string, detail: string);
|
|
366
|
+
}
|
|
367
|
+
/**
|
|
368
|
+
* Parse a handler's JSON. Claude Code's `hookSpecificOutput` form
|
|
369
|
+
* (`permissionDecision`, `updatedInput`, `additionalContext`) is accepted so a hook
|
|
370
|
+
* written for Claude Code runs unchanged. Unknown decisions and non-list findings
|
|
371
|
+
* are errors, not defaults: a handler that answers nonsense must not silently allow.
|
|
372
|
+
*/
|
|
373
|
+
declare function resultFromJson(raw: unknown, handler?: string): HookResult;
|
|
374
|
+
/** Fold a `rewrite` into the event so the next matcher's handlers see it. */
|
|
375
|
+
declare function applyResult(event: HookEvent, result: HookResult): void;
|
|
376
|
+
|
|
377
|
+
/**
|
|
378
|
+
* Which events a rule fires on: a tool-name pattern, a vendor, argument presence.
|
|
379
|
+
*
|
|
380
|
+
* matcher = "spycloud_.* | torchlight_.* | websearch_v1" # `A | B` alternation of unanchored regexes
|
|
381
|
+
* vendor = "spycloud" # the vendor the tools were wrapped with
|
|
382
|
+
* arg = "email" # the call must carry this argument (dotted path ok)
|
|
383
|
+
*
|
|
384
|
+
* The matcher grammar is Claude Code's: `""` or `"*"` is every tool, `A | B` is
|
|
385
|
+
* alternation, and each alternative is an unanchored regular expression (`^`/`$`
|
|
386
|
+
* anchor it). On the HTTP events the pattern is matched against the request path,
|
|
387
|
+
* and `arg` against the query and the body.
|
|
388
|
+
*/
|
|
389
|
+
|
|
390
|
+
type Matcher = {
|
|
391
|
+
/** Unanchored regexes; empty means every tool. */
|
|
392
|
+
patterns: readonly string[];
|
|
393
|
+
vendor?: string;
|
|
394
|
+
args: readonly string[];
|
|
395
|
+
};
|
|
396
|
+
/** Split a matcher on the `|` that sit OUTSIDE parentheses and brackets (and are
|
|
397
|
+
* not escaped), so `^(a|b)_tool$` stays one regex and `a | b` is two. */
|
|
398
|
+
declare function splitTopLevel(text: string): string[];
|
|
399
|
+
declare function parseMatcher(matcher?: string | readonly string[] | null, opts?: {
|
|
400
|
+
vendor?: string | null;
|
|
401
|
+
arg?: string | readonly string[] | null;
|
|
402
|
+
}): Matcher;
|
|
403
|
+
declare function describeMatcher(m: Matcher): string;
|
|
404
|
+
declare function matches(m: Matcher, event: HookEvent): boolean;
|
|
405
|
+
|
|
406
|
+
/**
|
|
407
|
+
* `gateway-hooks.toml` (JSON accepted): the rules, read and validated once at run
|
|
408
|
+
* start. `gateway hooks check` is the reload. The same grammar as the Python SDK's
|
|
409
|
+
* `gatewaysdk.hooks.config`:
|
|
410
|
+
*
|
|
411
|
+
* [alias]
|
|
412
|
+
* slugs = ["acme"] # worlds that store sha256:<slug>:<value> forms
|
|
413
|
+
* public_layer_wins = true # a `role: public` seed is never rewritten, even inside a private email's domain
|
|
414
|
+
* public_mailbox_domains = ["gmail.com"] # kept real in an email persona; omit for the built-in free-mail list, [] for none
|
|
415
|
+
* mint_inbound = ["email", "phone", "ip"] # kinds minted ON SIGHT in results (a third party found on the web gets a persona); omit = seeds only
|
|
416
|
+
* legend = "{run_dir}/legend.json" # write the run key + every persona (found ones too) here at run_end, for the owner's `gateway hooks legend|reveal`; omit = never written
|
|
417
|
+
*
|
|
418
|
+
* [vendors]
|
|
419
|
+
* spycloud = "spycloud_.*" # tool-name patterns -> vendor, for `vendor = ...` matchers
|
|
420
|
+
*
|
|
421
|
+
* [[hooks.pre_tool_call]] # or [[hooks.PreToolUse]]
|
|
422
|
+
* matcher = "spycloud_.* | websearch_v1" # omitted, "" or "*" = every tool; `A | B` alternation of regexes
|
|
423
|
+
* vendor = "spycloud" # optional
|
|
424
|
+
* arg = "email" # optional; the call must carry it
|
|
425
|
+
* handlers = [
|
|
426
|
+
* { type = "alias" }, # out on pre_*, in on post_*, outgoing on run_end
|
|
427
|
+
* { type = "command", command = "python guard.py", timeout = 10 }, # shell form
|
|
428
|
+
* { type = "command", command = "python", args = ["guard.py"] }, # exec form (no shell)
|
|
429
|
+
* { type = "http", url = "http://localhost:8080/hooks", headers = { Authorization = "Bearer $GUARD_TOKEN" }, allowed_env = ["GUARD_TOKEN"] },
|
|
430
|
+
* { type = "callable", target = "./guards.js#check" }, # a module export, in process
|
|
431
|
+
* { type = "deny", reason = "not in this run" },
|
|
432
|
+
* { type = "record", sink = "runs/transcript.jsonl", async = true }, # post_tool_call / post_response only
|
|
433
|
+
* ]
|
|
434
|
+
*
|
|
435
|
+
* Every handler may set `name` (the `[hook <name>]` label on its context), `timeout`
|
|
436
|
+
* (seconds; command 60, http 30, callable none, and 120 on run_end) and `async`
|
|
437
|
+
* (`true` runs it without blocking the call; its answer is logged, never applied).
|
|
438
|
+
*/
|
|
439
|
+
|
|
440
|
+
declare const HANDLER_TYPES: readonly ["alias", "command", "callable", "http", "deny", "record", "redact"];
|
|
441
|
+
type HandlerType = (typeof HANDLER_TYPES)[number];
|
|
442
|
+
declare class HookConfigError extends Error {
|
|
443
|
+
constructor(message: string);
|
|
444
|
+
}
|
|
445
|
+
type HandlerSpec = {
|
|
446
|
+
type: HandlerType;
|
|
447
|
+
name: string;
|
|
448
|
+
options: Record<string, unknown>;
|
|
449
|
+
/** Seconds; undefined means no limit (callables). */
|
|
450
|
+
timeout?: number;
|
|
451
|
+
/** `async = true`: run without blocking; the answer is logged only. */
|
|
452
|
+
background: boolean;
|
|
453
|
+
};
|
|
454
|
+
type HookRule = {
|
|
455
|
+
event: HookEventName;
|
|
456
|
+
matcher: Matcher;
|
|
457
|
+
handlers: HandlerSpec[];
|
|
458
|
+
/** `hooks.pre_tool_call[0]` — where the rule sits in the file, for messages. */
|
|
459
|
+
position: string;
|
|
460
|
+
};
|
|
461
|
+
type HookConfig = {
|
|
462
|
+
rules: HookRule[];
|
|
463
|
+
aliasSlugs: string[];
|
|
464
|
+
/** `[alias] public_layer_wins` and `public_mailbox_domains`; see `AliasMap`. */
|
|
465
|
+
aliasPublicLayerWins: boolean;
|
|
466
|
+
aliasPublicMailboxDomains: string[] | null;
|
|
467
|
+
/** `[alias] mint_inbound`: kinds minted on sight; empty = seeds only (the default). */
|
|
468
|
+
aliasMintInbound: string[];
|
|
469
|
+
/** `[alias] legend`: where the run writes its legend at run_end (`{run_dir}`,
|
|
470
|
+
* `{run_id}` interpolated); null (the default) writes nothing. */
|
|
471
|
+
aliasLegend: string | null;
|
|
472
|
+
/** vendor -> tool-name patterns, from `[vendors]`. */
|
|
473
|
+
vendors: Record<string, string[]>;
|
|
474
|
+
live: LiveConfig;
|
|
475
|
+
source?: string;
|
|
476
|
+
};
|
|
477
|
+
declare const TOOL_KINDS: readonly ["http", "callable", "connector"];
|
|
478
|
+
type ToolKind = (typeof TOOL_KINDS)[number];
|
|
479
|
+
declare const PARSE_MODES: readonly ["json", "regex", "text"];
|
|
480
|
+
type ParseMode = (typeof PARSE_MODES)[number];
|
|
481
|
+
declare const INPUT_TYPES: readonly ["string", "integer", "number", "boolean", "object", "array"];
|
|
482
|
+
/** A pattern is written with `(?<name>...)` groups so one file serves both runtimes;
|
|
483
|
+
* Python's `(?P<name>...)` spelling is accepted and normalised here. */
|
|
484
|
+
declare const jsPattern: (pattern: string) => string;
|
|
485
|
+
type JsonSchema = {
|
|
486
|
+
type: "object";
|
|
487
|
+
properties: Record<string, Record<string, unknown>>;
|
|
488
|
+
required: string[];
|
|
489
|
+
};
|
|
490
|
+
/** One `[tools.<name>]` entry: what the model sees (`description`, `input` as a JSON
|
|
491
|
+
* schema) and how the call is made (`kind` + `options`). */
|
|
492
|
+
type ToolSpec = {
|
|
493
|
+
name: string;
|
|
494
|
+
kind: ToolKind;
|
|
495
|
+
description: string;
|
|
496
|
+
input: JsonSchema;
|
|
497
|
+
options: Record<string, unknown>;
|
|
498
|
+
defaults: Record<string, unknown>;
|
|
499
|
+
/** The vendor the tool's events carry (`vendor = "..."` in the entry), for `vendor =` matchers. */
|
|
500
|
+
vendor?: string;
|
|
501
|
+
};
|
|
502
|
+
/** The `[live]` block, applying to every declared tool. */
|
|
503
|
+
type LiveConfig = {
|
|
504
|
+
record?: string;
|
|
505
|
+
replay?: string;
|
|
506
|
+
allowedEnv: string[];
|
|
507
|
+
timeout: number;
|
|
508
|
+
tools: Record<string, ToolSpec>;
|
|
509
|
+
};
|
|
510
|
+
declare const emptyLive: () => LiveConfig;
|
|
511
|
+
declare function describeTool(spec: ToolSpec): string;
|
|
512
|
+
/** `{ query = "string", max_results = "integer?: how many" }` -> a JSON schema:
|
|
513
|
+
* `type[?][: description]`; a table value is used as the property schema as it is
|
|
514
|
+
* (`optional = true` inside it makes the field optional). */
|
|
515
|
+
declare function inputSchema(shorthand: unknown, position: string): JsonSchema;
|
|
516
|
+
declare const emptyConfig: () => HookConfig;
|
|
517
|
+
declare function describeHandler(spec: HandlerSpec): string;
|
|
518
|
+
declare function vendorOf(config: HookConfig, toolName: string): string | undefined;
|
|
519
|
+
/** Read a TOML or JSON file. The suffix decides; `.json` is JSON, anything else is
|
|
520
|
+
* tried as TOML and then as JSON so a JSON file with an odd name still loads. */
|
|
521
|
+
declare function loadHookConfig(file: string): HookConfig;
|
|
522
|
+
/** Validate a parsed object (TOML or JSON) into a `HookConfig`. */
|
|
523
|
+
declare function parseHookConfig(data: unknown, source?: string): HookConfig;
|
|
524
|
+
|
|
525
|
+
/**
|
|
526
|
+
* The handlers: a command (JSON on stdin, JSON or text on stdout), an HTTP endpoint
|
|
527
|
+
* (the same JSON, POSTed), a function, and the built-ins `alias`, `record` and
|
|
528
|
+
* `deny`. The same contract as the Python SDK's `gatewaysdk.hooks.handlers`:
|
|
529
|
+
*
|
|
530
|
+
* stdin the event JSON (see events.ts)
|
|
531
|
+
* stdout {decision, reason?, updated_*?, additional_context?, findings?} — or plain text, which is context
|
|
532
|
+
* exit 0 continue (an empty stdout is "allow")
|
|
533
|
+
* exit 2 deny, stderr is the reason
|
|
534
|
+
* other a hook error: recorded on the run, never silent; it denies a pre_* call,
|
|
535
|
+
* fails run_end, and leaves a post_* result as it was
|
|
536
|
+
*/
|
|
537
|
+
|
|
538
|
+
type HandlerFn = (event: HookEvent) => HookResult | Record<string, unknown> | null | undefined | void | Promise<HookResult | Record<string, unknown> | null | undefined | void>;
|
|
539
|
+
type Handler = {
|
|
540
|
+
describe(): string;
|
|
541
|
+
run(event: HookEvent): Promise<HookResult>;
|
|
542
|
+
};
|
|
543
|
+
/** A JSON object on stdout is a structured answer; anything else is context. */
|
|
544
|
+
declare function parseStdout(text: string, handler: string): HookResult;
|
|
545
|
+
/** Run a program with the event on stdin and read its decision on stdout. Shell
|
|
546
|
+
* form (`command` alone, through the shell) or exec form (`command` + `args`). */
|
|
547
|
+
declare class CommandHandler implements Handler {
|
|
548
|
+
readonly command: string;
|
|
549
|
+
readonly opts: {
|
|
550
|
+
args?: string[];
|
|
551
|
+
timeout?: number;
|
|
552
|
+
cwd?: string;
|
|
553
|
+
env?: Record<string, string>;
|
|
554
|
+
};
|
|
555
|
+
constructor(command: string, opts?: {
|
|
556
|
+
args?: string[];
|
|
557
|
+
timeout?: number;
|
|
558
|
+
cwd?: string;
|
|
559
|
+
env?: Record<string, string>;
|
|
560
|
+
});
|
|
561
|
+
describe(): string;
|
|
562
|
+
run(event: HookEvent): Promise<HookResult>;
|
|
563
|
+
}
|
|
564
|
+
/** `$VAR` / `${VAR}` in a header value from the environment, allow-listed: a variable
|
|
565
|
+
* not in `allowedEnv` is an error, not an empty string. */
|
|
566
|
+
declare function interpolateHeaders(headers: Record<string, string>, allowedEnv: readonly string[]): Record<string, string>;
|
|
567
|
+
/** POST the event JSON; the response body is the stdout schema (empty = allow). A
|
|
568
|
+
* non-2xx status is a hook error. */
|
|
569
|
+
declare class HttpHandler implements Handler {
|
|
570
|
+
readonly url: string;
|
|
571
|
+
readonly opts: {
|
|
572
|
+
headers?: Record<string, string>;
|
|
573
|
+
allowedEnv?: string[];
|
|
574
|
+
timeout?: number;
|
|
575
|
+
};
|
|
576
|
+
constructor(url: string, opts?: {
|
|
577
|
+
headers?: Record<string, string>;
|
|
578
|
+
allowedEnv?: string[];
|
|
579
|
+
timeout?: number;
|
|
580
|
+
});
|
|
581
|
+
describe(): string;
|
|
582
|
+
run(event: HookEvent): Promise<HookResult>;
|
|
583
|
+
}
|
|
584
|
+
declare class DenyHandler implements Handler {
|
|
585
|
+
readonly reason: string;
|
|
586
|
+
constructor(reason?: string);
|
|
587
|
+
describe(): string;
|
|
588
|
+
run(): Promise<HookResult>;
|
|
589
|
+
}
|
|
590
|
+
/** Where a record handler writes: an array (pushed), a JSONL file path (appended),
|
|
591
|
+
* or a function (awaited) — the same sinks as `captureToolCalls`. */
|
|
592
|
+
type RecordSink = Record<string, unknown>[] | string | ((record: Record<string, unknown>) => unknown);
|
|
593
|
+
/** The ledger-shaped JSONL record `captureToolCalls` writes — `{tool, args, result |
|
|
594
|
+
* error, at, session, source}` — for every `post_tool_call` (and every `post_response`,
|
|
595
|
+
* with the request as `args` and the response as `result`). Handlers of one matcher
|
|
596
|
+
* all see the same event, so a record beside an `alias` handler holds what the tool
|
|
597
|
+
* returned; a record under a later `[[hooks.post_tool_call]]` holds the rewritten result. */
|
|
598
|
+
declare class RecordHandler implements Handler {
|
|
599
|
+
readonly sink: RecordSink;
|
|
600
|
+
readonly opts: {
|
|
601
|
+
session?: string;
|
|
602
|
+
source?: string;
|
|
603
|
+
};
|
|
604
|
+
constructor(sink: RecordSink, opts?: {
|
|
605
|
+
session?: string;
|
|
606
|
+
source?: string;
|
|
607
|
+
});
|
|
608
|
+
describe(): string;
|
|
609
|
+
run(event: HookEvent): Promise<HookResult>;
|
|
610
|
+
}
|
|
611
|
+
/** `{run_id}` and `{run_dir}` in a sink or recording path. */
|
|
612
|
+
declare const interpolatePath: (file: string, runId: string, runDir: string) => string;
|
|
613
|
+
/** Removes, where the alias door replaces: every value of the listed inbound kinds
|
|
614
|
+
* and every match of the listed patterns in what a tool returned becomes `token`.
|
|
615
|
+
* On its own rule after the door's, it takes the door's output, so a persona is
|
|
616
|
+
* never redacted and a real value the door had no seed for never reaches the agent. */
|
|
617
|
+
declare class RedactHandler implements Handler {
|
|
618
|
+
readonly aliases: AliasMap;
|
|
619
|
+
readonly kinds: readonly string[];
|
|
620
|
+
/** Literal strings (a name, a company, a phrase) removed wherever they appear, any
|
|
621
|
+
* case — the arbitrary half of redaction; `patterns` is the shaped half. */
|
|
622
|
+
readonly values: readonly string[];
|
|
623
|
+
readonly patterns: readonly RegExp[];
|
|
624
|
+
readonly token: string;
|
|
625
|
+
constructor(aliases: AliasMap, opts?: {
|
|
626
|
+
kinds?: readonly string[];
|
|
627
|
+
values?: readonly string[];
|
|
628
|
+
patterns?: readonly string[];
|
|
629
|
+
token?: string;
|
|
630
|
+
});
|
|
631
|
+
describe(): string;
|
|
632
|
+
private walk;
|
|
633
|
+
run(event: HookEvent): Promise<HookResult>;
|
|
634
|
+
}
|
|
635
|
+
/** The two-way door as a handler. The direction follows the event unless set:
|
|
636
|
+
* `out` on `pre_tool_call` / `pre_request` (aliases become real values; an unresolved
|
|
637
|
+
* alias or a `sha256:` digest used as a selector denies the call), `in` on
|
|
638
|
+
* `post_tool_call` / `post_response` (real values and every variant become aliases;
|
|
639
|
+
* leak-through is metered), and on `run_end` the report and the artifacts are
|
|
640
|
+
* scanned for real values, any hit failing the run. */
|
|
641
|
+
declare class AliasHandler implements Handler {
|
|
642
|
+
readonly aliases: AliasMap;
|
|
643
|
+
readonly opts: {
|
|
644
|
+
direction?: "in" | "out";
|
|
645
|
+
check?: "outgoing";
|
|
646
|
+
/** On `post_tool_call`: `alias` (default) also rewrites `tool_input` into alias
|
|
647
|
+
* space, unmetered, so a later `record` handler stores alias-space arguments;
|
|
648
|
+
* `keep` leaves the real selector in the event. */
|
|
649
|
+
args?: "alias" | "keep";
|
|
650
|
+
};
|
|
651
|
+
constructor(aliases: AliasMap, opts?: {
|
|
652
|
+
direction?: "in" | "out";
|
|
653
|
+
check?: "outgoing";
|
|
654
|
+
/** On `post_tool_call`: `alias` (default) also rewrites `tool_input` into alias
|
|
655
|
+
* space, unmetered, so a later `record` handler stores alias-space arguments;
|
|
656
|
+
* `keep` leaves the real selector in the event. */
|
|
657
|
+
args?: "alias" | "keep";
|
|
658
|
+
});
|
|
659
|
+
describe(): string;
|
|
660
|
+
run(event: HookEvent): Promise<HookResult>;
|
|
661
|
+
private out;
|
|
662
|
+
private in;
|
|
663
|
+
private outgoing;
|
|
664
|
+
}
|
|
665
|
+
declare class FunctionHandler implements Handler {
|
|
666
|
+
readonly fn: HandlerFn;
|
|
667
|
+
readonly name: string;
|
|
668
|
+
constructor(fn: HandlerFn, name: string);
|
|
669
|
+
describe(): string;
|
|
670
|
+
run(event: HookEvent): Promise<HookResult>;
|
|
671
|
+
}
|
|
672
|
+
/** `./module.js#exportName` -> the export, imported now so a typo fails at run
|
|
673
|
+
* start, not on the first matching call. A relative path resolves from `cwd`. */
|
|
674
|
+
declare function importCallable(target: string, cwd: string): Promise<HandlerFn>;
|
|
675
|
+
|
|
676
|
+
/**
|
|
677
|
+
* Live tools declared in the hook config: the generic drop-in. The twin of the
|
|
678
|
+
* Python SDK's `gatewaysdk.hooks.live`.
|
|
679
|
+
*
|
|
680
|
+
* A `[tools.<name>]` entry is one of three kinds and every kind produces the same
|
|
681
|
+
* callable shape, `fn(input) -> Promise<result>`:
|
|
682
|
+
*
|
|
683
|
+
* http method/url/headers/body templates over the input fields, then
|
|
684
|
+
* parse = json (a JSON path to the hit list + a field map) | regex (one
|
|
685
|
+
* object per match of a named-group pattern, HTML stripped) | text (the
|
|
686
|
+
* readable text of the page, scripts and styles gone, capped)
|
|
687
|
+
* callable `./module.mjs#export`, in process
|
|
688
|
+
* connector an operation of a `connector.toml` (the worlds grammar), sent with
|
|
689
|
+
* that connection's auth
|
|
690
|
+
*
|
|
691
|
+
* `[live]` applies to all of them: `record` writes one line per call (the input as
|
|
692
|
+
* SENT, the result as ANSWERED and as SHOWN once the door has done its inbound pass,
|
|
693
|
+
* and the elapsed time); `replay` answers every tool from such a recording instead of
|
|
694
|
+
* the network and refuses an unrecorded call by name; `allowed_env` is the only set of
|
|
695
|
+
* environment names a tool may read.
|
|
696
|
+
*
|
|
697
|
+
* Nothing here knows what a "search" is. A web search is one declared tool; the
|
|
698
|
+
* keyless DuckDuckGo one ships as `examples/hooks/duckduckgo.toml`.
|
|
699
|
+
*/
|
|
700
|
+
|
|
701
|
+
/** A declared tool could not answer: the request failed, the status was not an
|
|
702
|
+
* `ok_status`, the body matched `fail_if` or did not parse, or a replay had no
|
|
703
|
+
* recording for the call. `status` and `body` (the first bytes) are kept so the
|
|
704
|
+
* recording says what came back — a challenge page is never an empty answer. */
|
|
705
|
+
declare class LiveToolError extends Error {
|
|
706
|
+
readonly status?: number;
|
|
707
|
+
readonly body?: string;
|
|
708
|
+
constructor(message: string, opts?: {
|
|
709
|
+
status?: number;
|
|
710
|
+
body?: string;
|
|
711
|
+
});
|
|
712
|
+
}
|
|
713
|
+
/** One provider, one pace: `min_interval_ms` between two calls of a tool, shared by
|
|
714
|
+
* every materialization of the same tool in a run. */
|
|
715
|
+
declare class Pacer {
|
|
716
|
+
private readonly last;
|
|
717
|
+
/** Waits until the interval since the tool's last call has passed; resolves to the
|
|
718
|
+
* seconds waited. `sleep`/`clock` are injectable for tests. */
|
|
719
|
+
wait(name: string, intervalMs: number, opts?: {
|
|
720
|
+
sleep?: (seconds: number) => void | Promise<void>;
|
|
721
|
+
clock?: () => number;
|
|
722
|
+
}): Promise<number>;
|
|
723
|
+
}
|
|
724
|
+
type ToolFn = (input?: Record<string, unknown>) => Promise<unknown>;
|
|
725
|
+
/** `{field}` holes filled from `values`. A string that is exactly one hole becomes the
|
|
726
|
+
* field's typed value (an absent optional field becomes `undefined`); any other string
|
|
727
|
+
* gets `String(value)` substituted, URL-encoded when `encode`. Tables and lists are
|
|
728
|
+
* rendered inside, and a key whose value rendered to `undefined` is dropped. */
|
|
729
|
+
declare function render(template: unknown, values: Record<string, unknown>, encode?: boolean): unknown;
|
|
730
|
+
/** `$.a.b[*].c` / `$.items[0]` / `$` over a parsed body; `[*]` fans out. */
|
|
731
|
+
declare function jsonPath(node: unknown, pathText: string): unknown;
|
|
732
|
+
/** The common HTML entities, named and numeric (Python's `html.unescape` knows every
|
|
733
|
+
* HTML5 entity; the ones a search page carries are here). */
|
|
734
|
+
declare function unescapeHtml(text: string): string;
|
|
735
|
+
declare const stripTags: (text: string) => string;
|
|
736
|
+
/** The text of a page: scripts and styles gone, tags gone, entities decoded, whitespace folded. */
|
|
737
|
+
declare function readable(body: string): string;
|
|
738
|
+
declare function pageTitle(body: string): string;
|
|
739
|
+
/** The field map applied to every hit; without a map the hits are returned as they are. */
|
|
740
|
+
declare function mapFields(items: unknown[], fields: Record<string, unknown>, stripHtml: boolean): Record<string, unknown>[];
|
|
741
|
+
declare function parseJson(body: string, options: Record<string, unknown>): unknown;
|
|
742
|
+
declare function parseRegex(body: string, options: Record<string, unknown>): Record<string, unknown>[];
|
|
743
|
+
declare function parseText(body: string, status: number, url: string, options: Record<string, unknown>): Record<string, unknown>;
|
|
744
|
+
declare function applyLimit(rows: unknown, limit: unknown, values: Record<string, unknown>): unknown;
|
|
745
|
+
declare function withDefaults(spec: ToolSpec, given: Record<string, unknown>): Record<string, unknown>;
|
|
746
|
+
type LiveTool = {
|
|
747
|
+
spec: ToolSpec;
|
|
748
|
+
call(input: Record<string, unknown>): Promise<unknown>;
|
|
749
|
+
inputSchema(): ToolSpec["input"];
|
|
750
|
+
};
|
|
751
|
+
declare class HttpTool implements LiveTool {
|
|
752
|
+
readonly spec: ToolSpec;
|
|
753
|
+
readonly live: LiveConfig;
|
|
754
|
+
/** Shared across tools: the pace is per tool name, not per HttpTool instance. */
|
|
755
|
+
static pacer: Pacer;
|
|
756
|
+
/** The status of the most recent answer, for the recording line. */
|
|
757
|
+
lastStatus?: number;
|
|
758
|
+
constructor(spec: ToolSpec, live: LiveConfig);
|
|
759
|
+
inputSchema(): ToolSpec["input"];
|
|
760
|
+
request(values: Record<string, unknown>): {
|
|
761
|
+
url: string;
|
|
762
|
+
init: RequestInit;
|
|
763
|
+
};
|
|
764
|
+
call(given: Record<string, unknown>): Promise<unknown>;
|
|
765
|
+
/** `fail_if`: a body that matches is a refusal from the provider (a bot challenge,
|
|
766
|
+
* a block page), never an empty answer. */
|
|
767
|
+
private checkFailIf;
|
|
768
|
+
}
|
|
769
|
+
declare class CallableTool implements LiveTool {
|
|
770
|
+
readonly spec: ToolSpec;
|
|
771
|
+
readonly fn: (input: Record<string, unknown>) => unknown;
|
|
772
|
+
constructor(spec: ToolSpec, fn: (input: Record<string, unknown>) => unknown);
|
|
773
|
+
static create(spec: ToolSpec, cwd: string): Promise<CallableTool>;
|
|
774
|
+
inputSchema(): ToolSpec["input"];
|
|
775
|
+
call(given: Record<string, unknown>): Promise<unknown>;
|
|
776
|
+
}
|
|
777
|
+
type Connection = {
|
|
778
|
+
slug: string;
|
|
779
|
+
baseUrl: string;
|
|
780
|
+
scheme: string;
|
|
781
|
+
authName?: string;
|
|
782
|
+
secretEnv?: string;
|
|
783
|
+
clientIdEnv?: string;
|
|
784
|
+
tokenUrl?: string;
|
|
785
|
+
scope?: string;
|
|
786
|
+
extraHeaders: Record<string, string>;
|
|
787
|
+
operations: Record<string, {
|
|
788
|
+
name: string;
|
|
789
|
+
method: string;
|
|
790
|
+
path: string;
|
|
791
|
+
params: string[];
|
|
792
|
+
results?: string;
|
|
793
|
+
}>;
|
|
794
|
+
};
|
|
795
|
+
/** `connector.toml` as the worlds runtime reads it: `[connector] base_url`, `[auth]`
|
|
796
|
+
* (`scheme` none | bearer | header | basic | query | oauth2, `name`, `secret_env`,
|
|
797
|
+
* `client_id_env`, `token_url`, `scope`, `headers`), and the `[[operations]]`. */
|
|
798
|
+
declare function readConnection(root: string): Connection;
|
|
799
|
+
/** One operation of a `connector.toml`, sent with the connection's auth. Path
|
|
800
|
+
* placeholders and declared params become the tool's input when the entry declares none. */
|
|
801
|
+
declare class ConnectorTool implements LiveTool {
|
|
802
|
+
readonly spec: ToolSpec;
|
|
803
|
+
readonly live: LiveConfig;
|
|
804
|
+
readonly connection: Connection;
|
|
805
|
+
readonly operation: Connection["operations"][string];
|
|
806
|
+
constructor(spec: ToolSpec, live: LiveConfig, baseDir: string);
|
|
807
|
+
get placeholders(): string[];
|
|
808
|
+
inputSchema(): ToolSpec["input"];
|
|
809
|
+
private env;
|
|
810
|
+
private credential;
|
|
811
|
+
call(given: Record<string, unknown>): Promise<unknown>;
|
|
812
|
+
}
|
|
813
|
+
declare function buildTool(spec: ToolSpec, live: LiveConfig, baseDir: string): Promise<LiveTool>;
|
|
814
|
+
/** The tool for a model, in the shape `schemaFromSignature` uses. */
|
|
815
|
+
declare function definition(tool: LiveTool): Record<string, unknown>;
|
|
816
|
+
declare class Recorder {
|
|
817
|
+
readonly file: string;
|
|
818
|
+
constructor(file: string);
|
|
819
|
+
write(line: Record<string, unknown>): void;
|
|
820
|
+
}
|
|
821
|
+
/** Answers from a recording, by tool and input as SENT. */
|
|
822
|
+
declare class Replay {
|
|
823
|
+
readonly file: string;
|
|
824
|
+
readonly answers: Map<string, unknown>;
|
|
825
|
+
constructor(file: string);
|
|
826
|
+
tool(spec: ToolSpec): LiveTool;
|
|
827
|
+
}
|
|
828
|
+
type RunLike = {
|
|
829
|
+
liveLog: Record<string, unknown>[];
|
|
830
|
+
wrapTools<T extends Record<string, (args: Record<string, unknown>) => unknown | Promise<unknown>>>(tools: T, opts?: {
|
|
831
|
+
vendor?: string;
|
|
832
|
+
}): Record<string, (args?: Record<string, unknown>) => Promise<unknown>>;
|
|
833
|
+
};
|
|
834
|
+
/** The reason when an exception is a refusal, not a failure: a `HookDenied`, any
|
|
835
|
+
* error carrying a string `reason` (the harness's `ToolRefusal`), or one whose class
|
|
836
|
+
* is named `*Denied` / `*Refusal` / `*Refused`. Null otherwise. */
|
|
837
|
+
declare function refusalReason(error: unknown): string | null;
|
|
838
|
+
/** Materializes the `[tools]` table for one run: every tool built (or replayed),
|
|
839
|
+
* wrapped by the run's rules, and recorded. */
|
|
840
|
+
declare class LiveTools {
|
|
841
|
+
readonly run: RunLike;
|
|
842
|
+
readonly live: LiveConfig;
|
|
843
|
+
readonly replay?: Replay;
|
|
844
|
+
readonly recorder?: Recorder;
|
|
845
|
+
readonly built: Record<string, LiveTool>;
|
|
846
|
+
readonly raw: Record<string, LiveTool>;
|
|
847
|
+
private inside?;
|
|
848
|
+
private constructor();
|
|
849
|
+
static create(run: RunLike, live: LiveConfig, baseDir: string): Promise<LiveTools>;
|
|
850
|
+
/** The tools of a hooks file for an existing run: the file read, `{run_id}` /
|
|
851
|
+
* `{run_dir}` in its `[live]` paths filled from the run (`runDir` overrides the
|
|
852
|
+
* run's), the `connector` paths resolved from the file's directory. */
|
|
853
|
+
static fromConfig(file: string, run: RunLike & {
|
|
854
|
+
runId: string;
|
|
855
|
+
runDir: string;
|
|
856
|
+
}, opts?: {
|
|
857
|
+
runDir?: string;
|
|
858
|
+
}): Promise<LiveTools>;
|
|
859
|
+
/** The declared tools for a model. `openai`: `{type: "function", function: {name,
|
|
860
|
+
* description, parameters}}`; `anthropic`: `{name, description, input_schema}`. */
|
|
861
|
+
definitions(shape?: "openai" | "anthropic"): Record<string, unknown>[];
|
|
862
|
+
/** Every tool wrapped by the run's rules and recorded. A tool's own `vendor`
|
|
863
|
+
* (`vendor = "..."` in its entry) wins over the one given here. */
|
|
864
|
+
materialize(vendor?: string): Record<string, ToolFn>;
|
|
865
|
+
/** Inside the door: sees the input as SENT (defaults filled) and the result as
|
|
866
|
+
* ANSWERED — and, for an HTTP tool, the `status` it answered with (plus `body` on
|
|
867
|
+
* a `LiveToolError` that carries one). */
|
|
868
|
+
private capturing;
|
|
869
|
+
/** Outside the door: sees the input as ASKED and the result as SHOWN. */
|
|
870
|
+
private recording;
|
|
871
|
+
private write;
|
|
872
|
+
}
|
|
873
|
+
|
|
874
|
+
/**
|
|
875
|
+
* One run of an agent under hooks: the rules (read once), the run key, the alias
|
|
876
|
+
* map, and the attachments — `wrapTools(tools)` for a name -> async function map
|
|
877
|
+
* and `session(session)` for a world-session client — plus `end(report)` and the
|
|
878
|
+
* `legend()` / `summary()` a grader reads. The twin of the Python SDK's `HookRun`.
|
|
879
|
+
*
|
|
880
|
+
* const run = await HookRun.fromConfig("gateway-hooks.toml");
|
|
881
|
+
* run.seed([{ type: "person_name", value: "Matthew Nowell", identity: "subject" }]);
|
|
882
|
+
* const tools = run.wrapTools({ search, spycloud_lookup }, { vendor: "spycloud" });
|
|
883
|
+
* ... the agent calls tools ...
|
|
884
|
+
* const verdict = await run.end(report, { "graph.json": graphText });
|
|
885
|
+
* run.legend(); // run key + the map; never stored with world data
|
|
886
|
+
*
|
|
887
|
+
* How one event is applied, rule by rule in declaration order:
|
|
888
|
+
*
|
|
889
|
+
* every handler of the rule sees the SAME event (no implicit chaining);
|
|
890
|
+
* async handlers are started and their answers only logged;
|
|
891
|
+
* the others run in declared order and their answers MERGE:
|
|
892
|
+
* deny > rewrite > allow — any deny denies, with its reason;
|
|
893
|
+
* at most one handler may rewrite (a second is a HookError, never a race);
|
|
894
|
+
* additional_context lines are labelled `[hook <name>]` and reach the agent;
|
|
895
|
+
* findings accumulate on the run;
|
|
896
|
+
* a handler that fails is recorded; on pre_* it denies the call, on run_end it
|
|
897
|
+
* fails the run, on post_* the result stands.
|
|
898
|
+
* The merged rewrite is applied, and the next rule sees the rewritten event.
|
|
899
|
+
*/
|
|
900
|
+
|
|
901
|
+
/** Where `additional_context` lands in an object tool result. */
|
|
902
|
+
declare const CONTEXT_KEY = "hook_context";
|
|
903
|
+
type RunVerdict = {
|
|
904
|
+
passed: boolean;
|
|
905
|
+
reason?: string;
|
|
906
|
+
findings: Finding[];
|
|
907
|
+
context: string[];
|
|
908
|
+
};
|
|
909
|
+
/** One rule with its handlers built: what `dispatch` walks and `gateway hooks check` dry-runs. */
|
|
910
|
+
type Bound = {
|
|
911
|
+
rule: HookRule;
|
|
912
|
+
handlers: {
|
|
913
|
+
name: string;
|
|
914
|
+
handler: Handler;
|
|
915
|
+
background: boolean;
|
|
916
|
+
}[];
|
|
917
|
+
};
|
|
918
|
+
type ToolFunctions = Record<string, (args: Record<string, unknown>) => unknown | Promise<unknown>>;
|
|
919
|
+
/** The wrapped map: every tool takes one argument object (optional) and answers a promise. */
|
|
920
|
+
type WrappedTools<T extends ToolFunctions> = {
|
|
921
|
+
[K in keyof T]: (args?: Record<string, unknown>) => Promise<Awaited<ReturnType<T[K]>>>;
|
|
922
|
+
};
|
|
923
|
+
type HookRunOptions = {
|
|
924
|
+
runKey?: string;
|
|
925
|
+
runId?: string;
|
|
926
|
+
slugs?: readonly string[];
|
|
927
|
+
/** Overrides the file's `[alias] mint_inbound` for this run: what a task wants
|
|
928
|
+
* aliased is the task's decision, not the file's. */
|
|
929
|
+
mintInbound?: readonly string[];
|
|
930
|
+
/** Where the legend is written at run_end; overrides the file's `[alias] legend`
|
|
931
|
+
* (`null` writes nothing). The owner's way back to the real data. */
|
|
932
|
+
legend?: string | null;
|
|
933
|
+
session?: string;
|
|
934
|
+
source?: string;
|
|
935
|
+
cwd?: string;
|
|
936
|
+
/** What `{run_dir}` means in a `record` sink or a `[live]` path; default `<cwd>/runs/<run id>`. */
|
|
937
|
+
runDir?: string;
|
|
938
|
+
};
|
|
939
|
+
declare class HookRun {
|
|
940
|
+
readonly config: HookConfig;
|
|
941
|
+
readonly runId: string;
|
|
942
|
+
readonly runKey: string;
|
|
943
|
+
readonly alias: AliasMap;
|
|
944
|
+
readonly cwd: string;
|
|
945
|
+
/** What `{run_dir}` means in a `record` sink or a `[live]` path. */
|
|
946
|
+
readonly runDir: string;
|
|
947
|
+
/** Where `writeLegend()` writes at run_end — `[alias] legend` or the option; null
|
|
948
|
+
* writes nothing. Keep it with the run key, never with world data. */
|
|
949
|
+
readonly legendPath: string | null;
|
|
950
|
+
readonly denials: Record<string, unknown>[];
|
|
951
|
+
readonly errors: Record<string, unknown>[];
|
|
952
|
+
readonly findings: Finding[];
|
|
953
|
+
readonly context: Record<string, unknown>[];
|
|
954
|
+
/** Answers of `async` handlers, as they complete: `{event, tool, handler, result | error}`. */
|
|
955
|
+
readonly background: Record<string, unknown>[];
|
|
956
|
+
calls: number;
|
|
957
|
+
/** Every declared-tool call this run made: the recording lines, in memory. */
|
|
958
|
+
readonly liveLog: Record<string, unknown>[];
|
|
959
|
+
/** Where a relative `connector` path in `[tools.*]` resolves from: the config file's directory. */
|
|
960
|
+
readonly configDir: string;
|
|
961
|
+
private live?;
|
|
962
|
+
private readonly bound;
|
|
963
|
+
private pending;
|
|
964
|
+
private readonly sessionId?;
|
|
965
|
+
private readonly source?;
|
|
966
|
+
private constructor();
|
|
967
|
+
/** Build from a parsed config (an object in the file's shape, or a `HookConfig`);
|
|
968
|
+
* handlers are constructed now, so a callable that does not import fails here. */
|
|
969
|
+
static create(config?: HookConfig | Record<string, unknown> | null, options?: HookRunOptions): Promise<HookRun>;
|
|
970
|
+
private liveTools;
|
|
971
|
+
/** Read the file once; the run keeps that snapshot. Edit the file, start a new run. */
|
|
972
|
+
static fromConfig(file: string, options?: HookRunOptions): Promise<HookRun>;
|
|
973
|
+
/** Add handlers from code as one rule: `run.on("pre_tool_call", guard, { matcher: "spycloud_.*" })`.
|
|
974
|
+
* A handler is a function taking a `HookEvent` and returning a `HookResult`, an
|
|
975
|
+
* object of the same shape, or nothing (allow) — or a built-in instance
|
|
976
|
+
* (`AliasHandler`, `RecordHandler`, `DenyHandler`, `CommandHandler`, ...), used as
|
|
977
|
+
* it is. Several handlers in one call are the handlers of one matcher: they see the
|
|
978
|
+
* same event and their answers merge. `before: true` puts the rule ahead of the
|
|
979
|
+
* file's rules (and of earlier code rules) instead of after them. */
|
|
980
|
+
on(event: string, handlers: HandlerFn | Handler | (HandlerFn | Handler)[], opts?: {
|
|
981
|
+
matcher?: string | string[];
|
|
982
|
+
vendor?: string;
|
|
983
|
+
arg?: string | string[];
|
|
984
|
+
name?: string;
|
|
985
|
+
background?: boolean;
|
|
986
|
+
before?: boolean;
|
|
987
|
+
}): this;
|
|
988
|
+
/** Mint aliases for the task's known entities (see `AliasMap.seed`). */
|
|
989
|
+
seed(entities: readonly SeedEntity[]): SeedRow[];
|
|
990
|
+
/** The rules bound for one event, in the order `dispatch` applies them. */
|
|
991
|
+
bindings(event: HookEventName): readonly Bound[];
|
|
992
|
+
/** Apply every matching rule, in order, merging each rule's answers. Throws
|
|
993
|
+
* `HookDenied` on a deny and `HookError` when a rule cannot be applied; both are
|
|
994
|
+
* recorded on the run before they propagate. */
|
|
995
|
+
dispatch(event: HookEvent): Promise<HookEvent>;
|
|
996
|
+
private merge;
|
|
997
|
+
private startBackground;
|
|
998
|
+
/** Wait for every `async` handler started so far. */
|
|
999
|
+
drain(): Promise<void>;
|
|
1000
|
+
private recordError;
|
|
1001
|
+
private recordDenial;
|
|
1002
|
+
private event;
|
|
1003
|
+
/** `pre_tool_call` for one call: the (possibly rewritten) arguments and the context lines. */
|
|
1004
|
+
beforeCall(toolName: string, args: unknown, opts?: {
|
|
1005
|
+
vendor?: string;
|
|
1006
|
+
}): Promise<[unknown, string[]]>;
|
|
1007
|
+
/** `post_tool_call` for one call: the (possibly rewritten) result, carrying every
|
|
1008
|
+
* context line (from `pre_tool_call` too) for the agent. */
|
|
1009
|
+
afterCall(toolName: string, args: unknown, result: unknown, opts?: {
|
|
1010
|
+
vendor?: string;
|
|
1011
|
+
context?: string[];
|
|
1012
|
+
}): Promise<unknown>;
|
|
1013
|
+
/** `post_tool_call` for a call that threw or was denied; returns the error text the
|
|
1014
|
+
* agent should see (an alias handler rewrites it, a record handler records it). */
|
|
1015
|
+
afterError(toolName: string, args: unknown, error: string, opts?: {
|
|
1016
|
+
vendor?: string;
|
|
1017
|
+
}): Promise<string>;
|
|
1018
|
+
/** The error the agent should see after `post_tool_call` saw its text: the same
|
|
1019
|
+
* class with the rewritten message, or the original when nothing changed. */
|
|
1020
|
+
rewrittenError(toolName: string, args: unknown, error: unknown, vendor?: string): Promise<unknown>;
|
|
1021
|
+
/**
|
|
1022
|
+
* Wrap a name -> async function map — the shape the Vercel AI SDK's tools, a
|
|
1023
|
+
* `WorldToolkit`'s `impls` and `captureToolCalls` share — so `pre_tool_call` runs
|
|
1024
|
+
* before each call with its argument object as `tool_input` and `post_tool_call`
|
|
1025
|
+
* after it with the result.
|
|
1026
|
+
*
|
|
1027
|
+
* A deny throws `HookDenied` to the caller (after `post_tool_call` saw the denial as
|
|
1028
|
+
* `error`, so a record handler logs it); a rule that cannot be applied throws
|
|
1029
|
+
* `HookError`; a tool's own exception goes through `post_tool_call` as `error` text
|
|
1030
|
+
* and is re-thrown (same class with the rewritten message). `additional_context`
|
|
1031
|
+
* from the handlers is delivered with the result (see `withContext`).
|
|
1032
|
+
*/
|
|
1033
|
+
wrapTools<T extends ToolFunctions>(tools: T, opts?: {
|
|
1034
|
+
vendor?: string;
|
|
1035
|
+
}): WrappedTools<T>;
|
|
1036
|
+
/** Every `[tools.<name>]` entry as a name -> async function map, already wrapped by
|
|
1037
|
+
* this run's rules and, with `[live].record` set, recorded (`input_asked`,
|
|
1038
|
+
* `input_sent`, `result_raw`, `result_shown`, `elapsed` per call; also in `liveLog`).
|
|
1039
|
+
* With `[live].replay` set every tool answers from that recording and an unrecorded
|
|
1040
|
+
* call is refused by name. Built once per run. */
|
|
1041
|
+
tools(opts?: {
|
|
1042
|
+
vendor?: string;
|
|
1043
|
+
}): Promise<Record<string, (args?: Record<string, unknown>) => Promise<unknown>>>;
|
|
1044
|
+
/** The declared tools for a model: `{type: "function", function: {name, description, parameters}}`. */
|
|
1045
|
+
toolDefinitions(shape?: "openai" | "anthropic"): Promise<Record<string, unknown>[]>;
|
|
1046
|
+
/** A world-session client (`WorldSession`, or anything with `call(tool, args)`)
|
|
1047
|
+
* with the hooks on its boundary: `call` and `toolkit()` fire the tool-call events,
|
|
1048
|
+
* `request` fires `pre_request` / `post_response` around one HTTP request to the
|
|
1049
|
+
* session's api surface. */
|
|
1050
|
+
session<S extends SessionLike>(session: S, opts?: {
|
|
1051
|
+
vendor?: string;
|
|
1052
|
+
requestFn?: RequestFn;
|
|
1053
|
+
}): HookedSession<S>;
|
|
1054
|
+
beforeRequest(request: HookRequest, opts?: {
|
|
1055
|
+
vendor?: string;
|
|
1056
|
+
}): Promise<HookRequest>;
|
|
1057
|
+
afterResponse(request: HookRequest, response: HookResponse, opts?: {
|
|
1058
|
+
vendor?: string;
|
|
1059
|
+
}): Promise<HookResponse>;
|
|
1060
|
+
/** `run_end`: every handler sees the report and the artifacts; a deny (the alias
|
|
1061
|
+
* outgoing scan found a real value) or a failed handler fails the run. Waits for the
|
|
1062
|
+
* `async` handlers first. Findings are returned either way. */
|
|
1063
|
+
end(report: string, artifacts?: Record<string, string>): Promise<RunVerdict>;
|
|
1064
|
+
/** Write `legend()` as JSON to `file` (default: the configured legend path) and
|
|
1065
|
+
* return where. Found personas are in it: the map is complete. */
|
|
1066
|
+
writeLegend(file?: string): string;
|
|
1067
|
+
private writeLegendIfConfigured;
|
|
1068
|
+
/** The run key and the alias map, for the grader. Never stored with world data. */
|
|
1069
|
+
legend(): {
|
|
1070
|
+
run_id: string;
|
|
1071
|
+
run_key: string;
|
|
1072
|
+
aliases: ReturnType<AliasMap["legend"]>;
|
|
1073
|
+
};
|
|
1074
|
+
summary(): Record<string, unknown>;
|
|
1075
|
+
}
|
|
1076
|
+
/** Deliver `[hook <name>] …` lines with a tool result: an object gets them under
|
|
1077
|
+
* `hook_context`, a string gets them appended, anything else is wrapped as
|
|
1078
|
+
* `{result, hook_context}`. With no context the result is untouched. */
|
|
1079
|
+
declare function withContext(result: unknown, context: readonly string[]): unknown;
|
|
1080
|
+
type SessionLike = {
|
|
1081
|
+
call(tool: string, args?: Record<string, unknown>, ...rest: unknown[]): Promise<unknown>;
|
|
1082
|
+
toolkit?(): Promise<{
|
|
1083
|
+
impls: ToolFunctions;
|
|
1084
|
+
} & Record<string, unknown>>;
|
|
1085
|
+
api?(): Promise<string>;
|
|
1086
|
+
apiHeaders?(): Promise<Record<string, string>>;
|
|
1087
|
+
};
|
|
1088
|
+
/** A pluggable transport for `HookedSession.request`: `fn({method, path, query, body})
|
|
1089
|
+
* -> {status, body, headers?}`. A client with its own auth (an `x-api-key`, a password
|
|
1090
|
+
* grant, a key in the query) supplies it and still gets `pre_request` / `post_response`. */
|
|
1091
|
+
type RequestFn = (request: HookRequest) => Promise<HookResponse> | HookResponse;
|
|
1092
|
+
/** A world session behind the hooks. Everything else is reached through `.inner`. */
|
|
1093
|
+
declare class HookedSession<S extends SessionLike> {
|
|
1094
|
+
readonly run: HookRun;
|
|
1095
|
+
readonly inner: S;
|
|
1096
|
+
readonly vendor?: string | undefined;
|
|
1097
|
+
readonly requestFn?: RequestFn | undefined;
|
|
1098
|
+
constructor(run: HookRun, inner: S, vendor?: string | undefined, requestFn?: RequestFn | undefined);
|
|
1099
|
+
call(tool: string, args?: Record<string, unknown>, ...rest: unknown[]): Promise<unknown>;
|
|
1100
|
+
toolkit(): Promise<{
|
|
1101
|
+
impls: ToolFunctions;
|
|
1102
|
+
} & Record<string, unknown>>;
|
|
1103
|
+
/** One HTTP request to the session's api surface (`api()` + `path`, with
|
|
1104
|
+
* `apiHeaders()`), `pre_request` before it and `post_response` after. Returns
|
|
1105
|
+
* `{status, body, headers}`; a 4xx/5xx is returned, not thrown, so the agent sees
|
|
1106
|
+
* the vendor's own error shape (rewritten like any result). */
|
|
1107
|
+
request(method: string, path: string, opts?: {
|
|
1108
|
+
query?: Record<string, unknown>;
|
|
1109
|
+
body?: unknown;
|
|
1110
|
+
headers?: Record<string, string>;
|
|
1111
|
+
timeoutMs?: number;
|
|
1112
|
+
}): Promise<HookResponse>;
|
|
1113
|
+
}
|
|
1114
|
+
|
|
1115
|
+
/**
|
|
1116
|
+
* Hooks: Claude-Code-style rules that intercept an agent's tool calls.
|
|
1117
|
+
*
|
|
1118
|
+
* import { HookRun } from "@withgateway/sdk/hooks";
|
|
1119
|
+
*
|
|
1120
|
+
* const run = await HookRun.fromConfig("gateway-hooks.toml"); // rules; JSON accepted too
|
|
1121
|
+
* run.seed([{ type: "person_name", value: "Matthew Nowell", identity: "subject" }]);
|
|
1122
|
+
* const tools = run.wrapTools(tools, { vendor: "spycloud" }); // pre_tool_call / post_tool_call around each call
|
|
1123
|
+
* const session = run.session(await openSession(...)); // pre_request / post_response on the HTTP boundary
|
|
1124
|
+
* const verdict = await run.end(report, artifacts); // run_end: a real value in the report fails the run
|
|
1125
|
+
* run.legend(); run.summary(); // the map (with the run key) and the meters
|
|
1126
|
+
*
|
|
1127
|
+
* Events: `pre_tool_call` (allow, deny, rewrite `tool_input`), `post_tool_call`
|
|
1128
|
+
* (rewrite `tool_result`, findings), `pre_request` / `post_response` (one HTTP
|
|
1129
|
+
* request a world-session client makes), `run_end` (fail the run with findings).
|
|
1130
|
+
*
|
|
1131
|
+
* Handlers: `command` (JSON stdin/stdout, exit 0 continue, exit 2 deny with stderr
|
|
1132
|
+
* reason, other exit = recorded error), `http`, functions via `run.on(event, fn)`,
|
|
1133
|
+
* and the built-ins `alias` (the persona two-way door), `record` (the
|
|
1134
|
+
* `captureToolCalls` JSONL ledger) and `deny`.
|
|
1135
|
+
*
|
|
1136
|
+
* The package already owns `personas` (simulated users) and `security` (the policy
|
|
1137
|
+
* client); this module is neither. Security authorizes first, then hooks run.
|
|
1138
|
+
*/
|
|
1139
|
+
|
|
1140
|
+
type index_Alias = Alias;
|
|
1141
|
+
type index_AliasHandler = AliasHandler;
|
|
1142
|
+
declare const index_AliasHandler: typeof AliasHandler;
|
|
1143
|
+
type index_AliasMap = AliasMap;
|
|
1144
|
+
declare const index_AliasMap: typeof AliasMap;
|
|
1145
|
+
type index_Bound = Bound;
|
|
1146
|
+
declare const index_CONTEXT_KEY: typeof CONTEXT_KEY;
|
|
1147
|
+
type index_CallableTool = CallableTool;
|
|
1148
|
+
declare const index_CallableTool: typeof CallableTool;
|
|
1149
|
+
type index_CommandHandler = CommandHandler;
|
|
1150
|
+
declare const index_CommandHandler: typeof CommandHandler;
|
|
1151
|
+
type index_ConnectorTool = ConnectorTool;
|
|
1152
|
+
declare const index_ConnectorTool: typeof ConnectorTool;
|
|
1153
|
+
type index_Decision = Decision;
|
|
1154
|
+
type index_DenyHandler = DenyHandler;
|
|
1155
|
+
declare const index_DenyHandler: typeof DenyHandler;
|
|
1156
|
+
declare const index_EVENTS: typeof EVENTS;
|
|
1157
|
+
declare const index_EVENT_ALIASES: typeof EVENT_ALIASES;
|
|
1158
|
+
type index_Finding = Finding;
|
|
1159
|
+
type index_FunctionHandler = FunctionHandler;
|
|
1160
|
+
declare const index_FunctionHandler: typeof FunctionHandler;
|
|
1161
|
+
declare const index_HANDLER_TYPES: typeof HANDLER_TYPES;
|
|
1162
|
+
type index_Handler = Handler;
|
|
1163
|
+
type index_HandlerFn = HandlerFn;
|
|
1164
|
+
type index_HandlerSpec = HandlerSpec;
|
|
1165
|
+
type index_HandlerType = HandlerType;
|
|
1166
|
+
type index_HookConfig = HookConfig;
|
|
1167
|
+
type index_HookConfigError = HookConfigError;
|
|
1168
|
+
declare const index_HookConfigError: typeof HookConfigError;
|
|
1169
|
+
type index_HookDenied = HookDenied;
|
|
1170
|
+
declare const index_HookDenied: typeof HookDenied;
|
|
1171
|
+
type index_HookError = HookError;
|
|
1172
|
+
declare const index_HookError: typeof HookError;
|
|
1173
|
+
type index_HookEvent = HookEvent;
|
|
1174
|
+
type index_HookEventName = HookEventName;
|
|
1175
|
+
type index_HookRequest = HookRequest;
|
|
1176
|
+
type index_HookResponse = HookResponse;
|
|
1177
|
+
type index_HookResult = HookResult;
|
|
1178
|
+
type index_HookRule = HookRule;
|
|
1179
|
+
type index_HookRun = HookRun;
|
|
1180
|
+
declare const index_HookRun: typeof HookRun;
|
|
1181
|
+
type index_HookRunOptions = HookRunOptions;
|
|
1182
|
+
type index_HookedSession<S extends SessionLike> = HookedSession<S>;
|
|
1183
|
+
declare const index_HookedSession: typeof HookedSession;
|
|
1184
|
+
type index_HttpHandler = HttpHandler;
|
|
1185
|
+
declare const index_HttpHandler: typeof HttpHandler;
|
|
1186
|
+
type index_HttpTool = HttpTool;
|
|
1187
|
+
declare const index_HttpTool: typeof HttpTool;
|
|
1188
|
+
declare const index_INBOUND_KINDS: typeof INBOUND_KINDS;
|
|
1189
|
+
declare const index_INPUT_TYPES: typeof INPUT_TYPES;
|
|
1190
|
+
type index_Identity = Identity;
|
|
1191
|
+
type index_InboundKind = InboundKind;
|
|
1192
|
+
type index_JsonSchema = JsonSchema;
|
|
1193
|
+
declare const index_KINDS: typeof KINDS;
|
|
1194
|
+
type index_LegendRow = LegendRow;
|
|
1195
|
+
type index_LiveConfig = LiveConfig;
|
|
1196
|
+
type index_LiveTool = LiveTool;
|
|
1197
|
+
type index_LiveToolError = LiveToolError;
|
|
1198
|
+
declare const index_LiveToolError: typeof LiveToolError;
|
|
1199
|
+
type index_LiveTools = LiveTools;
|
|
1200
|
+
declare const index_LiveTools: typeof LiveTools;
|
|
1201
|
+
type index_Matcher = Matcher;
|
|
1202
|
+
declare const index_PARSE_MODES: typeof PARSE_MODES;
|
|
1203
|
+
type index_Pair = Pair;
|
|
1204
|
+
type index_ParseMode = ParseMode;
|
|
1205
|
+
type index_RecordHandler = RecordHandler;
|
|
1206
|
+
declare const index_RecordHandler: typeof RecordHandler;
|
|
1207
|
+
type index_RecordSink = RecordSink;
|
|
1208
|
+
type index_Recorder = Recorder;
|
|
1209
|
+
declare const index_Recorder: typeof Recorder;
|
|
1210
|
+
type index_RedactHandler = RedactHandler;
|
|
1211
|
+
declare const index_RedactHandler: typeof RedactHandler;
|
|
1212
|
+
type index_Replay = Replay;
|
|
1213
|
+
declare const index_Replay: typeof Replay;
|
|
1214
|
+
type index_RequestFn = RequestFn;
|
|
1215
|
+
type index_RunVerdict = RunVerdict;
|
|
1216
|
+
type index_SeedEntity = SeedEntity;
|
|
1217
|
+
type index_SeedRow = SeedRow;
|
|
1218
|
+
type index_SessionLike = SessionLike;
|
|
1219
|
+
declare const index_TOOL_KINDS: typeof TOOL_KINDS;
|
|
1220
|
+
type index_ToolFn = ToolFn;
|
|
1221
|
+
type index_ToolFunctions = ToolFunctions;
|
|
1222
|
+
type index_ToolKind = ToolKind;
|
|
1223
|
+
type index_ToolSpec = ToolSpec;
|
|
1224
|
+
type index_WrappedTools<T extends ToolFunctions> = WrappedTools<T>;
|
|
1225
|
+
declare const index_applyLimit: typeof applyLimit;
|
|
1226
|
+
declare const index_applyResult: typeof applyResult;
|
|
1227
|
+
declare const index_buildTool: typeof buildTool;
|
|
1228
|
+
declare const index_canonical: typeof canonical;
|
|
1229
|
+
declare const index_definition: typeof definition;
|
|
1230
|
+
declare const index_describeHandler: typeof describeHandler;
|
|
1231
|
+
declare const index_describeMatcher: typeof describeMatcher;
|
|
1232
|
+
declare const index_describeTool: typeof describeTool;
|
|
1233
|
+
declare const index_emailPairs: typeof emailPairs;
|
|
1234
|
+
declare const index_emptyConfig: typeof emptyConfig;
|
|
1235
|
+
declare const index_emptyLive: typeof emptyLive;
|
|
1236
|
+
declare const index_eventToJson: typeof eventToJson;
|
|
1237
|
+
declare const index_explodeIp: typeof explodeIp;
|
|
1238
|
+
declare const index_findKind: typeof findKind;
|
|
1239
|
+
declare const index_folded: typeof folded;
|
|
1240
|
+
declare const index_genericPairs: typeof genericPairs;
|
|
1241
|
+
declare const index_importCallable: typeof importCallable;
|
|
1242
|
+
declare const index_inputSchema: typeof inputSchema;
|
|
1243
|
+
declare const index_interpolateHeaders: typeof interpolateHeaders;
|
|
1244
|
+
declare const index_interpolatePath: typeof interpolatePath;
|
|
1245
|
+
declare const index_isGlobalIpv4: typeof isGlobalIpv4;
|
|
1246
|
+
declare const index_jsPattern: typeof jsPattern;
|
|
1247
|
+
declare const index_jsonPath: typeof jsonPath;
|
|
1248
|
+
declare const index_loadHookConfig: typeof loadHookConfig;
|
|
1249
|
+
declare const index_mapFields: typeof mapFields;
|
|
1250
|
+
declare const index_matches: typeof matches;
|
|
1251
|
+
declare const index_mirrorHandle: typeof mirrorHandle;
|
|
1252
|
+
declare const index_namePairs: typeof namePairs;
|
|
1253
|
+
declare const index_newRunKey: typeof newRunKey;
|
|
1254
|
+
declare const index_normalizeEvent: typeof normalizeEvent;
|
|
1255
|
+
declare const index_pageTitle: typeof pageTitle;
|
|
1256
|
+
declare const index_parseHookConfig: typeof parseHookConfig;
|
|
1257
|
+
declare const index_parseJson: typeof parseJson;
|
|
1258
|
+
declare const index_parseMatcher: typeof parseMatcher;
|
|
1259
|
+
declare const index_parseRegex: typeof parseRegex;
|
|
1260
|
+
declare const index_parseStdout: typeof parseStdout;
|
|
1261
|
+
declare const index_parseText: typeof parseText;
|
|
1262
|
+
declare const index_phonePairs: typeof phonePairs;
|
|
1263
|
+
declare const index_pyQuote: typeof pyQuote;
|
|
1264
|
+
declare const index_readConnection: typeof readConnection;
|
|
1265
|
+
declare const index_readable: typeof readable;
|
|
1266
|
+
declare const index_refusalReason: typeof refusalReason;
|
|
1267
|
+
declare const index_render: typeof render;
|
|
1268
|
+
declare const index_resultFromJson: typeof resultFromJson;
|
|
1269
|
+
declare const index_splitTopLevel: typeof splitTopLevel;
|
|
1270
|
+
declare const index_stripTags: typeof stripTags;
|
|
1271
|
+
declare const index_unescapeHtml: typeof unescapeHtml;
|
|
1272
|
+
declare const index_vendorOf: typeof vendorOf;
|
|
1273
|
+
declare const index_withContext: typeof withContext;
|
|
1274
|
+
declare const index_withDefaults: typeof withDefaults;
|
|
1275
|
+
declare namespace index {
|
|
1276
|
+
export { type index_Alias as Alias, index_AliasHandler as AliasHandler, index_AliasMap as AliasMap, type index_Bound as Bound, index_CONTEXT_KEY as CONTEXT_KEY, index_CallableTool as CallableTool, index_CommandHandler as CommandHandler, index_ConnectorTool as ConnectorTool, type index_Decision as Decision, index_DenyHandler as DenyHandler, index_EVENTS as EVENTS, index_EVENT_ALIASES as EVENT_ALIASES, type index_Finding as Finding, index_FunctionHandler as FunctionHandler, index_HANDLER_TYPES as HANDLER_TYPES, type index_Handler as Handler, type index_HandlerFn as HandlerFn, type index_HandlerSpec as HandlerSpec, type index_HandlerType as HandlerType, type index_HookConfig as HookConfig, index_HookConfigError as HookConfigError, index_HookDenied as HookDenied, index_HookError as HookError, type index_HookEvent as HookEvent, type index_HookEventName as HookEventName, type index_HookRequest as HookRequest, type index_HookResponse as HookResponse, type index_HookResult as HookResult, type index_HookRule as HookRule, index_HookRun as HookRun, type index_HookRunOptions as HookRunOptions, index_HookedSession as HookedSession, index_HttpHandler as HttpHandler, index_HttpTool as HttpTool, index_INBOUND_KINDS as INBOUND_KINDS, index_INPUT_TYPES as INPUT_TYPES, type index_Identity as Identity, type index_InboundKind as InboundKind, type index_JsonSchema as JsonSchema, index_KINDS as KINDS, type index_LegendRow as LegendRow, type index_LiveConfig as LiveConfig, type index_LiveTool as LiveTool, index_LiveToolError as LiveToolError, index_LiveTools as LiveTools, type index_Matcher as Matcher, index_PARSE_MODES as PARSE_MODES, type index_Pair as Pair, type index_ParseMode as ParseMode, index_RecordHandler as RecordHandler, type index_RecordSink as RecordSink, index_Recorder as Recorder, index_RedactHandler as RedactHandler, index_Replay as Replay, type index_RequestFn as RequestFn, type index_RunVerdict as RunVerdict, type index_SeedEntity as SeedEntity, type index_SeedRow as SeedRow, type index_SessionLike as SessionLike, index_TOOL_KINDS as TOOL_KINDS, type index_ToolFn as ToolFn, type index_ToolFunctions as ToolFunctions, type index_ToolKind as ToolKind, type index_ToolSpec as ToolSpec, type index_WrappedTools as WrappedTools, index_applyLimit as applyLimit, index_applyResult as applyResult, index_buildTool as buildTool, index_canonical as canonical, index_definition as definition, index_describeHandler as describeHandler, index_describeMatcher as describeMatcher, index_describeTool as describeTool, index_emailPairs as emailPairs, index_emptyConfig as emptyConfig, index_emptyLive as emptyLive, index_eventToJson as eventToJson, index_explodeIp as explodeIp, index_findKind as findKind, index_folded as folded, index_genericPairs as genericPairs, index_importCallable as importCallable, index_inputSchema as inputSchema, index_interpolateHeaders as interpolateHeaders, index_interpolatePath as interpolatePath, index_isGlobalIpv4 as isGlobalIpv4, index_jsPattern as jsPattern, index_jsonPath as jsonPath, index_loadHookConfig as loadHookConfig, index_mapFields as mapFields, index_matches as matches, index_mirrorHandle as mirrorHandle, index_namePairs as namePairs, index_newRunKey as newRunKey, index_normalizeEvent as normalizeEvent, index_pageTitle as pageTitle, index_parseHookConfig as parseHookConfig, index_parseJson as parseJson, index_parseMatcher as parseMatcher, index_parseRegex as parseRegex, index_parseStdout as parseStdout, index_parseText as parseText, index_phonePairs as phonePairs, index_pyQuote as pyQuote, index_readConnection as readConnection, index_readable as readable, index_refusalReason as refusalReason, index_render as render, index_resultFromJson as resultFromJson, index_splitTopLevel as splitTopLevel, index_stripTags as stripTags, index_unescapeHtml as unescapeHtml, index_vendorOf as vendorOf, index_withContext as withContext, index_withDefaults as withDefaults };
|
|
1277
|
+
}
|
|
1278
|
+
|
|
1279
|
+
export { RedactHandler as $, type Alias as A, type Bound as B, CONTEXT_KEY as C, type Decision as D, EVENTS as E, type Finding as F, HttpHandler as G, HANDLER_TYPES as H, HttpTool as I, INBOUND_KINDS as J, INPUT_TYPES as K, type Identity as L, type InboundKind as M, type JsonSchema as N, KINDS as O, type LegendRow as P, type LiveConfig as Q, type LiveTool as R, LiveToolError as S, LiveTools as T, type Matcher as U, PARSE_MODES as V, type Pair as W, type ParseMode as X, RecordHandler as Y, type RecordSink as Z, Recorder as _, AliasHandler as a, Replay as a0, type RequestFn as a1, type RunVerdict as a2, type SeedEntity as a3, type SeedRow as a4, type SessionLike as a5, TOOL_KINDS as a6, type ToolFn as a7, type ToolFunctions as a8, type ToolKind as a9, mapFields as aA, matches as aB, mirrorHandle as aC, namePairs as aD, newRunKey as aE, normalizeEvent as aF, pageTitle as aG, parseHookConfig as aH, parseJson as aI, parseMatcher as aJ, parseRegex as aK, parseStdout as aL, parseText as aM, phonePairs as aN, pyQuote as aO, readConnection as aP, readable as aQ, refusalReason as aR, render as aS, resultFromJson as aT, splitTopLevel as aU, stripTags as aV, unescapeHtml as aW, vendorOf as aX, withContext as aY, withDefaults as aZ, type ToolSpec as aa, type WrappedTools as ab, applyLimit as ac, applyResult as ad, buildTool as ae, canonical as af, definition as ag, describeHandler as ah, describeMatcher as ai, describeTool as aj, emailPairs as ak, emptyConfig as al, emptyLive as am, eventToJson as an, explodeIp as ao, findKind as ap, folded as aq, genericPairs as ar, importCallable as as, inputSchema as at, interpolateHeaders as au, interpolatePath as av, isGlobalIpv4 as aw, jsPattern as ax, jsonPath as ay, loadHookConfig as az, AliasMap as b, CallableTool as c, CommandHandler as d, ConnectorTool as e, DenyHandler as f, EVENT_ALIASES as g, FunctionHandler as h, index as i, type Handler as j, type HandlerFn as k, type HandlerSpec as l, type HandlerType as m, type HookConfig as n, HookConfigError as o, HookDenied as p, HookError as q, type HookEvent as r, type HookEventName as s, type HookRequest as t, type HookResponse as u, type HookResult as v, type HookRule as w, HookRun as x, type HookRunOptions as y, HookedSession as z };
|