@agento-nexus/sdk 0.1.0

package/dist/src/index.d.ts

@@ -0,0 +1,369 @@
+import { Sandbox } from 'e2b';
+
+/** Configuration for creating a FangBox sandbox */
+interface FangBoxConfig {
+    /** E2B template ID (default: "openfang-claude") */
+    templateId?: string;
+    /** Environment variables to inject into the sandbox */
+    envs?: Record<string, string>;
+    /** Sandbox timeout in seconds (default: 300) */
+    timeout?: number;
+    /** OpenFang daemon port inside sandbox (default: 4200) */
+    openfangPort?: number;
+    /** Metadata tags for the sandbox */
+    metadata?: Record<string, string>;
+}
+/** OpenFang Hand manifest (agent definition) */
+interface HandManifest {
+    name: string;
+    description?: string;
+    model?: string;
+    system_prompt?: string;
+    tools?: string[];
+    max_turns?: number;
+    temperature?: number;
+}
+/** Running agent info returned by OpenFang */
+interface AgentInfo {
+    id: string;
+    name: string;
+    status: "running" | "idle" | "error" | "completed";
+    created_at: string;
+    metadata?: Record<string, unknown>;
+}
+/** Agent message for conversation */
+interface AgentMessage {
+    role: "user" | "assistant" | "system";
+    content: string;
+    timestamp?: string;
+}
+/** Response from messaging an agent */
+interface AgentResponse {
+    id: string;
+    agent_id: string;
+    content: string;
+    role: "assistant";
+    metadata?: Record<string, unknown>;
+}
+/** Claude Code execution request */
+interface ClaudeCodeRequest {
+    prompt: string;
+    /** Output format: "text" or "json" (default: "text") */
+    outputFormat?: "text" | "json";
+    /** Working directory inside sandbox */
+    cwd?: string;
+    /** Additional CLI flags */
+    flags?: string[];
+    /** Session ID for multi-turn conversations */
+    sessionId?: string;
+    /** Max tokens for response */
+    maxTokens?: number;
+}
+/** Claude Code execution result */
+interface ClaudeCodeResult {
+    output: string;
+    exitCode: number;
+    /** Parsed JSON output if outputFormat was "json" */
+    parsed?: unknown;
+    /** Duration in milliseconds */
+    durationMs: number;
+    sessionId?: string;
+}
+/** OpenFang daemon health response */
+interface HealthResponse {
+    status: "ok" | "degraded" | "error";
+    version: string;
+    uptime_seconds: number;
+    agents_running: number;
+}
+/** Tool definition for OpenFang agents */
+interface ToolDefinition {
+    name: string;
+    description: string;
+    parameters?: Record<string, unknown>;
+}
+/** Workflow definition for fleet orchestration */
+interface WorkflowDefinition {
+    name: string;
+    description?: string;
+    version?: string;
+    steps: WorkflowStep[];
+    /** Global environment variables for all steps */
+    envs?: Record<string, string>;
+}
+/** Single step in a workflow */
+interface WorkflowStep {
+    id: string;
+    name: string;
+    /** Hand manifest name or inline definition */
+    hand: string | HandManifest;
+    /** Prompt template (supports {{outputKey}} interpolation) */
+    prompt: string;
+    /** Step IDs this step depends on */
+    dependsOn?: string[];
+    /** Condition to evaluate before running (JS expression) */
+    condition?: string;
+    /** Key to store output under for downstream steps */
+    outputKey?: string;
+    /** Override sandbox config for this step */
+    config?: FangBoxConfig;
+    /** Timeout for this step in seconds */
+    timeout?: number;
+}
+/** Result of a single workflow step */
+interface StepResult {
+    stepId: string;
+    status: "success" | "failure" | "skipped";
+    output?: string;
+    error?: string;
+    durationMs: number;
+}
+/** Result of a complete workflow run */
+interface WorkflowResult {
+    workflowName: string;
+    status: "success" | "partial" | "failure";
+    steps: StepResult[];
+    totalDurationMs: number;
+    outputs: Record<string, string>;
+}
+/** Events emitted by FangBox and Fleet */
+type FangBoxEvent = {
+    type: "sandbox:creating";
+} | {
+    type: "sandbox:ready";
+    sandboxId: string;
+} | {
+    type: "sandbox:error";
+    error: Error;
+} | {
+    type: "sandbox:destroyed";
+    sandboxId: string;
+} | {
+    type: "daemon:starting";
+} | {
+    type: "daemon:healthy";
+    version: string;
+} | {
+    type: "daemon:unhealthy";
+    error: string;
+} | {
+    type: "agent:spawned";
+    agentId: string;
+    name: string;
+} | {
+    type: "agent:message";
+    agentId: string;
+    content: string;
+} | {
+    type: "agent:completed";
+    agentId: string;
+} | {
+    type: "agent:error";
+    agentId: string;
+    error: string;
+};
+type FleetEvent = {
+    type: "workflow:start";
+    name: string;
+} | {
+    type: "workflow:complete";
+    result: WorkflowResult;
+} | {
+    type: "step:start";
+    stepId: string;
+} | {
+    type: "step:complete";
+    stepId: string;
+    result: StepResult;
+} | {
+    type: "step:skip";
+    stepId: string;
+    reason: string;
+};
+/** E2B template build configuration */
+interface TemplateBuildConfig {
+    /** Base E2B template to extend (default: "claude") */
+    baseTemplate?: string;
+    /** OpenFang version to install */
+    openfangVersion?: string;
+    /** Additional packages to install */
+    packages?: string[];
+    /** Custom setup script to run */
+    setupScript?: string;
+}
+
+interface RetryOptions {
+    maxAttempts?: number;
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    backoffMultiplier?: number;
+    retryIf?: (error: unknown) => boolean;
+}
+declare function retry<T>(fn: () => Promise<T>, opts?: RetryOptions): Promise<T>;
+
+interface OpenFangClientConfig {
+    /** Base URL for the OpenFang REST API */
+    baseUrl: string;
+    /** Request timeout in ms (default: 30000) */
+    timeoutMs?: number;
+    /** Retry options for failed requests */
+    retryOptions?: RetryOptions;
+}
+declare class OpenFangClient {
+    private baseUrl;
+    private timeoutMs;
+    private retryOpts;
+    private log;
+    constructor(config: OpenFangClientConfig);
+    /** Check daemon health */
+    health(): Promise<HealthResponse>;
+    /** Wait for daemon to become healthy */
+    waitForHealthy(maxWaitMs?: number): Promise<HealthResponse>;
+    /** Spawn a new agent from a Hand manifest */
+    spawnAgent(manifest: HandManifest): Promise<AgentInfo>;
+    /** List all running agents */
+    listAgents(): Promise<AgentInfo[]>;
+    /** Get agent info by ID */
+    getAgent(agentId: string): Promise<AgentInfo>;
+    /** Send a message to an agent */
+    messageAgent(agentId: string, content: string): Promise<AgentResponse>;
+    /** Stop an agent */
+    stopAgent(agentId: string): Promise<void>;
+    /** List available tools */
+    listTools(): Promise<ToolDefinition[]>;
+    private request;
+}
+declare class OpenFangError extends Error {
+    statusCode: number;
+    constructor(message: string, statusCode: number);
+}
+
+declare class ClaudeBridge {
+    private sandbox;
+    private log;
+    constructor(sandbox: Sandbox);
+    /** Execute a Claude Code prompt inside the sandbox */
+    execute(request: ClaudeCodeRequest): Promise<ClaudeCodeResult>;
+    /** Check if Claude Code is installed in the sandbox */
+    isAvailable(): Promise<boolean>;
+    private buildArgs;
+    private shellEscape;
+}
+
+type Listener<T> = (event: T) => void;
+declare class TypedEmitter<T> {
+    private listeners;
+    on(listener: Listener<T>): () => void;
+    emit(event: T): void;
+    removeAll(): void;
+}
+
+declare class FangBox {
+    readonly sandbox: Sandbox;
+    readonly client: OpenFangClient;
+    readonly claudeBridge: ClaudeBridge;
+    readonly events: TypedEmitter<FangBoxEvent>;
+    private log;
+    private constructor();
+    /**
+     * Create a new FangBox — spins up sandbox, starts daemon, waits for health.
+     * All commands run inside the E2B cloud sandbox (not local shell).
+     */
+    static create(config?: FangBoxConfig): Promise<FangBox>;
+    get sandboxId(): string;
+    /** Check daemon health */
+    health(): Promise<HealthResponse>;
+    /** Spawn an agent from a Hand manifest or name */
+    spawnAgent(handOrName: HandManifest | string): Promise<AgentInfo>;
+    /** Send a message to a running agent */
+    messageAgent(agentId: string, content: string): Promise<AgentResponse>;
+    /** List all running agents */
+    listAgents(): Promise<AgentInfo[]>;
+    /** Stop an agent */
+    stopAgent(agentId: string): Promise<void>;
+    /** Execute Claude Code in the sandbox */
+    runClaude(request: ClaudeCodeRequest): Promise<ClaudeCodeResult>;
+    /** Upload a file to the sandbox */
+    uploadFile(path: string, content: string): Promise<void>;
+    /** Read a file from the sandbox */
+    readFile(path: string): Promise<string>;
+    /**
+     * Run a command inside the E2B cloud sandbox.
+     * This uses E2B's sandbox.commands.run() which executes remotely,
+     * not on the local machine.
+     */
+    runInSandbox(command: string, opts?: {
+        cwd?: string;
+        timeoutMs?: number;
+    }): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+    /** Destroy the sandbox */
+    destroy(): Promise<void>;
+}
+/** Convenience function to create a FangBox */
+declare function createFangBox(config?: FangBoxConfig): Promise<FangBox>;
+
+interface FleetConfig {
+    /** Max concurrent sandboxes (default: 3) */
+    maxConcurrency?: number;
+    /** Default sandbox timeout in seconds */
+    defaultTimeout?: number;
+    /** Default environment variables for all sandboxes */
+    envs?: Record<string, string>;
+}
+declare class Fleet {
+    readonly events: TypedEmitter<FleetEvent>;
+    private log;
+    private maxConcurrency;
+    private defaultTimeout;
+    private envs;
+    constructor(config?: FleetConfig);
+    /** Run a workflow from a parsed definition */
+    run(workflow: WorkflowDefinition): Promise<WorkflowResult>;
+    /** Load and run a workflow from a JSON file path */
+    runFromFile(filePath: string): Promise<WorkflowResult>;
+    private executeStep;
+    /** Interpolate {{outputKey}} placeholders in a string */
+    private interpolate;
+    /**
+     * Evaluate a condition against available outputs.
+     * Supports safe expressions: "outputKey", "!outputKey",
+     * "outputKey == 'value'", "outputKey != 'value'"
+     */
+    private evaluateCondition;
+    /** Topological sort of workflow steps using Kahn's algorithm */
+    private topologicalSort;
+}
+
+declare class TemplateBuilder {
+    private log;
+    constructor();
+    /** Build an E2B template with OpenFang installed */
+    build(config?: TemplateBuildConfig): Promise<{
+        templateId: string;
+        openfangVersion: string;
+    }>;
+    /** Verify an existing template has OpenFang ready */
+    verify(templateId: string): Promise<{
+        healthy: boolean;
+        version?: string;
+        error?: string;
+    }>;
+}
+
+type LogLevel = "debug" | "info" | "warn" | "error";
+declare class Logger {
+    private prefix;
+    private minLevel;
+    constructor(prefix: string, level?: LogLevel);
+    debug(msg: string, data?: Record<string, unknown>): void;
+    info(msg: string, data?: Record<string, unknown>): void;
+    warn(msg: string, data?: Record<string, unknown>): void;
+    error(msg: string, data?: Record<string, unknown>): void;
+    private log;
+}
+
+export { type AgentInfo, type AgentMessage, type AgentResponse, ClaudeBridge, type ClaudeCodeRequest, type ClaudeCodeResult, FangBox, type FangBoxConfig, type FangBoxEvent, Fleet, type FleetEvent, type HandManifest, type HealthResponse, Logger, OpenFangClient, OpenFangError, type StepResult, type TemplateBuildConfig, TemplateBuilder, type ToolDefinition, TypedEmitter, type WorkflowDefinition, type WorkflowResult, type WorkflowStep, createFangBox, retry };

package/dist/src/index.js

@@ -0,0 +1,25 @@
+import {
+  ClaudeBridge,
+  FangBox,
+  Fleet,
+  Logger,
+  OpenFangClient,
+  OpenFangError,
+  TemplateBuilder,
+  TypedEmitter,
+  createFangBox,
+  retry
+} from "../chunk-UXIUTT4T.js";
+export {
+  ClaudeBridge,
+  FangBox,
+  Fleet,
+  Logger,
+  OpenFangClient,
+  OpenFangError,
+  TemplateBuilder,
+  TypedEmitter,
+  createFangBox,
+  retry
+};
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@agento-nexus/sdk",
+  "version": "0.1.0",
+  "description": "Agent OS in Cloud Sandboxes — OpenFang + E2B + Claude Code",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "agento-sdk": "./dist/cli/bin.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit"
+  },
+  "dependencies": {
+    "e2b": "^1.2.0",
+    "commander": "^13.1.0",
+    "chalk": "^5.4.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.3",
+    "tsup": "^8.4.0",
+    "vitest": "^3.0.0",
+    "@types/node": "^22.12.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agento-nexus/sdk.git"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}