ComputerAgent

import { ComputerAgent, LocalSubstrate } from "computeragent";

const agent = new ComputerAgent({
  source:  { type: "git", url: "github.com/open-gitagent/general-agent" },
  harness: "claude-agent-sdk",
  runtime: new LocalSubstrate(),
  envs:    { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
});

const result = await agent.chat("Summarize this repo in two sentences.");
console.log(result.messages.at(-1));
console.log(`Cost: $${result.usage.costUsd}`);

// Explicit:
const agent = new ComputerAgent({...});
try { /* … */ } finally { await agent.dispose(); }

// Modern (auto-dispose at scope exit):
await using agent = new ComputerAgent({...});
// no try/finally needed

interface ChatResult {
  readonly sessionId: string;
  readonly messages: ReadonlyArray<unknown>;
  readonly ended: { kind: "ca_session_ended"; reason: string; errorMessage?: string };
  readonly usage: UsageRollup;
}

interface UsageRollup {
  readonly inputTokens: number;
  readonly outputTokens: number;
  readonly cacheCreationInputTokens: number;
  readonly cacheReadInputTokens: number;
  readonly costUsd: number | undefined;
}

type ChatInput =
  | string                              // user text
  | UserMessage                         // {role:"user", content:[...]}
  | UserMessage[]                       // multi-message turn
  | AsyncIterable<UserMessage>;         // streaming input

import { runTask, LocalSubstrate } from "computeragent";

const result = await runTask({
  source:  { type: "git", url: "github.com/<org>/<repo>" },
  harness: "claude-agent-sdk",
  runtime: new LocalSubstrate(),
  envs:    { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
  message: "Summarize the code in 3 bullets.",
});

source: {
  type:   "git",
  url:    "github.com/<org>/<repo>",
  ref:    "v1.2.3",            // optional — branch/tag/SHA
  subdir: "agents/triage",     // optional — sub-path inside the repo
}

source: {
  type: "local",
  path: "/Users/me/my-agent",
}

source: {
  type: "inline",
  manifest: { name: "hello", version: "0.1.0" },
  files: {
    "agent.yaml": [
      'spec_version: "0.1.0"',
      "name: hello",
      "version: 0.1.0",
      "model:",
      "  preferred: claude-haiku-4-5-20251001",
    ].join("\n"),
    "SOUL.md": "Respond in one short sentence.",
  },
}

source: "github.com/<org>/<repo>"   // → { type: "git", url: "github.com/<org>/<repo>" }

// MongoDB — shared across pods, resume from any worker
sessionStore: {
  kind: "mongo",
  options: { url: process.env.MONGO_URL!, database: "agentos" },
},

// Resume a session
const agent = new ComputerAgent({
  ...opts,
  sessionId:    "sess_abc123",
  sessionStore: { kind: "mongo", options: { url, database } },
});
await agent.chat("Continue where we left off.");

import { ComputerAgent } from "computeragent";
import { MongoTelemetry } from "@open-gitagent/agent-registry-mongo";

const agent = new ComputerAgent({
  ...opts,
  telemetry: new MongoTelemetry({
    url:      process.env.MONGO_URL!,
    database: "agentos",
    agent:    { name: "triage", source: opts.source, harness: opts.harness },
  }),
});

interface AgentTelemetry {
  onAgentConstructed?(info: AgentConstructedInfo): void | Promise<void>;
  onChatStart?(info: ChatStartInfo): void | Promise<unknown>;
  onChatEnd?(info: ChatEndInfo, context?: unknown): void | Promise<void>;
  onClose?(): void | Promise<void>;
}

import { configureOtel, OtelAuditSink } from "@computeragent/observability";

configureOtel({
  serviceName: "computeragent",
  exporter:    "otlp-http",
  endpoint:    process.env.OTEL_EXPORTER_OTLP_ENDPOINT!,
});

const auditSink = new OtelAuditSink();
const server    = new ComputerAgentServer({ /* ..., */ auditSink });

const agent = new ComputerAgent({
  ...opts,
  onToolCall: async ({ callId, toolName, input, risk }) => {
    if (toolName === "Bash" && (input as { command?: string }).command?.startsWith("rm")) {
      return { decision: "deny", reason: "rm denied by policy" };
    }
    return { decision: "allow" };
  },
});

type PermissionDecision =
  | { decision: "allow" }
  | { decision: "deny";   reason?: string }
  | { decision: "modify"; input: Record<string, unknown> };

import { ttyApproval } from "computeragent";

const agent = new ComputerAgent({
  ...opts,
  onToolCall: ttyApproval(),   // prompts at the terminal for each tool call
});

const handle = agent.chat("...");
for await (const ev of handle) {
  if (ev.kind === "ca_permission_request") {
    await handle.respondToPermission(ev.callId, { decision: "allow" });
  }
}

const agent = new ComputerAgent({
  ...opts,
  policy: {
    kind:        "srs",
    endpoint:    "https://your-policy-service.example.com",
    apiKey:      process.env.SRS_API_KEY!,
    policyId:    "policy_abc123",
    principalId: "user:alice",
  },
});

type HarnessEvent =
  | { kind: "ca_session_started";    sessionId; engine; identity; capabilities }
  | { kind: "sdk_message";           sessionId; payload }
  | { kind: "ca_permission_request"; sessionId; callId; toolName; input; risk? }
  | { kind: "ca_permission_decision";sessionId; callId; decision; reason? }
  | { kind: "ca_turn_started";       sessionId; userTextLen? }
  | { kind: "ca_usage_snapshot";     sessionId;
                                     inputTokens?; outputTokens?;
                                     cacheCreationInputTokens?; cacheReadInputTokens?;
                                     costUsd?; costSemantic?: "cumulative" | "delta" }
  | { kind: "ca_session_ended";      sessionId; reason; errorMessage? };

curl -N -X POST http://127.0.0.1:7700/v1/sessions \
  -H 'content-type: application/json' \
  -d '{
    "source": "github.com/open-gitagent/general-agent",
    "harness": "claude-agent-sdk",
    "envs": { "ANTHROPIC_API_KEY": "sk-ant-…" },
    "message": "Reply: PING"
  }'

npx computeragent run \
  --source github.com/open-gitagent/general-agent \
  --harness claude-agent-sdk \
  --message "Summarize the README in 3 bullets"

import { HarnessProtocolError, UnknownEngineError } from "computeragent";

try {
  await agent.chat("…");
} catch (e) {
  if (e instanceof HarnessProtocolError) { /* retry, swap harness url, … */ }
  if (e instanceof UnknownEngineError)   { /* "did you mean…" */ }
  throw e;
}