@withgateway/sdk 0.2.2 → 0.2.4
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 +11992 -4572
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +11998 -4578
- package/dist/cli.mjs.map +1 -1
- package/dist/files/index.js +71 -31
- package/dist/files/index.js.map +1 -1
- package/dist/files/index.mjs +59 -20
- 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 +6547 -1552
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +6636 -1655
- package/dist/index.mjs.map +1 -1
- package/dist/traces/index.js +60 -20
- package/dist/traces/index.js.map +1 -1
- package/dist/traces/index.mjs +51 -12
- 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 +46 -3
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +41 -2
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +371 -6
- package/dist/worlds/index.d.ts +371 -6
- package/dist/worlds/index.js +2061 -235
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +2050 -224
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +6 -1
- package/runtime/gatewaysdk/environment/_materialize.py +3 -3
- package/runtime/gatewaysdk/environment/schema/api.py +116 -2
- package/runtime/gatewaysdk/environment/schema/compiler.py +14 -0
- package/runtime/gatewaysdk/environment/schema/host.py +37 -11
- package/runtime/gatewaysdk/environment/schema/skills/hooks-getting-started/SKILL.md +154 -0
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +5 -5
- package/runtime/gatewaysdk/environment/schema/snapshot.py +6 -5
- package/runtime/gatewaysdk/environment/schema/tasks.py +12 -2
- package/runtime/gatewaysdk/environment/schema/workers.py +30 -13
- package/skills/hooks-getting-started/SKILL.md +154 -0
- package/skills/worlds-getting-started/SKILL.md +5 -5
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: hooks-getting-started
|
|
3
|
+
description: Rules around an agent's tool calls from one gateway-hooks.toml — the alias door (personas in, real values out), identities that arrive from the web (mint_inbound), redaction of anything (kinds, literal values, patterns), per-task overrides, coding-agent and agent-SDK wiring, and how to check a file before an agent runs it. Use when an agent must not see a real person's identifiers, when web results must be scrubbed, or when wiring gateway hooks into Claude Code or an agent SDK.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Hooks: getting started
|
|
7
|
+
|
|
8
|
+
One file, `gateway-hooks.toml`, holds the rules that run around an agent's tool calls. The
|
|
9
|
+
same file is attached in code by an agent SDK (`HookRun.from_config` / `HookRun.fromConfig`),
|
|
10
|
+
run as a coding agent's hook (`gateway hooks run`), and validated without an agent
|
|
11
|
+
(`gateway hooks check`). Nothing in it is automatic: every behaviour is a rule you wrote or a
|
|
12
|
+
knob with a default, and a task can override the file.
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
gateway hooks guide # this page
|
|
16
|
+
gateway hooks check gateway-hooks.toml # validate, build every handler, dry-run one event
|
|
17
|
+
gateway hooks run # the command a coding agent names in its settings
|
|
18
|
+
gateway hooks legend <run dir> # persona -> real, for the owner
|
|
19
|
+
gateway hooks reveal <file> # a run's file with the real values put back
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
## The file, in one screen
|
|
23
|
+
|
|
24
|
+
```toml
|
|
25
|
+
[alias]
|
|
26
|
+
slugs = ["spycloud"] # worlds that store personal fields as sha256:<slug>:<value>
|
|
27
|
+
public_layer_wins = true # a `role: public` seed is never rewritten, even inside a private email's domain
|
|
28
|
+
public_mailbox_domains = ["gmail.com"] # kept real in an email persona; omit for the built-in free-mail list, [] for none
|
|
29
|
+
mint_inbound = ["email", "phone", "ip"] # kinds minted ON SIGHT in results; omit = seeds only
|
|
30
|
+
legend = "{run_dir}/legend.json" # the owner's way back: run key + every persona, written at run_end
|
|
31
|
+
|
|
32
|
+
[vendors]
|
|
33
|
+
spycloud = "spycloud_.*" # tool-name patterns -> a vendor label for `vendor = ...` matchers
|
|
34
|
+
|
|
35
|
+
[[hooks.pre_tool_call]] # or [[hooks.PreToolUse]] — Claude Code's names are accepted
|
|
36
|
+
matcher = "spycloud_.* | web_search" # `A | B` alternation of unanchored regexes; "" or "*" is every tool
|
|
37
|
+
handlers = [
|
|
38
|
+
{ type = "alias" }, # persona -> real on the way out
|
|
39
|
+
{ type = "command", command = "python guard.py", timeout = 10 }, # your hook: event on stdin, verdict on stdout
|
|
40
|
+
{ type = "deny", reason = "not in this run" },
|
|
41
|
+
]
|
|
42
|
+
|
|
43
|
+
[[hooks.post_tool_call]]
|
|
44
|
+
matcher = "spycloud_.* | web_search"
|
|
45
|
+
handlers = [
|
|
46
|
+
{ type = "alias" }, # real -> persona on the way in, leaks metered
|
|
47
|
+
{ type = "record", sink = "{run_dir}/transcript.jsonl", async = true },
|
|
48
|
+
]
|
|
49
|
+
|
|
50
|
+
[[hooks.post_tool_call]] # a SECOND rule: one rewriter per rule, and rules chain
|
|
51
|
+
matcher = "web_search | web_fetch"
|
|
52
|
+
handlers = [{ type = "redact", kinds = ["phone"], values = ["Acme Holdings"], patterns = ["\\bDOB[: ]+\\S+"] }]
|
|
53
|
+
|
|
54
|
+
[[hooks.run_end]]
|
|
55
|
+
handlers = [{ type = "alias", check = "outgoing" }] # a real value in the report fails the run
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Events: `pre_tool_call`, `post_tool_call`, `pre_request`, `post_response`, `run_end`.
|
|
59
|
+
Handlers: `alias`, `command`, `http`, `callable`, `deny`, `record`, `redact`. A rule's handlers
|
|
60
|
+
all see the same event and at most one of them may rewrite it; put a second rewriter under its
|
|
61
|
+
own `[[hooks.<event>]]` — rules apply in order and each sees the previous one's rewrite.
|
|
62
|
+
|
|
63
|
+
## The alias door
|
|
64
|
+
|
|
65
|
+
Seed it with the task's entities before the agent starts; the instruction the agent reads is
|
|
66
|
+
already in persona space, and every tool result is rewritten on the way in while every tool
|
|
67
|
+
call is resolved back to the real value on the way out.
|
|
68
|
+
|
|
69
|
+
```json
|
|
70
|
+
[{ "type": "person_name", "value": "Matthew Nowell", "identity": "subject" },
|
|
71
|
+
{ "type": "email", "value": "m.nowell@nowell-ltd.com", "identity": "subject" },
|
|
72
|
+
{ "type": "domain", "value": "star-co.net.kp", "role": "public" }]
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Kinds: `person_name`, `email`, `username`, `phone`, `company`, `domain`, `ip`, `account`,
|
|
76
|
+
`machine`, `log`; anything else gets a `REF-nnnn` stand-in. `identity` ties attributes to one
|
|
77
|
+
person so they stay consistent; `role: "public"` is never replaced. Every variant of a value is
|
|
78
|
+
tracked (bare surname, handle spellings, `(at)` emails, phone formats, percent-encoding, a
|
|
79
|
+
world's `sha256:` stored form); what slips through is counted (`leak_through_inbound`), and a
|
|
80
|
+
real value in the outgoing report fails the run (`leaks_outbound`).
|
|
81
|
+
|
|
82
|
+
## Identities that arrive, not seeded
|
|
83
|
+
|
|
84
|
+
A page or a vendor row brings people the seed list never named. By default they reach the
|
|
85
|
+
agent as they are. Two knobs change that:
|
|
86
|
+
|
|
87
|
+
- **`mint_inbound = ["email", "phone", "ip"]`** — an unseeded value of a listed kind met in a
|
|
88
|
+
result gets a persona on sight: aliased in, resolved back out on the next call, one persona
|
|
89
|
+
for the rest of the run whatever the spelling. Only these kinds are pattern-safe (a global
|
|
90
|
+
IP; a number with a `+` or an area code); a name or a handle is seeded, never guessed. The
|
|
91
|
+
whole result is read before any of it is rewritten, so a spelling in an earlier field is
|
|
92
|
+
caught by a later one. Listed in `found_inbound`.
|
|
93
|
+
- **`redact`** — removes instead of replacing, from ANY string a result carries (page body,
|
|
94
|
+
title, URL, vendor row): `kinds` for shaped values, `values` for arbitrary literals (a name,
|
|
95
|
+
a company, a phrase — any case, any whitespace), `patterns` for regular expressions;
|
|
96
|
+
`token` (default `[redacted {kind}]`) is what stands in. Runs after the door, leaves personas
|
|
97
|
+
alone, counted in `redactions` (kind and a three-letter prefix, never the value).
|
|
98
|
+
|
|
99
|
+
## Per task, not per file
|
|
100
|
+
|
|
101
|
+
What a task aliases is the task's decision — one wants a persona for every address the web
|
|
102
|
+
returns, another's selectors are public IPs that must stay facts — so the run overrides the
|
|
103
|
+
file:
|
|
104
|
+
|
|
105
|
+
```python
|
|
106
|
+
run = HookRun.from_config("gateway-hooks.toml", mint_inbound=["email"]) # this task only
|
|
107
|
+
run.seed(task["entities"] + task.get("replacements", [])) # values expected to surface, seeded early
|
|
108
|
+
run.on("post_tool_call", RedactHandler(run.alias, values=["Acme Holdings"]), matcher="web_.*")
|
|
109
|
+
run.mint("email", found_later) # one more persona, from code, any time
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
```ts
|
|
113
|
+
const run = await HookRun.fromConfig("gateway-hooks.toml", { mintInbound: [] }); // seeds only, whatever the file says
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
## Seeing the real data (the owner)
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
gateway hooks legend runs/<run id>/ # persona -> real, with role, provenance, identity
|
|
120
|
+
gateway hooks reveal runs/<run id>/report.md # the file with every persona put back
|
|
121
|
+
gateway hooks reveal transcript.jsonl --legend .gateway/hooks/<session>/legend.json --out transcript.real.jsonl
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
The run writes the legend where `[alias] legend` says (found personas included); a coding
|
|
125
|
+
agent's state dir keeps one beside `run.json` after every event. `reveal` puts every persona
|
|
126
|
+
spelling back in a JSON or text file; a `[redacted …]` token stays — redaction removed the
|
|
127
|
+
value, and its raw copy is a `record` sink placed before the `redact` rule. The legend maps
|
|
128
|
+
personas to people: keep it with the run key, out of version control, never beside world data.
|
|
129
|
+
|
|
130
|
+
## Wiring
|
|
131
|
+
|
|
132
|
+
- **Agent SDK** — `guarded = run.wrap({ lookup_email: lookupEmail })` and register the wrapped
|
|
133
|
+
function wherever the SDK takes a tool implementation; `run.tools()` materializes the file's
|
|
134
|
+
`[tools.*]` (a keyed web search, a connector operation) already wrapped;
|
|
135
|
+
`verdict = run.end(report)` runs `run_end`.
|
|
136
|
+
- **Claude Code / coding agents** — `.claude/settings.json`: `PreToolUse`, `PostToolUse` and
|
|
137
|
+
`Stop` entries whose command is `gateway hooks run`. State (run key + seeds) persists under
|
|
138
|
+
`--state`, `$GATEWAY_HOOKS_STATE`, else `.gateway/hooks/<session id>`. A coding agent shows the
|
|
139
|
+
model a result before its hook runs, so the inbound rewrite cannot reach it there (the
|
|
140
|
+
command says so: `rewrite reached nobody`); route such tools through the SDK or an MCP server
|
|
141
|
+
that wraps them.
|
|
142
|
+
- **Any transport** — `run.session(session, request_fn=...)` puts `pre_request` /
|
|
143
|
+
`post_response` around a client with its own auth.
|
|
144
|
+
|
|
145
|
+
## Check before wiring
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
gateway hooks check gateway-hooks.toml --event PreToolUse --tool Bash --input '{"command":"ls"}'
|
|
149
|
+
gateway hooks check gateway-hooks.toml --seed @entities.json --tool web_search --input '{"query":"Keith Yarrow"}'
|
|
150
|
+
```
|
|
151
|
+
|
|
152
|
+
`check` builds every handler (a callable that does not import, a bad pattern, two rewriters on
|
|
153
|
+
one rule fail here, not mid-run) and prints what each would do to one event. `--json` adds the
|
|
154
|
+
run's meters: aliases, substitutions, leaks, found identities, redactions, denials, hook errors.
|
|
@@ -337,7 +337,7 @@ SDK: `openSession(slug, { task: spec })` (TS), `open_session(slug, spec)` (Pytho
|
|
|
337
337
|
sessions open it by id and grades attribute to the task and its version:
|
|
338
338
|
|
|
339
339
|
```bash
|
|
340
|
-
gateway worlds task create task.json --world x # version 1; --name overrides the spec's name
|
|
340
|
+
gateway worlds task create task.json --world x # version 1; --name overrides the spec's name; --replace: a taken name becomes its next version
|
|
341
341
|
gateway worlds task list --world x --metadata externalUserId=u_42
|
|
342
342
|
gateway worlds task show <TASK_ID> [--version 2] # spec + version history
|
|
343
343
|
gateway worlds task validate <TASK_ID> # seed/grader entities against the pinned world's version
|
|
@@ -403,14 +403,14 @@ client is the agent. Dependency tools are `<alias>.<tool>`, each world grades on
|
|
|
403
403
|
```bash
|
|
404
404
|
gateway worlds serve ./whatsapp --task escalate_locked_account --port 8080 # prints {task, prompt, tools, verifiers, worlds}
|
|
405
405
|
curl -s localhost:8080/__session/task # + contracts: each tool's description and input schema
|
|
406
|
-
curl -s -X POST localhost:8080/__session/call -d '{"tool":"slack.post_message","args":{...}}'
|
|
407
406
|
gateway worlds call http://localhost:8080 list_conversations --state --grade # act from the CLI, read state, grade
|
|
408
407
|
gateway worlds call http://localhost:8080 slack.list_channels --args '{...}' --close # end it; the serve process exits
|
|
409
408
|
```
|
|
410
409
|
|
|
411
|
-
`GET /__session/{task,tools,state}`, `POST /__session/{call,grade,reset,seed,close}
|
|
412
|
-
|
|
413
|
-
|
|
410
|
+
`GET /__session/{task,tools,state}`, `POST /__session/{call,grade,reset,seed,close}`; `--task` and
|
|
411
|
+
`--scenario` belong to `serve`. A directory target (`worlds call ./x <tool>`) opens and closes its
|
|
412
|
+
own session per call. A HOSTED session is not a served url (the World Host serves no `/__session/*`;
|
|
413
|
+
its `api.url` takes the session's bearer): act on it by id, `gateway worlds call <sessionId> <tool> --state --grade --close`.
|
|
414
414
|
|
|
415
415
|
## 7. Run and grade
|
|
416
416
|
|