@withgateway/sdk 0.1.12 → 0.1.14

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.
@@ -0,0 +1,377 @@
1
+ /**
2
+ * LIVE WORLD SESSIONS from TypeScript: your agent, the platform's container.
3
+ *
4
+ * The other two ways of running a world each give up something. Pulling the
5
+ * bundle and executing it locally tests your agent against a COPY — your
6
+ * python, your sqlite, your machine's idea of the environment. Dispatching a
7
+ * hosted run gives you the real container but runs the platform's agent
8
+ * inside it, so your agent never touches the world.
9
+ *
10
+ * A session is both: the platform boots the task's container and holds it
11
+ * warm, and every `call()` here executes inside THAT container. Your agent
12
+ * stays where it is — this file is just the wire.
13
+ *
14
+ * const world = await openWorld("revenue-ops-sim@main");
15
+ * const session = await openSession(world.slug, "revops-mara-dedupe-contacts");
16
+ * await session.ready(); // wait for the container
17
+ * await session.call("crm_search", { entity: "deals" });
18
+ * const { reward, rewards } = await session.grade();
19
+ * await session.close({ keepWarm: true }); // hand it back to the pool
20
+ *
21
+ * Every call is a row on the platform before it is an effect in a container,
22
+ * so the episode is on the record — and the platform traces the session
23
+ * itself, which is why these sessions show up under Sessions without the
24
+ * caller instrumenting anything.
25
+ */
26
+ type WorldToolSpec = {
27
+ name: string;
28
+ /** The world's own signature, e.g. `crm_search(q=None, entity="deals")`. */
29
+ signature: string;
30
+ doc: string | null;
31
+ };
32
+ /** What a model needs to call a world: the schemas to advertise, and the
33
+ * implementations that run them in the container. */
34
+ type WorldToolkit = {
35
+ /** OpenAI-shaped tool definitions, derived from the world's signatures. */
36
+ schemas: {
37
+ type: "function";
38
+ function: {
39
+ name: string;
40
+ description: string;
41
+ parameters: Record<string, unknown>;
42
+ };
43
+ }[];
44
+ /** name -> implementation, each one a call into THIS session. */
45
+ impls: Record<string, (args: Record<string, unknown>) => Promise<unknown>>;
46
+ specs: WorldToolSpec[];
47
+ };
48
+ type WorldSessionState = {
49
+ sessionId: string;
50
+ state: string;
51
+ ready: boolean;
52
+ versionId: string;
53
+ contentHash: string;
54
+ taskName: string | null;
55
+ /** The task's objective — present when the session was opened (not on a
56
+ * bare status read), so a client never needs the bundle on disk. */
57
+ instruction?: string | null;
58
+ /** The tools this task serves. */
59
+ tools?: WorldToolSpec[];
60
+ };
61
+ type GradeResult = {
62
+ reward: number | null;
63
+ rewards: Record<string, number>;
64
+ raw: unknown;
65
+ };
66
+ /**
67
+ * Turn a world's Python signature into a JSON schema the model can call.
68
+ *
69
+ * `crm_update_deal(id, stage=None, owner=None, amount=None)` becomes an
70
+ * object with `id` required and the rest optional. Types are read from the
71
+ * DEFAULTS the world declares — a numeric default means a number, a boolean
72
+ * default a boolean — because that is the only type information a signature
73
+ * actually carries. Everything else is a string, which is what a tool CLI
74
+ * receives anyway.
75
+ */
76
+ declare function schemaFromSignature(spec: WorldToolSpec): {
77
+ type: "function";
78
+ function: {
79
+ name: string;
80
+ description: string;
81
+ parameters: Record<string, unknown>;
82
+ };
83
+ };
84
+ declare class WorldSessionTimeout extends Error {
85
+ }
86
+ declare class WorldSessionCallError extends Error {
87
+ }
88
+ declare class WorldSession {
89
+ readonly sessionId: string;
90
+ private state;
91
+ private readonly options;
92
+ constructor(sessionId: string, state: WorldSessionState, options: WorldsClientOptions);
93
+ get task(): string | null;
94
+ /** What this task asks for — the bundle's own instruction.md. */
95
+ get instruction(): string | null;
96
+ get versionId(): string;
97
+ /** The session's latest platform state (one request, no waiting). */
98
+ status(): Promise<WorldSessionState>;
99
+ /**
100
+ * Wait until the container is warm — meaning the process inside it has
101
+ * asked the platform for work, not merely that a job was accepted.
102
+ */
103
+ ready(opts?: {
104
+ timeoutMs?: number;
105
+ }): Promise<WorldSessionState>;
106
+ /** Enqueue one interaction and wait for the container's answer. */
107
+ private exchange;
108
+ /**
109
+ * Run one of the world's tools INSIDE the container. The arguments and the
110
+ * result are the world's own contract — this layer neither validates nor
111
+ * reshapes them, so a tool error reads exactly as it would in a hosted run.
112
+ */
113
+ call(tool: string, args?: Record<string, unknown>, opts?: {
114
+ timeoutMs?: number;
115
+ }): Promise<unknown>;
116
+ /**
117
+ * THE WORLD'S TOOLS, READY TO HAND TO A MODEL. Schemas come from the
118
+ * world's own signatures and implementations call into this session, so a
119
+ * caller never writes — and never has to re-sync — a tool map of their own:
120
+ *
121
+ * const { schemas, impls } = await session.toolkit();
122
+ * await runMyAgent(impls, schemas, session.instruction);
123
+ *
124
+ * A tool added to the world shows up here on the next run; a tool renamed
125
+ * in the world renames here too, instead of failing at call time against a
126
+ * hand-written map that still remembers the old name.
127
+ */
128
+ toolkit(): Promise<WorldToolkit>;
129
+ /** Run the task's grader against the container's END STATE. */
130
+ grade(opts?: {
131
+ timeoutMs?: number;
132
+ }): Promise<GradeResult>;
133
+ /**
134
+ * End the session. `keepWarm` hands the container back to the pool instead
135
+ * of tearing it down, so the next session for the same task starts warm —
136
+ * the pooled instance still obeys the fleet's idle TTL and pinning.
137
+ */
138
+ close(opts?: {
139
+ keepWarm?: boolean;
140
+ }): Promise<{
141
+ state: string;
142
+ }>;
143
+ }
144
+ /**
145
+ * Attach to a session that already exists — resuming after a crash, or
146
+ * driving a session someone else opened (a container started by hand on a
147
+ * self-hosted install, a session opened by CI and handed to a developer).
148
+ */
149
+ declare function attachSession(sessionId: string, options?: WorldsClientOptions): Promise<WorldSession>;
150
+ /**
151
+ * Open a live session against one task of a world. Returns as soon as the
152
+ * platform has accepted it — call `ready()` to wait for the container.
153
+ */
154
+ declare function openSession(slugOrRef: string, task: string, opts?: {
155
+ versionId?: string;
156
+ reuseWarm?: boolean;
157
+ options?: WorldsClientOptions;
158
+ }): Promise<WorldSession>;
159
+ type SessionRunResult = {
160
+ task: string;
161
+ sessionId: string;
162
+ reward: number | null;
163
+ rewards: Record<string, number>;
164
+ /** Set when the task threw instead of grading. */
165
+ error?: string;
166
+ };
167
+ type SessionRunReport = {
168
+ results: SessionRunResult[];
169
+ /** Mean reward over every task, counting failures as 0. */
170
+ mean: number;
171
+ /** True when `mean >= failUnder` (or no gate was set). */
172
+ passed: boolean;
173
+ };
174
+ /**
175
+ * RUN MANY TASKS IN PARALLEL, one warm container each.
176
+ *
177
+ * Parallelism against live worlds is the normal case — a suite is a dozen
178
+ * tasks and each needs its own container, because two agents sharing one
179
+ * world state would corrupt both episodes. Every caller was writing the same
180
+ * pool, the same per-task open/ready/toolkit/grade/close, and the same
181
+ * "don't let one failure kill the run" logic, so it belongs here:
182
+ *
183
+ * const report = await runSessions({
184
+ * world: "revenue-ops-sim@main",
185
+ * tasks, // default: every task in the world
186
+ * concurrency: 4,
187
+ * failUnder: 0.7,
188
+ * agent: async ({ toolkit, instruction }) =>
189
+ * myAgent(toolkit.impls, toolkit.schemas, instruction),
190
+ * });
191
+ *
192
+ * The handler gets a ready session with its toolkit already bound; grading,
193
+ * closing (warm) and aggregation are handled. A task that throws scores 0
194
+ * and records why — the tasks that passed keep their results.
195
+ */
196
+ declare function runSessions(opts: {
197
+ world: string;
198
+ tasks?: string[];
199
+ concurrency?: number;
200
+ failUnder?: number;
201
+ /** Pin every session to one version (default: the world's head). */
202
+ versionId?: string;
203
+ /** Hand the containers back warm for the next run (default: true). */
204
+ keepWarm?: boolean;
205
+ agent: (ctx: {
206
+ session: WorldSession;
207
+ toolkit: WorldToolkit;
208
+ instruction: string;
209
+ task: string;
210
+ }) => Promise<unknown>;
211
+ onResult?: (result: SessionRunResult) => void;
212
+ options?: WorldsClientOptions;
213
+ }): Promise<SessionRunReport>;
214
+
215
+ /**
216
+ * Worlds from TypeScript: identity, tasks, and HOSTED execution.
217
+ *
218
+ * The same three-level model as the Python SDK — WorldSet → Task — with one
219
+ * deliberate difference: a world's tools are Python modules, so TypeScript
220
+ * does not materialize task environments in-process. What a TS agent
221
+ * codebase needs is exactly what this module provides: resolve a world ref
222
+ * to its pinned version, read its task list, and dispatch HOSTED runs
223
+ * (parallelism included) that execute the world server-side and file graded,
224
+ * version-pinned rollouts. Local in-process execution stays a Python
225
+ * capability by design, not by omission.
226
+ */
227
+ type WorldsClientOptions = {
228
+ host?: string;
229
+ publicKey?: string;
230
+ secretKey?: string;
231
+ };
232
+ type ResolvedWorldVersion = {
233
+ versionId: string;
234
+ semanticVersion: string | null;
235
+ contentHash: string;
236
+ state?: string;
237
+ };
238
+ type WorldTaskInfo = {
239
+ name: string;
240
+ variant: string | null;
241
+ };
242
+ type DispatchedRun = {
243
+ model: string;
244
+ runId: string;
245
+ ok: boolean;
246
+ error?: string;
247
+ };
248
+ /** Authenticated JSON request against the platform API — the primitive the
249
+ * worlds helpers and the TS CLI share. */
250
+ declare function apiRequest<T>(options: WorldsClientOptions, method: "GET" | "POST" | "PUT" | "DELETE", path: string, body?: unknown): Promise<T>;
251
+ /** Set (or rotate) one environment secret — write-only: no API returns it. */
252
+ declare function setEnvSecret(slug: string, key: string, value: string, options?: WorldsClientOptions): Promise<{
253
+ key: string;
254
+ created: boolean;
255
+ }>;
256
+ /** Keys and rotation timestamps only — never values. */
257
+ declare function listEnvSecretKeys(slug: string, options?: WorldsClientOptions): Promise<{
258
+ key: string;
259
+ updatedAt: string;
260
+ }[]>;
261
+ declare function deleteEnvSecret(slug: string, key: string, options?: WorldsClientOptions): Promise<void>;
262
+ type RunConfigSummary = {
263
+ id: string;
264
+ name: string;
265
+ runType: string;
266
+ createdAt: string;
267
+ models: string[];
268
+ parallelism: number;
269
+ autoRunOnPush: boolean;
270
+ agent: string | null;
271
+ };
272
+ /** Run configs in the project. CI resolves by NAME and dispatches by id. */
273
+ declare function listRunConfigs(options?: WorldsClientOptions): Promise<RunConfigSummary[]>;
274
+ type RunReport = {
275
+ id: string;
276
+ status: string;
277
+ terminal: boolean;
278
+ score: number | null;
279
+ summary: string | null;
280
+ model: string | null;
281
+ versionLabel: string | null;
282
+ parallelism: number;
283
+ shardsCompleted: number | null;
284
+ evaluations: {
285
+ id: string;
286
+ status: string;
287
+ avgReward: number | null;
288
+ }[];
289
+ samples: {
290
+ task: string | null;
291
+ reward: number | null;
292
+ rewards: Record<string, unknown>;
293
+ sessionId: string | null;
294
+ }[];
295
+ };
296
+ /** The read half of dispatch: status, score, per-shard evaluations, and
297
+ * per-task rewards — everything a CI gate needs. */
298
+ declare function getRun(runId: string, options?: WorldsClientOptions): Promise<RunReport>;
299
+ /** Poll a run to terminal (default every 20s, up to `timeoutMinutes`). */
300
+ declare function waitForRun(runId: string, opts?: {
301
+ timeoutMinutes?: number;
302
+ intervalSeconds?: number;
303
+ onTick?: (run: RunReport) => void;
304
+ options?: WorldsClientOptions;
305
+ }): Promise<RunReport>;
306
+ type RunProvenance = {
307
+ branch?: string;
308
+ commit?: string;
309
+ repoUrl?: string;
310
+ actor?: {
311
+ id?: string;
312
+ name?: string;
313
+ imageUrl?: string;
314
+ kind?: string;
315
+ };
316
+ };
317
+ /**
318
+ * Where a dispatch comes from, DETECTED rather than configured: the CI
319
+ * checkout's branch/commit/actor under GitHub Actions, else the developer's
320
+ * own git checkout. A run nobody can trace to a branch is a score with no
321
+ * code attached, so every dispatch carries this unless overridden.
322
+ */
323
+ declare function detectProvenance(): RunProvenance;
324
+ /** One scenario of a world, as data. */
325
+ declare class WorldTask {
326
+ readonly world: WorldSet;
327
+ readonly name: string;
328
+ readonly variant: string | null;
329
+ constructor(world: WorldSet, name: string, variant: string | null);
330
+ }
331
+ /**
332
+ * THE world, from a TS process: pinned identity + its tasks + hosted runs.
333
+ *
334
+ * const world = await openWorld("google-drive-sim@main");
335
+ * console.log(world.version.semanticVersion, world.tasks.length);
336
+ * const runs = await world.dispatch(runConfigId);
337
+ */
338
+ declare class WorldSet {
339
+ readonly slugRef: string;
340
+ readonly slug: string;
341
+ readonly ref: string | null;
342
+ readonly version: ResolvedWorldVersion;
343
+ tasks: WorldTask[];
344
+ private readonly options;
345
+ constructor(slugRef: string, slug: string, ref: string | null, version: ResolvedWorldVersion, tasks: WorldTask[], options: WorldsClientOptions);
346
+ task(variant: string): WorldTask;
347
+ /**
348
+ * Open a LIVE session against one of this world's tasks: the platform boots
349
+ * (or reuses) a warm container, and your agent calls its tools through the
350
+ * platform. See worlds/session.ts.
351
+ */
352
+ open(task: string, opts?: {
353
+ reuseWarm?: boolean;
354
+ }): Promise<WorldSession>;
355
+ /**
356
+ * Start a HOSTED run of a run config against this world — the platform
357
+ * executes the (Python) world in parallel containers per the config's
358
+ * `parallelism` and files one graded run per model. Returns those runs.
359
+ */
360
+ dispatch(runConfigId: string, opts?: {
361
+ containerId?: string;
362
+ versionId?: string;
363
+ /** Override the auto-detected branch/commit/actor. */
364
+ provenance?: RunProvenance;
365
+ }): Promise<{
366
+ versionLabel: string;
367
+ runs: DispatchedRun[];
368
+ }>;
369
+ }
370
+ /**
371
+ * Resolve `slug` / `slug@branch|tag|semver|hash` to its pinned version and
372
+ * task list. The task list comes from the version's file manifest
373
+ * (`tasks/<name>/task.toml`), so it needs no bundle download.
374
+ */
375
+ declare function openWorld(slugRef: string, options?: WorldsClientOptions): Promise<WorldSet>;
376
+
377
+ export { type DispatchedRun, type GradeResult, type ResolvedWorldVersion, type RunConfigSummary, type RunProvenance, type RunReport, type SessionRunReport, type SessionRunResult, WorldSession, WorldSessionCallError, type WorldSessionState, WorldSessionTimeout, WorldSet, WorldTask, type WorldTaskInfo, type WorldToolSpec, type WorldToolkit, type WorldsClientOptions, apiRequest, attachSession, deleteEnvSecret, detectProvenance, getRun, listEnvSecretKeys, listRunConfigs, openSession, openWorld, runSessions, schemaFromSignature, setEnvSecret, waitForRun };