agents-city 0.3.0-beta.21

package/plugin/channel/runtime/opencode.ts

@@ -0,0 +1,248 @@
+import { ChildProcess } from 'child_process';
+import { randomBytes } from 'crypto';
+import { BusEnvelope } from '../protocol.js';
+import { NativeAcceptance } from '../runtime-metrics.js';
+import { executableFor, hasOption, optionValue } from './command.js';
+import { freeLoopbackPort, spawnNative, terminate, waitForHttp } from './process.js';
+import { ConnectorOptions, RuntimeConnector } from './types.js';
+
+export class OpenCodeConnector implements RuntimeConnector {
+  readonly runtime = 'opencode' as const;
+  readonly transport = 'opencode-http-sse';
+  private child: ChildProcess | null = null;
+  private baseUrl = '';
+  private headers: Record<string, string> = {};
+  private sessionId = '';
+  private eventsAbort: AbortController | null = null;
+  private turnDone: Promise<void> = Promise.resolve();
+  private finishTurn: (() => void) | null = null;
+  private assistantBuffer = '';
+  private activeSource = '';
+  private activeThread = '';
+
+  constructor(private readonly options: ConnectorOptions) {}
+
+  async start(): Promise<void> {
+    this.baseUrl = (process.env.CITY_OPENCODE_SERVER_URL || '').replace(/\/$/, '');
+    const configuredPassword = process.env.CITY_OPENCODE_SERVER_PASSWORD || '';
+    if (!this.baseUrl) {
+      const port = await freeLoopbackPort();
+      this.baseUrl = `http://127.0.0.1:${port}`;
+      const password = randomBytes(32).toString('base64url');
+      const username = 'agents-city';
+      this.headers.authorization = `Basic ${Buffer.from(`${username}:${password}`).toString('base64')}`;
+      this.child = spawnNative(
+        executableFor(this.options.command, 'opencode'),
+        ['serve', '--hostname', '127.0.0.1', '--port', String(port), '--print-logs'],
+        this.options.cwd,
+        {
+          ...process.env,
+          OPENCODE_SERVER_USERNAME: username,
+          OPENCODE_SERVER_PASSWORD: password,
+        },
+        `opencode:${this.options.actor}`,
+      );
+    } else if (configuredPassword) {
+      const username = process.env.CITY_OPENCODE_SERVER_USERNAME || 'opencode';
+      this.headers.authorization = `Basic ${Buffer.from(`${username}:${configuredPassword}`).toString('base64')}`;
+    }
+    await waitForHttp(`${this.baseUrl}/doc`, this.headers, this.child);
+    const model = parseModel(optionValue(this.options.command, ['--model', '-m']));
+    const session = await this.json('/session', {
+      method: 'POST',
+      body: JSON.stringify({
+        title: `Agents City · ${this.options.actor}`,
+        ...(model ? { model: { providerID: model.providerID, id: model.modelID } } : {}),
+        ...(this.autoApprove()
+          ? { permission: [{ permission: '*', pattern: '*', action: 'allow' }] }
+          : {}),
+      }),
+    });
+    this.sessionId = String(object(session).id || '');
+    if (!this.sessionId) throw new Error('OpenCode server did not return a session id');
+    await this.startEvents();
+    process.stderr.write(
+      `[city-gateway:${this.options.actor}] OpenCode session ${this.sessionId} ready over HTTP/SSE\n`,
+    );
+  }
+
+  async accept(prompt: string, envelope: BusEnvelope): Promise<NativeAcceptance> {
+    if (!this.sessionId) throw new Error('OpenCode connector is not ready');
+    await this.turnDone;
+    this.turnDone = new Promise<void>((resolve) => {
+      this.finishTurn = resolve;
+    });
+    this.assistantBuffer = '';
+    this.activeSource = envelope.id;
+    this.activeThread = envelope.thread || envelope.id;
+    const model = parseModel(optionValue(this.options.command, ['--model', '-m']));
+    const agent = optionValue(this.options.command, ['--agent']);
+    const response = await fetch(this.url(`/session/${this.sessionId}/prompt_async`), {
+      method: 'POST',
+      headers: { ...this.headers, 'content-type': 'application/json' },
+      body: JSON.stringify({
+        messageID: providerId('msg', envelope.id),
+        parts: [{ type: 'text', text: prompt }],
+        ...(model ? { model } : {}),
+        ...(agent ? { agent } : {}),
+      }),
+      signal: AbortSignal.timeout(30_000),
+    });
+    if (response.status !== 204) {
+      const detail = await response.text();
+      this.endTurn();
+      throw new Error(
+        `OpenCode rejected the prompt (HTTP ${response.status}): ${detail.slice(0, 400)}`,
+      );
+    }
+    return {
+      acceptedAt: new Date().toISOString(),
+      runtime: this.runtime,
+      transport: this.transport,
+      providerRequestId: envelope.id,
+    };
+  }
+
+  async close(): Promise<void> {
+    this.endTurn();
+    this.eventsAbort?.abort();
+    this.eventsAbort = null;
+    await terminate(this.child);
+    this.child = null;
+  }
+
+  private autoApprove(): boolean {
+    return this.options.autoApprove || hasOption(this.options.command, ['--auto']);
+  }
+
+  private url(path: string): string {
+    const url = new URL(path, `${this.baseUrl}/`);
+    url.searchParams.set('directory', this.options.cwd);
+    return url.toString();
+  }
+
+  private async json(path: string, init: RequestInit): Promise<unknown> {
+    const response = await fetch(this.url(path), {
+      ...init,
+      headers: { ...this.headers, 'content-type': 'application/json', ...(init.headers || {}) },
+      signal: AbortSignal.timeout(30_000),
+    });
+    if (!response.ok) {
+      throw new Error(
+        `OpenCode API ${path} failed (HTTP ${response.status}): ${(await response.text()).slice(0, 400)}`,
+      );
+    }
+    return response.json();
+  }
+
+  private async startEvents(): Promise<void> {
+    this.eventsAbort = new AbortController();
+    const response = await fetch(this.url('/event'), {
+      headers: this.headers,
+      signal: this.eventsAbort.signal,
+    });
+    if (!response.ok || !response.body) {
+      throw new Error(`OpenCode event stream failed (HTTP ${response.status})`);
+    }
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let pending = '';
+    const consume = async (): Promise<void> => {
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          pending += decoder.decode(value, { stream: true }).replaceAll('\r\n', '\n');
+          let boundary = pending.indexOf('\n\n');
+          while (boundary >= 0) {
+            const block = pending.slice(0, boundary);
+            pending = pending.slice(boundary + 2);
+            this.event(block);
+            boundary = pending.indexOf('\n\n');
+          }
+        }
+      } catch (error) {
+        if (!this.eventsAbort?.signal.aborted) {
+          process.stderr.write(`[opencode:${this.options.actor}] ${(error as Error).message}\n`);
+        }
+      }
+    };
+    void consume();
+  }
+
+  private event(block: string): void {
+    const data = block
+      .split('\n')
+      .filter((line) => line.startsWith('data:'))
+      .map((line) => line.slice(5).trimStart())
+      .join('\n');
+    if (!data) return;
+    let event: Record<string, unknown>;
+    try {
+      event = JSON.parse(data);
+    } catch {
+      return;
+    }
+    const properties = object(event.properties);
+    if (String(properties.sessionID || '') !== this.sessionId) return;
+    if (event.type === 'message.part.delta' && properties.field === 'text') {
+      const delta = String(properties.delta || '');
+      this.assistantBuffer += delta;
+      process.stdout.write(delta);
+    } else if (event.type === 'session.idle') {
+      process.stdout.write('\n');
+      const summary = this.assistantBuffer.trim().slice(0, 4_000);
+      if (summary) {
+        this.options.onActivity?.({
+          sourceId: `opencode:${this.sessionId}:${this.activeSource || 'turn'}:answer`,
+          kind: 'conversation.agent',
+          thread: this.activeThread || this.sessionId,
+          phase: 'answered',
+          tone: 'evidence',
+          title: `${this.options.actor} answered`,
+          summary,
+        });
+      }
+      this.endTurn();
+    } else if (event.type === 'session.error') {
+      process.stderr.write(
+        `[opencode:${this.options.actor}] ${JSON.stringify(properties.error)}\n`,
+      );
+      this.options.onActivity?.({
+        sourceId: `opencode:${this.sessionId}:${this.activeSource || 'turn'}:error`,
+        kind: 'runtime.turn.failed',
+        thread: this.activeThread || this.sessionId,
+        phase: 'failed',
+        tone: 'error',
+        title: `${this.options.actor} runtime failed`,
+        summary: 'OpenCode reported a turn error.',
+      });
+      this.endTurn();
+    }
+  }
+
+  private endTurn(): void {
+    this.assistantBuffer = '';
+    this.activeSource = '';
+    this.activeThread = '';
+    const finish = this.finishTurn;
+    this.finishTurn = null;
+    finish?.();
+  }
+}
+
+function parseModel(value: string): { providerID: string; modelID: string } | null {
+  const slash = value.indexOf('/');
+  if (slash <= 0 || slash === value.length - 1) return null;
+  return { providerID: value.slice(0, slash), modelID: value.slice(slash + 1) };
+}
+
+function providerId(prefix: string, envelopeId: string): string {
+  return `${prefix}_${envelopeId.replace(/[^a-zA-Z0-9_-]/g, '').slice(-48)}`;
+}
+
+function object(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}

package/plugin/channel/runtime/process.ts

@@ -0,0 +1,84 @@
+import { ChildProcess, spawn } from 'child_process';
+import { createServer } from 'net';
+
+export async function freeLoopbackPort(): Promise<number> {
+  const server = createServer();
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', resolve);
+  });
+  const address = server.address();
+  if (!address || typeof address === 'string')
+    throw new Error('could not allocate a loopback port');
+  const port = address.port;
+  await new Promise<void>((resolve) => server.close(() => resolve()));
+  return port;
+}
+
+export function spawnNative(
+  executable: string,
+  args: string[],
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+  label: string,
+  onOutput?: (text: string) => void,
+): ChildProcess {
+  const child = spawn(executable, args, {
+    cwd,
+    env,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  const output = onOutput || ((text: string) => process.stderr.write(`[${label}] ${text}`));
+  child.stdout?.on('data', (chunk) => output(String(chunk)));
+  child.stderr?.on('data', (chunk) => output(String(chunk)));
+  child.once('error', (error) => {
+    process.stderr.write(`[${label}] could not start: ${error.message}\n`);
+  });
+  return child;
+}
+
+export function spawnNativeUi(
+  executable: string,
+  args: string[],
+  cwd: string,
+  env: NodeJS.ProcessEnv,
+): ChildProcess {
+  return spawn(executable, args, { cwd, env, stdio: 'inherit' });
+}
+
+export async function waitForHttp(
+  url: string,
+  headers: Record<string, string> = {},
+  child: ChildProcess | null = null,
+  timeoutMs = 15_000,
+): Promise<Response> {
+  const deadline = Date.now() + timeoutMs;
+  let last = 'not listening';
+  while (Date.now() < deadline) {
+    if (child && child.exitCode !== null) {
+      throw new Error(`native runtime exited before its server was ready (${child.exitCode})`);
+    }
+    try {
+      const response = await fetch(url, { headers, signal: AbortSignal.timeout(700) });
+      if (response.ok) return response;
+      last = `HTTP ${response.status}`;
+    } catch (error) {
+      last = (error as Error).message;
+    }
+    await wait(100);
+  }
+  throw new Error(`native runtime server did not become ready: ${last}`);
+}
+
+export async function terminate(child: ChildProcess | null): Promise<void> {
+  if (!child || child.exitCode !== null) return;
+  child.kill('SIGTERM');
+  await Promise.race([
+    new Promise<void>((resolve) => child.once('exit', () => resolve())),
+    wait(2_000),
+  ]);
+  if (child.exitCode === null) child.kill('SIGKILL');
+}
+
+export const wait = (milliseconds: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, milliseconds));

package/plugin/channel/runtime/types.ts

@@ -0,0 +1,45 @@
+import { BusEnvelope } from '../protocol.js';
+import { NativeAcceptance } from '../runtime-metrics.js';
+
+export type NativeRuntime = 'claude' | 'codex' | 'opencode' | 'kimi';
+
+export interface RuntimeActivity {
+  sourceId?: string;
+  kind: string;
+  thread?: string | null;
+  phase?: string;
+  tone?:
+    'question' | 'work' | 'floor' | 'evidence' | 'decision' | 'verification' | 'error' | 'system';
+  title: string;
+  summary: string;
+  details?: string[];
+  target?: string;
+}
+
+export interface ConnectorOptions {
+  actor: string;
+  cwd: string;
+  command: string;
+  autoApprove: boolean;
+  interactive: boolean;
+  onActivity?: (activity: RuntimeActivity) => void;
+  onDiagnostic?: (event: string, fields?: Record<string, unknown>) => void;
+  onFatal?: (error: Error) => void;
+}
+
+export interface NativeUiCommand {
+  executable: string;
+  args: string[];
+  cwd: string;
+}
+
+export interface RuntimeConnector {
+  readonly runtime: NativeRuntime;
+  readonly transport: string;
+  start(): Promise<void>;
+  waitUntilReady?(): Promise<void>;
+  accept(prompt: string, envelope: BusEnvelope): Promise<NativeAcceptance>;
+  nativeUi?(): NativeUiCommand | null;
+  setNativeUiAttached?(attached: boolean): void;
+  close(): Promise<void>;
+}

package/plugin/channel/runtime-files.ts

@@ -0,0 +1,73 @@
+import { randomBytes } from 'crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { CityContext } from './city-config.js';
+import { ActorCredential, HubEndpoint, safeSegment } from './protocol.js';
+
+let counter = 0;
+
+export function atomicJson(path: string, value: unknown): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const tmp = `${path}.tmp-${process.pid}-${counter++}`;
+  writeFileSync(tmp, JSON.stringify(value, null, 2) + '\n', { mode: 0o600 });
+  renameSync(tmp, path);
+  try {
+    chmodSync(path, 0o600);
+  } catch {}
+}
+
+export function actorCredential(context: CityContext, actor: string): ActorCredential {
+  const definition = context.actors[actor];
+  if (!definition) throw new Error(`unknown city actor: ${actor}`);
+  const path = credentialPath(context, actor);
+  if (existsSync(path)) {
+    try {
+      const current = JSON.parse(readFileSync(path, 'utf8')) as ActorCredential;
+      if (current.actor === actor && current.role === definition.role && current.token)
+        return current;
+    } catch {}
+  }
+  const credential: ActorCredential = {
+    actor,
+    role: definition.role,
+    ...(definition.repo ? { repo: definition.repo } : {}),
+    token: randomBytes(32).toString('base64url'),
+  };
+  atomicJson(path, credential);
+  return credential;
+}
+
+export function allCredentials(context: CityContext): Record<string, ActorCredential> {
+  return Object.fromEntries(
+    Object.keys(context.actors).map((actor) => [actor, actorCredential(context, actor)]),
+  );
+}
+
+export function roadToken(context: CityContext): string {
+  const path = join(context.runtimeDir, 'road-token');
+  if (existsSync(path)) {
+    const value = readFileSync(path, 'utf8').trim();
+    if (value) return value;
+  }
+  const value = randomBytes(32).toString('base64url');
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  writeFileSync(path, value + '\n', { mode: 0o600 });
+  return value;
+}
+
+export function credentialPath(context: CityContext, actor: string): string {
+  return join(context.runtimeDir, 'actors', `${safeSegment(actor)}.json`);
+}
+
+export function endpointPath(context: CityContext): string {
+  return join(context.runtimeDir, 'endpoint.json');
+}
+
+export function readEndpoint(context: CityContext): HubEndpoint | null {
+  try {
+    const endpoint = JSON.parse(readFileSync(endpointPath(context), 'utf8')) as HubEndpoint;
+    return endpoint.cityId === context.city.id ? endpoint : null;
+  } catch {
+    return null;
+  }
+}