@withgateway/sdk 0.1.13 → 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.
- package/README.md +82 -4
- package/dist/cli.d.mts +1 -0
- package/dist/cli.d.ts +1 -0
- package/dist/cli.js +1303 -0
- package/dist/cli.js.map +1 -0
- package/dist/cli.mjs +1290 -0
- package/dist/cli.mjs.map +1 -0
- package/dist/index.d.mts +1 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +612 -4
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +593 -3
- package/dist/index.mjs.map +1 -1
- package/dist/tracing/index.js +27 -2
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +27 -2
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +377 -0
- package/dist/worlds/index.d.ts +377 -0
- package/dist/worlds/index.js +584 -0
- package/dist/worlds/index.js.map +1 -0
- package/dist/worlds/index.mjs +578 -0
- package/dist/worlds/index.mjs.map +1 -0
- package/package.json +27 -2
|
@@ -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 };
|