@withgateway/sdk 0.1.14 → 0.1.17

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.
@@ -212,6 +212,134 @@ declare function runSessions(opts: {
212
212
  options?: WorldsClientOptions;
213
213
  }): Promise<SessionRunReport>;
214
214
 
215
+ /**
216
+ * The working-dir half of the TS CLI: push / pull / checkout / status /
217
+ * branch / tag / propose — a faithful port of the Python client
218
+ * (`gatewaysdk/benchmark_hub/client.py` + `_archive.py`).
219
+ *
220
+ * LOCKSTEP WARNING — the content hash is the version's identity and is
221
+ * byte-compatible with Prime Intellect. It now has FOUR implementations that
222
+ * must stay identical: worker `environmentAgent/tar.ts`, web
223
+ * `benchmark-hub/server/benchmarkContentHash.ts`, Python `_archive.py`, and
224
+ * this file. This one is a line-for-line port of the WEB TypeScript
225
+ * implementation (same language, same crypto) — if the rule ever changes,
226
+ * change all four or push identity splits by client.
227
+ *
228
+ * One deliberate refusal, same policy as the web upload path: a bundle with
229
+ * a ROOT `.gitignore` is refused rather than mis-hashed — the Python CLI
230
+ * honors it via `gitignore_parser`, and an imperfect reimplementation here
231
+ * would produce a wrong, Prime-incompatible hash silently.
232
+ */
233
+ declare const DEFAULT_BRANCH = "main";
234
+ declare function isIncludedInContentHash(relPath: string, includeAllRootFiles: boolean): boolean;
235
+ /** The archive-visible files of a working dir, as sorted relpaths. Throws on
236
+ * a root .gitignore (see the header). */
237
+ declare function collectArchiveRelPaths(dir: string): string[];
238
+ declare function computeContentHash(dir: string): string;
239
+ /** A deterministic .tar.gz of the source files (node's gzip stamps no mtime,
240
+ * matching the Python's mtime=0 gzip). */
241
+ declare function buildSourceTarball(dir: string): Buffer;
242
+ type LocalMeta = Record<string, unknown> & {
243
+ slug?: string;
244
+ branch?: string;
245
+ versionId?: string;
246
+ contentHash?: string;
247
+ baseFiles?: Record<string, string>;
248
+ };
249
+ declare function readLocalMeta(dir: string): LocalMeta | null;
250
+ declare function writeLocalMeta(dir: string, meta: LocalMeta): void;
251
+ declare function snapshotTreeHashes(dir: string): Record<string, string>;
252
+ declare function localTreeState(dir: string): {
253
+ meta: LocalMeta | null;
254
+ dirty: string[];
255
+ clean: boolean;
256
+ };
257
+ declare function push(dir: string, opts?: {
258
+ slug?: string;
259
+ branch?: string;
260
+ force?: boolean;
261
+ message?: string;
262
+ author?: string;
263
+ options?: WorldsClientOptions;
264
+ }): Promise<{
265
+ slug: string;
266
+ versionId: string;
267
+ contentHash: string;
268
+ branch: string;
269
+ }>;
270
+ declare function pull(slugRef: string, target?: string, options?: WorldsClientOptions): Promise<{
271
+ slug: string;
272
+ dir: string;
273
+ versionId: string;
274
+ files: number;
275
+ }>;
276
+ declare function propose(dir: string, opts: {
277
+ title: string;
278
+ reason: string;
279
+ targetBranch?: string;
280
+ options?: WorldsClientOptions;
281
+ }): Promise<{
282
+ proposalId: string;
283
+ }>;
284
+ declare function createRef(slug: string, name: string, kind: "branch" | "tag", versionId?: string, options?: WorldsClientOptions): Promise<{
285
+ name: string;
286
+ kind: string;
287
+ versionId: string;
288
+ }>;
289
+
290
+ /**
291
+ * PR validation: push the checkout's world source, run it, gate on the graded
292
+ * result — one composed call, because CI should not have to re-derive the
293
+ * choreography from primitives.
294
+ *
295
+ * The differentiating property, stated so it stays true: validation runs the
296
+ * PULL REQUEST'S OWN world source. The push files the checkout as a version on
297
+ * the PR's branch (content-hash dedup makes re-runs cheap), the dispatch pins
298
+ * that version, and the platform resolves the branch back to its open PR — so
299
+ * the run page names the PR and the PR comment names the run. Nothing here
300
+ * validates a standing deployment while pretending to validate the change.
301
+ */
302
+
303
+ type ValidatedRun = {
304
+ model: string;
305
+ runId: string;
306
+ report: RunReport | null;
307
+ /** Why this run fails the gate, or null when it passes. */
308
+ failure: string | null;
309
+ };
310
+ type ValidateReport = {
311
+ ok: boolean;
312
+ slug: string;
313
+ branch: string;
314
+ versionId: string;
315
+ contentHash: string;
316
+ runConfig: {
317
+ id: string;
318
+ name: string;
319
+ };
320
+ runs: ValidatedRun[];
321
+ /** A PR-comment-ready summary of the whole validation. */
322
+ markdown: string;
323
+ };
324
+ /**
325
+ * Push `dir` on the current (or given) branch, dispatch the named run config
326
+ * against the pushed version, wait for every run, and gate.
327
+ *
328
+ * The gate: every dispatch accepted, every run terminal COMPLETED, and — when
329
+ * `minScore` is set — every run's score meets it. A run with NO score fails a
330
+ * score gate rather than passing it: null is "not scored", never 0 and never
331
+ * fine.
332
+ */
333
+ declare function validateWorld(dir: string, opts: {
334
+ slug?: string;
335
+ runConfig: string;
336
+ branch?: string;
337
+ minScore?: number | null;
338
+ timeoutMinutes?: number;
339
+ onProgress?: (line: string) => void;
340
+ options?: WorldsClientOptions;
341
+ }): Promise<ValidateReport>;
342
+
215
343
  /**
216
344
  * Worlds from TypeScript: identity, tasks, and HOSTED execution.
217
345
  *
@@ -281,10 +409,13 @@ type RunReport = {
281
409
  versionLabel: string | null;
282
410
  parallelism: number;
283
411
  shardsCompleted: number | null;
412
+ /** The run's page on the platform — what a PR comment should link. */
413
+ url: string | null;
284
414
  evaluations: {
285
415
  id: string;
286
416
  status: string;
287
417
  avgReward: number | null;
418
+ url: string | null;
288
419
  }[];
289
420
  samples: {
290
421
  task: string | null;
@@ -374,4 +505,4 @@ declare class WorldSet {
374
505
  */
375
506
  declare function openWorld(slugRef: string, options?: WorldsClientOptions): Promise<WorldSet>;
376
507
 
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 };
508
+ 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 };
@@ -212,6 +212,134 @@ declare function runSessions(opts: {
212
212
  options?: WorldsClientOptions;
213
213
  }): Promise<SessionRunReport>;
214
214
 
215
+ /**
216
+ * The working-dir half of the TS CLI: push / pull / checkout / status /
217
+ * branch / tag / propose — a faithful port of the Python client
218
+ * (`gatewaysdk/benchmark_hub/client.py` + `_archive.py`).
219
+ *
220
+ * LOCKSTEP WARNING — the content hash is the version's identity and is
221
+ * byte-compatible with Prime Intellect. It now has FOUR implementations that
222
+ * must stay identical: worker `environmentAgent/tar.ts`, web
223
+ * `benchmark-hub/server/benchmarkContentHash.ts`, Python `_archive.py`, and
224
+ * this file. This one is a line-for-line port of the WEB TypeScript
225
+ * implementation (same language, same crypto) — if the rule ever changes,
226
+ * change all four or push identity splits by client.
227
+ *
228
+ * One deliberate refusal, same policy as the web upload path: a bundle with
229
+ * a ROOT `.gitignore` is refused rather than mis-hashed — the Python CLI
230
+ * honors it via `gitignore_parser`, and an imperfect reimplementation here
231
+ * would produce a wrong, Prime-incompatible hash silently.
232
+ */
233
+ declare const DEFAULT_BRANCH = "main";
234
+ declare function isIncludedInContentHash(relPath: string, includeAllRootFiles: boolean): boolean;
235
+ /** The archive-visible files of a working dir, as sorted relpaths. Throws on
236
+ * a root .gitignore (see the header). */
237
+ declare function collectArchiveRelPaths(dir: string): string[];
238
+ declare function computeContentHash(dir: string): string;
239
+ /** A deterministic .tar.gz of the source files (node's gzip stamps no mtime,
240
+ * matching the Python's mtime=0 gzip). */
241
+ declare function buildSourceTarball(dir: string): Buffer;
242
+ type LocalMeta = Record<string, unknown> & {
243
+ slug?: string;
244
+ branch?: string;
245
+ versionId?: string;
246
+ contentHash?: string;
247
+ baseFiles?: Record<string, string>;
248
+ };
249
+ declare function readLocalMeta(dir: string): LocalMeta | null;
250
+ declare function writeLocalMeta(dir: string, meta: LocalMeta): void;
251
+ declare function snapshotTreeHashes(dir: string): Record<string, string>;
252
+ declare function localTreeState(dir: string): {
253
+ meta: LocalMeta | null;
254
+ dirty: string[];
255
+ clean: boolean;
256
+ };
257
+ declare function push(dir: string, opts?: {
258
+ slug?: string;
259
+ branch?: string;
260
+ force?: boolean;
261
+ message?: string;
262
+ author?: string;
263
+ options?: WorldsClientOptions;
264
+ }): Promise<{
265
+ slug: string;
266
+ versionId: string;
267
+ contentHash: string;
268
+ branch: string;
269
+ }>;
270
+ declare function pull(slugRef: string, target?: string, options?: WorldsClientOptions): Promise<{
271
+ slug: string;
272
+ dir: string;
273
+ versionId: string;
274
+ files: number;
275
+ }>;
276
+ declare function propose(dir: string, opts: {
277
+ title: string;
278
+ reason: string;
279
+ targetBranch?: string;
280
+ options?: WorldsClientOptions;
281
+ }): Promise<{
282
+ proposalId: string;
283
+ }>;
284
+ declare function createRef(slug: string, name: string, kind: "branch" | "tag", versionId?: string, options?: WorldsClientOptions): Promise<{
285
+ name: string;
286
+ kind: string;
287
+ versionId: string;
288
+ }>;
289
+
290
+ /**
291
+ * PR validation: push the checkout's world source, run it, gate on the graded
292
+ * result — one composed call, because CI should not have to re-derive the
293
+ * choreography from primitives.
294
+ *
295
+ * The differentiating property, stated so it stays true: validation runs the
296
+ * PULL REQUEST'S OWN world source. The push files the checkout as a version on
297
+ * the PR's branch (content-hash dedup makes re-runs cheap), the dispatch pins
298
+ * that version, and the platform resolves the branch back to its open PR — so
299
+ * the run page names the PR and the PR comment names the run. Nothing here
300
+ * validates a standing deployment while pretending to validate the change.
301
+ */
302
+
303
+ type ValidatedRun = {
304
+ model: string;
305
+ runId: string;
306
+ report: RunReport | null;
307
+ /** Why this run fails the gate, or null when it passes. */
308
+ failure: string | null;
309
+ };
310
+ type ValidateReport = {
311
+ ok: boolean;
312
+ slug: string;
313
+ branch: string;
314
+ versionId: string;
315
+ contentHash: string;
316
+ runConfig: {
317
+ id: string;
318
+ name: string;
319
+ };
320
+ runs: ValidatedRun[];
321
+ /** A PR-comment-ready summary of the whole validation. */
322
+ markdown: string;
323
+ };
324
+ /**
325
+ * Push `dir` on the current (or given) branch, dispatch the named run config
326
+ * against the pushed version, wait for every run, and gate.
327
+ *
328
+ * The gate: every dispatch accepted, every run terminal COMPLETED, and — when
329
+ * `minScore` is set — every run's score meets it. A run with NO score fails a
330
+ * score gate rather than passing it: null is "not scored", never 0 and never
331
+ * fine.
332
+ */
333
+ declare function validateWorld(dir: string, opts: {
334
+ slug?: string;
335
+ runConfig: string;
336
+ branch?: string;
337
+ minScore?: number | null;
338
+ timeoutMinutes?: number;
339
+ onProgress?: (line: string) => void;
340
+ options?: WorldsClientOptions;
341
+ }): Promise<ValidateReport>;
342
+
215
343
  /**
216
344
  * Worlds from TypeScript: identity, tasks, and HOSTED execution.
217
345
  *
@@ -281,10 +409,13 @@ type RunReport = {
281
409
  versionLabel: string | null;
282
410
  parallelism: number;
283
411
  shardsCompleted: number | null;
412
+ /** The run's page on the platform — what a PR comment should link. */
413
+ url: string | null;
284
414
  evaluations: {
285
415
  id: string;
286
416
  status: string;
287
417
  avgReward: number | null;
418
+ url: string | null;
288
419
  }[];
289
420
  samples: {
290
421
  task: string | null;
@@ -374,4 +505,4 @@ declare class WorldSet {
374
505
  */
375
506
  declare function openWorld(slugRef: string, options?: WorldsClientOptions): Promise<WorldSet>;
376
507
 
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 };
508
+ 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 };