@finalai/daytona-agent-provider 0.9.0 → 0.11.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 CHANGED
@@ -1,23 +1,83 @@
1
1
  # @finalai/daytona-agent-provider
2
2
 
3
+ The `daytona` sandbox provider: sandboxes in your own Daytona account, driven through
4
+ Daytona's public API and implementing only the `@finalai/agent-provider` sandbox
5
+ contract. `/sandboxes` exports `daytona(...)`, the provider environment a caller creates
6
+ sandboxes from; `/sandboxes/daytona` exports the provider a host runs.
7
+
8
+ ```ts
9
+ import { defineSandboxSetup } from '@finalai/agents/sandboxes';
10
+ import { daytona } from '@finalai/daytona-agent-provider/sandboxes';
11
+
12
+ const box = await project.sandboxes.create(
13
+ daytona({
14
+ credential: { secretRef: 'DAYTONA_API_KEY' },
15
+ image: 'node:26',
16
+ resources: { cpu: 2, memory: 4 },
17
+ region: 'eu',
18
+ autoStopMinutes: 30,
19
+ }),
20
+ {
21
+ setup: defineSandboxSetup({
22
+ repositories: [
23
+ { alias: 'app', url: 'https://github.com/acme/app.git', integration: 'intg_…' },
24
+ ],
25
+ steps: [{ cwd: 'app', run: 'pnpm install' }],
26
+ network: { allow: ['registry.npmjs.org'] },
27
+ }),
28
+ },
29
+ );
30
+ ```
31
+
32
+ ## Provider environment
33
+
34
+ `daytona({...})` holds Daytona's own options only:
35
+
36
+ - `credential`: the Daytona API key by reference, the name of a project secret. It is
37
+ read through the host's `credentials.secret`; a missing reference or value fails with
38
+ `credential_missing` when the sandbox is created.
39
+ - `image` (built into a Daytona snapshot once, by `prepare`) or `snapshot` (an existing
40
+ one by name), and `resources` for a snapshot built from an image.
41
+ - `region`, `user`, `workingDirectory`, `labels`.
42
+ - `autoStopMinutes` (Daytona stops an idle sandbox; default 15) and `autoArchiveMinutes`.
43
+ - `park`: what parking does, `stop` (default) or `archive`. Both keep the disk.
44
+
45
+ What should be on the machine (repositories, variables, setup steps, services, named
46
+ commands, network policy, notes) is a provider-neutral sandbox setup. The platform
47
+ applies it through the sandbox handle after each attach; the provider never runs it.
48
+
49
+ ## Lifecycle
50
+
51
+ - `create` validates the options, the credential and the setup's network policy, and
52
+ records the sandbox's Daytona name. Nothing exists in Daytona yet.
53
+ - The first `attach` creates the Daytona sandbox with the setup's network policy in its
54
+ create body, so the policy is enforced from the first boot. Daytona has no deny list
55
+ and cannot mix domains and IPv4 CIDRs in one allow list; a setup asking for either is
56
+ refused at `create`.
57
+ - `attach` reports `fresh` when the disk is new (first attach, or a sandbox Daytona lost
58
+ and the provider created again under its name) and `booted` when the sandbox was
59
+ stopped, archived or still booting. A sandbox in Daytona's error state is kept for
60
+ recovery and the attach fails.
61
+ - `detach` leaves the sandbox to Daytona's auto-stop. `park` stops or archives it.
62
+ `delete` deletes it; deleting one already gone succeeds.
63
+
64
+ Its sandboxes offer `files` with write access and `shell` with execute access. The
65
+ platform gates each handle call by the grant a session holds.
66
+
67
+ ## Networking
68
+
3
69
  Compose networking through the generic `networking: SandboxNetworkingExtensionIface`
4
- configuration. The provider supplies Daytona lifecycle/firewall operations; the
5
- extension owns routing, readiness, policy persistence and lease cleanup. Final
6
- Device egress uses this same contract via `createWorkspaceDeviceNetworking` from
7
- `@finalai/final-agent-provider/sandboxes/egress`; this package has no dependency on
8
- that implementation. `workspaceNetworkingBootFence` controls the provider's
70
+ configuration. The provider supplies Daytona lifecycle and firewall operations; the
71
+ extension owns routing, readiness, policy persistence and lease cleanup, keyed by the
72
+ platform's sandbox id. `workspaceNetworkingBootFence` controls the provider's
9
73
  startup-window guarantee, independently of the extension's tunnel technology.
10
74
  A stopped sandbox's control-plane policy readback does not prove pre-boot enforcement.
11
- By default resume logs this window, then fences the running sandbox before tools.
12
- Setting the option to true refuses an unverified stopped resume. Setting it to false skips only the pre-boot fence; runtime fences requested by the networking extension and teardown fences are still attempted. An account that rejects network settings cannot provide those outer fences; the namespace guard and explicit warning-backed startup window remain the supported fallback.
13
-
14
- Daytona sandbox bindings and a public API adapter implementing
15
- `@finalai/agent-provider` contracts. Import authoring from `/sandboxes` and the
16
- provider adapter from `/sandboxes/daytona`. Credentials and transport are supplied
17
- by the host; no Final platform credential is required. Declare the Daytona API key by
18
- reference, `daytona({ credential: { secretRef: 'DAYTONA_API_KEY' } })`; it is read
19
- through the context's `credentials.secret`, and a missing reference or value fails
20
- with `credential_missing`.
75
+ By default an attach that wakes a sandbox logs this window, then fences the running
76
+ sandbox before tools. Setting the option to true refuses an unverified stopped wake.
77
+ Setting it to false skips only the pre-boot fence; runtime fences requested by the
78
+ networking extension and teardown fences are still attempted. An account that rejects
79
+ network settings cannot provide those outer fences; the namespace guard and explicit
80
+ warning-backed startup window remain the supported fallback.
21
81
 
22
82
  Managed policy capture requires a complete policy readback; omitted allowlist fields are not treated as confirmed unrestricted access. Updates explicitly replace block-all and both allowlist fields, following [Daytona’s network-control contract](https://www.daytona.io/docs/en/network-limits/). Failed managed policy confirmation re-applies the provider fence where supported.
23
83
 
@@ -25,18 +85,18 @@ Allowlist updates explicitly clear the other stored list using Daytona's require
25
85
 
26
86
  Domain-list updates explicitly set `networkBlockAll: false` in the same request for compatibility with the last public Daytona server, where domain-only updates preserve block-all. CIDR updates already imply false. See [the public server implementation](https://github.com/daytonaio/daytona/blob/v0.190.0/apps/api/src/sandbox/services/sandbox.service.ts#L3067). No intermediate allow-all request is issued.
27
87
 
28
- Legacy sandboxes with both CIDR and domain lists must be repaired through the provider API before managed opt-in. The adapter refuses mixed policy snapshots rather than silently changing their meaning. Retain the networking extension while any saved managed workspace still exists; removing it refuses resume until the original policy is explicitly restored.
88
+ Legacy sandboxes with both CIDR and domain lists must be repaired through the provider API before managed opt-in. The adapter refuses mixed policy snapshots rather than silently changing their meaning. Retain the networking extension while any managed sandbox still exists; removing it refuses attach until the original policy is explicitly restored.
29
89
 
30
90
  ## Durable processes
31
91
 
32
92
  The `daytona` sandbox offers durable processes (`SandboxCapability.DurableProcesses`:
33
- `spawn({ durable: true })` and `attachProcess`) on write and execute bindings. Each runs in
34
- a Daytona process session of its own, which a dropped handle leaves running. Its
35
- `timeoutMs` is enforced inside the sandbox by coreutils `timeout` (exit 124, or a
36
- SIGKILL 5 s later for a process that ignores SIGTERM), so the
37
- image needs `timeout` as well as bash. Attaching replays the session's log from the
38
- start and skips the bytes the caller already has, so output is retained in full while
39
- the session exists, and an attached stream starts exactly where asked. Killing a durable
40
- process deletes its session. Exited durable sessions are kept for attaching; each
41
- durable spawn deletes the oldest exited ones beyond 64. A ref from another sandbox, or
42
- of a deleted session (killed, collected, or lost with the sandbox), attaches to nothing.
93
+ `spawn({ durable: true })` and `attachProcess`). Each runs in a Daytona process session
94
+ of its own, which a dropped handle leaves running. Its `timeoutMs` is enforced inside the
95
+ sandbox by coreutils `timeout` (exit 124, or a SIGKILL 5 s later for a process that
96
+ ignores SIGTERM), so the image needs `timeout` as well as bash. Attaching replays the
97
+ session's log from the start and skips the bytes the caller already has, so output is
98
+ retained in full while the session exists, and an attached stream starts exactly where
99
+ asked. Killing a durable process deletes its session. Exited durable sessions are kept
100
+ for attaching; each durable spawn deletes the oldest exited ones beyond 64. A ref from
101
+ another sandbox, or of a deleted session (killed, collected, or lost with the sandbox),
102
+ attaches to nothing.
@@ -1,17 +1,13 @@
1
- import { SandboxAccess, type JsonValue } from '@finalai/agent-provider';
2
- import { type SandboxNetworkingExtensionIface, SandboxWorkspace, type SandboxProviderIface } from '@finalai/agent-provider/sandbox';
1
+ import type { JsonValue } from '@finalai/agent-provider';
2
+ import { NetworkPolicy, type NetworkPolicyIface, type SandboxNetworkingExtensionIface, type SandboxProviderIface, type SandboxSetupIface } from '@finalai/agent-provider/sandbox';
3
3
  import * as z from 'zod';
4
4
  import { type DaytonaClientIface, type DaytonaFetchIface, type DaytonaWebSocketFactoryIface } from "../client/index.mjs";
5
- import { DaytonaSessionEndPolicy } from "./environment.mjs";
6
5
  import { type DaytonaSandboxSessionIface } from "./session.mjs";
7
- export { DAYTONA_SANDBOX_SPECIFIER, DaytonaSessionEndPolicy } from "./environment.mjs";
6
+ export { DAYTONA_SANDBOX_SPECIFIER, DaytonaParkPolicy } from "./environment.mjs";
8
7
  export type { DaytonaSandboxSessionIface } from "./session.mjs";
9
- export declare const daytonaWorkspaceName: (options: {
8
+ export declare const daytonaSandboxName: (args: {
10
9
  organizationId: string;
11
- bindingId: string;
12
- conversationId: string | null;
13
- target: string;
14
- conversationWorkspace: boolean;
10
+ sandboxId: string;
15
11
  }) => Promise<string>;
16
12
  export interface DaytonaSandboxProviderConfigIface {
17
13
  networking?: SandboxNetworkingExtensionIface;
@@ -53,17 +49,19 @@ declare const artifactSchema: z.ZodObject<{
53
49
  }, z.core.$strip>;
54
50
  export type DaytonaSandboxArtifact = z.infer<typeof artifactSchema>;
55
51
  declare const stateSchema: z.ZodObject<{
56
- version: z.ZodLiteral<1>;
57
- sandboxId: z.ZodString;
52
+ version: z.ZodLiteral<2>;
58
53
  sandboxName: z.ZodString;
59
- workingDirectory: z.ZodString;
60
- access: z.ZodEnum<typeof SandboxAccess>;
61
- workspace: z.ZodEnum<typeof SandboxWorkspace>;
62
- onSessionEnd: z.ZodEnum<typeof DaytonaSessionEndPolicy>;
63
- setupPending: z.ZodDefault<z.ZodBoolean>;
64
- networkingManaged: z.ZodDefault<z.ZodBoolean>;
65
- workspaceId: z.ZodOptional<z.ZodString>;
54
+ sandboxId: z.ZodNullable<z.ZodString>;
55
+ workingDirectory: z.ZodNullable<z.ZodString>;
56
+ network: z.ZodNullable<z.ZodObject<{
57
+ mode: z.ZodEnum<typeof NetworkPolicy>;
58
+ allow: z.ZodOptional<z.ZodArray<z.ZodString>>;
59
+ }, z.core.$strip>>;
60
+ ports: z.ZodArray<z.ZodNumber>;
61
+ seedPending: z.ZodBoolean;
62
+ networkingManaged: z.ZodBoolean;
66
63
  }, z.core.$strip>;
67
- export type DaytonaSandboxBindingState = z.infer<typeof stateSchema>;
68
- export type DaytonaSandboxProviderIface = SandboxProviderIface<JsonValue, JsonValue, DaytonaSandboxArtifact, DaytonaSandboxBindingState, DaytonaSandboxSessionIface>;
64
+ export type DaytonaSandboxResourceState = z.infer<typeof stateSchema>;
65
+ export type DaytonaSandboxProviderIface = SandboxProviderIface<JsonValue, DaytonaSandboxArtifact, DaytonaSandboxResourceState, DaytonaSandboxSessionIface>;
66
+ export declare const daytonaNetworkPolicyOf: (setup: SandboxSetupIface | null) => NetworkPolicyIface | null;
69
67
  export declare const createDaytonaSandboxProvider: (config: DaytonaSandboxProviderConfigIface) => DaytonaSandboxProviderIface;