Creating Plugins

import type { 
  PluginModule, 
  Runtime,
  RuntimeCreateConfig,
  RuntimeHandle,
  RuntimeMetrics,
  AttachInfo,
} from "@composio/ao-core";
import { execFile } from "node:child_process";
import { promisify } from "node:util";

const execFileAsync = promisify(execFile);

// =============================================================================
// Manifest
// =============================================================================

export const manifest = {
  name: "my-runtime",
  slot: "runtime" as const,
  description: "My custom runtime plugin",
  version: "0.1.0",
};

// =============================================================================
// Implementation
// =============================================================================

export function create(config?: Record<string, unknown>): Runtime {
  // Extract and validate config
  const timeout = typeof config?.timeout === "number" ? config.timeout : 30_000;
  
  return {
    name: "my-runtime",

    async create(config: RuntimeCreateConfig): Promise<RuntimeHandle> {
      // 1. Create execution environment
      // 2. Launch the agent with config.launchCommand
      // 3. Return handle for future operations
      
      return {
        id: "unique-session-id",
        runtimeName: "my-runtime",
        data: {
          createdAt: Date.now(),
          // Store runtime-specific data here
        },
      };
    },

    async destroy(handle: RuntimeHandle): Promise<void> {
      // Clean up the execution environment
      // Best-effort cleanup - don't throw if already dead
    },

    async sendMessage(handle: RuntimeHandle, message: string): Promise<void> {
      // Send a message to the running agent
      // This is how the orchestrator communicates with agents
    },

    async getOutput(handle: RuntimeHandle, lines = 50): Promise<string> {
      // Capture recent output from the session
      // Used for activity detection and debugging
      return "";
    },

    async isAlive(handle: RuntimeHandle): Promise<boolean> {
      // Check if the session environment is still running
      return false;
    },

    async getMetrics(handle: RuntimeHandle): Promise<RuntimeMetrics> {
      // Optional: return resource usage metrics
      return {
        uptimeMs: Date.now() - (handle.data.createdAt as number),
      };
    },

    async getAttachInfo(handle: RuntimeHandle): Promise<AttachInfo> {
      // Optional: return info for Terminal plugin to attach humans
      return {
        type: "process",
        target: handle.id,
        command: `attach-to ${handle.id}`,
      };
    },
  };
}

// =============================================================================
// Plugin Export
// =============================================================================

export default { manifest, create } satisfies PluginModule<Runtime>;

async destroy(handle: RuntimeHandle): Promise<void> {
  try {
    await execFileAsync("docker", ["rm", "-f", handle.id]);
  } catch {
    // Container may already be gone - that's fine
  }
}

import { describe, it, expect } from "vitest";
import { create, manifest } from "./index.js";

describe("my-plugin", () => {
  it("exports correct manifest", () => {
    expect(manifest.name).toBe("my-plugin");
    expect(manifest.slot).toBe("runtime");
  });
  
  it("creates valid instance", () => {
    const plugin = create();
    expect(plugin.name).toBe("my-plugin");
  });
  
  // Add more tests...
});

ao-plugin-runtime-my-plugin/
├── package.json
├── tsconfig.json
├── src/
│   └── index.ts
├── dist/           # Built output
│   └── index.js
└── README.md

{
  "name": "@ao-plugin/runtime-my-plugin",
  "version": "0.1.0",
  "type": "module",
  "main": "./dist/index.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "default": "./dist/index.js"
    }
  },
  "scripts": {
    "build": "tsc",
    "test": "vitest"
  },
  "dependencies": {
    "@composio/ao-core": "^0.1.0"
  },
  "devDependencies": {
    "typescript": "^5.3.0",
    "vitest": "^1.0.0"
  },
  "peerDependencies": {
    "@composio/ao-core": "^0.1.0"
  }
}

pnpm add @ao-plugin/runtime-my-plugin

# agent-orchestrator.yaml
defaults:
  runtime: my-plugin

export function create(config?: Record<string, unknown>): MyPlugin {
  // Extract with defaults
  const timeout = typeof config?.timeout === "number" ? config.timeout : 30_000;
  const apiKey = typeof config?.apiKey === "string" ? config.apiKey : process.env.MY_API_KEY;
  
  if (!apiKey) {
    throw new Error("API key required: set MY_API_KEY environment variable");
  }
  
  return { /* ... */ };
}

import { execFile } from "node:child_process";
import { promisify } from "node:util";

const execFileAsync = promisify(execFile);

async function runCommand(args: string[]): Promise<string> {
  try {
    const { stdout } = await execFileAsync("mycommand", args, { 
      timeout: 30_000,
      maxBuffer: 10 * 1024 * 1024,
    });
    return stdout.trim();
  } catch (err) {
    throw new Error(`Command failed: ${(err as Error).message}`, { cause: err });
  }
}

let cache: { data: string; timestamp: number } | null = null;
const CACHE_TTL_MS = 5_000;

async function getCachedData(): Promise<string> {
  const now = Date.now();
  if (cache && now - cache.timestamp < CACHE_TTL_MS) {
    return cache.data;
  }
  
  const data = await fetchExpensiveData();
  cache = { data, timestamp: now };
  return data;
}

const SAFE_PATH_SEGMENT = /^[a-zA-Z0-9_-]+$/;

function assertSafePathSegment(value: string, label: string): void {
  if (!SAFE_PATH_SEGMENT.test(value)) {
    throw new Error(`Invalid ${label} "${value}": must match ${SAFE_PATH_SEGMENT}`);
  }
}

// Usage
assertSafePathSegment(sessionId, "sessionId");
const path = join(baseDir, sessionId); // Safe - no directory traversal