@vibesdotdev/agent-execution 0.0.0-stage → 1.0.0-rc.2

package/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 VIBES DEV LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# @vibesdotdev/agent-execution
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Runtime contracts for persistent code sessions, sandbox execution, voice turns,
+and fleet-host code-session relays. See [SPEC.md](SPEC.md) for ownership.
+
+## Code sessions
+
+Compose `./code-session/plugin` for the universal kind and
+`./code-session/consumer.plugin` on consumer hosts. Consumer startup activates
+the `code-session-custody` semantic `runtime/client`. The compatible
+`remoteSetupCustody(runtime)` helper uses `tryGetVibesClient` after activation.
+Disposal cancels retained remote setups and reports unconfirmed cleanup with
+typed, value-free refusals. Resolver options and descriptors are schema-admitted,
+including throwing getters and proxies.
+
+Consumer Git commits reject failed add, staged inspection, commit and hash
+lookup stages with stable typed refusals containing only operation/exit-code
+facts. Git output and caught causes stay out of public failures. Existing staged
+changes, scoped commits and author handling remain supported.
+
+Explicit teardown can also report `code-session-cleanup-unconfirmed`.
+The recoverable cleanup contract retains durable authorization outside the
+workspace until removal is confirmed, then publishes the terminal tombstone.
+Legacy relay metadata without an operation identity is adopted before the
+workspace moves. Once adopted, pending cleanup refuses ordinary session work.
+Failed moves retain durable authorization for retry after
+runtime recreation, including reclaiming an expired lease after abrupt owner
+loss. Acquisition publishes a fully prepared lease atomically; interrupted
+preparation cannot block recovery. Initial adoption uses the same lease and
+rereads the durable record before publication. Delayed adopters preserve the
+authoritative cleanup state, and retired holders cannot publish operation records
+or release a successor's lease.
+Successful cleanup leaves an idempotent terminal tombstone.
+The [relay contract](src/code-session-relay/SPEC.md) owns recovery after partial
+deletion and restart. Relay clone and push preserve complete credential leases
+for the canonical Git owner's remote, operation and expiry checks. The binding
+adapter preserves the acting-user header on forwarded broker requests.
+
+## Voice
+
+Compose `./voice/plugin` for the universal kind and semantic client, then
+`./voice/consumer.plugin` for local resolution. Consumer loaders stay in that
+explicit subpath. Resolve `VoiceClient` from `./voice/client` using
+`getVibesClient('agent-voice', runtime)`. Sessions belong to that runtime and
+close when it disposes. `./voice/agent-voice` keeps the compatible
+`ConsumerAgentVoice` and `VoiceSession` entrypoints. Inject STT, agent and TTS
+stages; their unknown results pass through the pipeline's schemas.
+
+## Verification
+
+Run rules, lint, `bun run check`, `bun run test`, and `bun run build`.
+The no-emit project includes source and tests; the build project emits production
+artifacts only. Unit tests run in-process; publish preflight owns packed-artifact
+and external consumer proof.

package/dist/code-session/agent-code-session.consumer.descriptor.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Consumer `agent/code-session` descriptor instance.
+ *
+ * Backed by a persistent, profile-owned code-session workspace + git
+ * CLI + long-lived `Bun.spawn` handles on a platform Host (see
+ * `agent-code-session.impl.consumer.ts`). `priority: 100` (consumer default),
+ * `trustLevel: '2b'` — a code session is inherently FS-writable (it edits a
+ * cloned repo), so it sits at the writable tier.
+ */
+declare const consumerCodeSessionDescriptor: {
+    id: string;
+    kind: "agent/code-session";
+    name: string;
+    priority: number;
+    surfaces: ("agent" | "worker" | "direct")[];
+    timeoutMs: number;
+    memoryLimit: number;
+    trustLevel: "0" | "1" | "3" | "2a" | "2b";
+    os: ("linux" | "macos" | "windows")[];
+    arch: ("x64" | "arm64")[];
+    runtimeConfig: {
+        environmentName?: string | undefined;
+        node?: string | undefined;
+        bun?: string | undefined;
+        setupScript?: string | undefined;
+    };
+    exposedPorts: string[];
+    allowInteractiveShell: boolean;
+    billingGates: {
+        feature: string;
+        deniedMessage: string;
+    }[];
+    description?: string | undefined;
+    tags?: string[] | undefined;
+    hardware?: string[] | undefined;
+    enabled?: boolean | undefined;
+    capabilityId?: string | undefined;
+    requiredContext?: string[] | undefined;
+    optionalContext?: string[] | undefined;
+    config?: unknown;
+    retention?: string | {
+        reason: string;
+        maxAgeDays?: number | undefined;
+        maxEntries?: number | undefined;
+        maxBytes?: number | undefined;
+        cascadeFrom?: string | undefined;
+        ageField?: string | undefined;
+        enforcedBy?: string | undefined;
+    } | undefined;
+    hostTarget?: {
+        kind: "cloud";
+    } | {
+        kind: "host";
+        hostId: string;
+    } | {
+        kind: "provisioned";
+        adapter: string;
+        region?: string | undefined;
+        size?: string | undefined;
+        image?: string | undefined;
+        repo?: string | undefined;
+        branch?: string | undefined;
+        ttlHours?: number | undefined;
+        providerConfig?: Record<string, unknown> | undefined;
+    } | undefined;
+};
+export default consumerCodeSessionDescriptor;
+//# sourceMappingURL=agent-code-session.consumer.descriptor.d.ts.map

package/dist/code-session/agent-code-session.consumer.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-code-session.consumer.descriptor.d.ts","sourceRoot":"","sources":["../../src/code-session/agent-code-session.consumer.descriptor.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,QAAA,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAmBjC,CAAC;AAEH,eAAe,6BAA6B,CAAC"}

package/dist/code-session/agent-code-session.consumer.descriptor.js

@@ -0,0 +1,31 @@
+import { createAgentCodeSessionDescriptor } from "./agent-code-session.descriptor.js";
+/**
+ * Consumer `agent/code-session` descriptor instance.
+ *
+ * Backed by a persistent, profile-owned code-session workspace + git
+ * CLI + long-lived `Bun.spawn` handles on a platform Host (see
+ * `agent-code-session.impl.consumer.ts`). `priority: 100` (consumer default),
+ * `trustLevel: '2b'` — a code session is inherently FS-writable (it edits a
+ * cloned repo), so it sits at the writable tier.
+ */
+const consumerCodeSessionDescriptor = createAgentCodeSessionDescriptor({
+    id: 'agent-code-session-bun',
+    name: 'Agent Code Session — Bun on Host',
+    description: 'Consumer persistent code session. Clones a repo under the active Vibes profile, runs long-lived processes via Bun.spawn, and performs git ops via the git CLI on a platform Host.',
+    hardware: ['consumer'],
+    os: ['linux'],
+    arch: ['x64'],
+    priority: 100,
+    // Per-call ceiling. The tool's timeoutMs is clamped to this. 30 minutes covers
+    // a sequential package test run; the native-tool wrapper still defaults to 60s
+    // unless the caller raises timeoutMs.
+    timeoutMs: 1_800_000,
+    memoryLimit: 1024,
+    trustLevel: '2b',
+    hostTarget: { kind: 'host', hostId: 'local' },
+    runtimeConfig: {},
+    exposedPorts: [],
+    allowInteractiveShell: false
+});
+export default consumerCodeSessionDescriptor;
+//# sourceMappingURL=agent-code-session.consumer.descriptor.js.map

package/dist/code-session/agent-code-session.consumer.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-code-session.consumer.descriptor.js","sourceRoot":"","sources":["../../src/code-session/agent-code-session.consumer.descriptor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gCAAgC,EAAE,MAAM,oCAAoC,CAAC;AAEtF;;;;;;;;GAQG;AACH,MAAM,6BAA6B,GAAG,gCAAgC,CAAC;IACtE,EAAE,EAAE,wBAAwB;IAC5B,IAAI,EAAE,kCAAkC;IACxC,WAAW,EACV,mLAAmL;IACpL,QAAQ,EAAE,CAAC,UAAU,CAAC;IACtB,EAAE,EAAE,CAAC,OAAO,CAAC;IACb,IAAI,EAAE,CAAC,KAAK,CAAC;IACb,QAAQ,EAAE,GAAG;IACb,+EAA+E;IAC/E,+EAA+E;IAC/E,sCAAsC;IACtC,SAAS,EAAE,SAAS;IACpB,WAAW,EAAE,IAAI;IACjB,UAAU,EAAE,IAAI;IAChB,UAAU,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE;IAC7C,aAAa,EAAE,EAAE;IACjB,YAAY,EAAE,EAAE;IAChB,qBAAqB,EAAE,KAAK;CAC5B,CAAC,CAAC;AAEH,eAAe,6BAA6B,CAAC"}

package/dist/code-session/agent-code-session.consumer.plugin.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Agent Code Session — consumer (Bun-on-a-Host) impl plugin.
+ *
+ * Loader-only sub-plugin: registers the consumer `agent/code-session`
+ * descriptor + the consumer impl loader (the `*.impl.consumer.js` static edge)
+ * against the `agent/code-session` kind declared by `@vibesdotdev/agent-execution/code-session`.
+ *
+ * Split out of the kind-declaring plugin so the universal plugin carries NO
+ * `*.impl.consumer.*` import — cloud apps load the universal plugin (to declare
+ * the kind for the cloudflare adapter) without dragging the Node-only consumer
+ * impl (node:crypto, runtime-environment-bun, Bun.spawn) into the workerd
+ * bundle. Compose this plugin ONLY in a consumer-scope vibes.config (host
+ * daemon / CLI agent build); cloud configs must NOT import it. Mirrors the
+ * disjoint-loader shape of the provider-owned cloud plugin.
+ */
+export declare const agentCodeSessionConsumerPlugin: import("@vibesdotdev/kernel").RuntimePlugin;
+export default agentCodeSessionConsumerPlugin;
+//# sourceMappingURL=agent-code-session.consumer.plugin.d.ts.map

package/dist/code-session/agent-code-session.consumer.plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-code-session.consumer.plugin.d.ts","sourceRoot":"","sources":["../../src/code-session/agent-code-session.consumer.plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAQH,eAAO,MAAM,8BAA8B,6CA6BzC,CAAC;AAEH,eAAe,8BAA8B,CAAC"}

package/dist/code-session/agent-code-session.consumer.plugin.js

@@ -0,0 +1,47 @@
+/**
+ * Agent Code Session — consumer (Bun-on-a-Host) impl plugin.
+ *
+ * Loader-only sub-plugin: registers the consumer `agent/code-session`
+ * descriptor + the consumer impl loader (the `*.impl.consumer.js` static edge)
+ * against the `agent/code-session` kind declared by `@vibesdotdev/agent-execution/code-session`.
+ *
+ * Split out of the kind-declaring plugin so the universal plugin carries NO
+ * `*.impl.consumer.*` import — cloud apps load the universal plugin (to declare
+ * the kind for the cloudflare adapter) without dragging the Node-only consumer
+ * impl (node:crypto, runtime-environment-bun, Bun.spawn) into the workerd
+ * bundle. Compose this plugin ONLY in a consumer-scope vibes.config (host
+ * daemon / CLI agent build); cloud configs must NOT import it. Mirrors the
+ * disjoint-loader shape of the provider-owned cloud plugin.
+ */
+import { createRuntimePlugin, loader } from '@vibesdotdev/kernel';
+import { runtimeRpcExecutionPlugin } from '@vibesdotdev/kernel-rpc/execution';
+import consumerCodeSessionDescriptor from "./agent-code-session.consumer.descriptor.js";
+import { getVibesClient, runtimeClientPlugin } from '@vibesdotdev/kernel/client';
+import { remoteSetupCustodyDescriptor } from "./remote-setup-custody.js";
+export const agentCodeSessionConsumerPlugin = createRuntimePlugin({
+    id: 'agent-code-session-consumer',
+    name: 'Agent Code Session — Bun on Host (consumer impl)',
+    description: 'Consumer persistent code session for the agent/code-session kind. Clones a repo under the active Vibes profile, runs long-lived processes via Bun.spawn, performs git ops via the git CLI. Consumer-scope only — not loaded by cloud apps.',
+    dependencies: ['agent-code-session'],
+    descriptors: [consumerCodeSessionDescriptor],
+    loaders: [
+        loader(consumerCodeSessionDescriptor.id, { kind: 'agent/code-session', scope: 'consumer' }, () => import("./agent-code-session.impl.consumer.js"))
+    ],
+    async onRegister(runtime) {
+        // A remote spawn is acquired through the runtime-owned `execution-wire`
+        // client (kernel-rpc). The consumer impl resolves it synchronously at
+        // dispatch, so the plugin that owns the impl also composes its owner.
+        await runtime.registerPlugin(runtimeRpcExecutionPlugin);
+        if (!runtime.hasKind('runtime/client'))
+            await runtime.registerPlugin(runtimeClientPlugin);
+        runtime.registerDescriptor('runtime/client', remoteSetupCustodyDescriptor);
+        runtime.registerLoader('runtime/client', remoteSetupCustodyDescriptor.id, async () => ({ impl: (await import("./remote-setup-custody.js")).RemoteSetupCustodyClient }));
+        await getVibesClient(remoteSetupCustodyDescriptor.id, runtime);
+    },
+    onDispose(runtime) {
+        return runtime.query('runtime/client')
+            .withId(remoteSetupCustodyDescriptor.id).peek?.()?.dispose();
+    }
+});
+export default agentCodeSessionConsumerPlugin;
+//# sourceMappingURL=agent-code-session.consumer.plugin.js.map

package/dist/code-session/agent-code-session.consumer.plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-code-session.consumer.plugin.js","sourceRoot":"","sources":["../../src/code-session/agent-code-session.consumer.plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,mBAAmB,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,EAAE,yBAAyB,EAAE,MAAM,mCAAmC,CAAC;AAC9E,OAAO,6BAA6B,MAAM,6CAA6C,CAAC;AACxF,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjF,OAAO,EAAE,4BAA4B,EAAiC,MAAM,2BAA2B,CAAC;AAExG,MAAM,CAAC,MAAM,8BAA8B,GAAG,mBAAmB,CAAC;IACjE,EAAE,EAAE,6BAA6B;IACjC,IAAI,EAAE,kDAAkD;IACxD,WAAW,EACV,4OAA4O;IAC7O,YAAY,EAAE,CAAC,oBAAoB,CAAC;IACpC,WAAW,EAAE,CAAC,6BAA6B,CAAC;IAC5C,OAAO,EAAE;QACR,MAAM,CACL,6BAA6B,CAAC,EAAE,EAChC,EAAE,IAAI,EAAE,oBAAoB,EAAE,KAAK,EAAE,UAAU,EAAE,EACjD,GAAG,EAAE,CAAC,MAAM,CAAC,uCAAuC,CAAC,CACrD;KACD;IAED,KAAK,CAAC,UAAU,CAAC,OAAO;QACvB,wEAAwE;QACxE,sEAAsE;QACtE,sEAAsE;QACtE,MAAM,OAAO,CAAC,cAAc,CAAC,yBAAyB,CAAC,CAAC;QACxD,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,gBAAgB,CAAC;YAAE,MAAM,OAAO,CAAC,cAAc,CAAC,mBAAmB,CAAC,CAAC;QAC1F,OAAO,CAAC,kBAAkB,CAAC,gBAAgB,EAAE,4BAA4B,CAAC,CAAC;QAC3E,OAAO,CAAC,cAAc,CAAC,gBAAgB,EAAE,4BAA4B,CAAC,EAAE,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,MAAM,MAAM,CAAC,2BAA2B,CAAC,CAAC,CAAC,wBAAwB,EAAE,CAAC,CAAC,CAAC;QACxK,MAAM,cAAc,CAA2B,4BAA4B,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IAC1F,CAAC;IACD,SAAS,CAAC,OAAO;QAChB,OAAO,OAAO,CAAC,KAAK,CAAgE,gBAAgB,CAAC;aACnG,MAAM,CAAC,4BAA4B,CAAC,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC;IAC/D,CAAC;CACD,CAAC,CAAC;AAEH,eAAe,8BAA8B,CAAC"}

package/dist/code-session/agent-code-session.descriptor.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Agent Code Session Descriptor Schema (WS3)
+ *
+ * Defines the `agent/code-session` runtime kind. A code session EXTENDS the
+ * `agent/sandbox` contract from a one-shot throwaway exec into a *persistent*
+ * workspace bound to `{repository, hostTarget, runtimeConfig}`:
+ *
+ *   one-shot agent/sandbox   →   persistent agent/code-session
+ *   ──────────────────────       ─────────────────────────────
+ *   run snippet, capture,        clone repo once, then attach/run/edit/commit
+ *   tear down workspace          across many calls; workspace survives until
+ *                                an explicit teardown; long-lived procs +
+ *                                exposed ports + a preview URL.
+ *
+ * Why a kind: the *how* of a persistent workspace is scope-specific — a
+ * consumer Host runs a profile-owned workspace + long-lived `Bun.spawn`
+ * handles, cloud runs a per-session Cloudflare Sandbox — but the lifecycle
+ * contract (initialize → attach → runCommand → read/write/patch → git → expose
+ * port → teardown) is universal. Build mode's code-session tools call one kind
+ * regardless of where the bytes run.
+ *
+ * The descriptor mirrors `AgentSandboxDescriptorSchema` (same trust ladder,
+ * priority, timeout/memory ceilings) and adds the session-binding fields.
+ */
+import * as z from 'zod/v4';
+/** Surfaces a code session can be addressed through (mirrors agent/sandbox). */
+export declare const CodeSessionSurfaceSchema: z.ZodEnum<{
+    agent: "agent";
+    worker: "worker";
+    direct: "direct";
+}>;
+export type CodeSessionSurface = z.infer<typeof CodeSessionSurfaceSchema>;
+/**
+ * A billing gate this execution surface requires BEFORE a session may start.
+ * Each gate is a billing feature slug checked via the account billing client
+ * (`checkQuota(feature) → allowed`), plus the operator-facing message to
+ * surface on denial. The RESOLVED descriptor's gates are enforced by the
+ * platform route — so a surface declares its own billing posture here rather
+ * than the endpoint growing a `hostTarget.kind` conditional.
+ *
+ * `feature` values are `@vibesdotdev/account` FEATURE_SLUGS (a stable public
+ * contract — the descriptor declares the slug string rather than importing the
+ * account package, keeping the runtime tier billing-agnostic). A composition
+ * point that imports both (platform-web) guards them against drift.
+ */
+export declare const CodeSessionBillingGateSchema: z.ZodObject<{
+    feature: z.ZodString;
+    deniedMessage: z.ZodString;
+}, z.core.$strip>;
+export type CodeSessionBillingGate = z.infer<typeof CodeSessionBillingGateSchema>;
+/**
+ * Trust ladder, aligned with the agent capability-tier values. A code session
+ * is inherently FS-writable (it edits a repo), so it sits at the same tier as
+ * the writable sandbox (`'2b'`+).
+ */
+export declare const CodeSessionTrustLevelSchema: z.ZodEnum<{
+    0: "0";
+    1: "1";
+    3: "3";
+    "2a": "2a";
+    "2b": "2b";
+}>;
+export type CodeSessionTrustLevel = z.infer<typeof CodeSessionTrustLevelSchema>;
+/** Lowest trust level at which a code session (writable repo workspace) may run. */
+export declare const CODE_SESSION_MIN_TRUST_LEVEL: CodeSessionTrustLevel;
+/**
+ * Runtime toolchain pinning for the session workspace. Advisory on consumer
+ * (uses whatever's on the Host PATH unless a version manager is present);
+ * the cloud adapter pins exact images.
+ */
+export declare const CodeSessionRuntimeConfigSchema: z.ZodObject<{
+    environmentName: z.ZodOptional<z.ZodString>;
+    node: z.ZodOptional<z.ZodString>;
+    bun: z.ZodOptional<z.ZodString>;
+    setupScript: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type CodeSessionRuntimeConfig = z.infer<typeof CodeSessionRuntimeConfigSchema>;
+export declare const AgentCodeSessionDescriptorSchema: z.ZodObject<{
+    id: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    hardware: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    capabilityId: z.ZodOptional<z.ZodString>;
+    requiredContext: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    optionalContext: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    config: z.ZodOptional<z.ZodUnknown>;
+    retention: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+        maxAgeDays: z.ZodOptional<z.ZodNumber>;
+        maxEntries: z.ZodOptional<z.ZodNumber>;
+        maxBytes: z.ZodOptional<z.ZodNumber>;
+        cascadeFrom: z.ZodOptional<z.ZodString>;
+        ageField: z.ZodOptional<z.ZodString>;
+        reason: z.ZodString;
+        enforcedBy: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>]>>;
+    kind: z.ZodLiteral<"agent/code-session">;
+    name: z.ZodDefault<z.ZodString>;
+    priority: z.ZodDefault<z.ZodNumber>;
+    surfaces: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+        agent: "agent";
+        worker: "worker";
+        direct: "direct";
+    }>>>;
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+    memoryLimit: z.ZodDefault<z.ZodNumber>;
+    trustLevel: z.ZodDefault<z.ZodEnum<{
+        0: "0";
+        1: "1";
+        3: "3";
+        "2a": "2a";
+        "2b": "2b";
+    }>>;
+    os: z.ZodArray<z.ZodEnum<{
+        linux: "linux";
+        macos: "macos";
+        windows: "windows";
+    }>>;
+    arch: z.ZodArray<z.ZodEnum<{
+        x64: "x64";
+        arm64: "arm64";
+    }>>;
+    hostTarget: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        kind: z.ZodLiteral<"cloud">;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"host">;
+        hostId: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        kind: z.ZodLiteral<"provisioned">;
+        adapter: z.ZodString;
+        region: z.ZodOptional<z.ZodString>;
+        size: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodString>;
+        repo: z.ZodOptional<z.ZodString>;
+        branch: z.ZodOptional<z.ZodString>;
+        ttlHours: z.ZodOptional<z.ZodNumber>;
+        providerConfig: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>], "kind">>;
+    runtimeConfig: z.ZodDefault<z.ZodObject<{
+        environmentName: z.ZodOptional<z.ZodString>;
+        node: z.ZodOptional<z.ZodString>;
+        bun: z.ZodOptional<z.ZodString>;
+        setupScript: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    exposedPorts: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    allowInteractiveShell: z.ZodDefault<z.ZodBoolean>;
+    billingGates: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        feature: z.ZodString;
+        deniedMessage: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type AgentCodeSessionDescriptor = z.infer<typeof AgentCodeSessionDescriptorSchema>;
+/**
+ * Author an `agent/code-session` descriptor without restating the `kind`.
+ * Mirrors `createAgentSandboxDescriptor`.
+ */
+export declare function createAgentCodeSessionDescriptor(options: Omit<Partial<AgentCodeSessionDescriptor>, 'kind' | 'os' | 'arch'> & {
+    id: string;
+    os: AgentCodeSessionDescriptor['os'];
+    arch: AgentCodeSessionDescriptor['arch'];
+}): AgentCodeSessionDescriptor;
+export default AgentCodeSessionDescriptorSchema;
+//# sourceMappingURL=agent-code-session.descriptor.d.ts.map

package/dist/code-session/agent-code-session.descriptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-code-session.descriptor.d.ts","sourceRoot":"","sources":["../../src/code-session/agent-code-session.descriptor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,CAAC,MAAM,QAAQ,CAAC;AAI5B,gFAAgF;AAChF,eAAO,MAAM,wBAAwB;;;;EAAwC,CAAC;AAC9E,MAAM,MAAM,kBAAkB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE1E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,4BAA4B;;;iBAKvC,CAAC;AACH,MAAM,MAAM,sBAAsB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,4BAA4B,CAAC,CAAC;AAElF;;;;GAIG;AACH,eAAO,MAAM,2BAA2B;;;;;;EAAsC,CAAC;AAC/E,MAAM,MAAM,qBAAqB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAEhF,oFAAoF;AACpF,eAAO,MAAM,4BAA4B,EAAE,qBAA4B,CAAC;AAExE;;;;GAIG;AACH,eAAO,MAAM,8BAA8B;;;;;iBASzC,CAAC;AACH,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,8BAA8B,CAAC,CAAC;AAEtF,eAAO,MAAM,gCAAgC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA6C3C,CAAC;AAEH,MAAM,MAAM,0BAA0B,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gCAAgC,CAAC,CAAC;AAE1F;;;GAGG;AACH,wBAAgB,gCAAgC,CAC/C,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,0BAA0B,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC,GAAG;IAC5E,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,0BAA0B,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,EAAE,0BAA0B,CAAC,MAAM,CAAC,CAAC;CACzC,GACC,0BAA0B,CAK5B;AAED,eAAe,gCAAgC,CAAC"}

package/dist/code-session/agent-code-session.descriptor.js

@@ -0,0 +1,129 @@
+/**
+ * Agent Code Session Descriptor Schema (WS3)
+ *
+ * Defines the `agent/code-session` runtime kind. A code session EXTENDS the
+ * `agent/sandbox` contract from a one-shot throwaway exec into a *persistent*
+ * workspace bound to `{repository, hostTarget, runtimeConfig}`:
+ *
+ *   one-shot agent/sandbox   →   persistent agent/code-session
+ *   ──────────────────────       ─────────────────────────────
+ *   run snippet, capture,        clone repo once, then attach/run/edit/commit
+ *   tear down workspace          across many calls; workspace survives until
+ *                                an explicit teardown; long-lived procs +
+ *                                exposed ports + a preview URL.
+ *
+ * Why a kind: the *how* of a persistent workspace is scope-specific — a
+ * consumer Host runs a profile-owned workspace + long-lived `Bun.spawn`
+ * handles, cloud runs a per-session Cloudflare Sandbox — but the lifecycle
+ * contract (initialize → attach → runCommand → read/write/patch → git → expose
+ * port → teardown) is universal. Build mode's code-session tools call one kind
+ * regardless of where the bytes run.
+ *
+ * The descriptor mirrors `AgentSandboxDescriptorSchema` (same trust ladder,
+ * priority, timeout/memory ceilings) and adds the session-binding fields.
+ */
+import * as z from 'zod/v4';
+import { RuntimeDescriptorSchema } from '@vibesdotdev/kernel/schemas/descriptor';
+import { SessionHostTargetSchema } from "./host-target.js";
+/** Surfaces a code session can be addressed through (mirrors agent/sandbox). */
+export const CodeSessionSurfaceSchema = z.enum(['agent', 'worker', 'direct']);
+/**
+ * A billing gate this execution surface requires BEFORE a session may start.
+ * Each gate is a billing feature slug checked via the account billing client
+ * (`checkQuota(feature) → allowed`), plus the operator-facing message to
+ * surface on denial. The RESOLVED descriptor's gates are enforced by the
+ * platform route — so a surface declares its own billing posture here rather
+ * than the endpoint growing a `hostTarget.kind` conditional.
+ *
+ * `feature` values are `@vibesdotdev/account` FEATURE_SLUGS (a stable public
+ * contract — the descriptor declares the slug string rather than importing the
+ * account package, keeping the runtime tier billing-agnostic). A composition
+ * point that imports both (platform-web) guards them against drift.
+ */
+export const CodeSessionBillingGateSchema = z.object({
+    /** Account billing feature slug (e.g. 'build-mode-access', 'sandbox-uptime-minutes'). */
+    feature: z.string().min(1),
+    /** 403 message when this gate denies (e.g. 'Code mode requires the Plus plan or higher'). */
+    deniedMessage: z.string().min(1)
+});
+/**
+ * Trust ladder, aligned with the agent capability-tier values. A code session
+ * is inherently FS-writable (it edits a repo), so it sits at the same tier as
+ * the writable sandbox (`'2b'`+).
+ */
+export const CodeSessionTrustLevelSchema = z.enum(['0', '1', '2a', '2b', '3']);
+/** Lowest trust level at which a code session (writable repo workspace) may run. */
+export const CODE_SESSION_MIN_TRUST_LEVEL = '2b';
+/**
+ * Runtime toolchain pinning for the session workspace. Advisory on consumer
+ * (uses whatever's on the Host PATH unless a version manager is present);
+ * the cloud adapter pins exact images.
+ */
+export const CodeSessionRuntimeConfigSchema = z.object({
+    /** Friendly environment label recorded for resume/UI. */
+    environmentName: z.string().optional(),
+    /** Node major (e.g. '20', '22'); undefined = Host default. */
+    node: z.string().optional(),
+    /** Bun version (e.g. '1.3'); undefined = Host default. */
+    bun: z.string().optional(),
+    /** Optional shell setup script run once after clone before the session is exposed. */
+    setupScript: z.string().optional()
+});
+export const AgentCodeSessionDescriptorSchema = RuntimeDescriptorSchema.extend({
+    kind: z.literal('agent/code-session'),
+    /** Human label for selectors/logs. */
+    name: z.string().default('Agent Code Session'),
+    /**
+     * Selection priority when multiple impls match the scope. Consumer defaults
+     * to 100, cloud sibling to 110 (disjoint hardware, so priority is only a
+     * defensive tie-breaker).
+     */
+    priority: z.number().int().default(100),
+    /** Surfaces this session can be reached through. */
+    surfaces: z.array(CodeSessionSurfaceSchema).default(['agent', 'worker', 'direct']),
+    /** Wall-clock budget for a single `runCommand` before it is aborted. */
+    timeoutMs: z.number().int().positive().default(300_000),
+    /** Soft memory ceiling for session processes, in megabytes. */
+    memoryLimit: z.number().int().positive().default(1024),
+    /** Trust ceiling for this session (gates writable-FS / network). */
+    trustLevel: CodeSessionTrustLevelSchema.default('2b'),
+    /**
+     * Operating systems this impl declares. The resolver keeps a candidate only
+     * when this list includes the requested OS. Omission does not become linux.
+     */
+    os: z.array(z.enum(['linux', 'macos', 'windows'])).min(1),
+    /**
+     * CPU architectures this impl declares. Omission does not become x64.
+     */
+    arch: z.array(z.enum(['x64', 'arm64'])).min(1),
+    /** Where the session executes (cloud CF Sandbox vs platform Host). */
+    hostTarget: SessionHostTargetSchema.optional(),
+    /** Toolchain pinning for the workspace. */
+    runtimeConfig: CodeSessionRuntimeConfigSchema.default({}),
+    /** Ports the session may expose for preview (string spec, e.g. '5173'). */
+    exposedPorts: z.array(z.string()).default([]),
+    /** Whether an interactive shell is allowed in this session. */
+    allowInteractiveShell: z.boolean().default(false),
+    /**
+     * Billing gates enforced BEFORE a session starts on this surface. The route
+     * enforces whatever the RESOLVED descriptor declares — so a new execution
+     * surface gates itself here instead of the endpoint growing a `hostTarget`
+     * conditional. Empty (the default) = FREE: a session that runs on the user's
+     * OWN hardware (a fleet host / consumer Host) is rated zero, so it carries no
+     * entitlement gate. The cloud descriptor declares the build-mode + sandbox
+     * quota gates because it runs on OUR metered compute.
+     */
+    billingGates: z.array(CodeSessionBillingGateSchema).default([])
+});
+/**
+ * Author an `agent/code-session` descriptor without restating the `kind`.
+ * Mirrors `createAgentSandboxDescriptor`.
+ */
+export function createAgentCodeSessionDescriptor(options) {
+    return AgentCodeSessionDescriptorSchema.parse({
+        ...options,
+        kind: 'agent/code-session'
+    });
+}
+export default AgentCodeSessionDescriptorSchema;
+//# sourceMappingURL=agent-code-session.descriptor.js.map

package/dist/code-session/agent-code-session.descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-code-session.descriptor.js","sourceRoot":"","sources":["../../src/code-session/agent-code-session.descriptor.ts"],"names":[],"mappings":"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"}