@intutic/gate 1.10.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +261 -0
- package/dist/actions.d.ts +86 -0
- package/dist/actions.d.ts.map +1 -0
- package/dist/actions.js +239 -0
- package/dist/actions.js.map +1 -0
- package/dist/client.d.ts +94 -0
- package/dist/client.d.ts.map +1 -0
- package/dist/client.js +207 -0
- package/dist/client.js.map +1 -0
- package/dist/dsh.d.ts +162 -0
- package/dist/dsh.d.ts.map +1 -0
- package/dist/dsh.js +189 -0
- package/dist/dsh.js.map +1 -0
- package/dist/errors.d.ts +41 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +53 -0
- package/dist/errors.js.map +1 -0
- package/dist/eve.d.ts +425 -0
- package/dist/eve.d.ts.map +1 -0
- package/dist/eve.js +378 -0
- package/dist/eve.js.map +1 -0
- package/dist/gate.d.ts +113 -0
- package/dist/gate.d.ts.map +1 -0
- package/dist/gate.js +274 -0
- package/dist/gate.js.map +1 -0
- package/dist/harness.d.ts +482 -0
- package/dist/harness.d.ts.map +1 -0
- package/dist/harness.js +504 -0
- package/dist/harness.js.map +1 -0
- package/dist/headers.d.ts +26 -0
- package/dist/headers.d.ts.map +1 -0
- package/dist/headers.js +30 -0
- package/dist/headers.js.map +1 -0
- package/dist/imagecheck.d.ts +93 -0
- package/dist/imagecheck.d.ts.map +1 -0
- package/dist/imagecheck.js +286 -0
- package/dist/imagecheck.js.map +1 -0
- package/dist/index.d.ts +26 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +19 -0
- package/dist/index.js.map +1 -0
- package/dist/managedAgents.d.ts +375 -0
- package/dist/managedAgents.d.ts.map +1 -0
- package/dist/managedAgents.js +446 -0
- package/dist/managedAgents.js.map +1 -0
- package/dist/mastra.d.ts +175 -0
- package/dist/mastra.d.ts.map +1 -0
- package/dist/mastra.js +161 -0
- package/dist/mastra.js.map +1 -0
- package/dist/openai.d.ts +392 -0
- package/dist/openai.d.ts.map +1 -0
- package/dist/openai.js +658 -0
- package/dist/openai.js.map +1 -0
- package/dist/shlex.d.ts +16 -0
- package/dist/shlex.d.ts.map +1 -0
- package/dist/shlex.js +78 -0
- package/dist/shlex.js.map +1 -0
- package/dist/snapshot.d.ts +111 -0
- package/dist/snapshot.d.ts.map +1 -0
- package/dist/snapshot.js +243 -0
- package/dist/snapshot.js.map +1 -0
- package/dist/soprules.d.ts +88 -0
- package/dist/soprules.d.ts.map +1 -0
- package/dist/soprules.js +176 -0
- package/dist/soprules.js.map +1 -0
- package/dist/trueforge.d.ts +191 -0
- package/dist/trueforge.d.ts.map +1 -0
- package/dist/trueforge.js +184 -0
- package/dist/trueforge.js.map +1 -0
- package/dist/vercel.d.ts +174 -0
- package/dist/vercel.d.ts.map +1 -0
- package/dist/vercel.js +157 -0
- package/dist/vercel.js.map +1 -0
- package/dist/workflow.d.ts +209 -0
- package/dist/workflow.d.ts.map +1 -0
- package/dist/workflow.js +254 -0
- package/dist/workflow.js.map +1 -0
- package/dist/wrapTools.d.ts +68 -0
- package/dist/wrapTools.d.ts.map +1 -0
- package/dist/wrapTools.js +95 -0
- package/dist/wrapTools.js.map +1 -0
- package/package.json +123 -0
|
@@ -0,0 +1,375 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Anthropic Managed Agents (public beta since 2026-04-08) — a session
|
|
3
|
+
* confirmation responder, plus guidance for the two execution surfaces this
|
|
4
|
+
* adapter does NOT cover the same way.
|
|
5
|
+
*
|
|
6
|
+
* `@intutic/gate/managed-agents` — the TypeScript twin of the Python SDK's
|
|
7
|
+
* `intutic_clawde.gate.adapters.managed_agents`. See that module's doc for
|
|
8
|
+
* the full research trail; this header covers only what differs for the
|
|
9
|
+
* TypeScript SDK.
|
|
10
|
+
*
|
|
11
|
+
* Managed Agents is architecturally different from every other adapter in
|
|
12
|
+
* this package: the customer's process does not run the tool-call loop.
|
|
13
|
+
* Anthropic hosts a "session" that emits an event stream, and the customer's
|
|
14
|
+
* backend answers it. There is no local function call to wrap the way
|
|
15
|
+
* `wrapTools()` wraps a Mastra tool.
|
|
16
|
+
*
|
|
17
|
+
* ## The veto mechanism — CONFIRMED against a real install
|
|
18
|
+
*
|
|
19
|
+
* `@anthropic-ai/sdk@0.117.1` (the latest published release at the time this
|
|
20
|
+
* adapter was built) was installed as a devDependency of this package and its
|
|
21
|
+
* shipped `.d.ts` read directly (not inferred from docs alone; the Python
|
|
22
|
+
* twin was checked the same way against `anthropic==0.122.0`, its own
|
|
23
|
+
* latest):
|
|
24
|
+
*
|
|
25
|
+
* * `resources/beta/sessions/events.d.ts` — every request this module
|
|
26
|
+
* issues (`.list()`, `.send()`, `.stream()`) carries
|
|
27
|
+
* `anthropic-beta: managed-agents-2026-04-01` automatically (the real
|
|
28
|
+
* client sets it); {@link MANAGED_AGENTS_BETA} documents the value for a
|
|
29
|
+
* caller building a raw request.
|
|
30
|
+
* * `BetaManagedAgentsUserToolConfirmationEventParams` — the wire shape
|
|
31
|
+
* this module builds: `{ type: 'user.tool_confirmation', tool_use_id,
|
|
32
|
+
* result: 'allow' | 'deny', deny_message?, session_thread_id? }`.
|
|
33
|
+
* * `BetaManagedAgentsAgentToolUseEvent` and
|
|
34
|
+
* `BetaManagedAgentsAgentMCPToolUseEvent` both carry
|
|
35
|
+
* `evaluated_permission?: 'allow' | 'ask' | 'deny'`. A call the server
|
|
36
|
+
* evaluated to `'ask'` (e.g. because its `permission_policy` is
|
|
37
|
+
* `always_ask` — Anthropic's docs mark MCP toolsets as `always_ask` by
|
|
38
|
+
* default; the SDK types do not encode a default for built-in
|
|
39
|
+
* agent-toolset tools, so check current docs) PAUSES the session —
|
|
40
|
+
* Anthropic's own docs: "Denied tools do not run." A `'deny'` verdict
|
|
41
|
+
* means the SERVER already denied the call (no confirmation is expected
|
|
42
|
+
* or accepted); `'allow'` or unset means the call never paused at all.
|
|
43
|
+
* **This is the real, documented pre-execution veto this module answers
|
|
44
|
+
* — it is not observe-only.**
|
|
45
|
+
* * `lib/tools/SessionToolRunner.d.ts` is Anthropic's OWN reference
|
|
46
|
+
* dispatcher: it executes `agent.tool_use` / `agent.custom_tool_use`
|
|
47
|
+
* calls and posts results, but it does **not** decide `allow`/`deny` for
|
|
48
|
+
* an `ask`-gated call itself — it holds until *something* sends the
|
|
49
|
+
* matching `user.tool_confirmation` event. That "something" is what this
|
|
50
|
+
* module provides: {@link confirmationForEvent} /
|
|
51
|
+
* {@link IntuticSessionConfirmer} turn a paused `agent.tool_use` /
|
|
52
|
+
* `agent.mcp_tool_use` event into a `Gate.guard()`-driven verdict.
|
|
53
|
+
* * `lib/environments/worker.d.ts`'s `EnvironmentWorker` (the self-hosted
|
|
54
|
+
* sandbox driver) is built on `SessionToolRunner` for built-in
|
|
55
|
+
* agent-toolset tools (bash, edit, read, write, glob, grep, web_fetch,
|
|
56
|
+
* web_search). **Self-hosted built-in tools therefore pause and resolve
|
|
57
|
+
* through the IDENTICAL `agent.tool_use` / `evaluated_permission` /
|
|
58
|
+
* `user.tool_confirmation` mechanism as hosted ones** — this adapter
|
|
59
|
+
* covers them the same way. What differs for self-hosted is only WHERE
|
|
60
|
+
* the tool body executes (the customer's own worker process), not how
|
|
61
|
+
* the pre-execution veto works.
|
|
62
|
+
* * `agent.mcp_tool_use` is explicitly excluded from `SessionToolRunner`'s
|
|
63
|
+
* own dispatch (its own doc comment: "Server-side `agent.mcp_tool_use`
|
|
64
|
+
* calls are intentionally excluded — the runner does not handle them" —
|
|
65
|
+
* MCP tools run server-side at Anthropic). But the confirmation gate is a
|
|
66
|
+
* SEPARATE mechanism from execution: `BetaManagedAgentsAgentMCPToolUseEvent`
|
|
67
|
+
* carries `evaluated_permission` exactly like the built-in event does, so
|
|
68
|
+
* this module answers MCP pauses too, even though nothing in the official
|
|
69
|
+
* SDK dispatches their execution locally.
|
|
70
|
+
*
|
|
71
|
+
* ## What this module does NOT cover the same way — custom tools
|
|
72
|
+
*
|
|
73
|
+
* `BetaManagedAgentsAgentCustomToolUseEvent` has **no** `evaluated_permission`
|
|
74
|
+
* field and no `permission_policy` concept at all: a custom tool always
|
|
75
|
+
* executes wherever the client that owns its name is listening, with no
|
|
76
|
+
* pause. It is answered with `user.custom_tool_result`
|
|
77
|
+
* (`custom_tool_use_id` + `content` + `is_error`), not
|
|
78
|
+
* `user.tool_confirmation`. This is the "customer's own process runs the
|
|
79
|
+
* call" surface the phase brief anticipated — the natural integration point
|
|
80
|
+
* IS this package's `wrapTools()`/`wrapTool()`, exactly as the brief
|
|
81
|
+
* guessed. BUT verify the shape, because the generic helper does not apply
|
|
82
|
+
* as-is: `BetaRunnableTool` (`lib/tools/BetaRunnableTool.d.ts`, what
|
|
83
|
+
* `SessionToolRunner` dispatches against) exposes a `run(args, context)`
|
|
84
|
+
* method, not the `execute(input)` method `wrapTools()`'s object branch looks
|
|
85
|
+
* for (`wrapTools.ts` only recognises `.execute`) — handing it a
|
|
86
|
+
* `BetaRunnableTool` throws a `TypeError` rather than silently skipping
|
|
87
|
+
* governance, but it still means the generic helper needs a `.run`-aware
|
|
88
|
+
* sibling rather than "just works". {@link wrapManagedAgentsCustomTool} /
|
|
89
|
+
* {@link wrapManagedAgentsCustomTools} are that sibling — same throw-based
|
|
90
|
+
* refusal contract, applied to `.run` instead of `.execute`.
|
|
91
|
+
*
|
|
92
|
+
* ## What this module does NOT cover at all — the sandbox tool BODY
|
|
93
|
+
*
|
|
94
|
+
* The self-hosted `EnvironmentWorker` gates tool PAUSES exactly like the
|
|
95
|
+
* hosted path (see above) — but the tool's actual execution runs inside the
|
|
96
|
+
* customer's own worker process, outside this adapter's reach, same as every
|
|
97
|
+
* other Intutic adapter's posture toward a framework's built-in tool bodies
|
|
98
|
+
* (see openai.ts's module doc for the precedent). This module governs
|
|
99
|
+
* WHETHER the call runs; it does not — and cannot — inspect or modify what
|
|
100
|
+
* the tool body does once allowed.
|
|
101
|
+
*
|
|
102
|
+
* ## Webhook vs. streamed/polled delivery — both are real, verified live
|
|
103
|
+
*
|
|
104
|
+
* `resources/beta/webhooks.d.ts`: `client.beta.webhooks.unwrap(body, {
|
|
105
|
+
* headers, key })` verifies the HMAC signature and returns a typed event
|
|
106
|
+
* (synchronously — no network call); for a pause it is
|
|
107
|
+
* `session.requires_action`, which carries only `id` (the session id),
|
|
108
|
+
* `organization_id`, `workspace_id` — NOT the tool call itself. A webhook is
|
|
109
|
+
* therefore a NOTIFICATION to re-poll, not a self-contained payload —
|
|
110
|
+
* {@link IntuticSessionConfirmer.handleWebhook} does exactly that: re-lists
|
|
111
|
+
* the session's unanswered events and answers them. `events.stream()` /
|
|
112
|
+
* `events.list()` are the poll/stream alternative this module also supports
|
|
113
|
+
* directly via {@link IntuticSessionConfirmer.poll} /
|
|
114
|
+
* {@link IntuticSessionConfirmer.watch}.
|
|
115
|
+
*
|
|
116
|
+
* ## Fail-closed posture
|
|
117
|
+
*
|
|
118
|
+
* Matches every other adapter in this package: no gate configured, or an
|
|
119
|
+
* unexpected exception out of `Gate.guard()`, both produce a `'deny'` verdict
|
|
120
|
+
* — never a silently-allowed, unevaluated call. Only `IntuticGateRefusal` is
|
|
121
|
+
* distinguished (its own message becomes `deny_message`); anything else is
|
|
122
|
+
* wrapped in a generic "gate crashed" `deny_message`.
|
|
123
|
+
*
|
|
124
|
+
* ## What this module does NOT import
|
|
125
|
+
*
|
|
126
|
+
* Deliberately no runtime dependency on `@anthropic-ai/sdk` — the types below
|
|
127
|
+
* are narrow structural copies of only the shapes this adapter touches, same
|
|
128
|
+
* policy as openai.ts / mastra.ts / vercel.ts (see openai.ts's module doc for
|
|
129
|
+
* the full rationale). The real package is a devDependency used by
|
|
130
|
+
* `__tests__/managedAgents.test.ts` to type-check these structural types
|
|
131
|
+
* against the real shipped ones.
|
|
132
|
+
*
|
|
133
|
+
* @module
|
|
134
|
+
*/
|
|
135
|
+
import { Gate } from './gate.js';
|
|
136
|
+
/** The beta header every Sessions-API request needs. The real SDK sets this
|
|
137
|
+
* on every `.list()`/`.send()`/`.stream()` call automatically — this
|
|
138
|
+
* constant exists for callers building their own request against the
|
|
139
|
+
* endpoint directly. */
|
|
140
|
+
export declare const MANAGED_AGENTS_BETA = "managed-agents-2026-04-01";
|
|
141
|
+
/** Slice of `BetaManagedAgentsAgentToolUseEvent` this module reads. */
|
|
142
|
+
export interface AgentToolUseEventLike {
|
|
143
|
+
id: string;
|
|
144
|
+
type: 'agent.tool_use';
|
|
145
|
+
name: string;
|
|
146
|
+
input: Record<string, unknown>;
|
|
147
|
+
evaluated_permission?: 'allow' | 'ask' | 'deny' | null;
|
|
148
|
+
session_thread_id?: string | null;
|
|
149
|
+
}
|
|
150
|
+
/** Slice of `BetaManagedAgentsAgentMCPToolUseEvent` this module reads. */
|
|
151
|
+
export interface AgentMcpToolUseEventLike {
|
|
152
|
+
id: string;
|
|
153
|
+
type: 'agent.mcp_tool_use';
|
|
154
|
+
name: string;
|
|
155
|
+
mcp_server_name: string;
|
|
156
|
+
input: Record<string, unknown>;
|
|
157
|
+
evaluated_permission?: 'allow' | 'ask' | 'deny' | null;
|
|
158
|
+
session_thread_id?: string | null;
|
|
159
|
+
}
|
|
160
|
+
/** Slice of `BetaManagedAgentsAgentCustomToolUseEvent` — carries no
|
|
161
|
+
* `evaluated_permission`: custom tools never pause (see module doc). */
|
|
162
|
+
export interface AgentCustomToolUseEventLike {
|
|
163
|
+
id: string;
|
|
164
|
+
type: 'agent.custom_tool_use';
|
|
165
|
+
name: string;
|
|
166
|
+
input: Record<string, unknown>;
|
|
167
|
+
session_thread_id?: string | null;
|
|
168
|
+
}
|
|
169
|
+
/** Any session event — this module inspects only `.type` (and, for the
|
|
170
|
+
* confirmable two, the fields above) so a wider real event passes through
|
|
171
|
+
* this structural type untouched. */
|
|
172
|
+
export type ManagedAgentsSessionEventLike = AgentToolUseEventLike | AgentMcpToolUseEventLike | AgentCustomToolUseEventLike | {
|
|
173
|
+
id?: string;
|
|
174
|
+
type: string;
|
|
175
|
+
tool_use_id?: string;
|
|
176
|
+
[key: string]: unknown;
|
|
177
|
+
};
|
|
178
|
+
/** Structural copy of `BetaManagedAgentsUserToolConfirmationEventParams` —
|
|
179
|
+
* exactly what this module sends via `events.send()`. */
|
|
180
|
+
export interface UserToolConfirmationParams {
|
|
181
|
+
type: 'user.tool_confirmation';
|
|
182
|
+
tool_use_id: string;
|
|
183
|
+
result: 'allow' | 'deny';
|
|
184
|
+
deny_message?: string;
|
|
185
|
+
session_thread_id?: string;
|
|
186
|
+
}
|
|
187
|
+
/** Structural slice of `client.beta.sessions.events` — only the three
|
|
188
|
+
* methods this module calls, positional-argument-compatible with the real
|
|
189
|
+
* SDK's `list(sessionID, params?, options?)` / `send(sessionID, params,
|
|
190
|
+
* options?)` / `stream(sessionID, params?, options?)`. */
|
|
191
|
+
export interface ManagedAgentsSessionEventsClientLike {
|
|
192
|
+
list(sessionId: string, params?: {
|
|
193
|
+
limit?: number;
|
|
194
|
+
types?: string[];
|
|
195
|
+
}): AsyncIterable<ManagedAgentsSessionEventLike>;
|
|
196
|
+
send(sessionId: string, params: {
|
|
197
|
+
events: UserToolConfirmationParams[];
|
|
198
|
+
}): Promise<unknown>;
|
|
199
|
+
stream(sessionId: string): Promise<AsyncIterable<ManagedAgentsSessionEventLike>>;
|
|
200
|
+
}
|
|
201
|
+
/** Structural slice of the Anthropic client this module needs:
|
|
202
|
+
* `client.beta.sessions.events`. */
|
|
203
|
+
export interface ManagedAgentsClientLike {
|
|
204
|
+
beta: {
|
|
205
|
+
sessions: {
|
|
206
|
+
events: ManagedAgentsSessionEventsClientLike;
|
|
207
|
+
};
|
|
208
|
+
};
|
|
209
|
+
}
|
|
210
|
+
export interface ManagedAgentsWrapOptions {
|
|
211
|
+
/** Overrides the process-wide installed gate (`install(new Gate(...))`). */
|
|
212
|
+
gate?: Gate;
|
|
213
|
+
}
|
|
214
|
+
/**
|
|
215
|
+
* Build the `user.tool_confirmation` params answering `event`, or `null` if
|
|
216
|
+
* `event` needs no answer from this module.
|
|
217
|
+
*
|
|
218
|
+
* `null` covers three cases, all correct to send nothing for: the event
|
|
219
|
+
* isn't `agent.tool_use`/`agent.mcp_tool_use` (including
|
|
220
|
+
* `agent.custom_tool_use` — see the module doc); its `evaluated_permission`
|
|
221
|
+
* is `'allow'` or unset (the call never paused); or it is already `'deny'`
|
|
222
|
+
* (the SERVER already resolved it — sending a confirmation for an id the
|
|
223
|
+
* server considers closed would just error).
|
|
224
|
+
*
|
|
225
|
+
* Anything else — `'ask'`, or a permission value this module doesn't
|
|
226
|
+
* recognise — is treated as a pause needing a verdict, matching
|
|
227
|
+
* `SessionToolRunner`'s own fail-closed handling of unrecognised wire values
|
|
228
|
+
* (hold/deny rather than dispatch).
|
|
229
|
+
*
|
|
230
|
+
* ASYNC: `Gate.guard()` is async in this package (unlike the Python SDK's
|
|
231
|
+
* synchronous twin) — every caller must `await` this.
|
|
232
|
+
*/
|
|
233
|
+
export declare function confirmationForEvent(event: ManagedAgentsSessionEventLike, opts?: ManagedAgentsWrapOptions): Promise<UserToolConfirmationParams | null>;
|
|
234
|
+
/**
|
|
235
|
+
* Attaches Intutic governance to one Managed Agents session's confirmation
|
|
236
|
+
* pauses.
|
|
237
|
+
*
|
|
238
|
+
* Duck-typed on `client`: only `client.beta.sessions.events.list(sessionId,
|
|
239
|
+
* ...)`, `.send(sessionId, { events })`, and `.stream(sessionId)` are ever
|
|
240
|
+
* called — pass a real `Anthropic` client, or a test double satisfying
|
|
241
|
+
* {@link ManagedAgentsClientLike}.
|
|
242
|
+
*
|
|
243
|
+
* Usage — polling (e.g. right after creating a session, or from a
|
|
244
|
+
* cron/worker loop):
|
|
245
|
+
*
|
|
246
|
+
* ```ts
|
|
247
|
+
* import { Anthropic } from '@anthropic-ai/sdk'
|
|
248
|
+
* import { Gate, install } from '@intutic/gate'
|
|
249
|
+
* import { IntuticSessionConfirmer } from '@intutic/gate/managed-agents'
|
|
250
|
+
*
|
|
251
|
+
* install(new Gate({ workspaceId: process.env.INTUTIC_WORKSPACE_ID }))
|
|
252
|
+
* const client = new Anthropic()
|
|
253
|
+
* const confirmer = new IntuticSessionConfirmer(client, session.id)
|
|
254
|
+
* await confirmer.poll() // answers every currently-pending tool_use/mcp_tool_use pause
|
|
255
|
+
* ```
|
|
256
|
+
*
|
|
257
|
+
* Usage — webhook (`session.requires_action`):
|
|
258
|
+
*
|
|
259
|
+
* ```ts
|
|
260
|
+
* const event = client.beta.webhooks.unwrap(rawBody, { headers })
|
|
261
|
+
* if (event.data.type === 'session.requires_action') {
|
|
262
|
+
* await new IntuticSessionConfirmer(client, event.data.id).poll()
|
|
263
|
+
* }
|
|
264
|
+
* ```
|
|
265
|
+
*
|
|
266
|
+
* Usage — live stream. `watch()` reconnects with capped backoff and re-polls
|
|
267
|
+
* after every reconnect, so a pause raised while the stream was down is
|
|
268
|
+
* still answered (see {@link watch} and {@link WatchOptions}):
|
|
269
|
+
*
|
|
270
|
+
* ```ts
|
|
271
|
+
* const ac = new AbortController()
|
|
272
|
+
* for await (const sent of confirmer.watch({ signal: ac.signal, idleTimeoutMs: 120_000 })) {
|
|
273
|
+
* console.log(sent.tool_use_id, sent.result)
|
|
274
|
+
* }
|
|
275
|
+
* ```
|
|
276
|
+
*/
|
|
277
|
+
/** Options for {@link IntuticSessionConfirmer.watch} (TD-428). */
|
|
278
|
+
export interface WatchOptions {
|
|
279
|
+
/** Reconnects allowed after the first connection; unbounded by default. */
|
|
280
|
+
maxReconnects?: number;
|
|
281
|
+
backoffStartMs?: number;
|
|
282
|
+
backoffCapMs?: number;
|
|
283
|
+
/** Drop and reopen a stream that has been silent this long. */
|
|
284
|
+
idleTimeoutMs?: number;
|
|
285
|
+
/** Aborting ends `watch()` at the next opportunity. */
|
|
286
|
+
signal?: AbortSignal;
|
|
287
|
+
}
|
|
288
|
+
/** 400–499 except 408 (timeout) and 429 (rate limit): a retry cannot help. */
|
|
289
|
+
export declare function isFatal4xx(err: unknown): boolean;
|
|
290
|
+
export declare class IntuticSessionConfirmer {
|
|
291
|
+
readonly sessionId: string;
|
|
292
|
+
private readonly client;
|
|
293
|
+
private readonly gate;
|
|
294
|
+
/** Tool-call event ids already answered (by this instance), so a `poll()`
|
|
295
|
+
* that overlaps a live `watch()` — or a re-delivered webhook — never
|
|
296
|
+
* double-sends a confirmation for the same id. */
|
|
297
|
+
private readonly answered;
|
|
298
|
+
constructor(client: ManagedAgentsClientLike, sessionId: string, opts?: ManagedAgentsWrapOptions);
|
|
299
|
+
private noteConfirmationEvent;
|
|
300
|
+
/** Answer one event if it needs an answer; returns the sent params, or
|
|
301
|
+
* `null` if nothing was sent (already answered, or
|
|
302
|
+
* {@link confirmationForEvent} returned `null` — see its doc). */
|
|
303
|
+
handleEvent(event: ManagedAgentsSessionEventLike): Promise<UserToolConfirmationParams | null>;
|
|
304
|
+
/**
|
|
305
|
+
* List recent events and answer every unanswered
|
|
306
|
+
* `agent.tool_use`/`agent.mcp_tool_use` pause found. Returns the sent
|
|
307
|
+
* confirmations, in event order.
|
|
308
|
+
*/
|
|
309
|
+
poll(opts?: {
|
|
310
|
+
limit?: number;
|
|
311
|
+
}): Promise<UserToolConfirmationParams[]>;
|
|
312
|
+
/**
|
|
313
|
+
* Answer the pause a `session.requires_action` webhook signalled.
|
|
314
|
+
*
|
|
315
|
+
* `unwrapped` is what `client.beta.webhooks.unwrap(rawBody, { headers })`
|
|
316
|
+
* returns (or its `.data`, or a plain object of the same shape). Anything
|
|
317
|
+
* other than a `session.requires_action` payload is a no-op (`[]`): this
|
|
318
|
+
* module only ever answers tool-confirmation pauses, so every other
|
|
319
|
+
* webhook event type is intentionally ignored here.
|
|
320
|
+
*
|
|
321
|
+
* The webhook payload carries only the session id — it does NOT carry the
|
|
322
|
+
* tool call itself — so this always falls through to a {@link poll}.
|
|
323
|
+
*/
|
|
324
|
+
handleWebhook(unwrapped: {
|
|
325
|
+
data?: {
|
|
326
|
+
type?: string;
|
|
327
|
+
id?: string;
|
|
328
|
+
};
|
|
329
|
+
type?: string;
|
|
330
|
+
id?: string;
|
|
331
|
+
}): Promise<UserToolConfirmationParams[]>;
|
|
332
|
+
/**
|
|
333
|
+
* Catch up on anything already pending, then follow the live event
|
|
334
|
+
* stream, yielding each confirmation as it is sent, reconnecting when the
|
|
335
|
+
* stream drops (TD-428).
|
|
336
|
+
*
|
|
337
|
+
* Modelled on the SDK's own `SessionToolRunner#streamLoop`: open the
|
|
338
|
+
* stream FIRST, then reconcile with `poll()` — an event emitted in the gap
|
|
339
|
+
* is buffered on the stream rather than lost, and `answered` dedups
|
|
340
|
+
* anything that shows up on both. On end or error the loop sleeps
|
|
341
|
+
* (backoff doubling from `backoffStartMs` to `backoffCapMs`, reset on any
|
|
342
|
+
* received event) and reopens. A fatal 4xx (anything 400–499 other than
|
|
343
|
+
* 408 and 429) rethrows: the session is gone or the key is wrong, and
|
|
344
|
+
* retrying would loop forever. `idleTimeoutMs` drops a stream that has
|
|
345
|
+
* gone silent and reopens it, which re-polls. Ends only on a terminal
|
|
346
|
+
* event, `signal` abort, or `maxReconnects` exhausted (unbounded by
|
|
347
|
+
* default, the SDK's own choice).
|
|
348
|
+
*/
|
|
349
|
+
watch(opts?: WatchOptions): AsyncGenerator<UserToolConfirmationParams>;
|
|
350
|
+
}
|
|
351
|
+
/** Structural slice of `BetaRunnableTool` — the shape
|
|
352
|
+
* `SessionToolRunner`/`EnvironmentWorker` dispatch custom tools against
|
|
353
|
+
* (`lib/tools/BetaRunnableTool.d.ts`). Note the method is `run`, not
|
|
354
|
+
* `execute` — the reason `wrapTools()`'s generic object branch cannot be
|
|
355
|
+
* used as-is here (see module doc). */
|
|
356
|
+
export interface ManagedAgentsRunnableToolLike {
|
|
357
|
+
name: string;
|
|
358
|
+
run: (args: Record<string, unknown>, context?: unknown) => unknown;
|
|
359
|
+
[key: string]: unknown;
|
|
360
|
+
}
|
|
361
|
+
/**
|
|
362
|
+
* Wrap one Managed Agents custom tool (`BetaRunnableTool` shape) so
|
|
363
|
+
* `Gate.guard()` runs before `run()` executes.
|
|
364
|
+
*
|
|
365
|
+
* Returns a NEW object (a shallow copy with `run` replaced); does not mutate
|
|
366
|
+
* the one passed in. On refusal the wrapped `run()` THROWS
|
|
367
|
+
* `IntuticGateRefusal` before the real implementation ever runs — the same
|
|
368
|
+
* throw-based contract `wrapTool()` uses. Already-wrapped tools pass through
|
|
369
|
+
* unchanged.
|
|
370
|
+
*/
|
|
371
|
+
export declare function wrapManagedAgentsCustomTool<T extends ManagedAgentsRunnableToolLike>(tool: T, opts?: ManagedAgentsWrapOptions): T;
|
|
372
|
+
/** Wrap a collection of Managed Agents custom tools in one call — see
|
|
373
|
+
* {@link wrapManagedAgentsCustomTool}. */
|
|
374
|
+
export declare function wrapManagedAgentsCustomTools<T extends ManagedAgentsRunnableToolLike>(tools: readonly T[], opts?: ManagedAgentsWrapOptions): T[];
|
|
375
|
+
//# sourceMappingURL=managedAgents.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"managedAgents.d.ts","sourceRoot":"","sources":["../src/managedAgents.ts"],"names":[],"mappings":"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"}
|