veryfront 0.1.274 → 0.1.276

package/esm/src/sandbox/sandbox.js

@@ -10,6 +10,21 @@ import * as dntShim from "../../_dnt.shims.js";
 import { createError, INITIALIZATION_ERROR, REQUEST_ERROR, TIMEOUT_ERROR, toError, } from "../errors/index.js";
 import { getVeryfrontCloudAuthToken } from "../platform/cloud/resolver.js";
 import { getHostEnv } from "../platform/compat/process.js";
+import { LazySandbox } from "./lazy-sandbox.js";
+export function resolveSandboxApiUrl(options = {}) {
+    return options.apiUrl ||
+        getHostEnv("VERYFRONT_API_URL") ||
+        "https://api.veryfront.com";
+}
+export function resolveSandboxAuthToken(options = {}) {
+    const authToken = options.authToken?.trim() || getVeryfrontCloudAuthToken();
+    if (authToken)
+        return authToken;
+    throw toError(createError({
+        type: "config",
+        message: "Sandbox auth not configured. Set VERYFRONT_API_TOKEN, provide request-scoped Veryfront credentials, or pass authToken explicitly.",
+    }));
+}
 /** Client for isolated ephemeral compute environments with command execution and file I/O. */
 export class Sandbox {
     endpoint;
@@ -23,18 +38,10 @@ export class Sandbox {
         this.apiUrl = apiUrl;
     }
     static resolveApiUrl(options = {}) {
-        return options.apiUrl ||
-            getHostEnv("VERYFRONT_API_URL") ||
-            "https://api.veryfront.com";
+        return resolveSandboxApiUrl(options);
     }
     static resolveAuthToken(options = {}) {
-        const authToken = options.authToken?.trim() || getVeryfrontCloudAuthToken();
-        if (authToken)
-            return authToken;
-        throw toError(createError({
-            type: "config",
-            message: "Sandbox auth not configured. Set VERYFRONT_API_TOKEN, provide request-scoped Veryfront credentials, or pass authToken explicitly.",
-        }));
+        return resolveSandboxAuthToken(options);
     }
     /** Create a new sandbox session. Claims a warm pod or creates a new one. */
     static async create(options = {}) {
@@ -112,25 +119,11 @@ export class Sandbox {
         };
     }
     static async waitForReady(apiUrl, id, authToken, maxWaitMs = 60_000, pollIntervalMs = 2_000) {
-        const start = Date.now();
-        while (Date.now() - start < maxWaitMs) {
-            // no cleanup needed: one-shot
-            await new Promise((r) => dntShim.setTimeout(r, pollIntervalMs));
-            const res = await fetch(`${apiUrl}/sandbox-sessions/${id}`, {
-                headers: { Authorization: `Bearer ${authToken}` },
-            });
-            if (res.ok) {
-                const data = await res.json();
-                if (data.status === "running")
-                    return;
-                if (data.status === "error" || data.status === "deleting") {
-                    throw INITIALIZATION_ERROR.create({
-                        detail: `Sandbox failed to start: status=${data.status}`,
-                    });
-                }
-            }
-        }
-        throw TIMEOUT_ERROR.create({ detail: "Sandbox did not become ready within timeout" });
+        await waitForSandboxReady({ apiUrl, id, authToken, maxWaitMs, pollIntervalMs });
+    }
+    /** Create a lazily-provisioned sandbox session with automatic heartbeats. */
+    static createLazy(options = {}) {
+        return new LazySandbox(options);
     }
     /** Execute a bash command in the sandbox and return buffered result. */
     async executeCommand(command, options) {
@@ -326,3 +319,26 @@ export class Sandbox {
         return this.endpoint;
     }
 }
+export async function waitForSandboxReady(input) {
+    const maxWaitMs = input.maxWaitMs ?? 60_000;
+    const pollIntervalMs = input.pollIntervalMs ?? 2_000;
+    const start = Date.now();
+    while (Date.now() - start < maxWaitMs) {
+        await new Promise((resolve) => dntShim.setTimeout(resolve, pollIntervalMs));
+        const res = await fetch(`${input.apiUrl}/sandbox-sessions/${input.id}`, {
+            headers: { Authorization: `Bearer ${input.authToken}` },
+        });
+        if (!res.ok) {
+            continue;
+        }
+        const data = await res.json();
+        if (data.status === "running")
+            return;
+        if (data.status === "error" || data.status === "deleting") {
+            throw INITIALIZATION_ERROR.create({
+                detail: `Sandbox failed to start: status=${data.status}`,
+            });
+        }
+    }
+    throw TIMEOUT_ERROR.create({ detail: "Sandbox did not become ready within timeout" });
+}

package/esm/src/utils/version-constant.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.1.274";
+export declare const VERSION = "0.1.276";
 //# sourceMappingURL=version-constant.d.ts.map

package/esm/src/utils/version-constant.js

@@ -1,3 +1,3 @@
 // Keep in sync with deno.json version.
 // scripts/release.ts updates this constant during releases.
-export const VERSION = "0.1.274";
+export const VERSION = "0.1.276";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "veryfront",
-  "version": "0.1.274",
+  "version": "0.1.276",
   "description": "The simplest way to build AI-powered apps",
   "keywords": [
     "react",

package/src/deno.js

@@ -1,6 +1,6 @@
 export default {
   "name": "veryfront",
-  "version": "0.1.274",
+  "version": "0.1.276",
   "license": "Apache-2.0",
   "nodeModulesDir": "auto",
   "workspace": [

package/src/src/agent/agent-service.ts

@@ -16,6 +16,16 @@ export interface DurableRunSink<
   cancelRun(run: TRun, terminalState: TTerminalState): Promise<void> | void;
 }
 
+/**
+ * Placeholder host-facing server config reserved for the future hosted service
+ * implementation.
+ */
+export interface AgentServiceServerConfig {
+  port?: number;
+  basePath?: string;
+  cors?: boolean;
+}
+
 /**
  * Phase-0 contract draft for the future framework-owned hosted agent service.
  */
@@ -25,7 +35,9 @@ export interface AgentContract<
   TEvent = unknown,
   TTerminalState = unknown,
 > {
+  serviceName: string;
   agent: Agent;
+  server?: AgentServiceServerConfig;
   durableRunSink?: DurableRunSink<TStartInput, TRun, TEvent, TTerminalState>;
 }
 

package/src/src/agent/index.ts

@@ -144,6 +144,7 @@ export { agent } from "./factory.js";
 export {
   type AgentContract,
   type AgentServiceDefinition,
+  type AgentServiceServerConfig,
   defineAgentService,
   type DurableRunSink,
 } from "./agent-service.js";

package/src/src/sandbox/index.ts

@@ -33,3 +33,4 @@ export {
   type SandboxOptions,
   type SandboxSession,
 } from "./sandbox.js";
+export { LazySandbox, type LazySandboxOptions } from "./lazy-sandbox.js";

package/src/src/sandbox/lazy-sandbox.ts

@@ -0,0 +1,504 @@
+import * as dntShim from "../../_dnt.shims.js";
+import { REQUEST_ERROR } from "../errors/index.js";
+import {
+  type CommandJob,
+  type CommandJobOutput,
+  type CommandJobStatus,
+  type ExecOptions,
+  type ExecResult,
+  type ExecStreamEvent,
+  resolveSandboxApiUrl,
+  resolveSandboxAuthToken,
+  type SandboxOptions,
+  waitForSandboxReady,
+} from "./sandbox.js";
+
+export interface LazySandboxOptions extends SandboxOptions {
+  getProjectId?: () => string | null | undefined;
+  startupTimeoutMs?: number;
+  pollIntervalMs?: number;
+  heartbeatIntervalMs?: number;
+  heartbeatGraceMs?: number;
+}
+
+interface SandboxSessionRecord {
+  id: string;
+  endpoint: string;
+  status: string;
+}
+
+const DEFAULT_STARTUP_TIMEOUT_MS = 180_000;
+const DEFAULT_POLL_INTERVAL_MS = 2_000;
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 30_000;
+const DEFAULT_HEARTBEAT_GRACE_MS = 5_000;
+
+/** Lazily provisions sandbox sessions and keeps them alive while in use. */
+export class LazySandbox {
+  private readonly apiUrl: string;
+  private readonly authToken: string;
+  private readonly getProjectId: () => string | null | undefined;
+  private readonly startupTimeoutMs: number;
+  private readonly pollIntervalMs: number;
+  private readonly heartbeatIntervalMs: number;
+  private readonly heartbeatGraceMs: number;
+
+  private endpoint: string | null = null;
+  private sessionId: string | null = null;
+  private sessionProjectId: string | null = null;
+  private ensurePromise: Promise<void> | null = null;
+  private closePromise: Promise<void> | null = null;
+  private heartbeatPromise: Promise<void> | null = null;
+  private heartbeatTimer: ReturnType<typeof dntShim.setInterval> | null = null;
+  private lastHeartbeatAt = 0;
+
+  constructor(options: LazySandboxOptions = {}) {
+    this.apiUrl = resolveSandboxApiUrl(options);
+    this.authToken = resolveSandboxAuthToken(options);
+    this.getProjectId = options.getProjectId ?? (() => options.projectId);
+    this.startupTimeoutMs = options.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS;
+    this.pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+    this.heartbeatGraceMs = options.heartbeatGraceMs ?? DEFAULT_HEARTBEAT_GRACE_MS;
+  }
+
+  async ensure(): Promise<void> {
+    if (this.endpoint) return;
+    if (this.ensurePromise) {
+      await this.ensurePromise;
+      return;
+    }
+
+    const promise = this.bootstrapSession();
+    this.ensurePromise = promise;
+
+    try {
+      await promise;
+    } finally {
+      if (this.ensurePromise === promise) {
+        this.ensurePromise = null;
+      }
+    }
+  }
+
+  async executeCommand(command: string, options?: ExecOptions): Promise<ExecResult> {
+    let stdout = "";
+    let stderr = "";
+    let exitCode = 1;
+
+    for await (const event of this.executeStream(command, options)) {
+      switch (event.type) {
+        case "stdout":
+          stdout += event.data ?? "";
+          break;
+        case "stderr":
+          stderr += event.data ?? "";
+          break;
+        case "exit":
+          exitCode = event.exitCode ?? 1;
+          break;
+      }
+    }
+
+    return { stdout, stderr, exitCode };
+  }
+
+  async *executeStream(command: string, options?: ExecOptions): AsyncGenerator<ExecStreamEvent> {
+    await this.touchSession();
+
+    const res = await fetch(`${this.requireEndpoint()}/exec`, {
+      method: "POST",
+      headers: this.jsonHeaders(),
+      body: JSON.stringify({ command, ...options }),
+    });
+
+    if (!res.ok) {
+      throw REQUEST_ERROR.create({ detail: `Exec failed: ${res.status} ${await res.text()}` });
+    }
+
+    if (!res.body) {
+      throw new Error("Exec response has no body");
+    }
+
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split("\n");
+      buffer = lines.pop() ?? "";
+
+      for (const line of lines) {
+        if (!line.trim()) continue;
+        yield JSON.parse(line) as ExecStreamEvent;
+      }
+    }
+
+    if (buffer.trim()) {
+      yield JSON.parse(buffer) as ExecStreamEvent;
+    }
+  }
+
+  async readFile(path: string): Promise<string> {
+    await this.touchSession();
+
+    const res = await fetch(`${this.requireEndpoint()}/file?path=${encodeURIComponent(path)}`, {
+      headers: this.authHeaders(),
+    });
+
+    if (!res.ok) {
+      throw REQUEST_ERROR.create({ detail: `Read file failed: ${res.status} ${await res.text()}` });
+    }
+
+    return await res.text();
+  }
+
+  async writeFiles(files: Array<{ path: string; content: string }>): Promise<void> {
+    await this.touchSession();
+
+    const res = await fetch(`${this.requireEndpoint()}/files`, {
+      method: "POST",
+      headers: this.jsonHeaders(),
+      body: JSON.stringify({ files }),
+    });
+
+    if (!res.ok) {
+      throw REQUEST_ERROR.create({
+        detail: `Write files failed: ${res.status} ${await res.text()}`,
+      });
+    }
+  }
+
+  async startCommandJob(command: string, options?: ExecOptions): Promise<CommandJob> {
+    await this.touchSession();
+
+    const res = await fetch(`${this.requireEndpoint()}/exec/jobs`, {
+      method: "POST",
+      headers: this.jsonHeaders(),
+      body: JSON.stringify({ command, ...options }),
+    });
+
+    if (!res.ok) {
+      throw REQUEST_ERROR.create({
+        detail: `Start command job failed: ${res.status} ${await res.text()}`,
+      });
+    }
+
+    return mapCommandJob(await res.json());
+  }
+
+  async getCommandJob(jobId: string): Promise<CommandJob> {
+    await this.ensure();
+
+    const res = await fetch(`${this.requireEndpoint()}/exec/jobs/${jobId}`, {
+      headers: this.authHeaders(),
+    });
+
+    if (!res.ok) {
+      throw REQUEST_ERROR.create({
+        detail: `Get command job failed: ${res.status} ${await res.text()}`,
+      });
+    }
+
+    return mapCommandJob(await res.json());
+  }
+
+  async getCommandJobOutput(jobId: string): Promise<CommandJobOutput> {
+    await this.ensure();
+
+    const res = await fetch(`${this.requireEndpoint()}/exec/jobs/${jobId}/output`, {
+      headers: this.authHeaders(),
+    });
+
+    if (!res.ok) {
+      throw REQUEST_ERROR.create({
+        detail: `Get command job output failed: ${res.status} ${await res.text()}`,
+      });
+    }
+
+    const json = await res.json();
+    return {
+      ...mapCommandJob(json),
+      stdout: json.stdout,
+      stderr: json.stderr,
+      stdoutTruncated: json.stdout_truncated,
+      stderrTruncated: json.stderr_truncated,
+    };
+  }
+
+  async listCommandJobs(): Promise<CommandJob[]> {
+    await this.ensure();
+
+    const res = await fetch(`${this.requireEndpoint()}/exec/jobs`, {
+      headers: this.authHeaders(),
+    });
+
+    if (!res.ok) {
+      throw REQUEST_ERROR.create({
+        detail: `List command jobs failed: ${res.status} ${await res.text()}`,
+      });
+    }
+
+    const json = await res.json();
+    const jobs = Array.isArray(json) ? json : (json.jobs ?? []);
+    return jobs.map((job: Record<string, unknown>) => mapCommandJob(job));
+  }
+
+  async cancelCommandJob(jobId: string): Promise<CommandJob> {
+    await this.ensure();
+
+    const res = await fetch(`${this.requireEndpoint()}/exec/jobs/${jobId}/cancel`, {
+      method: "POST",
+      headers: this.authHeaders(),
+    });
+
+    if (!res.ok) {
+      throw REQUEST_ERROR.create({
+        detail: `Cancel command job failed: ${res.status} ${await res.text()}`,
+      });
+    }
+
+    return mapCommandJob(await res.json());
+  }
+
+  async heartbeat(force = false): Promise<void> {
+    const currentSessionId = this.sessionId;
+    if (!currentSessionId) return;
+
+    if (this.heartbeatPromise) {
+      await this.heartbeatPromise;
+      return;
+    }
+
+    if (
+      !force && this.lastHeartbeatAt > 0 &&
+      Date.now() - this.lastHeartbeatAt < this.heartbeatGraceMs
+    ) {
+      return;
+    }
+
+    const promise = (async () => {
+      const res = await fetch(`${this.apiUrl}/sandbox-sessions/${currentSessionId}/heartbeat`, {
+        method: "POST",
+        headers: this.authHeaders(),
+      });
+
+      if (!res.ok) {
+        if (this.sessionId === currentSessionId) {
+          await this.deleteSession(currentSessionId);
+          this.resetSessionState(currentSessionId);
+        }
+
+        throw new Error(`Sandbox heartbeat failed: ${res.status} ${await res.text()}`);
+      }
+
+      this.lastHeartbeatAt = Date.now();
+    })();
+
+    this.heartbeatPromise = promise;
+
+    try {
+      await promise;
+    } finally {
+      if (this.heartbeatPromise === promise) {
+        this.heartbeatPromise = null;
+      }
+    }
+  }
+
+  async close(): Promise<void> {
+    if (this.closePromise) {
+      await this.closePromise;
+      return;
+    }
+
+    const promise = (async () => {
+      if (this.ensurePromise) {
+        try {
+          await this.ensurePromise;
+        } catch {
+          // startup failure already handled by the caller path
+        }
+      }
+
+      const currentSessionId = this.sessionId;
+      if (!currentSessionId) {
+        this.resetSessionState();
+        return;
+      }
+
+      await this.deleteSession(currentSessionId);
+      this.resetSessionState(currentSessionId);
+    })();
+
+    this.closePromise = promise;
+
+    try {
+      await promise;
+    } finally {
+      if (this.closePromise === promise) {
+        this.closePromise = null;
+      }
+    }
+  }
+
+  get id(): string | null {
+    return this.sessionId;
+  }
+
+  get url(): string | null {
+    return this.endpoint;
+  }
+
+  get isActive(): boolean {
+    return this.endpoint !== null;
+  }
+
+  private async bootstrapSession(): Promise<void> {
+    const projectId = this.resolveProjectId();
+    const res = await fetch(`${this.apiUrl}/sandbox-sessions`, {
+      method: "POST",
+      headers: this.jsonHeaders(),
+      body: JSON.stringify(projectId ? { project_id: projectId } : {}),
+    });
+
+    if (!res.ok) {
+      throw REQUEST_ERROR.create({
+        detail: `Failed to create sandbox: ${res.status} ${await res.text()}`,
+      });
+    }
+
+    const session = await res.json();
+    this.sessionId = session.id;
+    this.sessionProjectId = projectId;
+
+    try {
+      const endpoint = await this.resolveReadyEndpoint(session);
+      this.endpoint = endpoint;
+      await this.heartbeat(true);
+      this.startHeartbeatLoop();
+    } catch (error) {
+      const currentSessionId = this.sessionId;
+      if (currentSessionId) {
+        await this.deleteSession(currentSessionId);
+      }
+      this.resetSessionState(currentSessionId ?? undefined);
+      throw error;
+    }
+  }
+
+  private async resolveReadyEndpoint(session: SandboxSessionRecord): Promise<string> {
+    if (session.status === "running") {
+      return session.endpoint;
+    }
+
+    await waitForSandboxReady({
+      apiUrl: this.apiUrl,
+      id: session.id,
+      authToken: this.authToken,
+      maxWaitMs: this.startupTimeoutMs,
+      pollIntervalMs: this.pollIntervalMs,
+    });
+
+    const res = await fetch(`${this.apiUrl}/sandbox-sessions/${session.id}`, {
+      headers: this.authHeaders(),
+    });
+
+    if (!res.ok) {
+      throw REQUEST_ERROR.create({
+        detail: `Failed to get sandbox: ${res.status} ${await res.text()}`,
+      });
+    }
+
+    const nextSession = await res.json();
+    return nextSession.endpoint;
+  }
+
+  private async touchSession(): Promise<void> {
+    const projectId = this.resolveProjectId();
+    if (this.endpoint && this.sessionProjectId !== projectId) {
+      const currentSessionId = this.sessionId;
+      if (currentSessionId) {
+        await this.deleteSession(currentSessionId);
+      }
+      this.resetSessionState(currentSessionId ?? undefined);
+    }
+
+    await this.ensure();
+    await this.heartbeat();
+  }
+
+  private startHeartbeatLoop(): void {
+    if (!this.sessionId || this.heartbeatTimer) return;
+
+    this.heartbeatTimer = dntShim.setInterval(() => {
+      void this.heartbeat().catch(() => {
+        // next operation will reprovision
+      });
+    }, this.heartbeatIntervalMs);
+  }
+
+  private stopHeartbeatLoop(): void {
+    if (!this.heartbeatTimer) return;
+    clearInterval(this.heartbeatTimer);
+    this.heartbeatTimer = null;
+  }
+
+  private async deleteSession(sessionId: string): Promise<void> {
+    await fetch(`${this.apiUrl}/sandbox-sessions/${sessionId}`, {
+      method: "DELETE",
+      headers: this.authHeaders(),
+    });
+  }
+
+  private requireEndpoint(): string {
+    if (!this.endpoint) {
+      throw new Error("Sandbox endpoint unavailable");
+    }
+    return this.endpoint;
+  }
+
+  private resolveProjectId(): string | null {
+    return this.getProjectId() ?? null;
+  }
+
+  private resetSessionState(sessionId?: string): void {
+    if (!sessionId || this.sessionId === sessionId) {
+      this.stopHeartbeatLoop();
+      this.endpoint = null;
+      this.sessionId = null;
+      this.sessionProjectId = null;
+      this.heartbeatPromise = null;
+      this.lastHeartbeatAt = 0;
+    }
+  }
+
+  private authHeaders(): HeadersInit {
+    return { Authorization: `Bearer ${this.authToken}` };
+  }
+
+  private jsonHeaders(): HeadersInit {
+    return {
+      ...this.authHeaders(),
+      "Content-Type": "application/json",
+    };
+  }
+}
+
+function mapCommandJob(json: Record<string, unknown>): CommandJob {
+  return {
+    id: json.id as string,
+    status: json.status as CommandJobStatus,
+    exitCode: json.exit_code as number | null,
+    signal: json.signal as string | null,
+    startedAt: json.started_at as string,
+    finishedAt: json.finished_at as string | null,
+    heartbeatStatus: json.heartbeat_status as "disabled" | "healthy" | "degraded",
+    lastHeartbeatAt: json.last_heartbeat_at as string | null,
+    lastHeartbeatError: json.last_heartbeat_error as string | null,
+    heartbeatFailureCount: json.heartbeat_failure_count as number,
+  };
+}