@withgateway/sdk 0.1.20 → 0.2.0
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 +141 -2
- package/dist/cli.js +8683 -1343
- package/dist/cli.js.map +1 -1
- package/dist/cli.mjs +8683 -1344
- package/dist/cli.mjs.map +1 -1
- package/dist/index.d.mts +1 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.js +979 -46
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +943 -38
- package/dist/index.mjs.map +1 -1
- package/dist/tracing/index.js +9 -2
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +9 -2
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +738 -28
- package/dist/worlds/index.d.ts +738 -28
- package/dist/worlds/index.js +940 -42
- package/dist/worlds/index.js.map +1 -1
- package/dist/worlds/index.mjs +934 -36
- package/dist/worlds/index.mjs.map +1 -1
- package/package.json +9 -2
- package/runtime/gatewaysdk/__init__.py +0 -0
- package/runtime/gatewaysdk/environment/__init__.py +108 -0
- package/runtime/gatewaysdk/environment/_bundle.py +281 -0
- package/runtime/gatewaysdk/environment/_harbor.py +276 -0
- package/runtime/gatewaysdk/environment/_materialize.py +97 -0
- package/runtime/gatewaysdk/environment/_tar.py +33 -0
- package/runtime/gatewaysdk/environment/_world.py +346 -0
- package/runtime/gatewaysdk/environment/core.py +527 -0
- package/runtime/gatewaysdk/environment/errors.py +58 -0
- package/runtime/gatewaysdk/environment/runtime.py +150 -0
- package/runtime/gatewaysdk/environment/schema/__init__.py +35 -0
- package/runtime/gatewaysdk/environment/schema/__main__.py +225 -0
- package/runtime/gatewaysdk/environment/schema/_slack_fidelity.py +116 -0
- package/runtime/gatewaysdk/environment/schema/_slack_scenario.py +183 -0
- package/runtime/gatewaysdk/environment/schema/api.py +1628 -0
- package/runtime/gatewaysdk/environment/schema/batch.py +755 -0
- package/runtime/gatewaysdk/environment/schema/compiler.py +615 -0
- package/runtime/gatewaysdk/environment/schema/conform.py +428 -0
- package/runtime/gatewaysdk/environment/schema/connector.py +777 -0
- package/runtime/gatewaysdk/environment/schema/connectors/apple-business-manager/handlers.py +17 -0
- package/runtime/gatewaysdk/environment/schema/connectors/apple-business-manager/parity.json +28 -0
- package/runtime/gatewaysdk/environment/schema/connectors/apple-business-manager/provenance.json +233 -0
- package/runtime/gatewaysdk/environment/schema/connectors/apple-business-manager/scope.toml +112 -0
- package/runtime/gatewaysdk/environment/schema/connectors/apple-business-manager/world.json +1380 -0
- package/runtime/gatewaysdk/environment/schema/connectors/base.json +28 -0
- package/runtime/gatewaysdk/environment/schema/connectors/custom/handlers.py +18 -0
- package/runtime/gatewaysdk/environment/schema/connectors/custom/world.json +123 -0
- package/runtime/gatewaysdk/environment/schema/connectors/github/handlers.py +81 -0
- package/runtime/gatewaysdk/environment/schema/connectors/github/parity.json +37 -0
- package/runtime/gatewaysdk/environment/schema/connectors/github/provenance.json +134 -0
- package/runtime/gatewaysdk/environment/schema/connectors/github/scope.toml +158 -0
- package/runtime/gatewaysdk/environment/schema/connectors/github/world.json +5869 -0
- package/runtime/gatewaysdk/environment/schema/connectors/google-calendar/handlers.py +23 -0
- package/runtime/gatewaysdk/environment/schema/connectors/google-calendar/world.json +209 -0
- package/runtime/gatewaysdk/environment/schema/connectors/google-drive/handlers.py +18 -0
- package/runtime/gatewaysdk/environment/schema/connectors/google-drive/world.json +286 -0
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/handlers.py +34 -0
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/parity.json +49 -0
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/provenance.json +181 -0
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/scope.toml +128 -0
- package/runtime/gatewaysdk/environment/schema/connectors/jamf/world.json +2218 -0
- package/runtime/gatewaysdk/environment/schema/connectors/jira/handlers.py +28 -0
- package/runtime/gatewaysdk/environment/schema/connectors/jira/world.json +389 -0
- package/runtime/gatewaysdk/environment/schema/connectors/kandji/handlers.py +38 -0
- package/runtime/gatewaysdk/environment/schema/connectors/kandji/parity.json +29 -0
- package/runtime/gatewaysdk/environment/schema/connectors/kandji/provenance.json +152 -0
- package/runtime/gatewaysdk/environment/schema/connectors/kandji/scope.toml +120 -0
- package/runtime/gatewaysdk/environment/schema/connectors/kandji/world.json +765 -0
- package/runtime/gatewaysdk/environment/schema/connectors/linear/handlers.py +20 -0
- package/runtime/gatewaysdk/environment/schema/connectors/linear/world.json +363 -0
- package/runtime/gatewaysdk/environment/schema/connectors/microsoft-teams/fidelity.json +45 -0
- package/runtime/gatewaysdk/environment/schema/connectors/microsoft-teams/handlers.py +1 -0
- package/runtime/gatewaysdk/environment/schema/connectors/microsoft-teams/provenance.json +851 -0
- package/runtime/gatewaysdk/environment/schema/connectors/microsoft-teams/scope.md +231 -0
- package/runtime/gatewaysdk/environment/schema/connectors/microsoft-teams/teams-types.json +1710 -0
- package/runtime/gatewaysdk/environment/schema/connectors/microsoft-teams/world.json +858 -0
- package/runtime/gatewaysdk/environment/schema/connectors/netsuite/handlers.py +32 -0
- package/runtime/gatewaysdk/environment/schema/connectors/netsuite/parity.json +50 -0
- package/runtime/gatewaysdk/environment/schema/connectors/netsuite/provenance.json +137 -0
- package/runtime/gatewaysdk/environment/schema/connectors/netsuite/scope.toml +78 -0
- package/runtime/gatewaysdk/environment/schema/connectors/netsuite/world.json +16243 -0
- package/runtime/gatewaysdk/environment/schema/connectors/salesforce/handlers.py +806 -0
- package/runtime/gatewaysdk/environment/schema/connectors/salesforce/parity.json +46 -0
- package/runtime/gatewaysdk/environment/schema/connectors/salesforce/provenance.json +143 -0
- package/runtime/gatewaysdk/environment/schema/connectors/salesforce/scope.toml +174 -0
- package/runtime/gatewaysdk/environment/schema/connectors/salesforce/world.json +4695 -0
- package/runtime/gatewaysdk/environment/schema/connectors/slack/MODEL.md +236 -0
- package/runtime/gatewaysdk/environment/schema/connectors/slack/capabilities.json +1039 -0
- package/runtime/gatewaysdk/environment/schema/connectors/slack/handlers.py +762 -0
- package/runtime/gatewaysdk/environment/schema/connectors/slack/parity.json +65 -0
- package/runtime/gatewaysdk/environment/schema/connectors/slack/provenance.json +294 -0
- package/runtime/gatewaysdk/environment/schema/connectors/slack/scope.toml +44 -0
- package/runtime/gatewaysdk/environment/schema/connectors/slack/world.json +4993 -0
- package/runtime/gatewaysdk/environment/schema/connectors/workday/handlers.py +75 -0
- package/runtime/gatewaysdk/environment/schema/connectors/workday/parity.json +36 -0
- package/runtime/gatewaysdk/environment/schema/connectors/workday/provenance.json +179 -0
- package/runtime/gatewaysdk/environment/schema/connectors/workday/scope.toml +180 -0
- package/runtime/gatewaysdk/environment/schema/connectors/workday/world.json +806 -0
- package/runtime/gatewaysdk/environment/schema/data.py +593 -0
- package/runtime/gatewaysdk/environment/schema/extract.py +263 -0
- package/runtime/gatewaysdk/environment/schema/host.py +2407 -0
- package/runtime/gatewaysdk/environment/schema/host_surfaces.py +275 -0
- package/runtime/gatewaysdk/environment/schema/platform.py +1272 -0
- package/runtime/gatewaysdk/environment/schema/scaffold.py +250 -0
- package/runtime/gatewaysdk/environment/schema/skill.py +118 -0
- package/runtime/gatewaysdk/environment/schema/skills/agents/connector-template-author.md +202 -0
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/CONNECTORS.md +331 -0
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/CONVENTIONS.md +100 -0
- package/runtime/gatewaysdk/environment/schema/skills/connector-schema-authoring/SKILL.md +313 -0
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/ROWS.md +223 -0
- package/runtime/gatewaysdk/environment/schema/skills/world-data-ingestion/SKILL.md +293 -0
- package/runtime/gatewaysdk/environment/schema/skills/worlds-getting-started/SKILL.md +390 -0
- package/runtime/gatewaysdk/environment/schema/slack.py +757 -0
- package/runtime/gatewaysdk/environment/schema/snapshot.py +479 -0
- package/runtime/gatewaysdk/environment/schema/store.py +904 -0
- package/runtime/gatewaysdk/environment/schema/tasks.py +525 -0
- package/runtime/gatewaysdk/environment/schema/tools_world.py +322 -0
- package/runtime/gatewaysdk/environment/schema/validation.py +577 -0
- package/runtime/gatewaysdk/environment/schema/worker.py +78 -0
- package/runtime/gatewaysdk/environment/schema/workers.py +500 -0
- package/runtime/gatewaysdk/environment/schema/world_tests.py +336 -0
- package/skills/agents/connector-template-author.md +202 -0
- package/skills/connector-schema-authoring/CONNECTORS.md +331 -0
- package/skills/connector-schema-authoring/CONVENTIONS.md +100 -0
- package/skills/connector-schema-authoring/SKILL.md +313 -0
- package/skills/world-data-ingestion/ROWS.md +223 -0
- package/skills/world-data-ingestion/SKILL.md +293 -0
- package/skills/worlds-getting-started/SKILL.md +390 -0
package/dist/worlds/index.d.mts
CHANGED
|
@@ -1,3 +1,115 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* STORED WORLD TASKS: a task spec kept by the project, outside any bundle.
|
|
3
|
+
*
|
|
4
|
+
* An inline task (`openSession(world, { task: { instruction, … } })`) belongs
|
|
5
|
+
* to one session. A stored task is the same spec as a named, versioned
|
|
6
|
+
* project resource: create it once, open as many sessions on it as you like
|
|
7
|
+
* with `{ task: { id } }`, and every grade attributes back to the task and
|
|
8
|
+
* its version. Updating the spec never rewrites history — it appends a
|
|
9
|
+
* version, and a session opened on `{ id, version: 2 }` keeps running v2
|
|
10
|
+
* after v3 exists.
|
|
11
|
+
*
|
|
12
|
+
* const task = await createTask({
|
|
13
|
+
* name: "refund-late-invoice",
|
|
14
|
+
* world: "acme-billing",
|
|
15
|
+
* spec: { instruction: "…", seed: {…}, grader: {…} },
|
|
16
|
+
* });
|
|
17
|
+
* const session = await openSession("acme-billing", { task: { id: task.id } });
|
|
18
|
+
*
|
|
19
|
+
* Tasks are project-scoped: another project's task id is not found (404),
|
|
20
|
+
* never forbidden. `world` pins a task to one world's slug (validated against
|
|
21
|
+
* that world's contract); null leaves it usable with any world.
|
|
22
|
+
*/
|
|
23
|
+
type WorldTaskSummary = {
|
|
24
|
+
id: string;
|
|
25
|
+
name: string;
|
|
26
|
+
world: string | null;
|
|
27
|
+
version: number;
|
|
28
|
+
hash: string;
|
|
29
|
+
spec: WorldTaskSpec;
|
|
30
|
+
createdAt: string;
|
|
31
|
+
updatedAt: string;
|
|
32
|
+
createdBy: string;
|
|
33
|
+
updatedBy: string;
|
|
34
|
+
};
|
|
35
|
+
type WorldTaskVersionSummary = {
|
|
36
|
+
version: number;
|
|
37
|
+
hash: string;
|
|
38
|
+
createdAt: string;
|
|
39
|
+
createdBy: string;
|
|
40
|
+
message: string | null;
|
|
41
|
+
};
|
|
42
|
+
type WorldTaskDetail = WorldTaskSummary & {
|
|
43
|
+
versions: WorldTaskVersionSummary[];
|
|
44
|
+
};
|
|
45
|
+
type WorldTaskPage = {
|
|
46
|
+
tasks: WorldTaskSummary[];
|
|
47
|
+
meta: {
|
|
48
|
+
page: number;
|
|
49
|
+
limit: number;
|
|
50
|
+
totalItems: number;
|
|
51
|
+
totalPages: number;
|
|
52
|
+
};
|
|
53
|
+
};
|
|
54
|
+
type WorldTaskValidation = {
|
|
55
|
+
taskId: string;
|
|
56
|
+
version: number;
|
|
57
|
+
/** The world version the task was checked against. */
|
|
58
|
+
versionId: string;
|
|
59
|
+
ok: boolean;
|
|
60
|
+
/** `entities` when the world's contract was read and every seed and check
|
|
61
|
+
* entity was matched against it; `none` when the version has no contract
|
|
62
|
+
* to check (a mock-tools world), in which case `ok` says only that the
|
|
63
|
+
* version exists and is READY. */
|
|
64
|
+
checked: "entities" | "none";
|
|
65
|
+
problems: string[];
|
|
66
|
+
entities: string[] | null;
|
|
67
|
+
};
|
|
68
|
+
/** Store a task. `name` defaults to `spec.name`; one of the two is needed. */
|
|
69
|
+
declare function createTask(input: {
|
|
70
|
+
spec: WorldTaskSpec;
|
|
71
|
+
name?: string;
|
|
72
|
+
world?: string | null;
|
|
73
|
+
message?: string;
|
|
74
|
+
}, options?: WorldsClientOptions): Promise<WorldTaskSummary>;
|
|
75
|
+
/** Change a task. A new `spec` becomes the next version (the old ones stay
|
|
76
|
+
* readable and openable); `name` and `world` change in place. */
|
|
77
|
+
declare function updateTask(taskId: string, input: {
|
|
78
|
+
spec?: WorldTaskSpec;
|
|
79
|
+
name?: string;
|
|
80
|
+
world?: string | null;
|
|
81
|
+
message?: string;
|
|
82
|
+
}, options?: WorldsClientOptions): Promise<WorldTaskSummary>;
|
|
83
|
+
/** The project's tasks, newest change first. `world` keeps only tasks
|
|
84
|
+
* pinned to that slug; `metadata` keeps tasks whose spec metadata carries
|
|
85
|
+
* every given key/value (`{ externalUserId: "u_42" }`). */
|
|
86
|
+
declare function listTasks(filter?: {
|
|
87
|
+
world?: string;
|
|
88
|
+
metadata?: Record<string, string>;
|
|
89
|
+
page?: number;
|
|
90
|
+
limit?: number;
|
|
91
|
+
}, options?: WorldsClientOptions): Promise<WorldTaskPage>;
|
|
92
|
+
/** One task with its version history; `version` reads that version's spec
|
|
93
|
+
* instead of the current one. */
|
|
94
|
+
declare function getTask(taskId: string, opts?: {
|
|
95
|
+
version?: number;
|
|
96
|
+
}, options?: WorldsClientOptions): Promise<WorldTaskDetail>;
|
|
97
|
+
/** Remove a task and every version. Sessions already opened on it keep
|
|
98
|
+
* their copy of the spec. */
|
|
99
|
+
declare function deleteTask(taskId: string, options?: WorldsClientOptions): Promise<{
|
|
100
|
+
id: string;
|
|
101
|
+
name: string;
|
|
102
|
+
}>;
|
|
103
|
+
/** Check a task against a world version without opening a session: every
|
|
104
|
+
* seed entity and every check's entity must exist in the world's contract.
|
|
105
|
+
* `slug` checks against that world's head, `versionId` against an exact
|
|
106
|
+
* version, neither against the task's own `world` pin. */
|
|
107
|
+
declare function validateTask(taskId: string, target?: {
|
|
108
|
+
version?: number;
|
|
109
|
+
slug?: string;
|
|
110
|
+
versionId?: string;
|
|
111
|
+
}, options?: WorldsClientOptions): Promise<WorldTaskValidation>;
|
|
112
|
+
|
|
1
113
|
/**
|
|
2
114
|
* LIVE WORLD SESSIONS from TypeScript: your agent, the platform's container.
|
|
3
115
|
*
|
|
@@ -12,12 +124,27 @@
|
|
|
12
124
|
* stays where it is — this file is just the wire.
|
|
13
125
|
*
|
|
14
126
|
* const world = await openWorld("revenue-ops-sim@main");
|
|
15
|
-
* const session = await openSession(world.slug, "revops-mara-dedupe-contacts");
|
|
127
|
+
* const session = await openSession(world.slug, { task: "revops-mara-dedupe-contacts" });
|
|
16
128
|
* await session.ready(); // wait for the container
|
|
17
129
|
* await session.call("crm_search", { entity: "deals" });
|
|
18
130
|
* const { reward, rewards } = await session.grade();
|
|
19
131
|
* await session.close({ keepWarm: true }); // hand it back to the pool
|
|
20
132
|
*
|
|
133
|
+
* The task can also be YOURS rather than the bundle's — an instruction, the
|
|
134
|
+
* rows the session starts with and how it is graded, for one end user:
|
|
135
|
+
*
|
|
136
|
+
* const session = await openSession("acme-billing@main", {
|
|
137
|
+
* task: {
|
|
138
|
+
* instruction: "Mark invoice INV-7 as paid.",
|
|
139
|
+
* seed: { rows: { invoices: [{ id: "INV-7", status: "open" }] } },
|
|
140
|
+
* grader: { kind: "assertions", checks: [
|
|
141
|
+
* { entity: "invoices", where: { id: "INV-7", status: "paid" } },
|
|
142
|
+
* ] },
|
|
143
|
+
* metadata: { externalUserId: "u_42" },
|
|
144
|
+
* },
|
|
145
|
+
* surfaces: ["api"],
|
|
146
|
+
* });
|
|
147
|
+
*
|
|
21
148
|
* Every call is a row on the platform before it is an effect in a container,
|
|
22
149
|
* so the episode is on the record — and the platform traces the session
|
|
23
150
|
* itself, which is why these sessions show up under Sessions without the
|
|
@@ -28,6 +155,7 @@ type WorldToolSpec = {
|
|
|
28
155
|
/** The world's own signature, e.g. `crm_search(q=None, entity="deals")`. */
|
|
29
156
|
signature: string;
|
|
30
157
|
doc: string | null;
|
|
158
|
+
inputSchema?: Record<string, unknown>;
|
|
31
159
|
};
|
|
32
160
|
/** What a model needs to call a world: the schemas to advertise, and the
|
|
33
161
|
* implementations that run them in the container. */
|
|
@@ -45,6 +173,132 @@ type WorldToolkit = {
|
|
|
45
173
|
impls: Record<string, (args: Record<string, unknown>) => Promise<unknown>>;
|
|
46
174
|
specs: WorldToolSpec[];
|
|
47
175
|
};
|
|
176
|
+
/** A JSON scalar: what `where` filters and field predicates compare against. */
|
|
177
|
+
type WorldTaskScalar = string | number | boolean | null;
|
|
178
|
+
/** The rows a task starts the session with — the `seed()` contract, applied
|
|
179
|
+
* by the host right after it clones the version's snapshot. `append`
|
|
180
|
+
* (default) upserts by primary key onto the base data; `replace` makes the
|
|
181
|
+
* named entities hold exactly these rows. */
|
|
182
|
+
type WorldTaskSeed = {
|
|
183
|
+
mode?: "append" | "replace";
|
|
184
|
+
rows: Record<string, Record<string, unknown>[]>;
|
|
185
|
+
};
|
|
186
|
+
type WorldTaskFieldOp = "eq" | "neq" | "in" | "gt" | "gte" | "lt" | "lte" | "contains";
|
|
187
|
+
/**
|
|
188
|
+
* One declarative check over the session's final rows. `where` selects rows
|
|
189
|
+
* of `entity` by equality (dotted paths reach into nested objects); the
|
|
190
|
+
* assertion says what must hold of the selection:
|
|
191
|
+
*
|
|
192
|
+
* exists (default) / absent at least one row / none
|
|
193
|
+
* count `count` bound on how many
|
|
194
|
+
* all / any `field op value` on every / some selected row
|
|
195
|
+
*
|
|
196
|
+
* A check's `id` names its entry in `rewards`; the task's reward is the
|
|
197
|
+
* weighted share of checks that passed.
|
|
198
|
+
*/
|
|
199
|
+
type WorldTaskCheck = {
|
|
200
|
+
id?: string;
|
|
201
|
+
weight?: number;
|
|
202
|
+
entity: string;
|
|
203
|
+
where?: Record<string, WorldTaskScalar>;
|
|
204
|
+
assert?: "exists" | "absent" | "count" | "all" | "any";
|
|
205
|
+
count?: {
|
|
206
|
+
eq?: number;
|
|
207
|
+
gte?: number;
|
|
208
|
+
lte?: number;
|
|
209
|
+
};
|
|
210
|
+
field?: string;
|
|
211
|
+
op?: WorldTaskFieldOp;
|
|
212
|
+
value?: WorldTaskScalar | WorldTaskScalar[];
|
|
213
|
+
};
|
|
214
|
+
/** One thing a rubric judge scores in [0, 1]; `id` names its entry in
|
|
215
|
+
* `rewards`, `weight` (default 1) its share of the task's reward. */
|
|
216
|
+
type WorldTaskRubricCriterion = {
|
|
217
|
+
id: string;
|
|
218
|
+
description: string;
|
|
219
|
+
weight?: number;
|
|
220
|
+
};
|
|
221
|
+
/** A rubric is prose: what a good outcome looks like. The platform (never the
|
|
222
|
+
* host) has a model read the session's final state and its call log against
|
|
223
|
+
* it; the project's default evaluation model judges unless `model` pins one.
|
|
224
|
+
* `grade()` then resolves asynchronously — `pending: true` first, the reward
|
|
225
|
+
* once the judge has answered. */
|
|
226
|
+
type WorldTaskRubricGrader = {
|
|
227
|
+
kind: "rubric";
|
|
228
|
+
rubric: string;
|
|
229
|
+
criteria?: WorldTaskRubricCriterion[];
|
|
230
|
+
model?: {
|
|
231
|
+
provider: string;
|
|
232
|
+
model: string;
|
|
233
|
+
};
|
|
234
|
+
};
|
|
235
|
+
/** How a task is graded: checks the host evaluates in-process, a `verify.py`
|
|
236
|
+
* body (state JSON on stdin, last stdout line `{reward, ...}`) run through the
|
|
237
|
+
* host's confined verifier, or a rubric judged by a model on the platform. */
|
|
238
|
+
type WorldTaskGrader = {
|
|
239
|
+
kind: "assertions";
|
|
240
|
+
checks: WorldTaskCheck[];
|
|
241
|
+
} | {
|
|
242
|
+
kind: "python";
|
|
243
|
+
source: string;
|
|
244
|
+
timeoutSeconds?: number;
|
|
245
|
+
} | WorldTaskRubricGrader;
|
|
246
|
+
/** A task supplied at open, for one session, instead of a bundled scenario.
|
|
247
|
+
* `instruction` is what the agent is told; without `seed` the session starts
|
|
248
|
+
* on the version's base data, without `grader` `grade()` answers
|
|
249
|
+
* `reward: null`; `tools` is the allow-list of the version's tools the agent
|
|
250
|
+
* may call in this session (unset: all of them; a call outside it is refused
|
|
251
|
+
* and logged); `metadata` is yours (an end-user id, a ticket) and is echoed
|
|
252
|
+
* on the session, never read. Limits: shared/domain/worldTasks.ts. */
|
|
253
|
+
type WorldTaskSpec = {
|
|
254
|
+
name?: string;
|
|
255
|
+
instruction: string;
|
|
256
|
+
seed?: WorldTaskSeed;
|
|
257
|
+
grader?: WorldTaskGrader;
|
|
258
|
+
tools?: string[];
|
|
259
|
+
metadata?: Record<string, unknown>;
|
|
260
|
+
};
|
|
261
|
+
/** A stored task of the project (see worlds/tasks.ts), opened by id; the
|
|
262
|
+
* session runs a copy of one version's spec — the current one by default. */
|
|
263
|
+
type WorldTaskIdRef = {
|
|
264
|
+
id: string;
|
|
265
|
+
version?: number;
|
|
266
|
+
};
|
|
267
|
+
/** What `openSession` takes as the task: a bundled scenario's name, a
|
|
268
|
+
* stored task's `{ id, version? }`, or an inline spec. */
|
|
269
|
+
type WorldTaskRef = string | WorldTaskIdRef | WorldTaskSpec;
|
|
270
|
+
/** What a session's task is, on every session response. `hash` is the
|
|
271
|
+
* content hash of the spec (inline or stored) — what warm reuse matches on;
|
|
272
|
+
* `id`/`version` name the stored task the session was opened on. */
|
|
273
|
+
type WorldSessionTask = {
|
|
274
|
+
source: "bundled" | "inline" | "stored";
|
|
275
|
+
name: string | null;
|
|
276
|
+
hash: string | null;
|
|
277
|
+
id?: string | null;
|
|
278
|
+
version?: number | null;
|
|
279
|
+
metadata: Record<string, unknown>;
|
|
280
|
+
};
|
|
281
|
+
declare const isTaskIdRef: (task: WorldTaskRef) => task is WorldTaskIdRef;
|
|
282
|
+
declare const isTaskSpec: (task: WorldTaskRef) => task is WorldTaskSpec;
|
|
283
|
+
/** The label a task goes by in results: its name, `inline:<hash>` for an
|
|
284
|
+
* unnamed inline task once the platform has hashed it, or the stored task's
|
|
285
|
+
* name (its id until the platform has answered). */
|
|
286
|
+
declare const taskLabel: (task: WorldTaskRef, info?: WorldSessionTask | null) => string;
|
|
287
|
+
type SeedResult = {
|
|
288
|
+
seeded: number;
|
|
289
|
+
mode: "append" | "replace";
|
|
290
|
+
entity_counts: Record<string, number>;
|
|
291
|
+
};
|
|
292
|
+
/** One row of the session's call log. */
|
|
293
|
+
type WorldSessionCall = {
|
|
294
|
+
seq: number;
|
|
295
|
+
kind: string;
|
|
296
|
+
tool: string | null;
|
|
297
|
+
args: unknown;
|
|
298
|
+
result: unknown;
|
|
299
|
+
error: string | null;
|
|
300
|
+
completedAt: string | null;
|
|
301
|
+
};
|
|
48
302
|
type WorldSessionState = {
|
|
49
303
|
sessionId: string;
|
|
50
304
|
state: string;
|
|
@@ -52,11 +306,16 @@ type WorldSessionState = {
|
|
|
52
306
|
versionId: string;
|
|
53
307
|
contentHash: string;
|
|
54
308
|
taskName: string | null;
|
|
309
|
+
/** Where the task came from and what it is; absent on platforms that
|
|
310
|
+
* predate session tasks, in which case it is derived from `taskName`. */
|
|
311
|
+
task?: WorldSessionTask;
|
|
55
312
|
/** The task's objective — present when the session was opened (not on a
|
|
56
313
|
* bare status read), so a client never needs the bundle on disk. */
|
|
57
314
|
instruction?: string | null;
|
|
58
315
|
/** The tools this task serves. */
|
|
59
316
|
tools?: WorldToolSpec[];
|
|
317
|
+
/** Where the session answers besides `tools` — see worlds/browser.ts. */
|
|
318
|
+
surfaces?: SessionSurfaces;
|
|
60
319
|
};
|
|
61
320
|
type GradeResult = {
|
|
62
321
|
reward: number | null;
|
|
@@ -87,13 +346,55 @@ declare class WorldSessionCallError extends Error {
|
|
|
87
346
|
}
|
|
88
347
|
declare class WorldSession {
|
|
89
348
|
readonly sessionId: string;
|
|
90
|
-
private
|
|
349
|
+
private current;
|
|
91
350
|
private readonly options;
|
|
92
|
-
constructor(sessionId: string,
|
|
351
|
+
constructor(sessionId: string, current: WorldSessionState, options: WorldsClientOptions);
|
|
352
|
+
/** The task's display name: a bundled scenario's, or the inline spec's
|
|
353
|
+
* `name` (null when the spec was unnamed). Same as `taskName`. */
|
|
93
354
|
get task(): string | null;
|
|
94
|
-
/**
|
|
355
|
+
/** The task's display name: a bundled scenario's, or the inline spec's
|
|
356
|
+
* `name` (null when the spec was unnamed). */
|
|
357
|
+
get taskName(): string | null;
|
|
358
|
+
/** The task this session runs: bundled scenario, stored task or inline
|
|
359
|
+
* spec, its name, hash and the caller's metadata. */
|
|
360
|
+
get taskInfo(): WorldSessionTask;
|
|
361
|
+
/** What this task asks for — the bundle's instruction.md, or the inline
|
|
362
|
+
* spec's `instruction`. */
|
|
95
363
|
get instruction(): string | null;
|
|
96
364
|
get versionId(): string;
|
|
365
|
+
/** Whether the session answered ready as of the last state read (the open,
|
|
366
|
+
* a `status()`, or the poll inside `ready()`); no request is made. */
|
|
367
|
+
get isReady(): boolean;
|
|
368
|
+
/** `api` / `ui` / `browser` are present exactly when the world declares
|
|
369
|
+
* them AND the session was opened asking for them. */
|
|
370
|
+
surfaces(): Promise<SessionSurfaces>;
|
|
371
|
+
/** Base URL of the world's own HTTP API for this session. */
|
|
372
|
+
api(): Promise<string>;
|
|
373
|
+
/** Headers every request to `api()` needs. A World Host session gates its
|
|
374
|
+
* api surface on a per-session token; a pod or hosted twin answers with the
|
|
375
|
+
* world's own declared auth and this is `{}`. */
|
|
376
|
+
apiHeaders(): Promise<Record<string, string>>;
|
|
377
|
+
/** URL of the world's UI entry page for this session. */
|
|
378
|
+
ui(): Promise<string>;
|
|
379
|
+
/** A Playwright browser on this session's UI: `hosted` drives the one the
|
|
380
|
+
* platform runs next to the world, `local` launches one here, `auto`
|
|
381
|
+
* prefers hosted. Call `close()` when done.
|
|
382
|
+
*
|
|
383
|
+
* Every action is reported to the platform under `agentId` (default:
|
|
384
|
+
* `GATEWAY_AGENT_ID` or a fresh `agent-<hex>`) so the session page shows
|
|
385
|
+
* this agent's own timeline — several agents may share one session and
|
|
386
|
+
* one hosted browser. `record: false` opts out. */
|
|
387
|
+
browser(opts?: {
|
|
388
|
+
mode?: BrowserMode;
|
|
389
|
+
headless?: boolean;
|
|
390
|
+
playwright?: PlaywrightLike;
|
|
391
|
+
agentId?: string;
|
|
392
|
+
record?: boolean;
|
|
393
|
+
}): Promise<WorldBrowser>;
|
|
394
|
+
/** The reporter `browser()` uses; exposed for a page you drive yourself. */
|
|
395
|
+
browserRecorder(agentId?: string): BrowserActionRecorder;
|
|
396
|
+
/** Browser actions as model tools, in the same shape as `toolkit()`. */
|
|
397
|
+
computerUseTools(browser: WorldBrowser): WorldToolkit;
|
|
97
398
|
/** The session's latest platform state (one request, no waiting). */
|
|
98
399
|
status(): Promise<WorldSessionState>;
|
|
99
400
|
/**
|
|
@@ -126,10 +427,57 @@ declare class WorldSession {
|
|
|
126
427
|
* hand-written map that still remembers the old name.
|
|
127
428
|
*/
|
|
128
429
|
toolkit(): Promise<WorldToolkit>;
|
|
129
|
-
/** Run the task's grader against the container's END STATE.
|
|
430
|
+
/** Run the task's grader against the container's END STATE. Graders answer
|
|
431
|
+
* in one of two shapes: the scalar with named rewards beside it
|
|
432
|
+
* (`{reward, check_a, check_b}`, a task's own `grade.py`), or the named
|
|
433
|
+
* rewards nested under `rewards` (the api, mock-tools and World Host
|
|
434
|
+
* runners). Both land in `rewards`.
|
|
435
|
+
*
|
|
436
|
+
* A rubric grade is finalized by the platform's judge, not the container:
|
|
437
|
+
* the platform answers the enqueue with `pending: true`, and this waits on
|
|
438
|
+
* the judge's budget (15 min) instead of a call's. `timeoutMs` overrides
|
|
439
|
+
* either. */
|
|
130
440
|
grade(opts?: {
|
|
131
441
|
timeoutMs?: number;
|
|
132
442
|
}): Promise<GradeResult>;
|
|
443
|
+
/**
|
|
444
|
+
* Put rows into the LIVE world through its contract, in one batch:
|
|
445
|
+
* `append` (default) upserts by primary key, `replace` makes the named
|
|
446
|
+
* entities hold exactly these rows. Atomic — a refused row leaves the
|
|
447
|
+
* session unchanged and the error names the entity, row and field.
|
|
448
|
+
*/
|
|
449
|
+
seed(rows: Record<string, Record<string, unknown>[]>, opts?: {
|
|
450
|
+
mode?: "append" | "replace";
|
|
451
|
+
timeoutMs?: number;
|
|
452
|
+
}): Promise<SeedResult>;
|
|
453
|
+
/** Every entity's rows as the world holds them now — the same dump a
|
|
454
|
+
* grader reads. The shape is the world runtime's: a schema world answers
|
|
455
|
+
* `{<entity>: {<key>: row}, snapshot}`, a mock-tools world
|
|
456
|
+
* `{entities: {<entity>: [row]}}`. */
|
|
457
|
+
state(opts?: {
|
|
458
|
+
timeoutMs?: number;
|
|
459
|
+
}): Promise<unknown>;
|
|
460
|
+
/** Back to the opening state: the version's data plus the bundled
|
|
461
|
+
* scenario's or the inline task's seed. Rows written since are gone; the
|
|
462
|
+
* call log stays. */
|
|
463
|
+
reset(opts?: {
|
|
464
|
+
timeoutMs?: number;
|
|
465
|
+
}): Promise<void>;
|
|
466
|
+
/** The session's call log, oldest first: every tool call, seed, reset,
|
|
467
|
+
* grade with its result — the record of the episode. */
|
|
468
|
+
export(): Promise<WorldSessionCall[]>;
|
|
469
|
+
/**
|
|
470
|
+
* Promote this session's inline task into a stored task of the project
|
|
471
|
+
* (version 1, pinned to the session's world unless `world` says otherwise),
|
|
472
|
+
* so a task written for one end user can be reused and its grades
|
|
473
|
+
* compared. The session then records the new task's id. A session on a
|
|
474
|
+
* bundled task has nothing to save; one on a stored task is already saved.
|
|
475
|
+
*/
|
|
476
|
+
saveTask(opts?: {
|
|
477
|
+
name?: string;
|
|
478
|
+
world?: string | null;
|
|
479
|
+
message?: string;
|
|
480
|
+
}): Promise<WorldTaskSummary>;
|
|
133
481
|
/**
|
|
134
482
|
* End the session. `keepWarm` hands the container back to the pool instead
|
|
135
483
|
* of tearing it down, so the next session for the same task starts warm —
|
|
@@ -147,16 +495,29 @@ declare class WorldSession {
|
|
|
147
495
|
* self-hosted install, a session opened by CI and handed to a developer).
|
|
148
496
|
*/
|
|
149
497
|
declare function attachSession(sessionId: string, options?: WorldsClientOptions): Promise<WorldSession>;
|
|
498
|
+
type OpenSessionOptions = {
|
|
499
|
+
versionId?: string;
|
|
500
|
+
reuseWarm?: boolean;
|
|
501
|
+
/** More than `tools`: `["api"]`, `["ui"]`, `["browser"]`. The platform
|
|
502
|
+
* refuses (HTTP 400) rather than quietly serving less than asked. */
|
|
503
|
+
surfaces?: WorldSurfaceKind[];
|
|
504
|
+
options?: WorldsClientOptions;
|
|
505
|
+
};
|
|
150
506
|
/**
|
|
151
507
|
* Open a live session against one task of a world. Returns as soon as the
|
|
152
508
|
* platform has accepted it — call `ready()` to wait for the container.
|
|
509
|
+
*
|
|
510
|
+
* `task` is a bundled scenario's name, a stored task's `{ id, version? }`
|
|
511
|
+
* or an inline `WorldTaskSpec` (the latter two need a host engine world — the
|
|
512
|
+
* platform answers 400 for a pod world). The older positional form
|
|
513
|
+
* `openSession(slug, "task-name", opts)` still works.
|
|
153
514
|
*/
|
|
154
|
-
declare function openSession(slugOrRef: string, task:
|
|
155
|
-
|
|
156
|
-
reuseWarm?: boolean;
|
|
157
|
-
options?: WorldsClientOptions;
|
|
515
|
+
declare function openSession(slugOrRef: string, task: OpenSessionOptions & {
|
|
516
|
+
task: WorldTaskRef;
|
|
158
517
|
}): Promise<WorldSession>;
|
|
518
|
+
declare function openSession(slugOrRef: string, task: WorldTaskRef, opts?: OpenSessionOptions): Promise<WorldSession>;
|
|
159
519
|
type SessionRunResult = {
|
|
520
|
+
/** The task's name, or `inline:<hash>` for an unnamed inline task. */
|
|
160
521
|
task: string;
|
|
161
522
|
sessionId: string;
|
|
162
523
|
reward: number | null;
|
|
@@ -195,7 +556,9 @@ type SessionRunReport = {
|
|
|
195
556
|
*/
|
|
196
557
|
declare function runSessions(opts: {
|
|
197
558
|
world: string;
|
|
198
|
-
|
|
559
|
+
/** Bundled task names, stored task refs and/or inline task specs
|
|
560
|
+
* (default: every bundled task in the world). */
|
|
561
|
+
tasks?: WorldTaskRef[];
|
|
199
562
|
concurrency?: number;
|
|
200
563
|
failUnder?: number;
|
|
201
564
|
/** Pin every session to one version (default: the world's head). */
|
|
@@ -206,12 +569,334 @@ declare function runSessions(opts: {
|
|
|
206
569
|
session: WorldSession;
|
|
207
570
|
toolkit: WorldToolkit;
|
|
208
571
|
instruction: string;
|
|
572
|
+
/** The task's label — see `SessionRunResult.task`. */
|
|
209
573
|
task: string;
|
|
574
|
+
/** The task as it was given: a bundled name, a stored ref or the
|
|
575
|
+
* inline spec. */
|
|
576
|
+
taskRef: WorldTaskRef;
|
|
210
577
|
}) => Promise<unknown>;
|
|
211
578
|
onResult?: (result: SessionRunResult) => void;
|
|
212
579
|
options?: WorldsClientOptions;
|
|
213
580
|
}): Promise<SessionRunReport>;
|
|
214
581
|
|
|
582
|
+
/**
|
|
583
|
+
* A BROWSER ON A WORLD'S UI — the computer-use half of a live session.
|
|
584
|
+
*
|
|
585
|
+
* A session answers on SURFACES. `tools` is always there (the world's own
|
|
586
|
+
* operations over the rendezvous). An api-type world may also answer on
|
|
587
|
+
* `api` (the service itself), `ui` (its dashboard, over the same state) and
|
|
588
|
+
* `browser` — a headless Chromium the platform runs NEXT TO that UI, which
|
|
589
|
+
* an agent drives through Playwright. This file is the TS client for the
|
|
590
|
+
* last two, call for call with `gatewaysdk/world_browser.py`.
|
|
591
|
+
*
|
|
592
|
+
* const s = await openSession("payments-like", "refund-dispute", {
|
|
593
|
+
* surfaces: ["ui", "browser"],
|
|
594
|
+
* });
|
|
595
|
+
* await s.ready();
|
|
596
|
+
* const b = await s.browser(); // hosted, next to the world
|
|
597
|
+
* await b.goto(); // the UI's entry page
|
|
598
|
+
* await b.click("text=Refund");
|
|
599
|
+
* const tools = computerUseToolkit(b); // the same actions as model tools
|
|
600
|
+
* await b.close();
|
|
601
|
+
*
|
|
602
|
+
* Playwright is an OPTIONAL peer: nothing here imports it until a browser is
|
|
603
|
+
* opened, so sessions that never touch a UI never load it.
|
|
604
|
+
*
|
|
605
|
+
* MODES. `hosted` connects to the session's own browser (a Playwright server
|
|
606
|
+
* the pod exposes over an authenticated websocket). `local` launches Chromium
|
|
607
|
+
* on this machine and points it at the UI — a laptop against a hosted twin,
|
|
608
|
+
* or a test. `auto` prefers hosted. Asking for a mode the session cannot
|
|
609
|
+
* serve throws `WorldSurfaceUnavailable`; there is no silent fallback to a
|
|
610
|
+
* browser other than the one the episode is judged on.
|
|
611
|
+
*
|
|
612
|
+
* OBSERVABILITY. Every action a `WorldBrowser` takes (goto, click, type,
|
|
613
|
+
* press, scroll, back) is reported to the platform as one event — what was
|
|
614
|
+
* done, whether it worked, where the page ended up, and a JPEG of the screen
|
|
615
|
+
* after — through a `BrowserActionRecorder`. Reporting is fire-and-forget
|
|
616
|
+
* and never fails the action; the platform renders it as the session's
|
|
617
|
+
* browser timeline. Text typed into secret-looking fields is redacted before
|
|
618
|
+
* it leaves the process.
|
|
619
|
+
*/
|
|
620
|
+
declare const SURFACE_KINDS: readonly ["tools", "api", "ui", "browser"];
|
|
621
|
+
type WorldSurfaceKind = (typeof SURFACE_KINDS)[number];
|
|
622
|
+
declare const DEFAULT_VIEWPORT: {
|
|
623
|
+
width: number;
|
|
624
|
+
height: number;
|
|
625
|
+
};
|
|
626
|
+
declare const EVENT_BATCH_SIZE = 10;
|
|
627
|
+
declare const EVENT_FLUSH_INTERVAL_MS = 1000;
|
|
628
|
+
declare const EVENT_MAX_RETRIES = 3;
|
|
629
|
+
/** The `surfaces` block of a session descriptor, as the platform sends it. */
|
|
630
|
+
type SessionSurfaces = {
|
|
631
|
+
tools: {
|
|
632
|
+
kind: "rendezvous";
|
|
633
|
+
};
|
|
634
|
+
api?: {
|
|
635
|
+
url: string;
|
|
636
|
+
/** Per-session credential of a World Host session: send it as
|
|
637
|
+
* `Authorization: Bearer <token>` (the header only; a token in the URL is
|
|
638
|
+
* refused). Absent when the world
|
|
639
|
+
* itself answers with its declared auth (a pod or a customer-hosted twin). */
|
|
640
|
+
token?: string;
|
|
641
|
+
};
|
|
642
|
+
ui?: {
|
|
643
|
+
url: string;
|
|
644
|
+
entry: string;
|
|
645
|
+
/** Same-origin prefix the UI proxies to the world API, e.g. `/__world-api`;
|
|
646
|
+
* null when the UI only reaches the API server-side. */
|
|
647
|
+
apiPath?: string | null;
|
|
648
|
+
/** Per-session credential of a World Host UI. A browser navigation cannot
|
|
649
|
+
* carry a header, so the first page load presents it once as `?token=`
|
|
650
|
+
* and the host answers with an HttpOnly cookie. Absent for pod UIs. */
|
|
651
|
+
token?: string;
|
|
652
|
+
};
|
|
653
|
+
browser?: {
|
|
654
|
+
wsUrl: string;
|
|
655
|
+
/** `cdp`: the platform's Chromium relay (any number of agents share one
|
|
656
|
+
* browser, each in its own context). `playwright`: a `run-server` endpoint. */
|
|
657
|
+
protocol: "cdp" | "playwright";
|
|
658
|
+
viewport: {
|
|
659
|
+
width: number;
|
|
660
|
+
height: number;
|
|
661
|
+
};
|
|
662
|
+
};
|
|
663
|
+
};
|
|
664
|
+
declare class WorldSurfaceUnavailable extends Error {
|
|
665
|
+
readonly surface: WorldSurfaceKind;
|
|
666
|
+
constructor(surface: WorldSurfaceKind, reason: string);
|
|
667
|
+
}
|
|
668
|
+
declare function surfaceKinds(s: SessionSurfaces): WorldSurfaceKind[];
|
|
669
|
+
/** The URL of `path` on a UI surface, carrying the session token when the
|
|
670
|
+
* surface has one. `path` may already have a query string; the token is
|
|
671
|
+
* appended to it. */
|
|
672
|
+
declare function uiUrl(ui: NonNullable<SessionSurfaces["ui"]>, path: string): string;
|
|
673
|
+
declare function uiEntryUrl(ui: NonNullable<SessionSurfaces["ui"]>): string;
|
|
674
|
+
/** `url` without its `token` query parameter: what may be logged or shown. */
|
|
675
|
+
declare function withoutUiToken(url: string): string;
|
|
676
|
+
/** The slice of a Playwright `Page` this module drives. */
|
|
677
|
+
type BrowserPage = {
|
|
678
|
+
url(): string;
|
|
679
|
+
goto(url: string, opts?: {
|
|
680
|
+
waitUntil?: "load";
|
|
681
|
+
}): Promise<unknown>;
|
|
682
|
+
click(selector: string): Promise<void>;
|
|
683
|
+
fill(selector: string, value: string): Promise<void>;
|
|
684
|
+
screenshot(opts?: {
|
|
685
|
+
type?: "png" | "jpeg";
|
|
686
|
+
quality?: number;
|
|
687
|
+
fullPage?: boolean;
|
|
688
|
+
}): Promise<Buffer>;
|
|
689
|
+
innerText(selector: string): Promise<string>;
|
|
690
|
+
content(): Promise<string>;
|
|
691
|
+
goBack(opts?: {
|
|
692
|
+
waitUntil?: "load";
|
|
693
|
+
}): Promise<unknown>;
|
|
694
|
+
waitForLoadState(state?: "load"): Promise<void>;
|
|
695
|
+
waitForTimeout(ms: number): Promise<void>;
|
|
696
|
+
on(event: "request" | "requestfinished" | "requestfailed", handler: (request: unknown) => void): unknown;
|
|
697
|
+
title(): Promise<string>;
|
|
698
|
+
keyboard: {
|
|
699
|
+
press(key: string): Promise<void>;
|
|
700
|
+
};
|
|
701
|
+
mouse: {
|
|
702
|
+
wheel(dx: number, dy: number): Promise<void>;
|
|
703
|
+
};
|
|
704
|
+
};
|
|
705
|
+
type BrowserMode = "auto" | "hosted" | "local";
|
|
706
|
+
/** One browser action as the platform ingests it
|
|
707
|
+
* (`POST /world-sessions/{id}/browser-events`). */
|
|
708
|
+
type BrowserActionEvent = {
|
|
709
|
+
agentId: string;
|
|
710
|
+
seq: number;
|
|
711
|
+
ts: string;
|
|
712
|
+
action: string;
|
|
713
|
+
args: Record<string, unknown>;
|
|
714
|
+
ok: boolean;
|
|
715
|
+
error: string | null;
|
|
716
|
+
durationMs: number;
|
|
717
|
+
url: string | null;
|
|
718
|
+
title: string | null;
|
|
719
|
+
mode: Exclude<BrowserMode, "auto">;
|
|
720
|
+
viewport: {
|
|
721
|
+
width: number;
|
|
722
|
+
height: number;
|
|
723
|
+
};
|
|
724
|
+
/** base64 JPEG of the screen after the action; null if it could not be taken. */
|
|
725
|
+
screenshot: string | null;
|
|
726
|
+
};
|
|
727
|
+
/** What of an action's arguments may leave the process. Selectors, paths
|
|
728
|
+
* and keys are what a reviewer needs; anything keyed like a credential, or
|
|
729
|
+
* typed into a field whose selector names one, or shaped like a known key,
|
|
730
|
+
* is replaced. Strings are capped, nested values dropped. */
|
|
731
|
+
declare function redactActionArgs(action: string, args: Record<string, unknown>): Record<string, unknown>;
|
|
732
|
+
/**
|
|
733
|
+
* Ships browser action events to the platform, off the action's hot path.
|
|
734
|
+
*
|
|
735
|
+
* `post` receives a batch of events (the request body's `events`). Events
|
|
736
|
+
* are numbered here, so ordering survives batching and retries — the
|
|
737
|
+
* platform dedups on `(agentId, seq)`. A batch that keeps failing is dropped
|
|
738
|
+
* with a warning: telemetry must never stall or fail the agent.
|
|
739
|
+
*
|
|
740
|
+
* Numbering is durable across recorders: `nextSeq()` hands out a position
|
|
741
|
+
* within this recorder, and the first send adds the base `resumeFrom`
|
|
742
|
+
* reports — the platform's next free seq for this agent — so an agent id
|
|
743
|
+
* reopened in a later process appends to its timeline instead of colliding
|
|
744
|
+
* with (and being deduplicated against) what it already recorded. The base
|
|
745
|
+
* is fixed once resolved, which keeps retries idempotent.
|
|
746
|
+
*/
|
|
747
|
+
declare class BrowserActionRecorder {
|
|
748
|
+
private readonly post;
|
|
749
|
+
readonly agentId: string;
|
|
750
|
+
private readonly opts;
|
|
751
|
+
private seq;
|
|
752
|
+
private base;
|
|
753
|
+
private queue;
|
|
754
|
+
private timer;
|
|
755
|
+
private inflight;
|
|
756
|
+
sent: number;
|
|
757
|
+
dropped: number;
|
|
758
|
+
constructor(post: (events: BrowserActionEvent[]) => Promise<void>, agentId: string, opts?: {
|
|
759
|
+
/** The platform's next free seq for `agentId`; 0 when not given. */
|
|
760
|
+
resumeFrom?: () => Promise<number>;
|
|
761
|
+
batchSize?: number;
|
|
762
|
+
flushIntervalMs?: number;
|
|
763
|
+
maxRetries?: number;
|
|
764
|
+
sleep?: (ms: number) => Promise<void>;
|
|
765
|
+
warn?: (message: string) => void;
|
|
766
|
+
});
|
|
767
|
+
/** This recorder's next position; the wire seq is `resumeFrom() + this`. */
|
|
768
|
+
nextSeq(): number;
|
|
769
|
+
private resolveBase;
|
|
770
|
+
record(event: BrowserActionEvent): void;
|
|
771
|
+
/** Resolve once everything recorded so far has been posted (or dropped). */
|
|
772
|
+
flush(): Promise<void>;
|
|
773
|
+
close(): Promise<void>;
|
|
774
|
+
private drain;
|
|
775
|
+
private send;
|
|
776
|
+
}
|
|
777
|
+
/**
|
|
778
|
+
* One Playwright page on the session's UI. Thin on purpose — `page` is the
|
|
779
|
+
* real Playwright page for anything this wrapper does not cover.
|
|
780
|
+
*/
|
|
781
|
+
declare class WorldBrowser {
|
|
782
|
+
readonly page: BrowserPage;
|
|
783
|
+
readonly ui: SessionSurfaces["ui"] | undefined;
|
|
784
|
+
readonly mode: Exclude<BrowserMode, "auto">;
|
|
785
|
+
private readonly teardown;
|
|
786
|
+
readonly viewport: {
|
|
787
|
+
width: number;
|
|
788
|
+
height: number;
|
|
789
|
+
};
|
|
790
|
+
readonly recorder: BrowserActionRecorder | null;
|
|
791
|
+
constructor(page: BrowserPage, ui: SessionSurfaces["ui"] | undefined, mode: Exclude<BrowserMode, "auto">, teardown: () => Promise<void>, viewport?: {
|
|
792
|
+
width: number;
|
|
793
|
+
height: number;
|
|
794
|
+
}, recorder?: BrowserActionRecorder | null);
|
|
795
|
+
private inflight;
|
|
796
|
+
private lastNetwork;
|
|
797
|
+
get agentId(): string | null;
|
|
798
|
+
/** Run one action and report it: the event carries what was asked,
|
|
799
|
+
* whether it worked, and the screen after — for failures too, so a
|
|
800
|
+
* reviewer sees what the agent saw when the selector did not match. */
|
|
801
|
+
private act;
|
|
802
|
+
private observeForEvent;
|
|
803
|
+
/** Open a UI path (`/customers`), a full URL, or — with no argument — the
|
|
804
|
+
* UI's declared entry page. */
|
|
805
|
+
goto(pathOrUrl?: string): Promise<string>;
|
|
806
|
+
back(): Promise<string>;
|
|
807
|
+
/** Wait for the page to finish reacting to an action. `load` alone is not
|
|
808
|
+
* enough for client-rendered UIs (React et al.): a click returns before the
|
|
809
|
+
* fetch that re-renders the page, so an agent would read stale text.
|
|
810
|
+
* Playwright's `networkidle` is per navigation and resolves at once after
|
|
811
|
+
* the first one, so this tracks requests itself: done when nothing is in
|
|
812
|
+
* flight and the network has been quiet for `SETTLE_QUIET_MS`, bounded so
|
|
813
|
+
* long-polling UIs cannot hang us. */
|
|
814
|
+
private settle;
|
|
815
|
+
click(selector: string): Promise<void>;
|
|
816
|
+
type(selector: string, text: string): Promise<void>;
|
|
817
|
+
press(key: string): Promise<void>;
|
|
818
|
+
scroll(dy: number): Promise<void>;
|
|
819
|
+
screenshot(fullPage?: boolean): Promise<Buffer>;
|
|
820
|
+
screenshotBase64(fullPage?: boolean): Promise<string>;
|
|
821
|
+
text(selector?: string): Promise<string>;
|
|
822
|
+
html(): Promise<string>;
|
|
823
|
+
get url(): string;
|
|
824
|
+
title(): Promise<string>;
|
|
825
|
+
close(): Promise<void>;
|
|
826
|
+
}
|
|
827
|
+
/** The Playwright entry points this module needs, so tests can inject a fake. */
|
|
828
|
+
type PlaywrightLike = {
|
|
829
|
+
chromium: {
|
|
830
|
+
connect(wsEndpoint: string): Promise<PlaywrightBrowserLike>;
|
|
831
|
+
connectOverCDP(endpointURL: string): Promise<PlaywrightBrowserLike>;
|
|
832
|
+
launch(opts?: {
|
|
833
|
+
headless?: boolean;
|
|
834
|
+
}): Promise<PlaywrightBrowserLike>;
|
|
835
|
+
};
|
|
836
|
+
};
|
|
837
|
+
type PlaywrightBrowserLike = {
|
|
838
|
+
newContext(opts?: {
|
|
839
|
+
viewport?: {
|
|
840
|
+
width: number;
|
|
841
|
+
height: number;
|
|
842
|
+
};
|
|
843
|
+
}): Promise<{
|
|
844
|
+
newPage(): Promise<BrowserPage>;
|
|
845
|
+
close(): Promise<void>;
|
|
846
|
+
}>;
|
|
847
|
+
close(): Promise<void>;
|
|
848
|
+
};
|
|
849
|
+
declare function resolveBrowserMode(surfaces: SessionSurfaces, mode: BrowserMode): Exclude<BrowserMode, "auto">;
|
|
850
|
+
/** Open a browser on the session's UI in `hosted`, `local` or `auto` mode. */
|
|
851
|
+
declare function openBrowser(surfaces: SessionSurfaces, opts?: {
|
|
852
|
+
mode?: BrowserMode;
|
|
853
|
+
headless?: boolean;
|
|
854
|
+
playwright?: PlaywrightLike;
|
|
855
|
+
recorder?: BrowserActionRecorder | null;
|
|
856
|
+
}): Promise<WorldBrowser>;
|
|
857
|
+
declare const COMPUTER_USE_SPECS: readonly [{
|
|
858
|
+
readonly name: "browser_goto";
|
|
859
|
+
readonly signature: "browser_goto(path=None)";
|
|
860
|
+
readonly doc: "Open a page of the world's UI. `path` is a UI path like /customers, a full URL, or omitted for the entry page. Returns the URL and page text.";
|
|
861
|
+
}, {
|
|
862
|
+
readonly name: "browser_click";
|
|
863
|
+
readonly signature: "browser_click(selector)";
|
|
864
|
+
readonly doc: "Click an element by Playwright selector (CSS, `text=Refund`, `role=button[name=Save]`). Returns the page text after the click.";
|
|
865
|
+
}, {
|
|
866
|
+
readonly name: "browser_type";
|
|
867
|
+
readonly signature: "browser_type(selector, text)";
|
|
868
|
+
readonly doc: "Replace the value of an input/textarea found by selector with `text`.";
|
|
869
|
+
}, {
|
|
870
|
+
readonly name: "browser_press";
|
|
871
|
+
readonly signature: "browser_press(key)";
|
|
872
|
+
readonly doc: "Press a key (Enter, Tab, Escape, ArrowDown, ...). Returns the page text after.";
|
|
873
|
+
}, {
|
|
874
|
+
readonly name: "browser_scroll";
|
|
875
|
+
readonly signature: "browser_scroll(dy=600)";
|
|
876
|
+
readonly doc: "Scroll the page vertically by `dy` pixels (negative scrolls up).";
|
|
877
|
+
}, {
|
|
878
|
+
readonly name: "browser_screenshot";
|
|
879
|
+
readonly signature: "browser_screenshot(full_page=False)";
|
|
880
|
+
readonly doc: "Take a PNG screenshot; returns {image_base64, url}.";
|
|
881
|
+
}, {
|
|
882
|
+
readonly name: "browser_read";
|
|
883
|
+
readonly signature: "browser_read(selector='body')";
|
|
884
|
+
readonly doc: "Return the visible text of an element (default: whole page) plus the URL and title.";
|
|
885
|
+
}, {
|
|
886
|
+
readonly name: "browser_back";
|
|
887
|
+
readonly signature: "browser_back()";
|
|
888
|
+
readonly doc: "Go back one page in history.";
|
|
889
|
+
}];
|
|
890
|
+
/**
|
|
891
|
+
* The browser as model tools, in the same `WorldToolkit` shape the world's
|
|
892
|
+
* own tools come in — so an agent loop that already dispatches
|
|
893
|
+
* `toolkit().impls` merges `computerUseToolkit(b).impls` and gains a screen
|
|
894
|
+
* without a second dispatch path.
|
|
895
|
+
*/
|
|
896
|
+
declare function computerUseToolkit(browser: WorldBrowser, opts?: {
|
|
897
|
+
maxText?: number;
|
|
898
|
+
}): WorldToolkit;
|
|
899
|
+
|
|
215
900
|
/**
|
|
216
901
|
* The working-dir half of the TS CLI: push / pull / checkout / status /
|
|
217
902
|
* branch / tag / propose — a faithful port of the Python client
|
|
@@ -265,12 +950,23 @@ declare function push(dir: string, opts?: {
|
|
|
265
950
|
* branch tip, so re-validating a PR replaces its own previous push
|
|
266
951
|
* instead of 409ing against it. */
|
|
267
952
|
baseVersionId?: string | null;
|
|
953
|
+
/** Container metadata recorded on resolve — the Python CLI's --name,
|
|
954
|
+
* --description, --tag and --visibility. */
|
|
955
|
+
name?: string;
|
|
956
|
+
description?: string;
|
|
957
|
+
tags?: string[];
|
|
958
|
+
visibility?: string;
|
|
959
|
+
/** Pre-built OCI image ref for image/agentic envs (recorded on the version). */
|
|
960
|
+
imageRef?: string;
|
|
268
961
|
options?: WorldsClientOptions;
|
|
269
962
|
}): Promise<{
|
|
963
|
+
containerId: string;
|
|
270
964
|
slug: string;
|
|
271
965
|
versionId: string;
|
|
272
966
|
contentHash: string;
|
|
273
967
|
branch: string;
|
|
968
|
+
state: string | null;
|
|
969
|
+
alreadyUploaded: boolean;
|
|
274
970
|
}>;
|
|
275
971
|
declare function pull(slugRef: string, target?: string, options?: WorldsClientOptions): Promise<{
|
|
276
972
|
slug: string;
|
|
@@ -345,18 +1041,6 @@ declare function validateWorld(dir: string, opts: {
|
|
|
345
1041
|
options?: WorldsClientOptions;
|
|
346
1042
|
}): Promise<ValidateReport>;
|
|
347
1043
|
|
|
348
|
-
/**
|
|
349
|
-
* Worlds from TypeScript: identity, tasks, and HOSTED execution.
|
|
350
|
-
*
|
|
351
|
-
* The same three-level model as the Python SDK — WorldSet → Task — with one
|
|
352
|
-
* deliberate difference: a world's tools are Python modules, so TypeScript
|
|
353
|
-
* does not materialize task environments in-process. What a TS agent
|
|
354
|
-
* codebase needs is exactly what this module provides: resolve a world ref
|
|
355
|
-
* to its pinned version, read its task list, and dispatch HOSTED runs
|
|
356
|
-
* (parallelism included) that execute the world server-side and file graded,
|
|
357
|
-
* version-pinned rollouts. Local in-process execution stays a Python
|
|
358
|
-
* capability by design, not by omission.
|
|
359
|
-
*/
|
|
360
1044
|
type WorldsClientOptions = {
|
|
361
1045
|
host?: string;
|
|
362
1046
|
publicKey?: string;
|
|
@@ -380,7 +1064,7 @@ type DispatchedRun = {
|
|
|
380
1064
|
};
|
|
381
1065
|
/** Authenticated JSON request against the platform API — the primitive the
|
|
382
1066
|
* worlds helpers and the TS CLI share. */
|
|
383
|
-
declare function apiRequest<T>(options: WorldsClientOptions, method: "GET" | "POST" | "PUT" | "DELETE", path: string, body?: unknown): Promise<T>;
|
|
1067
|
+
declare function apiRequest<T>(options: WorldsClientOptions, method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", path: string, body?: unknown): Promise<T>;
|
|
384
1068
|
/** Set (or rotate) one environment secret — write-only: no API returns it. */
|
|
385
1069
|
declare function setEnvSecret(slug: string, key: string, value: string, options?: WorldsClientOptions): Promise<{
|
|
386
1070
|
key: string;
|
|
@@ -404,6 +1088,30 @@ type RunConfigSummary = {
|
|
|
404
1088
|
};
|
|
405
1089
|
/** Run configs in the project. CI resolves by NAME and dispatches by id. */
|
|
406
1090
|
declare function listRunConfigs(options?: WorldsClientOptions): Promise<RunConfigSummary[]>;
|
|
1091
|
+
/** What a run config selects for the runner to work through. A config runs
|
|
1092
|
+
* EITHER the bundle's own scenarios (`taskNames`, `taskSetDatasetId`) OR the
|
|
1093
|
+
* project's stored tasks (`worldTasks`, api worlds only) — never both. A
|
|
1094
|
+
* stored task ref without `version` runs the task's current version at
|
|
1095
|
+
* dispatch time; with it, that version forever. */
|
|
1096
|
+
type RunConfigInput = {
|
|
1097
|
+
id?: string;
|
|
1098
|
+
name: string;
|
|
1099
|
+
models: string[];
|
|
1100
|
+
parallelism?: number;
|
|
1101
|
+
numExamples?: number;
|
|
1102
|
+
rolloutsPerExample?: number;
|
|
1103
|
+
timeoutMinutes?: number;
|
|
1104
|
+
agent?: string;
|
|
1105
|
+
taskSetDatasetId?: string | null;
|
|
1106
|
+
taskNames?: string[];
|
|
1107
|
+
worldTasks?: WorldTaskIdRef[];
|
|
1108
|
+
autoRunOnPush?: boolean;
|
|
1109
|
+
};
|
|
1110
|
+
/** Create a run config, or update the one named by `id`. */
|
|
1111
|
+
declare function upsertRunConfig(input: RunConfigInput, options?: WorldsClientOptions): Promise<RunConfigSummary>;
|
|
1112
|
+
/** `id[@version]` items (comma-separated or an array) → stored task refs;
|
|
1113
|
+
* the spelling `bench run-configs create --world-tasks` takes. */
|
|
1114
|
+
declare function parseWorldTaskRefs(spec: string | string[]): WorldTaskIdRef[];
|
|
407
1115
|
type RunReport = {
|
|
408
1116
|
id: string;
|
|
409
1117
|
status: string;
|
|
@@ -481,12 +1189,14 @@ declare class WorldSet {
|
|
|
481
1189
|
constructor(slugRef: string, slug: string, ref: string | null, version: ResolvedWorldVersion, tasks: WorldTask[], options: WorldsClientOptions);
|
|
482
1190
|
task(variant: string): WorldTask;
|
|
483
1191
|
/**
|
|
484
|
-
* Open a LIVE session against one of this world's tasks
|
|
485
|
-
*
|
|
486
|
-
* platform. See
|
|
1192
|
+
* Open a LIVE session against one of this world's tasks — a bundled task's
|
|
1193
|
+
* name or an inline `WorldTaskSpec`: the platform boots (or reuses) a warm
|
|
1194
|
+
* container, and your agent calls its tools through the platform. See
|
|
1195
|
+
* worlds/session.ts.
|
|
487
1196
|
*/
|
|
488
|
-
open(task:
|
|
1197
|
+
open(task: WorldTaskRef, opts?: {
|
|
489
1198
|
reuseWarm?: boolean;
|
|
1199
|
+
surfaces?: WorldSurfaceKind[];
|
|
490
1200
|
}): Promise<WorldSession>;
|
|
491
1201
|
/**
|
|
492
1202
|
* Start a HOSTED run of a run config against this world — the platform
|
|
@@ -510,4 +1220,4 @@ declare class WorldSet {
|
|
|
510
1220
|
*/
|
|
511
1221
|
declare function openWorld(slugRef: string, options?: WorldsClientOptions): Promise<WorldSet>;
|
|
512
1222
|
|
|
513
|
-
export { DEFAULT_BRANCH, type DispatchedRun, type GradeResult, type LocalMeta, type ResolvedWorldVersion, type RunConfigSummary, type RunProvenance, type RunReport, type SessionRunReport, type SessionRunResult, type ValidateReport, type ValidatedRun, WorldSession, WorldSessionCallError, type WorldSessionState, WorldSessionTimeout, WorldSet, WorldTask, type WorldTaskInfo, type WorldToolSpec, type WorldToolkit, type WorldsClientOptions, apiRequest, attachSession, buildSourceTarball, collectArchiveRelPaths, computeContentHash, createRef, deleteEnvSecret, detectProvenance, getRun, isIncludedInContentHash, listEnvSecretKeys, listRunConfigs, localTreeState, openSession, openWorld, propose, pull, push, readLocalMeta, runSessions, schemaFromSignature, setEnvSecret, snapshotTreeHashes, validateWorld, waitForRun, writeLocalMeta };
|
|
1223
|
+
export { type BrowserActionEvent, BrowserActionRecorder, type BrowserMode, type BrowserPage, COMPUTER_USE_SPECS, DEFAULT_BRANCH, DEFAULT_VIEWPORT, type DispatchedRun, EVENT_BATCH_SIZE, EVENT_FLUSH_INTERVAL_MS, EVENT_MAX_RETRIES, type GradeResult, type LocalMeta, type OpenSessionOptions, type PlaywrightBrowserLike, type PlaywrightLike, type ResolvedWorldVersion, type RunConfigInput, type RunConfigSummary, type RunProvenance, type RunReport, SURFACE_KINDS, type SeedResult, type SessionRunReport, type SessionRunResult, type SessionSurfaces, type ValidateReport, type ValidatedRun, WorldBrowser, WorldSession, type WorldSessionCall, WorldSessionCallError, type WorldSessionState, type WorldSessionTask, WorldSessionTimeout, WorldSet, type WorldSurfaceKind, WorldSurfaceUnavailable, WorldTask, type WorldTaskCheck, type WorldTaskDetail, type WorldTaskFieldOp, type WorldTaskGrader, type WorldTaskIdRef, type WorldTaskInfo, type WorldTaskPage, type WorldTaskRef, type WorldTaskRubricCriterion, type WorldTaskRubricGrader, type WorldTaskScalar, type WorldTaskSeed, type WorldTaskSpec, type WorldTaskSummary, type WorldTaskValidation, type WorldTaskVersionSummary, type WorldToolSpec, type WorldToolkit, type WorldsClientOptions, apiRequest, attachSession, buildSourceTarball, collectArchiveRelPaths, computeContentHash, computerUseToolkit, createRef, createTask, deleteEnvSecret, deleteTask, detectProvenance, getRun, getTask, isIncludedInContentHash, isTaskIdRef, isTaskSpec, listEnvSecretKeys, listRunConfigs, listTasks, localTreeState, openBrowser, openSession, openWorld, parseWorldTaskRefs, propose, pull, push, readLocalMeta, redactActionArgs, resolveBrowserMode, runSessions, schemaFromSignature, setEnvSecret, snapshotTreeHashes, surfaceKinds, taskLabel, uiEntryUrl, uiUrl, updateTask, upsertRunConfig, validateTask, validateWorld, waitForRun, withoutUiToken, writeLocalMeta };
|