xapi-to 0.1.19 → 0.1.21

package/dist/openai-sandbox-client.d.ts

@@ -0,0 +1,85 @@
+import { SandboxClient, SandboxSessionState, SandboxSession, ExecCommandArgs, SandboxExecResult, SandboxClientCreateArgs, Manifest } from '@openai/agents/sandbox';
+
+/**
+ * xAPI Sandbox Gateway client.
+ *
+ * State-changing calls are never retried blindly. A lost POST response may have
+ * created, executed, or terminated a real billable instance. Read-only calls and
+ * quotes opt into the shared client's conservative transient retry policy.
+ */
+interface SandboxClientOptions {
+    sandboxHost: string;
+    apiKey: string;
+    provider?: string;
+}
+
+/** OpenAI Sandbox Agents SDK client backed by the xAPI Sandbox Gateway. */
+
+type XapiAgentsSandboxOptions = {
+    apiKey: string;
+    sandboxHost?: string;
+    provider?: string;
+    maxHourlyUsd?: number;
+    model?: string;
+    workspaceRoot?: string;
+};
+type XapiAgentsSandboxState = SandboxSessionState & {
+    instanceId: string;
+    provider: string;
+};
+type XapiAgentsSandboxEvidence = {
+    instanceId?: string;
+    provider?: string;
+    execCount: number;
+    shellMarkerSeen: boolean;
+    finalState?: string;
+    totalCost?: string | number;
+    auditCounts?: Record<string, number>;
+    auditStatuses?: Record<string, string[]>;
+    auditVerified?: boolean;
+};
+type RunOptions = {
+    provider?: string;
+    maxHourlyUsd?: number;
+};
+declare class XapiAgentsSandboxSession implements SandboxSession<XapiAgentsSandboxState> {
+    private readonly options;
+    private readonly owner;
+    readonly state: XapiAgentsSandboxState;
+    private closed;
+    private closePromise?;
+    constructor(state: XapiAgentsSandboxState, options: SandboxClientOptions, owner: XapiAgentsSandboxClient);
+    running(): Promise<boolean>;
+    exec(args: ExecCommandArgs): Promise<SandboxExecResult>;
+    execCommand(args: ExecCommandArgs): Promise<string>;
+    stop(): Promise<void>;
+    shutdown(): Promise<void>;
+    delete(): Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * Minimal provider adapter for Shell-based SandboxAgent examples.
+ *
+ * It intentionally rejects materialized Manifest entries and environment
+ * values. A production adapter should add file/mount/snapshot translations
+ * instead of pretending those optional surfaces work.
+ */
+declare class XapiAgentsSandboxClient implements SandboxClient<RunOptions, XapiAgentsSandboxState> {
+    readonly backendId = "xapi-sandbox";
+    readonly supportsDefaultOptions = true;
+    readonly evidence: XapiAgentsSandboxEvidence;
+    readonly workspaceRoot: string;
+    lastSession?: XapiAgentsSandboxSession;
+    private readonly apiKey;
+    private readonly sandboxHost;
+    private readonly provider;
+    private readonly maxHourlyUsd;
+    private readonly model;
+    private readonly terminationKeys;
+    constructor(options: XapiAgentsSandboxOptions);
+    create(args?: SandboxClientCreateArgs<RunOptions> | Manifest, legacyOptions?: RunOptions): Promise<XapiAgentsSandboxSession>;
+    delete(state: XapiAgentsSandboxState): Promise<void>;
+    terminate(state: XapiAgentsSandboxState): Promise<void>;
+}
+
+export { XapiAgentsSandboxClient, type XapiAgentsSandboxEvidence, type XapiAgentsSandboxOptions, type XapiAgentsSandboxState };

package/dist/openai-sandbox-client.js

@@ -0,0 +1,285 @@
+import {
+  HttpError,
+  sandboxAudit,
+  sandboxCreate,
+  sandboxExec,
+  sandboxGet,
+  sandboxQuote,
+  sandboxStateAction,
+  sandboxWait
+} from "./chunk-UEQCIJ7T.js";
+
+// src/openai-sandbox-client.ts
+import { randomUUID } from "crypto";
+import {
+  normalizeSandboxClientCreateArgs
+} from "@openai/agents/sandbox";
+function countItems(value) {
+  if (Array.isArray(value)) return value.length;
+  const item = value;
+  return item?.items?.length ?? item?.data?.length ?? 0;
+}
+function items(value) {
+  if (Array.isArray(value)) return value;
+  const page = value;
+  return page?.items ?? page?.data ?? [];
+}
+function positivePrice(value, name) {
+  if (!Number.isFinite(value) || value <= 0) throw new Error(`${name} must be a positive finite number`);
+  return value;
+}
+function shellQuote(value) {
+  if (!value || value.length > 4096 || value.includes("\0")) {
+    throw new Error("workspaceRoot must be a non-empty path no longer than 4096 characters");
+  }
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function defaultWorkspaceRoot(provider) {
+  if (provider === "daytona") return "/home/daytona/openai-xapi";
+  return "/tmp/openai-xapi";
+}
+var XapiAgentsSandboxSession = class {
+  constructor(state, options, owner) {
+    this.options = options;
+    this.owner = owner;
+    this.state = state;
+  }
+  options;
+  owner;
+  state;
+  closed = false;
+  closePromise;
+  async running() {
+    const detail = await sandboxGet(this.options, this.state.instanceId);
+    return detail.observedState === "RUNNING";
+  }
+  async exec(args) {
+    const before = Date.now();
+    const result = await sandboxExec(this.options, this.state.instanceId, {
+      command: args.cmd,
+      ...args.workdir ? { cwd: args.workdir } : {},
+      timeoutSeconds: 120
+    });
+    const stdout = String(result.stdout || "");
+    const stderr = String(result.stderr || "");
+    this.owner.evidence.execCount += 1;
+    if (/(?:OPENAI_XAPI_SANDBOX_OK|SDK_OK)=42/.test(`${stdout}
+${stderr}`)) {
+      this.owner.evidence.shellMarkerSeen = true;
+    }
+    return {
+      output: [stdout, stderr].filter(Boolean).join("\n"),
+      stdout,
+      stderr,
+      exitCode: typeof result.exitCode === "number" ? result.exitCode : null,
+      wallTimeSeconds: (Date.now() - before) / 1e3
+    };
+  }
+  async execCommand(args) {
+    return (await this.exec(args)).output;
+  }
+  async stop() {
+    await this.close();
+  }
+  async shutdown() {
+    await this.close();
+  }
+  async delete() {
+    await this.close();
+  }
+  async close() {
+    if (this.closed) return;
+    if (this.closePromise) return this.closePromise;
+    this.closePromise = this.owner.terminate(this.state);
+    try {
+      await this.closePromise;
+      this.closed = true;
+    } finally {
+      this.closePromise = void 0;
+    }
+  }
+};
+var XapiAgentsSandboxClient = class {
+  backendId = "xapi-sandbox";
+  supportsDefaultOptions = true;
+  evidence = { execCount: 0, shellMarkerSeen: false };
+  workspaceRoot;
+  lastSession;
+  apiKey;
+  sandboxHost;
+  provider;
+  maxHourlyUsd;
+  model;
+  terminationKeys = /* @__PURE__ */ new Map();
+  constructor(options) {
+    if (!options.apiKey) throw new Error("XapiAgentsSandboxClient requires apiKey");
+    this.apiKey = options.apiKey;
+    this.sandboxHost = options.sandboxHost || "sandbox.xapi.to";
+    this.provider = options.provider || "daytona";
+    this.maxHourlyUsd = positivePrice(options.maxHourlyUsd ?? 0.2, "maxHourlyUsd");
+    this.model = options.model || "deepseek-v4-pro";
+    this.workspaceRoot = options.workspaceRoot || defaultWorkspaceRoot(this.provider);
+    shellQuote(this.workspaceRoot);
+  }
+  async create(args = {}, legacyOptions) {
+    const normalized = normalizeSandboxClientCreateArgs(args, legacyOptions);
+    const provider = normalized.options?.provider || this.provider;
+    const maxHourlyUsd = positivePrice(
+      normalized.options?.maxHourlyUsd ?? this.maxHourlyUsd,
+      "maxHourlyUsd"
+    );
+    const manifest = normalized.manifest;
+    if (Object.keys(manifest.validatedEntries()).length !== 0) {
+      throw new Error("XapiAgentsSandboxClient example currently supports an empty Manifest only");
+    }
+    if (Object.keys(manifest.environment).length !== 0) {
+      throw new Error("XapiAgentsSandboxClient keeps credentials/environment out of the Manifest");
+    }
+    const options = {
+      sandboxHost: this.sandboxHost,
+      apiKey: this.apiKey,
+      provider
+    };
+    const quote = await sandboxQuote(options, {
+      requirements: { capabilities: ["exec", "files"] },
+      maxEstimatedHourlyUsd: maxHourlyUsd.toFixed(8)
+    });
+    if (!quote?.quoteId) throw new Error("xAPI Sandbox quote did not return quoteId");
+    const created = await sandboxCreate(options, {
+      selection: { quoteId: quote.quoteId },
+      metadata: { client: "openai-agents-sdk", modelGateway: "ai.xapi.to", model: this.model },
+      idempotencyKey: `openai-agents-sdk:${randomUUID()}`
+    });
+    if (!created.id) throw new Error("xAPI Sandbox create did not return instance id");
+    const state = {
+      manifest,
+      workspaceReady: false,
+      instanceId: created.id,
+      provider
+    };
+    const session = new XapiAgentsSandboxSession(state, options, this);
+    this.lastSession = session;
+    this.evidence.instanceId = created.id;
+    this.evidence.provider = provider;
+    try {
+      await sandboxWait(options, created.id, ["RUNNING"], 36e4, 2e3);
+      const prepared = await session.exec({ cmd: `mkdir -p -- ${shellQuote(manifest.root)}` });
+      if (prepared.exitCode !== 0) throw new Error(`could not prepare ${manifest.root}`);
+      state.workspaceReady = true;
+      return session;
+    } catch (error) {
+      await this.terminate(state).catch(() => void 0);
+      throw error;
+    }
+  }
+  async delete(state) {
+    await this.terminate(state);
+  }
+  async terminate(state) {
+    const options = {
+      sandboxHost: this.sandboxHost,
+      apiKey: this.apiKey,
+      provider: state.provider
+    };
+    const aggregateOptions = { ...options, provider: void 0 };
+    const readDetail = async () => {
+      try {
+        return await sandboxGet(options, state.instanceId);
+      } catch (error) {
+        if (!(error instanceof HttpError) || error.status !== 404 || !options.provider) throw error;
+        return sandboxGet(aggregateOptions, state.instanceId);
+      }
+    };
+    const deadline = Date.now() + 36e4;
+    const intervalMs = 2e3;
+    const terminationKey = this.terminationKeys.get(state.instanceId) || `openai-agents-sdk:terminate:${randomUUID()}`;
+    this.terminationKeys.set(state.instanceId, terminationKey);
+    let detail = await readDetail();
+    while (!["TERMINATED", "FAILED"].includes(String(detail.observedState)) && Date.now() < deadline) {
+      try {
+        await sandboxStateAction(options, state.instanceId, "terminate", {
+          idempotencyKey: terminationKey
+        });
+        break;
+      } catch (error) {
+        if (!(error instanceof HttpError) || error.status !== 409) throw error;
+        await sleep(intervalMs);
+        detail = await readDetail();
+      }
+    }
+    if (!["TERMINATED", "FAILED"].includes(String(detail.observedState))) {
+      try {
+        detail = await sandboxWait(
+          options,
+          state.instanceId,
+          ["TERMINATED", "FAILED"],
+          Math.max(1, deadline - Date.now()),
+          intervalMs
+        );
+      } catch (error) {
+        if (!(error instanceof HttpError) || error.status !== 404 || !options.provider) throw error;
+        detail = await sandboxWait(
+          aggregateOptions,
+          state.instanceId,
+          ["TERMINATED", "FAILED"],
+          Math.max(1, deadline - Date.now()),
+          intervalMs
+        );
+      }
+    }
+    const auditDeadline = Date.now() + 6e4;
+    let audit = {};
+    let auditError = "audit has not settled";
+    while (Date.now() < auditDeadline) {
+      detail = await sandboxGet(aggregateOptions, state.instanceId);
+      audit = {};
+      for (const kind of ["operations", "events", "usageSegments", "billingPeriods"]) {
+        audit[kind] = await sandboxAudit(aggregateOptions, state.instanceId, kind);
+      }
+      const operations = items(audit.operations);
+      const events = items(audit.events);
+      const usageSegments = items(audit.usageSegments);
+      const billingPeriods = items(audit.billingPeriods);
+      const operationStatuses = operations.map((item) => String(item.status || "UNKNOWN"));
+      const operationSettled = operations.length > 0 && operationStatuses.every((status) => ["SUCCEEDED", "FAILED"].includes(status));
+      const eventSettled = events.some((item) => ["TERMINATED", "FAILED"].includes(String(item.currentState)));
+      const usageSettled = usageSegments.length > 0 && usageSegments.every((item) => item.status === "SETTLED" && item.endsAt);
+      const billingSettled = billingPeriods.length > 0 && billingPeriods.every((item) => item.status === "SETTLED" && item.endedAt);
+      const billed = billingPeriods.reduce((sum, item) => sum + Number(item.amount || 0), 0);
+      const totalCost = Number(detail.totalCost);
+      const costMatches = Number.isFinite(totalCost) && Number.isFinite(billed) && Math.abs(totalCost - billed) <= 1e-9;
+      if (operationSettled && eventSettled && usageSettled && billingSettled && costMatches) {
+        auditError = "";
+        break;
+      }
+      auditError = [
+        !operationSettled && "operations are not terminal",
+        !eventSettled && "terminal event is missing",
+        !usageSettled && "usage is not settled",
+        !billingSettled && "billing is not settled",
+        !costMatches && `billing sum ${billed} does not match totalCost ${detail.totalCost}`
+      ].filter(Boolean).join("; ");
+      await sleep(1e3);
+    }
+    if (auditError) throw new Error(`xAPI Sandbox audit verification failed: ${auditError}`);
+    const auditCounts = {};
+    const auditStatuses = {};
+    for (const kind of ["operations", "events", "usageSegments", "billingPeriods"]) {
+      auditCounts[kind] = countItems(audit[kind]);
+      auditStatuses[kind] = items(audit[kind]).map((item) => String(
+        item.status || item.currentState || "UNKNOWN"
+      ));
+    }
+    this.evidence.finalState = detail.observedState;
+    this.evidence.totalCost = detail.totalCost;
+    this.evidence.auditCounts = auditCounts;
+    this.evidence.auditStatuses = auditStatuses;
+    this.evidence.auditVerified = true;
+  }
+};
+export {
+  XapiAgentsSandboxClient
+};

package/examples/openai-agents-sandbox-local.ts

@@ -0,0 +1,131 @@
+#!/usr/bin/env bun
+
+/**
+ * Local OpenAI SandboxAgent + xAPI example.
+ *
+ * This file imports the xAPI adapter from ../src, so it works before the next
+ * xapi-to package release. The model call uses DeepSeek through ai.xapi.to;
+ * shell execution uses the xAPI Sandbox test gateway by default.
+ */
+
+import { OpenAIProvider, Runner } from '@openai/agents';
+import { Manifest, SandboxAgent, shell } from '@openai/agents/sandbox';
+import { getConfig } from '../src/config.ts';
+import { XapiAgentsSandboxClient } from '../src/openai-sandbox-client.ts';
+
+const configuredApiKey = process.env.XAPI_KEY || process.env.XAPI_API_KEY || getConfig().apiKey;
+const sandboxApiKey =
+  process.env.XAPI_SANDBOX_KEY || process.env.XAPI_TEST_API_KEY || configuredApiKey;
+const aiApiKey = process.env.XAPI_AI_KEY || configuredApiKey;
+
+if (!sandboxApiKey) {
+  throw new Error(
+    'Sandbox key is required. Set XAPI_SANDBOX_KEY (or XAPI_TEST_API_KEY/XAPI_KEY).',
+  );
+}
+if (!aiApiKey) {
+  throw new Error(
+    'AI Gateway key is required. Set XAPI_AI_KEY (or configure a production xAPI key).',
+  );
+}
+
+const sandboxHost = process.env.XAPI_SANDBOX_HOST || 'sandbox.test.xapi.to';
+const provider = process.env.XAPI_SANDBOX_PROVIDER || 'daytona';
+const model = process.env.XAPI_MODEL || 'deepseek-v4-pro';
+const maxHourlyUsd = Number(process.env.XAPI_SANDBOX_MAX_HOURLY_USD || '0.20');
+
+if (!Number.isFinite(maxHourlyUsd) || maxHourlyUsd <= 0) {
+  throw new Error('XAPI_SANDBOX_MAX_HOURLY_USD must be a positive number');
+}
+
+// Compute plane: xAPI quotes, creates, executes, audits, bills, and terminates.
+const sandbox = new XapiAgentsSandboxClient({
+  apiKey: sandboxApiKey,
+  sandboxHost,
+  provider,
+  maxHourlyUsd,
+  model,
+});
+
+// Model plane: DeepSeek through xAPI's OpenAI Chat Completions-compatible API.
+const modelProvider = new OpenAIProvider({
+  apiKey: aiApiKey,
+  baseURL: 'https://ai.xapi.to/v1',
+  useResponses: false,
+  strictFeatureValidation: true,
+});
+
+// The xAPI key is not an OpenAI telemetry credential.
+const runner = new Runner({ modelProvider, tracingDisabled: true });
+
+const agent = new SandboxAgent({
+  name: 'xAPI DeepSeek local sandbox agent',
+  model,
+  defaultManifest: new Manifest({ root: sandbox.workspaceRoot }),
+  capabilities: [shell()],
+  instructions: [
+    'Work only inside the sandbox workspace.',
+    'Use shell to complete the task.',
+    'Use two separate shell calls: first write the artifact, then read it back.',
+    'Verify the shell output before reporting success.',
+  ].join(' '),
+});
+
+let finalOutput = '';
+let failure: unknown;
+let cleanupError: string | undefined;
+const startedAt = new Date();
+
+try {
+  const result = await runner.run(
+    agent,
+    'Write exactly SDK_OK=42 to result.txt. Then read result.txt and verify it. ' +
+      'Only after the shell output confirms the marker, reply exactly SDK_OK=42.',
+    {
+      maxTurns: 8,
+      sandbox: { client: sandbox },
+    },
+  );
+
+  finalOutput = String(result.finalOutput || '');
+  if (!finalOutput.includes('SDK_OK=42')) {
+    throw new Error(`agent final output did not contain SDK_OK=42: ${finalOutput}`);
+  }
+  if (sandbox.evidence.execCount < 2) {
+    throw new Error(`expected at least 2 shell calls, got ${sandbox.evidence.execCount}`);
+  }
+} catch (error) {
+  failure = error;
+} finally {
+  try {
+    // close() terminates the instance, waits for a terminal state, then reads
+    // operations, events, usage segments, billing periods, and final cost.
+    await sandbox.lastSession?.close();
+  } catch (error) {
+    cleanupError = error instanceof Error ? error.message : String(error);
+    failure ||= error;
+  }
+}
+
+const report = {
+  status: failure ? 'failed' : 'passed',
+  startedAt: startedAt.toISOString(),
+  finishedAt: new Date().toISOString(),
+  modelGateway: 'https://ai.xapi.to/v1',
+  model,
+  sandboxHost,
+  provider,
+  maxHourlyUsd,
+  finalOutput,
+  sandbox: sandbox.evidence,
+  ...(cleanupError ? { cleanupError } : {}),
+  ...(failure
+    ? { error: failure instanceof Error ? failure.message : String(failure) }
+    : {}),
+};
+
+console.log(JSON.stringify(report, null, 2));
+
+if (failure) {
+  throw failure;
+}