withruntime 0.3.1 → 0.5.0

package/dist/openai-agents/index.d.ts

@@ -0,0 +1,132 @@
+/** Runtime Cloud sandboxes for the OpenAI Agents SDK (JavaScript).
+ *
+ * `RuntimeCloudSandboxClient` is a sandbox client for `SandboxAgent`: the
+ * agent's shell (with PTY sessions and stdin), file edits, image views and
+ * manifest all live in one Runtime Cloud microVM, and the agent definition
+ * does not change:
+ *
+ *   import { run } from "@openai/agents";
+ *   import { SandboxAgent } from "@openai/agents/sandbox";
+ *   import { RuntimeCloudSandboxClient } from "withruntime/openai-agents";
+ *
+ *   const agent = new SandboxAgent({ name: "Coder", instructions: "Fix the failing test." });
+ *   await run(agent, "Go.", {
+ *     sandbox: { client: new RuntimeCloudSandboxClient({ create: { funding: "trial" } }) },
+ *   });
+ *
+ * Needs `@openai/agents` 0.18 or newer beside this package. The key comes from
+ * RUNTIME_API_KEY or this machine's `runtime login`. Plain function tools for
+ * an ordinary `Agent` are `runtimeFunctionTools(sandbox)`. */
+import { type Editor } from "@openai/agents-core";
+import type { Manifest } from "@openai/agents-core/sandbox";
+import { type ExecCommandArgs, type ExposedPortEndpoint, type ListDirectoryArgs, type MaterializeEntryArgs, type ReadFileArgs, type SandboxClient, type SandboxClientCreateArgs, type SandboxDirectoryEntry, type SandboxExecResult, type SandboxSession, type SandboxSessionState, type ViewImageArgs, type WorkspaceArchiveData, type WriteStdinArgs } from "@openai/agents-core/sandbox";
+import { Runtime } from "../client.js";
+import type { Sandbox } from "../sandbox.js";
+import { type SandboxToolOptions } from "../tools/index.js";
+import type { CreateSandbox } from "../types.js";
+export declare const BACKEND_ID = "runtime_cloud";
+export type RuntimeCloudSandboxClientOptions = {
+    /** How to create the sandbox: every field `runtime.sandboxes.create` takes
+     * (funding, image, snapshot, vcpu, memoryMiB, network...). */
+    create?: CreateSandbox;
+    /** Set for every command, under the manifest's own environment. */
+    env?: Record<string, string>;
+    /** Ports `resolveExposedPort` may share as Runtime previews. */
+    exposedPorts?: number[];
+    /** Private previews carry their token in the endpoint's query. Default private. */
+    previewVisibility?: "private" | "public";
+    /** Pause instead of stopping at the end, so `resume` wakes the same machine. */
+    pauseOnExit?: boolean;
+    /** Longest a command may run. Default one hour; at most 24 hours. */
+    execTimeoutMs?: number;
+};
+export interface RuntimeCloudSandboxSessionState extends SandboxSessionState {
+    sandboxId: string;
+    create: CreateSandbox;
+    environment: Record<string, string>;
+    configuredExposedPorts?: number[];
+    previewVisibility: "private" | "public";
+    pauseOnExit: boolean;
+    execTimeoutMs: number;
+}
+/** One Runtime Cloud sandbox as an Agents SDK sandbox session. */
+export declare class RuntimeCloudSandboxSession implements SandboxSession<RuntimeCloudSandboxSessionState> {
+    #private;
+    readonly state: RuntimeCloudSandboxSessionState;
+    constructor(args: {
+        state: RuntimeCloudSandboxSessionState;
+        runtime: Runtime;
+        sandbox?: Sandbox;
+    });
+    /** The Runtime sandbox, created (or woken) on first use. */
+    sandbox(): Promise<Sandbox>;
+    /** An absolute path inside the workspace root or a granted path; anything else is refused. */
+    resolvePath(path: string): string;
+    supportsPty(): boolean;
+    exec(args: ExecCommandArgs): Promise<SandboxExecResult>;
+    /** Starts the command and returns its output so far: finished, with its exit
+     * code, or still running, with a session id for `writeStdin`. */
+    execCommand(args: ExecCommandArgs): Promise<string>;
+    writeStdin(args: WriteStdinArgs): Promise<string>;
+    readFile(args: ReadFileArgs): Promise<Uint8Array>;
+    viewImage(args: ViewImageArgs): Promise<{
+        type: "image";
+        providerData?: Record<string, any> | undefined;
+        image?: string | {
+            data: string | Uint8Array<ArrayBuffer>;
+            mediaType?: string | undefined;
+        } | {
+            url: string;
+        } | {
+            fileId: string;
+        } | undefined;
+        detail?: "auto" | "high" | "low" | (string & {}) | undefined;
+    }>;
+    listDir(args: ListDirectoryArgs): Promise<SandboxDirectoryEntry[]>;
+    pathExists(path: string, runAs?: string): Promise<boolean>;
+    directoryExists(path: string, runAs?: string): Promise<boolean>;
+    createEditor(runAs?: string): Editor;
+    prepareWorkspaceRoot(): Promise<void>;
+    applyManifest(manifest: Manifest, runAs?: string): Promise<void>;
+    materializeEntry(args: MaterializeEntryArgs): Promise<void>;
+    resolveExposedPort(port: number): Promise<ExposedPortEndpoint>;
+    persistWorkspace(): Promise<Uint8Array>;
+    hydrateWorkspace(data: WorkspaceArchiveData): Promise<void>;
+    running(): Promise<boolean>;
+    /** Ends every process the agent started. */
+    shutdown(): Promise<void>;
+    /** Stops the sandbox, or pauses it with `pauseOnExit`. */
+    delete(): Promise<void>;
+    close(): Promise<void>;
+}
+/** Creates, resumes and deletes Runtime Cloud sandbox sessions. */
+export declare class RuntimeCloudSandboxClient implements SandboxClient<RuntimeCloudSandboxClientOptions, RuntimeCloudSandboxSessionState> {
+    #private;
+    readonly backendId = "runtime_cloud";
+    readonly runtime: Runtime;
+    constructor(options?: RuntimeCloudSandboxClientOptions & {
+        runtime?: Runtime;
+    });
+    create(args?: SandboxClientCreateArgs<RuntimeCloudSandboxClientOptions> | Manifest, manifestOptions?: RuntimeCloudSandboxClientOptions): Promise<RuntimeCloudSandboxSession>;
+    /** Reattaches to the same sandbox while it runs (waking it when paused);
+     * otherwise starts a new one and applies the manifest again. */
+    resume(state: RuntimeCloudSandboxSessionState): Promise<RuntimeCloudSandboxSession>;
+    delete(state: RuntimeCloudSandboxSessionState): Promise<void>;
+    canPersistOwnedSessionState(state: RuntimeCloudSandboxSessionState): boolean;
+    /** The state without secrets: the environment is materialized again on the way back. */
+    serializeSessionState(state: RuntimeCloudSandboxSessionState): Promise<Record<string, unknown>>;
+    deserializeSessionState(record: Record<string, unknown>): Promise<RuntimeCloudSandboxSessionState>;
+}
+/** The four sandbox tools as function tools for an ordinary `Agent`
+ * (no SandboxAgent): runtime_exec, runtime_read_file, runtime_write_file and
+ * runtime_list_files, bound to `sandbox`. */
+export declare function runtimeFunctionTools(sandbox: Sandbox, options?: SandboxToolOptions): import("@openai/agents-core").FunctionTool<unknown, {
+    type: "object";
+    properties: Record<string, {
+        type: "string" | "integer";
+        description: string;
+        minimum?: number;
+    }>;
+    required: string[];
+    additionalProperties: true;
+}, string>[];