computer-agents 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Testbase
+
+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

@@ -0,0 +1,184 @@
+# computer-agents
+
+[![npm version](https://badge.fury.io/js/computer-agents.svg)](https://www.npmjs.com/package/computer-agents)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Build computer-use agents that write code, run tests, and deploy apps. Seamless local and cloud execution with automatic session continuity.
+
+## Installation
+
+```bash
+npm install computer-agents
+```
+
+## Quick Start
+
+```typescript
+import { Agent, run, LocalRuntime } from 'computer-agents';
+
+const agent = new Agent({
+  agentType: 'computer',
+  runtime: new LocalRuntime(),
+  instructions: 'You are an expert developer.'
+});
+
+const result = await run(agent, "Create a Python script that prints 'Hello World'");
+console.log(result.finalOutput);
+```
+
+## Features
+
+- **🎯 Two Agent Types** - `'llm'` for reasoning, `'computer'` for execution
+- **🔄 Runtime Abstraction** - Seamless local ↔ cloud switching
+- **⚡️ Automatic Session Continuity** - Multi-turn conversations work automatically
+- **🔌 Unified MCP Config** - Single configuration for all agent types
+- **📦 Manual Composition** - Build custom workflows explicitly
+- **☁️ Cloud Execution** - GCE-based with workspace sync
+- **✨ Professional** - Zero type assertions, clean abstractions
+
+## Agent Types
+
+### Computer Agent (Local)
+
+```typescript
+import { Agent, run, LocalRuntime } from 'computer-agents';
+
+const agent = new Agent({
+  agentType: 'computer',
+  runtime: new LocalRuntime(),
+  workspace: './my-project',
+  instructions: 'You are an expert developer.'
+});
+
+const result = await run(agent, 'Add a README to the project');
+```
+
+### Computer Agent (Cloud)
+
+```typescript
+import { Agent, run, CloudRuntime } from 'computer-agents';
+
+const agent = new Agent({
+  agentType: 'computer',
+  runtime: new CloudRuntime({ debug: true }),
+  workspace: './my-project'
+});
+
+const result = await run(agent, 'Run the tests');
+```
+
+### LLM Agent
+
+```typescript
+import { Agent, run } from 'computer-agents';
+
+const agent = new Agent({
+  agentType: 'llm',
+  model: 'gpt-4o',
+  instructions: 'You create detailed implementation plans.'
+});
+
+const result = await run(agent, 'Plan how to add user authentication');
+```
+
+## Multi-Agent Workflows
+
+```typescript
+import { Agent, run, LocalRuntime } from 'computer-agents';
+
+// LLM creates plan
+const planner = new Agent({
+  agentType: 'llm',
+  model: 'gpt-4o',
+  instructions: 'Create detailed implementation plans.'
+});
+
+// Computer agent executes plan
+const executor = new Agent({
+  agentType: 'computer',
+  runtime: new LocalRuntime(),
+  instructions: 'Execute implementation plans.'
+});
+
+// LLM reviews result
+const reviewer = new Agent({
+  agentType: 'llm',
+  model: 'gpt-4o',
+  instructions: 'Review implementations for quality.'
+});
+
+// Manual workflow
+const task = "Add user authentication";
+const plan = await run(planner, `Plan: ${task}`);
+const code = await run(executor, plan.finalOutput);
+const review = await run(reviewer, `Review: ${code.finalOutput}`);
+```
+
+## Session Continuity
+
+Multiple `run()` calls automatically maintain context:
+
+```typescript
+const agent = new Agent({
+  agentType: 'computer',
+  runtime: new LocalRuntime()
+});
+
+await run(agent, 'Create app.py');           // New session
+await run(agent, 'Add error handling');      // Continues same session!
+await run(agent, 'Add tests');               // Still same session!
+
+agent.resetSession();                         // Start fresh
+await run(agent, 'Start new project');       // New session
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Required - Codex SDK and OpenAI both need this
+OPENAI_API_KEY=your-openai-key
+```
+
+### MCP Server Integration
+
+```typescript
+import type { McpServerConfig } from 'computer-agents';
+
+const mcpServers: McpServerConfig[] = [
+  {
+    type: 'stdio',
+    name: 'filesystem',
+    command: 'npx',
+    args: ['@modelcontextprotocol/server-filesystem', '/workspace']
+  },
+  {
+    type: 'http',
+    name: 'notion',
+    url: 'https://notion-mcp.example.com/mcp',
+    bearerToken: process.env.NOTION_TOKEN
+  }
+];
+
+const agent = new Agent({
+  agentType: 'computer',
+  runtime: new LocalRuntime(),
+  mcpServers  // Works for both LLM and computer agents!
+});
+```
+
+## Documentation
+
+- [GitHub Repository](https://github.com/testbasehq/computer-agents)
+- [Examples](https://github.com/testbasehq/computer-agents/tree/main/examples)
+- [API Reference](https://github.com/testbasehq/computer-agents/blob/main/docs)
+
+## License
+
+MIT
+
+## Credits
+
+- Built on [OpenAI Agents SDK](https://github.com/openai/openai-agents-js)
+- Integrates with [@openai/codex-sdk](https://www.npmjs.com/package/@openai/codex-sdk)

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type * as CoreTypes from '@testbase/agents-core';
+export declare function run<TAgent extends CoreTypes.Agent<any, any>, TContext = undefined>(agent: TAgent, input: string | CoreTypes.AgentInputItem[] | CoreTypes.RunState<TContext, TAgent>, options?: CoreTypes.StreamRunOptions<TContext> | CoreTypes.NonStreamRunOptions<TContext>): Promise<CoreTypes.RunResult<TContext, TAgent> | CoreTypes.StreamedRunResult<TContext, TAgent>>;
+export * from '@testbase/agents-core';

package/dist/index.js

@@ -0,0 +1,73 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.run = run;
+const node_url_1 = require("node:url");
+const node_path_1 = require("node:path");
+const dynamicImport = new Function('specifier', 'return import(specifier);');
+let coreModule;
+function getCore() {
+    if (coreModule) {
+        return coreModule;
+    }
+    try {
+        coreModule = require('@testbase/agents-core');
+    }
+    catch {
+        const localPath = (0, node_path_1.resolve)(__dirname, '../../agents-core/dist/index.js');
+        coreModule = require(localPath);
+    }
+    return coreModule;
+}
+let openAIProviderCtorPromise;
+async function loadOpenAIProvider() {
+    if (openAIProviderCtorPromise) {
+        return openAIProviderCtorPromise;
+    }
+    openAIProviderCtorPromise = (async () => {
+        try {
+            const mod = await dynamicImport('@testbase/agents-openai');
+            return mod.OpenAIProvider;
+        }
+        catch {
+            const localUrl = (0, node_url_1.pathToFileURL)((0, node_path_1.resolve)(__dirname, '../../agents-openai/dist/index.mjs')).href;
+            const mod = await dynamicImport(localUrl);
+            return mod.OpenAIProvider;
+        }
+    })();
+    return openAIProviderCtorPromise;
+}
+let llmProvider;
+async function ensureProviderForAgent(agent) {
+    const Core = getCore();
+    const agentType = agent.agentType ?? 'llm';
+    if (agentType === 'llm') {
+        if (!llmProvider) {
+            const OpenAIProviderCtor = await loadOpenAIProvider();
+            llmProvider = new OpenAIProviderCtor();
+        }
+        Core.setDefaultModelProvider(llmProvider);
+    }
+    // Computer agents bypass the model provider entirely
+    // They execute directly via runtime.execute() in run.ts
+}
+const coreRun = getCore().run;
+async function run(agent, input, options) {
+    await ensureProviderForAgent(agent);
+    return coreRun(agent, input, options);
+}
+__exportStar(require("@testbase/agents-core"), exports);
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAwEA,kBAcC;AAtFD,uCAAyC;AACzC,yCAAoC;AAQpC,MAAM,aAAa,GAAG,IAAI,QAAQ,CAChC,WAAW,EACX,2BAA2B,CACW,CAAC;AAEzC,IAAI,UAAwC,CAAC;AAC7C,SAAS,OAAO;IACd,IAAI,UAAU,EAAE,CAAC;QACf,OAAO,UAAU,CAAC;IACpB,CAAC;IACD,IAAI,CAAC;QACH,UAAU,GAAG,OAAO,CAAC,uBAAuB,CAAqB,CAAC;IACpE,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,SAAS,GAAG,IAAA,mBAAO,EAAC,SAAS,EAAE,iCAAiC,CAAC,CAAC;QACxE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAqB,CAAC;IACtD,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,IAAI,yBAES,CAAC;AAEd,KAAK,UAAU,kBAAkB;IAC/B,IAAI,yBAAyB,EAAE,CAAC;QAC9B,OAAO,yBAAyB,CAAC;IACnC,CAAC;IAED,yBAAyB,GAAG,CAAC,KAAK,IAAI,EAAE;QACtC,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,aAAa,CAAC,yBAAyB,CAAC,CAAC;YAC3D,OAAO,GAAG,CAAC,cAA2C,CAAC;QACzD,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,QAAQ,GAAG,IAAA,wBAAa,EAC5B,IAAA,mBAAO,EAAC,SAAS,EAAE,oCAAoC,CAAC,CACzD,CAAC,IAAI,CAAC;YACP,MAAM,GAAG,GAAG,MAAM,aAAa,CAAC,QAAQ,CAAC,CAAC;YAC1C,OAAO,GAAG,CAAC,cAA2C,CAAC;QACzD,CAAC;IACH,CAAC,CAAC,EAAE,CAAC;IAEL,OAAO,yBAAyB,CAAC;AACnC,CAAC;AAED,IAAI,WAA4B,CAAC;AAEjC,KAAK,UAAU,sBAAsB,CAAC,KAAgC;IACpE,MAAM,IAAI,GAAG,OAAO,EAAE,CAAC;IAEvB,MAAM,SAAS,GAAG,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC;IAC3C,IAAI,SAAS,KAAK,KAAK,EAAE,CAAC;QACxB,IAAI,CAAC,WAAW,EAAE,CAAC;YACjB,MAAM,kBAAkB,GAAG,MAAM,kBAAkB,EAAE,CAAC;YACtD,WAAW,GAAG,IAAI,kBAAkB,EAAE,CAAC;QACzC,CAAC;QACD,IAAI,CAAC,uBAAuB,CAAC,WAAW,CAAC,CAAC;IAC5C,CAAC;IACD,qDAAqD;IACrD,wDAAwD;AAC1D,CAAC;AAED,MAAM,OAAO,GAAG,OAAO,EAAE,CAAC,GAAG,CAAC;AAEvB,KAAK,UAAU,GAAG,CAIvB,KAAa,EACb,KAAiF,EACjF,OAE2C;IAI3C,MAAM,sBAAsB,CAAC,KAAK,CAAC,CAAC;IACpC,OAAO,OAAO,CAAC,KAAK,EAAE,KAAK,EAAE,OAAc,CAAC,CAAC;AAC/C,CAAC;AAED,wDAAsC"}

package/dist/index.mjs

@@ -0,0 +1,57 @@
+import { pathToFileURL } from 'node:url';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import * as CoreModule from '@testbase/agents-core';
+const __dirname = fileURLToPath(new URL('.', import.meta.url));
+const dynamicImport = new Function('specifier', 'return import(specifier);');
+function getCore() {
+    return CoreModule;
+}
+let openAIProviderCtorPromise;
+async function loadOpenAIProvider() {
+    if (openAIProviderCtorPromise) {
+        return openAIProviderCtorPromise;
+    }
+    openAIProviderCtorPromise = (async () => {
+        try {
+            const mod = await dynamicImport('@testbase/agents-openai');
+            return mod.OpenAIProvider;
+        }
+        catch {
+            const localUrl = pathToFileURL(resolve(__dirname, '../../agents-openai/dist/index.mjs')).href;
+            const mod = await dynamicImport(localUrl);
+            return mod.OpenAIProvider;
+        }
+    })();
+    return openAIProviderCtorPromise;
+}
+let llmProvider;
+let codexProvider;
+async function ensureProviderForAgent(agent) {
+    const Core = getCore();
+    const agentType = agent.agentType ?? 'llm';
+    if (agentType === 'llm') {
+        if (!llmProvider) {
+            const OpenAIProviderCtor = await loadOpenAIProvider();
+            llmProvider = new OpenAIProviderCtor();
+        }
+        Core.setDefaultModelProvider(llmProvider);
+    }
+    else {
+        if (!codexProvider) {
+            codexProvider = new Core.CodexModelProvider();
+        }
+        Core.setDefaultModelProvider(codexProvider);
+    }
+}
+// Lazy getter for coreRun to avoid calling getCore() at module init time
+function getCoreRun() {
+    return getCore().run;
+}
+export async function run(agent, input, options) {
+    await ensureProviderForAgent(agent);
+    const coreRun = getCoreRun();
+    return coreRun(agent, input, options);
+}
+export * from '@testbase/agents-core';
+//# sourceMappingURL=index.js.map

package/dist/metadata.d.ts

@@ -0,0 +1,8 @@
+export declare const METADATA: {
+    name: string;
+    version: string;
+    versions: {
+        "@testbase/agents": string;
+    };
+};
+export default METADATA;

package/dist/metadata.js

@@ -0,0 +1,13 @@
+"use strict";
+// This file is automatically generated
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.METADATA = void 0;
+exports.METADATA = {
+    "name": "@testbase/agents",
+    "version": "0.1.0",
+    "versions": {
+        "@testbase/agents": "0.1.0"
+    }
+};
+exports.default = exports.METADATA;
+//# sourceMappingURL=metadata.js.map

package/dist/metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":";AACA,uCAAuC;;;AAE1B,QAAA,QAAQ,GAAG;IACtB,MAAM,EAAE,kBAAkB;IAC1B,SAAS,EAAE,OAAO;IAClB,UAAU,EAAE;QACV,kBAAkB,EAAE,OAAO;KAC5B;CACF,CAAC;AAEF,kBAAe,gBAAQ,CAAC"}

package/dist/metadata.mjs

@@ -0,0 +1,10 @@
+// This file is automatically generated
+export const METADATA = {
+    "name": "@testbase/agents",
+    "version": "0.1.0",
+    "versions": {
+        "@testbase/agents": "0.1.0"
+    }
+};
+export default METADATA;
+//# sourceMappingURL=metadata.js.map

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "computer-agents",
+  "repository": "https://github.com/testbasehq/computer-agents",
+  "homepage": "https://github.com/testbasehq/computer-agents",
+  "version": "0.2.0",
+  "description": "Build computer-use agents that write code, run tests, and deploy apps. Seamless local and cloud execution with automatic session continuity.",
+  "author": "Testbase",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "dependencies": {
+    "computer-agents-openai": "0.2.0",
+    "computer-agents-core": "0.2.0"
+  },
+  "keywords": [
+    "computer-agents",
+    "codex",
+    "agents",
+    "ai",
+    "automation",
+    "code-generation",
+    "computer-use",
+    "openai"
+  ],
+  "license": "MIT",
+  "devDependencies": {
+    "zod": "^3.25.40"
+  },
+  "peerDependencies": {
+    "zod": "^3.25.40"
+  },
+  "files": [
+    "dist"
+  ],
+  "typesVersions": {},
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prebuild": "tsx ../../scripts/embedMeta.ts",
+    "build": "tsc",
+    "build-check": "tsc --noEmit -p ./tsconfig.test.json"
+  }
+}