@agent-relay/sandbox 0.1.1 → 0.1.3

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.
Files changed (121) hide show
  1. package/README.md +226 -5
  2. package/dist/agent37/client.d.ts +115 -0
  3. package/dist/agent37/client.d.ts.map +1 -0
  4. package/dist/agent37/client.js +270 -0
  5. package/dist/agent37/client.js.map +1 -0
  6. package/dist/agent37/runtime.d.ts +415 -0
  7. package/dist/agent37/runtime.d.ts.map +1 -0
  8. package/dist/agent37/runtime.js +855 -0
  9. package/dist/agent37/runtime.js.map +1 -0
  10. package/dist/agentcore/bench.d.ts +93 -0
  11. package/dist/agentcore/bench.d.ts.map +1 -0
  12. package/dist/agentcore/bench.js +125 -0
  13. package/dist/agentcore/bench.js.map +1 -0
  14. package/dist/agentcore/capabilities.d.ts +169 -0
  15. package/dist/agentcore/capabilities.d.ts.map +1 -0
  16. package/dist/agentcore/capabilities.js +153 -0
  17. package/dist/agentcore/capabilities.js.map +1 -0
  18. package/dist/agentcore/config.d.ts +156 -0
  19. package/dist/agentcore/config.d.ts.map +1 -0
  20. package/dist/agentcore/config.js +12 -0
  21. package/dist/agentcore/config.js.map +1 -0
  22. package/dist/agentcore/internal/sdk.d.ts +181 -0
  23. package/dist/agentcore/internal/sdk.d.ts.map +1 -0
  24. package/dist/agentcore/internal/sdk.js +223 -0
  25. package/dist/agentcore/internal/sdk.js.map +1 -0
  26. package/dist/agentcore/runtime.d.ts +177 -0
  27. package/dist/agentcore/runtime.d.ts.map +1 -0
  28. package/dist/agentcore/runtime.js +706 -0
  29. package/dist/agentcore/runtime.js.map +1 -0
  30. package/dist/daytona/runtime.d.ts +23 -0
  31. package/dist/daytona/runtime.d.ts.map +1 -1
  32. package/dist/daytona/runtime.js +292 -10
  33. package/dist/daytona/runtime.js.map +1 -1
  34. package/dist/daytona/wire-supplement.d.ts +25 -0
  35. package/dist/daytona/wire-supplement.d.ts.map +1 -0
  36. package/dist/daytona/wire-supplement.js +16 -0
  37. package/dist/daytona/wire-supplement.js.map +1 -0
  38. package/dist/e2b/runtime.d.ts +107 -72
  39. package/dist/e2b/runtime.d.ts.map +1 -1
  40. package/dist/e2b/runtime.js +675 -190
  41. package/dist/e2b/runtime.js.map +1 -1
  42. package/dist/freestyle/capabilities.d.ts +28 -0
  43. package/dist/freestyle/capabilities.d.ts.map +1 -0
  44. package/dist/freestyle/capabilities.js +42 -0
  45. package/dist/freestyle/capabilities.js.map +1 -0
  46. package/dist/freestyle/config.d.ts +36 -0
  47. package/dist/freestyle/config.d.ts.map +1 -0
  48. package/dist/freestyle/config.js +2 -0
  49. package/dist/freestyle/config.js.map +1 -0
  50. package/dist/freestyle/internal/sdk.d.ts +69 -0
  51. package/dist/freestyle/internal/sdk.d.ts.map +1 -0
  52. package/dist/freestyle/internal/sdk.js +19 -0
  53. package/dist/freestyle/internal/sdk.js.map +1 -0
  54. package/dist/freestyle/runtime.d.ts +163 -0
  55. package/dist/freestyle/runtime.d.ts.map +1 -0
  56. package/dist/freestyle/runtime.js +798 -0
  57. package/dist/freestyle/runtime.js.map +1 -0
  58. package/dist/index.d.ts +35 -4
  59. package/dist/index.d.ts.map +1 -1
  60. package/dist/index.js +16 -2
  61. package/dist/index.js.map +1 -1
  62. package/dist/microsandbox/runtime.d.ts +793 -0
  63. package/dist/microsandbox/runtime.d.ts.map +1 -0
  64. package/dist/microsandbox/runtime.js +2303 -0
  65. package/dist/microsandbox/runtime.js.map +1 -0
  66. package/dist/modal/bench.d.ts +199 -0
  67. package/dist/modal/bench.d.ts.map +1 -0
  68. package/dist/modal/bench.js +450 -0
  69. package/dist/modal/bench.js.map +1 -0
  70. package/dist/modal/capabilities.d.ts +180 -0
  71. package/dist/modal/capabilities.d.ts.map +1 -0
  72. package/dist/modal/capabilities.js +159 -0
  73. package/dist/modal/capabilities.js.map +1 -0
  74. package/dist/modal/config.d.ts +192 -0
  75. package/dist/modal/config.d.ts.map +1 -0
  76. package/dist/modal/config.js +169 -0
  77. package/dist/modal/config.js.map +1 -0
  78. package/dist/modal/internal/sdk.d.ts +141 -0
  79. package/dist/modal/internal/sdk.d.ts.map +1 -0
  80. package/dist/modal/internal/sdk.js +51 -0
  81. package/dist/modal/internal/sdk.js.map +1 -0
  82. package/dist/modal/runtime.d.ts +271 -0
  83. package/dist/modal/runtime.d.ts.map +1 -0
  84. package/dist/modal/runtime.js +871 -0
  85. package/dist/modal/runtime.js.map +1 -0
  86. package/dist/mount-script.d.ts +16 -1
  87. package/dist/mount-script.d.ts.map +1 -1
  88. package/dist/mount-script.js +76 -15
  89. package/dist/mount-script.js.map +1 -1
  90. package/dist/orchestrator.d.ts +15 -0
  91. package/dist/orchestrator.d.ts.map +1 -1
  92. package/dist/orchestrator.js +13 -1
  93. package/dist/orchestrator.js.map +1 -1
  94. package/dist/port.d.ts +144 -6
  95. package/dist/port.d.ts.map +1 -1
  96. package/dist/port.js +27 -5
  97. package/dist/port.js.map +1 -1
  98. package/dist/types.d.ts +55 -1
  99. package/dist/types.d.ts.map +1 -1
  100. package/dist/vercel/bench.d.ts +169 -0
  101. package/dist/vercel/bench.d.ts.map +1 -0
  102. package/dist/vercel/bench.js +337 -0
  103. package/dist/vercel/bench.js.map +1 -0
  104. package/dist/vercel/capabilities.d.ts +106 -0
  105. package/dist/vercel/capabilities.d.ts.map +1 -0
  106. package/dist/vercel/capabilities.js +128 -0
  107. package/dist/vercel/capabilities.js.map +1 -0
  108. package/dist/vercel/config.d.ts +119 -0
  109. package/dist/vercel/config.d.ts.map +1 -0
  110. package/dist/vercel/config.js +8 -0
  111. package/dist/vercel/config.js.map +1 -0
  112. package/dist/vercel/internal/sdk.d.ts +173 -0
  113. package/dist/vercel/internal/sdk.d.ts.map +1 -0
  114. package/dist/vercel/internal/sdk.js +117 -0
  115. package/dist/vercel/internal/sdk.js.map +1 -0
  116. package/dist/vercel/runtime.d.ts +305 -0
  117. package/dist/vercel/runtime.d.ts.map +1 -0
  118. package/dist/vercel/runtime.js +1169 -0
  119. package/dist/vercel/runtime.js.map +1 -0
  120. package/docs/freestyle.md +110 -0
  121. package/package.json +35 -4
@@ -0,0 +1,415 @@
1
+ import { Buffer } from "node:buffer";
2
+ import type { ExecOptions, ExecResult, LaunchOptions, RuntimeCapabilities, RuntimeHandle, WorkflowRuntime } from "../types.js";
3
+ import type { RunScriptResult, SandboxRuntime } from "../port.js";
4
+ import { Agent37Client } from "./client.js";
5
+ import type { Agent37Fetch } from "./client.js";
6
+ /** Instance lifecycle states the hosting API reports. */
7
+ export type Agent37InstanceStatus = "provisioning" | "running" | "stopping" | "stopped" | "starting" | "restarting" | "updating" | "sleeping" | "waking" | "failed" | "deleting" | "deleted";
8
+ /** Instance shape. Valid combinations are provider- and plan-specific. */
9
+ export type Agent37Resources = {
10
+ cpu: number;
11
+ memory: number;
12
+ disk?: number;
13
+ };
14
+ /**
15
+ * A port exposed at a permanent unauthenticated URL, for user-space services.
16
+ *
17
+ * The instance plane (file API) is authenticated with `X-Agent37-Key` and does
18
+ * NOT require a public port. Register public ports only for services that need
19
+ * anonymous ingress from outside the instance.
20
+ */
21
+ export type Agent37PublicPort = {
22
+ port: number;
23
+ prefix?: string;
24
+ };
25
+ /** Ceilings on an instance's managed-service usage, in micros. */
26
+ export type Agent37Budget = {
27
+ monthly_cap_micros?: number;
28
+ credit_micros?: number;
29
+ };
30
+ /** The instance object, as returned by the hosting plane. */
31
+ export type Agent37Instance = {
32
+ id: string;
33
+ status: Agent37InstanceStatus;
34
+ status_reason?: string | null;
35
+ template?: string | null;
36
+ url?: string | null;
37
+ user?: string | null;
38
+ name?: string | null;
39
+ metadata?: Record<string, string> | null;
40
+ resources?: Agent37Resources | null;
41
+ auto_sleep?: boolean;
42
+ idle_timeout_seconds?: number;
43
+ past_due?: boolean;
44
+ created?: number;
45
+ };
46
+ /** Snapshot of a container's own output plus a compact health readout. */
47
+ export type Agent37ContainerLogs = {
48
+ logs: string;
49
+ truncated: boolean;
50
+ health: Record<string, unknown> | null;
51
+ fetched_at?: number;
52
+ };
53
+ export type Agent37RuntimeOptions = {
54
+ /** `sk_live_` workspace key. Never sourced from the environment here. */
55
+ apiKey: string;
56
+ /**
57
+ * Origin of the hosting API. Required: this package ships no endpoint
58
+ * defaults, so the caller names the control plane (or a proxy in front of
59
+ * it) explicitly.
60
+ */
61
+ baseUrl: string;
62
+ /**
63
+ * Home directory inside the instance image. Required: it is template-
64
+ * specific, so there is no default correct for every consumer.
65
+ */
66
+ defaultHomeDir: string;
67
+ /**
68
+ * Template to launch. Omitted, the field is left off the create body and the
69
+ * provider applies its own default — this package does not substitute one.
70
+ */
71
+ template?: string;
72
+ /** Instance shape. Omitted, the provider applies its own smallest shape. */
73
+ resources?: Agent37Resources;
74
+ /** `dedicated` or `shared`. Omitted, the provider applies its own default. */
75
+ type?: string;
76
+ /** Managed-service ceilings. Omitted, the provider applies its own default. */
77
+ budget?: Agent37Budget;
78
+ /** Opt instances into idle checkpointing. */
79
+ autoSleep?: boolean;
80
+ /** Idle seconds before sleeping. Only meaningful with `autoSleep`. */
81
+ idleTimeoutSeconds?: number;
82
+ /**
83
+ * Ports to expose at permanent unauthenticated URLs, for user-space services.
84
+ * The instance plane (file API) uses `X-Agent37-Key` auth and does not need
85
+ * a public port.
86
+ */
87
+ publicPorts?: readonly Agent37PublicPort[];
88
+ /** Opaque attribution tag stamped on every instance this runtime launches. */
89
+ user?: string;
90
+ /** Transport seam. Defaults to the global `fetch`. */
91
+ fetch?: Agent37Fetch;
92
+ /** Retry policy passthrough. */
93
+ maxAttempts?: number;
94
+ retryBaseDelayMs?: number;
95
+ sleep?: (ms: number) => Promise<void>;
96
+ /** Pre-built client, for tests or for sharing one transport across runtimes. */
97
+ client?: Agent37Client;
98
+ /**
99
+ * Largest file `uploadBundle` will push through the base64-over-exec
100
+ * fallback, used only when an instance exposes no URL of its own.
101
+ */
102
+ execUploadMaxBytes?: number;
103
+ };
104
+ export type Agent37LookupOptions = {
105
+ states?: readonly string[] | null;
106
+ limit?: number;
107
+ pageSize?: number;
108
+ owned?: boolean;
109
+ excludeIds?: readonly string[];
110
+ timeoutMs?: number;
111
+ };
112
+ export type Agent37CountOptions = {
113
+ states?: readonly string[] | null;
114
+ limit?: number;
115
+ pageSize?: number;
116
+ maxCount?: number;
117
+ timeoutMs?: number;
118
+ };
119
+ export type Agent37LaunchOptions = {
120
+ name?: string;
121
+ env?: Record<string, string>;
122
+ labels?: Record<string, string>;
123
+ workdir?: string;
124
+ };
125
+ export type Agent37RunScriptOptions = {
126
+ command: string;
127
+ /**
128
+ * Command lifetime, per the port's contract: once it elapses the command is
129
+ * no longer running. Agent37 can only satisfy this via its own
130
+ * {@link AGENT37_COMMAND_CAP_MS} cap, so a shorter value is rejected with
131
+ * {@link Agent37CommandTimeoutUnsupportedError} rather than silently
132
+ * downgraded to an HTTP abort that would not stop anything.
133
+ */
134
+ timeoutMs?: number;
135
+ /**
136
+ * How long this client waits for the HTTP response, and nothing more. On
137
+ * expiry the request is abandoned and **the command keeps running inside the
138
+ * instance** — this is a budget for the caller, not a cancellation.
139
+ */
140
+ requestTimeoutMs?: number;
141
+ env?: Record<string, string>;
142
+ cwd?: string;
143
+ };
144
+ /** `ExecOptions` plus the request budget that has no bootstrap-plane equivalent. */
145
+ export type Agent37ExecOptions = ExecOptions & {
146
+ requestTimeoutMs?: number;
147
+ };
148
+ export type Agent37BundleFile = {
149
+ source: string | Buffer;
150
+ destination: string;
151
+ };
152
+ export type Agent37UploadBundleOptions = {
153
+ files: Array<Agent37BundleFile>;
154
+ };
155
+ /**
156
+ * The provider's hard ceiling on a single command, in milliseconds. Every
157
+ * command is bounded by this whether the caller asks for it or not, which is
158
+ * what makes a `timeoutMs` of at least this value honestly satisfiable.
159
+ */
160
+ export declare const AGENT37_COMMAND_CAP_MS = 280000;
161
+ /** Raised when `env` would be rejected by the provider's own create validation. */
162
+ export declare class Agent37EnvValidationError extends Error {
163
+ constructor(message: string);
164
+ }
165
+ /**
166
+ * Raised when start / stop / destroy is handed an instance this runtime knows
167
+ * nothing about.
168
+ *
169
+ * Ownership here is *caller-declared attachment*, not in-process provenance:
170
+ * `launch` owns what it creates, and `getById` / `findAllByLabels` attach as
171
+ * unowned unless the caller passes `owned: true`. An instance that was never
172
+ * resolved through any of those is refused outright rather than mutated on a
173
+ * guess.
174
+ *
175
+ * This is deliberately louder than the Daytona adapter, which silently returns
176
+ * for an unregistered handle. A destroy that quietly does nothing reads to the
177
+ * caller as a completed teardown that never happened, which is the more
178
+ * expensive of the two failure modes.
179
+ */
180
+ export declare class Agent37ForeignHandleError extends Error {
181
+ constructor(id: string, operation: string);
182
+ }
183
+ /**
184
+ * Raised when a command completes but the provider's reply carries no
185
+ * `exit_code`, so its outcome is unknown.
186
+ *
187
+ * `runScript` reports this as `exitCode: null`, which the port models. `exec`
188
+ * cannot: `ExecResult.exitCode` is a number, and the only numbers available are
189
+ * lies — `0` would report a command that may have failed as a success.
190
+ */
191
+ export declare class Agent37UnknownExitCodeError extends Error {
192
+ readonly output: string;
193
+ constructor(id: string, output: string);
194
+ }
195
+ /**
196
+ * Raised when a caller asks for a command lifetime Agent37 cannot enforce.
197
+ *
198
+ * `timeoutMs` on the port means the command is no longer running once it
199
+ * elapses. Agent37's `exec` accepts no timeout, and aborting the HTTP request
200
+ * only abandons the response — the command keeps running inside the instance.
201
+ * The single lifetime bound Agent37 genuinely enforces is its own
202
+ * {@link AGENT37_COMMAND_CAP_MS} cap, so anything shorter is refused instead of
203
+ * being faked with an `AbortSignal`.
204
+ *
205
+ * Callers that want to stop *waiting* (as opposed to stopping the command) want
206
+ * `requestTimeoutMs`, which is named for what it actually does.
207
+ */
208
+ export declare class Agent37CommandTimeoutUnsupportedError extends Error {
209
+ constructor(timeoutMs: number);
210
+ }
211
+ /**
212
+ * Raised when a 2xx reply does not carry the shape the endpoint documents.
213
+ *
214
+ * The alternative is worse than an error, because a tolerant decode turns a
215
+ * broken response into a *confident negative*: `GET /v1/instances` answering
216
+ * with HTML from a proxy would read as "no instance matches these labels",
217
+ * which is the exact answer that makes a caller abandon a running warm lease
218
+ * and pay to launch a replacement. Similarly, a create reply with no `id`
219
+ * would register ownership under `undefined` and aim a later DELETE at a
220
+ * garbage path.
221
+ *
222
+ * So the adapter fails closed: an unusable reply is reported as unusable, and
223
+ * the caller retries or escalates instead of acting on a fiction. Only `id` and
224
+ * `status` are required to be non-empty strings — an *unrecognized* status is
225
+ * forward compatibility, not corruption, and {@link normalizeStatus} already
226
+ * treats anything but `running` as not ready.
227
+ */
228
+ export declare class Agent37MalformedResponseError extends Error {
229
+ /** Method and path only, matching {@link Agent37ApiError.request}. */
230
+ readonly request: string;
231
+ constructor(request: string, detail: string);
232
+ }
233
+ /**
234
+ * Raised when a caller asks `launch` to bound how long instance creation may
235
+ * take.
236
+ *
237
+ * HOLD — not implementable against the documented contract. `POST
238
+ * /v1/instances` is synchronous: it returns 201 only once the instance reports
239
+ * `running`. Abandoning that request client-side does not un-allocate anything
240
+ * the provider has already started building, and the reply that would have
241
+ * carried the new instance's `id` is discarded with it. The result is an
242
+ * orphan the caller cannot name, let alone delete — a billed leak dressed up
243
+ * as a timeout.
244
+ *
245
+ * Cleaning up afterwards would need one of three things the API does not
246
+ * document: an idempotency key to correlate a retry with the original create,
247
+ * a create call that returns an id before the instance is ready, or a
248
+ * guarantee about whether a still-provisioning instance appears in `GET
249
+ * /v1/instances` (and carries the `metadata` it was created with) so a bounded
250
+ * sweep could identify exactly the one that was abandoned. Sweeping on labels
251
+ * alone is not a substitute: labels are reused precisely so warm leases can be
252
+ * found by them, so a sweep could delete a healthy instance belonging to
253
+ * someone else.
254
+ *
255
+ * Verifying any of that needs live calls against the provider, which this work
256
+ * is not authorized to make. Until it is verified, the option is refused rather
257
+ * than shipped as an `AbortSignal` that reads like a cancellation and is not
258
+ * one.
259
+ *
260
+ * The refusal is purely a runtime one, and deliberately so. `createTimeoutSeconds`
261
+ * lives on the shared `LaunchOptions` and on `SandboxRuntime.launch` because
262
+ * other providers honour it, so it typechecks against this adapter too and no
263
+ * compile error is available to lean on. Narrowing this one signature would not
264
+ * change that — TypeScript compares method parameters bivariantly, so a caller
265
+ * holding a `SandboxRuntime` reference could still pass the option — and it
266
+ * would trade a real guarantee for the appearance of one while breaking the
267
+ * substitutability the port exists to provide.
268
+ *
269
+ * Callers that need a bound should launch with labels unique to the attempt,
270
+ * apply their own deadline around `launch`, and reconcile with
271
+ * `findAllByLabels(..., { owned: true })` — a recovery they can reason about,
272
+ * because they chose the labels.
273
+ */
274
+ export declare class Agent37CreateTimeoutUnsupportedError extends Error {
275
+ constructor();
276
+ }
277
+ export declare class Agent37Runtime implements SandboxRuntime, WorkflowRuntime {
278
+ readonly id = "agent37";
279
+ /**
280
+ * Bootstrap-plane capabilities (the live in-sandbox session), distinct from
281
+ * `SandboxRuntimeCapabilities`.
282
+ *
283
+ * `pty: false` and `streamingLogs: false` are facts, not caution: `exec` is a
284
+ * single buffered request/response with no TTY, and the one log endpoint
285
+ * (`GET /v1/instances/{id}/logs`) returns a snapshot with a `tail` count, not
286
+ * a stream. `snapshots: false` likewise — templates are built from a
287
+ * Dockerfile ahead of time; there is no documented call that captures a
288
+ * running instance as a reusable image.
289
+ */
290
+ readonly capabilities: RuntimeCapabilities;
291
+ /**
292
+ * `lifecycle: true` because `start` and `stop` are real hosting-plane calls
293
+ * that change `status`, not the no-ops some providers ship.
294
+ *
295
+ * `warmLease: true` because label lookup returns real matches. `GET
296
+ * /v1/instances` documents no server-side filter, so the filtering happens
297
+ * here — but it happens over a complete, unpaginated list, which makes an
298
+ * empty result mean "no match" and nothing else. That is the ambiguity the
299
+ * capability exists to rule out, and it is ruled out.
300
+ *
301
+ * `asyncExec` is not declared here; it is derived from method presence by
302
+ * `resolveSandboxRuntimeCapabilities`. Async exec is absent from this adapter
303
+ * because nohup+/tmp emulation cannot provide durable, idempotent guarantees.
304
+ */
305
+ readonly declaredCapabilities: {
306
+ readonly warmLease: true;
307
+ readonly lifecycle: true;
308
+ };
309
+ private readonly client;
310
+ private readonly defaultHomeDir;
311
+ private readonly template?;
312
+ private readonly resources?;
313
+ private readonly instanceType?;
314
+ private readonly budget?;
315
+ private readonly autoSleep?;
316
+ private readonly idleTimeoutSeconds?;
317
+ private readonly publicPorts?;
318
+ private readonly user?;
319
+ private readonly execUploadMaxBytes;
320
+ private readonly instanceUrls;
321
+ private readonly ownership;
322
+ constructor(options: Agent37RuntimeOptions);
323
+ findByLabels(labels: Record<string, string>, options?: Agent37LookupOptions): Promise<RuntimeHandle | null>;
324
+ findAllByLabels(labels: Record<string, string>, options?: Agent37LookupOptions): Promise<RuntimeHandle[]>;
325
+ countByLabels(labels: Record<string, string>, options?: Agent37CountOptions): Promise<number>;
326
+ getById(id: string, options?: {
327
+ states?: readonly string[] | null;
328
+ owned?: boolean;
329
+ homeDir?: string;
330
+ workdir?: string;
331
+ }): Promise<RuntimeHandle | null>;
332
+ launch(options?: Agent37LaunchOptions & LaunchOptions): Promise<RuntimeHandle>;
333
+ start(handle: RuntimeHandle): Promise<RuntimeHandle>;
334
+ stop(handle: RuntimeHandle): Promise<void>;
335
+ destroy(handle: RuntimeHandle): Promise<void>;
336
+ exec(handle: RuntimeHandle, command: string, options?: Agent37ExecOptions): Promise<ExecResult>;
337
+ runScript(handle: RuntimeHandle, options: Agent37RunScriptOptions): Promise<RunScriptResult>;
338
+ uploadBundle(handle: RuntimeHandle, options: Agent37UploadBundleOptions): Promise<void>;
339
+ uploadFile(handle: RuntimeHandle, source: string | Buffer, destination: string): Promise<void>;
340
+ downloadFile(handle: RuntimeHandle, source: string, destination?: string): Promise<Buffer | void>;
341
+ /**
342
+ * Read-side counterpart to `uploadFile`'s exec fallback: templates registered
343
+ * with no ports have no URL of their own, so the file plane is unreachable
344
+ * and the only way out is through the hosting plane's exec. The payload is
345
+ * carried inside a bounded shell script that first sizes the file, refuses
346
+ * anything larger than `execUploadMaxBytes` (the same cap as the upload
347
+ * path), then emits base64 on stdout. Truncated exec output is rejected
348
+ * rather than decoded — a truncated base64 stream would decode into the
349
+ * wrong bytes without error.
350
+ */
351
+ private downloadFileViaExec;
352
+ getHomeDir(handle: RuntimeHandle): Promise<string>;
353
+ /**
354
+ * Container boot and runtime logs. Unlike `exec`, this works in any state,
355
+ * which is what makes it the tool for an instance that will not stay up.
356
+ */
357
+ getContainerLogs(handle: RuntimeHandle, options?: {
358
+ tail?: number;
359
+ }): Promise<Agent37ContainerLogs>;
360
+ /**
361
+ * Record what the caller declared about an instance.
362
+ *
363
+ * Monotonic on purpose: once ownership is claimed it survives later read-only
364
+ * resolutions of the same id. A plain `findAllByLabels` sweep listing an
365
+ * instance must not quietly revoke the delete rights a caller already
366
+ * declared through `getById(id, { owned: true })`.
367
+ */
368
+ private declareOwnership;
369
+ /**
370
+ * Resolve what may be done to `id`: `true` to mutate it, `false` for an
371
+ * attachment this runtime must leave alone. Throws when the id was never
372
+ * registered, because that is a caller mistake rather than a policy decision.
373
+ */
374
+ private requireOwnership;
375
+ /** Drop every trace of an instance this runtime is done with. */
376
+ private forget;
377
+ private execRaw;
378
+ private listInstances;
379
+ private fetchInstance;
380
+ private resolveInstanceUrl;
381
+ private registerInstance;
382
+ }
383
+ /**
384
+ * Map a provider status onto the normalized vocabulary the delivery path
385
+ * reasons about.
386
+ *
387
+ * Only `running` is `STARTED`. Every transitional status — `provisioning`,
388
+ * `starting`, `waking`, `restarting`, `updating` — reads as `STOPPED`, so the
389
+ * default `["STARTED"]` filter can never hand a caller an instance that is not
390
+ * yet able to accept an exec.
391
+ */
392
+ export declare function normalizeStatus(status: Agent37InstanceStatus | undefined): string;
393
+ /**
394
+ * Reject a command lifetime Agent37 cannot deliver.
395
+ *
396
+ * Anything at or above the provider's cap is genuinely satisfied — the command
397
+ * cannot outlive the cap, so it certainly cannot outlive a longer deadline.
398
+ * Anything below it would need real cancellation, which `exec` does not offer.
399
+ */
400
+ export declare function assertHonourableCommandTimeout(timeoutMs: number | undefined): void;
401
+ export declare function assertValidEnv(env: Record<string, string>): void;
402
+ /**
403
+ * Build the shell program for one run.
404
+ *
405
+ * `exec` accepts a command and nothing else — no cwd, no env, no timeout — so
406
+ * both are expressed in the program itself. Values are single-quoted, and a
407
+ * failed `cd` aborts rather than silently running the command in the wrong
408
+ * directory.
409
+ */
410
+ export declare function composeScript(command: string, options?: {
411
+ cwd?: string;
412
+ env?: Record<string, string>;
413
+ }): string;
414
+ export declare function shellQuote(value: string): string;
415
+ //# sourceMappingURL=runtime.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/agent37/runtime.ts"],"names":[],"mappings":"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"}