@agent-harness-experimental/adapter-openai-agents 0.0.0 → 0.0.1

package/LICENSE

@@ -0,0 +1 @@
+Copyright Vercel Inc. Pre-release. Not licensed as OSS yet.

package/README.md

@@ -1,3 +1,140 @@
-# @agent-harness-experimental/adapter-openai-agents
+# `@agent-harness-experimental/adapter-openai-agents`
 
-Placeholder package.
+Adapter for running [OpenAI Agents JS](https://github.com/openai/openai-agents-js)
+inside `agent-harness-experimental` with the OpenAI runner on the host and sandbox-backed
+file and shell tools.
+
+## Install
+
+```bash
+npm install agent-harness-experimental @agent-harness-experimental/adapter-openai-agents
+```
+
+## Usage
+
+```ts
+import { createAgentSession } from "agent-harness-experimental";
+import { openaiAgents } from "@agent-harness-experimental/adapter-openai-agents";
+
+const agent = createAgentSession({
+  adapter: openaiAgents(),
+});
+
+const result = await agent.generate("Refactor the auth module to use JWT");
+console.log(result.text);
+await agent.close("stop");
+```
+
+## Configuration
+
+```ts
+openaiAgents({
+  // OpenAI model ID
+  model: "gpt-5.4-mini",
+
+  // Maximum OpenAI Agents turns for one run
+  maxTurns: 10,
+
+  // OpenAI Agents SDK instructions appended by the adapter
+  instructions: "Prefer concise, targeted code changes.",
+
+  // Skill descriptors are exposed eagerly or through load_skill
+  skills: { loading: "lazy" },
+});
+```
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `model` | `string` | OpenAI Agents SDK default | Model ID |
+| `name` | `string` | `"Coding Agent"` | OpenAI Agents SDK agent name |
+| `instructions` | `string` | — | Adapter-level instructions appended to the agent |
+| `maxTurns` | `number` | — | Maximum SDK turns per run |
+| `modelSettings` | `ModelSettings` | — | OpenAI Agents SDK model settings |
+| `useResponses` | `boolean` | — | Passed to `OpenAIProvider` |
+| `tracing` | `object` | — | OpenAI Agents SDK tracing controls |
+| `skills.loading` | `'eager' \| 'lazy'` | `'eager'` | Whether skills are described up front or loaded through `load_skill` |
+| `auth` | `object` | — | Optional per-adapter auth override (`gateway`, `openai`, or `openaiCompatible`) |
+
+Sandbox runtime options such as `template`, `timeoutMs`, and `httpHandler`
+belong on `createAgentSession({ sandbox })`.
+
+```ts
+const agent = createAgentSession({
+  adapter: openaiAgents({ model: "gpt-5.4-mini" }),
+  sandbox: {
+    template: "snap_abc123",
+    timeoutMs: 60000,
+    httpHandler: async (request: Request) => fetch(request),
+  },
+});
+```
+
+## Auth
+
+`auth` is optional. If you omit it, OpenAI Agents uses ambient OpenAI
+environment variables such as `OPENAI_API_KEY`, `OPENAI_BASE_URL`,
+`OPENAI_ORGANIZATION`, and `OPENAI_PROJECT`.
+
+```ts
+openaiAgents({
+  model: "gpt-5.4-mini",
+  auth: {
+    gateway: {
+      apiKey: { env: "AI_GATEWAY_API_KEY" },
+      baseURL: "https://ai-gateway.vercel.sh/v1",
+    },
+  },
+});
+```
+
+Use `auth.openaiCompatible` for OpenAI-compatible providers:
+
+```ts
+openaiAgents({
+  model: "openai-compatible-model",
+  auth: {
+    openaiCompatible: {
+      name: "internal-openai-compatible",
+      apiKey: { env: "OPENAI_COMPATIBLE_API_KEY" },
+      baseURL: "https://models.example.invalid/v1",
+    },
+  },
+});
+```
+
+## Built-in Tools
+
+OpenAI Agents exposes standardized builtin names through `agent-harness-experimental`.
+
+| Tool | Native Capability | Description |
+| --- | --- | --- |
+| `exec_command` | `shell()` | Execute a one-shot shell command in the sandbox |
+| `apply_patch` | `filesystem()` patch tool | Create, update, move, or delete files |
+| `view_image` | `filesystem()` image read | Return local sandbox image contents to the model |
+| `load_skill` | `skills()` lazy loader | Materialize and load a lazily configured skill |
+
+## Features
+
+- **Split runtime**: OpenAI Agents JS runs on the host while file and shell tools
+  operate inside the sandbox.
+- **AI SDK tools**: User-defined AI SDK tools execute on the host and are
+  exposed to the OpenAI model as function tools.
+- **Tool interception**: Built-in tools can be intercepted for approval via the
+  `permissions` option on `createAgentSession`.
+- **Step-level `prepareStep`**: Tool visibility, instructions, and skill state
+  can change between internal OpenAI Agents model calls.
+- **Skills**: Exposed through OpenAI Agents SDK `skills()` descriptors with
+  eager or lazy loading.
+- **Subagents**: `createAgentSession({ agents })` is exposed through the canonical
+  host-side `delegate_task` tool with a shared split sandbox session.
+- **Replay-friendly HTTP**: Sandbox-side HTTP traffic can be routed through the
+  test replay handler via `sandbox.httpHandler`.
+- **Changed files**: `apply_patch` and shell-created file mutations are reported
+  through changed-file tracking.
+
+## Limitations
+
+`exec_command` is one-shot shell execution. This adapter does not currently
+expose PTY sessions or `write_stdin`, so workflows that need to feed input into
+a long-running terminal process, REPL, watcher, or interactive prompt are not
+fully portable to OpenAI Agents.

package/dist/adapter.d.ts

@@ -0,0 +1,31 @@
+import type { AgentAdapter, GatewayAuthOptions, OpenAIAuthOptions, OpenAICompatibleAuthOptions } from 'agent-harness-experimental';
+import { type ModelSettings } from '@openai/agents';
+import { type OpenAIAgentsAdapterState } from './state.js';
+export declare const OPENAI_AGENTS_BUILTIN_TOOLS: {
+    name: string;
+    inputSchema: import("agent-harness-experimental").JsonSchema;
+    nativeName?: string | undefined;
+    description?: string | undefined;
+}[], OPENAI_AGENTS_PERMISSION_TOOL_CATEGORIES: import("agent-harness-experimental").PermissionToolCategories;
+export interface OpenAIAgentsAdapterOptions {
+    model?: string;
+    name?: string;
+    instructions?: string;
+    maxTurns?: number;
+    modelSettings?: ModelSettings;
+    useResponses?: boolean;
+    tracing?: {
+        disabled?: boolean;
+        includeSensitiveData?: boolean;
+    };
+    skills?: {
+        loading?: 'eager' | 'lazy';
+    };
+    auth?: {
+        gateway?: GatewayAuthOptions;
+        openai?: OpenAIAuthOptions;
+        openaiCompatible?: OpenAICompatibleAuthOptions;
+    };
+}
+export declare function openaiAgents(options?: OpenAIAgentsAdapterOptions): AgentAdapter<OpenAIAgentsAdapterState>;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAGV,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,2BAA2B,EAE5B,MAAM,4BAA4B,CAAC;AAepC,OAAO,EAA4F,KAAK,aAAa,EAAa,MAAM,gBAAgB,CAAC;AAOzJ,OAAO,EAAiE,KAAK,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAa1H,eAAO,MAAe,2BAA2B;;;;;KAA4B,wCAAwC,+DA4DnH,CAAC;AAEH,MAAM,WAAW,0BAA0B;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,OAAO,CAAC,EAAE;QACR,QAAQ,CAAC,EAAE,OAAO,CAAC;QACnB,oBAAoB,CAAC,EAAE,OAAO,CAAC;KAChC,CAAC;IACF,MAAM,CAAC,EAAE;QACP,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;KAC5B,CAAC;IACF,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,EAAE,kBAAkB,CAAC;QAC7B,MAAM,CAAC,EAAE,iBAAiB,CAAC;QAC3B,gBAAgB,CAAC,EAAE,2BAA2B,CAAC;KAChD,CAAC;CACH;AAukBD,wBAAgB,YAAY,CAAC,OAAO,CAAC,EAAE,0BAA0B,GAAG,YAAY,CAAC,wBAAwB,CAAC,CAuMzG"}