@standardagents/code 0.0.0-dev.fffff

package/src/bridge.ts

@@ -0,0 +1,303 @@
+/**
+ * The client-tool bridge: holds a WebSocket open to the instance, receives
+ * forwarded tool requests, runs them through the permission engine + safety
+ * guard, executes the approved ones on the host, and returns results.
+ */
+import type { ApiClient } from "./api.ts";
+import type { HostTools } from "./host-tools.ts";
+import { decide, isCatastrophic, type PermissionState } from "./permissions.ts";
+import { saveApprovals } from "./approvals.ts";
+import type { ToolRequest } from "./types.ts";
+
+export type ApprovalChoice = "allow" | "deny" | "always" | "always_risk";
+
+export type ConnectionState = "connected" | "reconnecting" | "reconnected";
+
+export interface BridgeHooks {
+  /** Print a permanent line (a finished/denied/blocked tool). */
+  onActivity(line: string): void;
+  /** Update the live working status (the currently-running tool, or null = idle). */
+  onStatus?(label: string | null): void;
+  /** Report connection lifecycle so the UI can show disconnect/reconnect state. */
+  onConnection?(state: ConnectionState, attempt: number): void;
+  /** Ask the user to approve a tool; resolve with their choice. */
+  requestApproval(req: ToolRequest, summary: string, effectiveRisk: number): Promise<ApprovalChoice>;
+}
+
+/** Tools that mutate or execute (used to deny in plan mode cleanly). */
+const PATH_ARG_TOOLS = new Set(["read_file", "list_dir", "grep", "glob", "write_file", "edit_file", "delete"]);
+
+export class Bridge {
+  private ws: WebSocket | null = null;
+  private closed = false;
+  private heartbeat: ReturnType<typeof setInterval> | null = null;
+  private reconnectAttempt = 0;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private resolveConnected: (() => void) | null = null;
+  // Durable forwarded calls we've started handling, so a server re-send (after a
+  // reconnect) doesn't prompt or run them twice.
+  private handledDurable = new Set<string>();
+
+  constructor(
+    private api: ApiClient,
+    private threadId: string,
+    private host: HostTools,
+    private perm: PermissionState,
+    private hooks: BridgeHooks
+  ) {}
+
+  /**
+   * Connect and keep the bridge connected. Resolves on the first successful
+   * open; thereafter any drop is reconnected automatically with exponential
+   * backoff (disconnections are expected — e.g. a dev-server reload — so this
+   * must be rock solid). A short safety timeout resolves startup even if the
+   * very first attempt is slow, since reconnection continues in the background.
+   */
+  connect(): Promise<void> {
+    return new Promise((resolve) => {
+      let settled = false;
+      this.resolveConnected = () => {
+        if (!settled) {
+          settled = true;
+          resolve();
+        }
+      };
+      // Don't hang startup forever if the first attempt is slow.
+      setTimeout(() => this.resolveConnected?.(), 8000);
+      this.openSocket();
+    });
+  }
+
+  private openSocket(): void {
+    if (this.closed) return;
+    const url = `${this.api.wsEndpoint}/api/threads/${this.threadId}/bridge?token=${encodeURIComponent(this.api.bearer)}`;
+    let ws: WebSocket;
+    try {
+      ws = new WebSocket(url);
+    } catch {
+      this.scheduleReconnect();
+      return;
+    }
+    this.ws = ws;
+
+    ws.addEventListener("open", () => {
+      const wasReconnecting = this.reconnectAttempt > 0;
+      this.reconnectAttempt = 0;
+      this.startHeartbeat(ws);
+      this.hooks.onConnection?.(wasReconnecting ? "reconnected" : "connected", 0);
+      this.resolveConnected?.();
+    });
+
+    ws.addEventListener("message", (ev) => this.onMessage(String((ev as MessageEvent).data)));
+
+    // A socket that fails to open fires 'error' but may never fire 'close', so
+    // both must drive reconnection. handleDrop dedupes via the current-socket check.
+    ws.addEventListener("error", () => this.handleDrop(ws));
+    ws.addEventListener("close", () => this.handleDrop(ws));
+  }
+
+  private handleDrop(ws: WebSocket): void {
+    if (this.ws !== ws) return; // stale event from a superseded socket
+    this.ws = null;
+    this.stopHeartbeat();
+    this.scheduleReconnect();
+  }
+
+  private scheduleReconnect(): void {
+    if (this.closed || this.reconnectTimer) return;
+    this.reconnectAttempt++;
+    this.hooks.onConnection?.("reconnecting", this.reconnectAttempt);
+    // Exponential backoff with jitter, capped — keep trying indefinitely.
+    const base = Math.min(500 * 2 ** (this.reconnectAttempt - 1), 15000);
+    const delay = base + Math.floor(Math.random() * 400);
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.openSocket();
+    }, delay);
+  }
+
+  private startHeartbeat(ws: WebSocket): void {
+    this.stopHeartbeat();
+    // Heartbeat so the server can tell a live client (mid-build or awaiting an
+    // approval) from a dead one and never freeze a thread on us.
+    this.heartbeat = setInterval(() => {
+      try {
+        if (ws.readyState === WebSocket.OPEN) ws.send("ping");
+      } catch {
+        // ignore
+      }
+    }, 5000);
+  }
+
+  private stopHeartbeat(): void {
+    if (this.heartbeat) {
+      clearInterval(this.heartbeat);
+      this.heartbeat = null;
+    }
+  }
+
+  close(): void {
+    this.closed = true;
+    this.stopHeartbeat();
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    this.ws?.close();
+  }
+
+  private send(payload: object): void {
+    try {
+      this.ws?.send(JSON.stringify(payload));
+    } catch {
+      // socket gone; the server will time the call out
+    }
+  }
+
+  private async onMessage(raw: string): Promise<void> {
+    let msg: any;
+    try {
+      msg = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    if (msg.type !== "tool_request") return;
+    const req = msg as ToolRequest;
+    await this.handleToolRequest(req);
+  }
+
+  /**
+   * Reply to a tool request. Durable calls (the agent parked them) deliver the
+   * result over HTTP so it lands even if this socket later drops; legacy calls
+   * reply over the WebSocket.
+   */
+  private respond(req: ToolRequest, ok: boolean, result?: string, error?: string): void {
+    if (req.durable && req.toolCallId) {
+      void this.api.postToolResult(this.threadId, req.toolCallId, ok, result, error);
+    } else {
+      this.send({ type: "tool_response", id: req.id, ok, result, error });
+    }
+  }
+
+  private async handleToolRequest(req: ToolRequest): Promise<void> {
+    // Durable calls may be re-sent by the server after a reconnect — only handle
+    // each once (prompt + run), so the user isn't asked twice.
+    if (req.durable && req.toolCallId) {
+      if (this.handledDurable.has(req.toolCallId)) return;
+      this.handledDurable.add(req.toolCallId);
+    }
+
+    const summary = describe(req);
+
+    // Compute an effective risk, escalating anything that touches paths outside
+    // the project directory (the agent is told to stay inside it).
+    let effectiveRisk = typeof req.risk === "number" ? req.risk : req.requestPermission ? 3 : 1;
+    if (PATH_ARG_TOOLS.has(req.tool) && this.host.isOutsideProject(req.args.path as string | undefined)) {
+      effectiveRisk = Math.max(effectiveRisk, 4);
+    }
+
+    // Hard safety: never run catastrophic shell commands, even in bypass mode.
+    if (req.tool === "bash" && isCatastrophic(String(req.args.command || ""))) {
+      this.hooks.onActivity(`⛔ blocked dangerous command: ${summary}`);
+      this.respond(req, false, undefined, "Blocked: this command is considered catastrophic and was refused by the client safety guard.");
+      return;
+    }
+
+    // Permission key: normally the tool name, but MCP calls are gated at the
+    // finer `mcp:<server>/<tool>` granularity so "always allow this tool" approves
+    // one server's tool rather than every MCP call.
+    const permKey = permissionKey(req);
+    const decision = decide(this.perm, permKey, effectiveRisk, !!req.requestPermission);
+
+    if (decision === "deny") {
+      this.hooks.onActivity(`⛔ ${summary} — blocked (risk ${effectiveRisk})`);
+      this.respond(req, false, undefined, `Denied by policy (risk ${effectiveRisk}).`);
+      return;
+    }
+
+    if (decision === "ask") {
+      const choice = await this.hooks.requestApproval(req, summary, effectiveRisk);
+      if (choice === "deny") {
+        this.hooks.onActivity(`⛔ ${summary} — you declined`);
+        this.respond(req, false, undefined, "The user declined to run this operation.");
+        return;
+      }
+      if (choice === "always") this.perm.alwaysAllow.add(permKey);
+      if (choice === "always_risk") this.perm.allowRisk.add(effectiveRisk);
+      if (choice === "always" || choice === "always_risk") {
+        saveApprovals(this.api, this.threadId, this.perm);
+      }
+    }
+
+    // Show the running tool in the live status, then leave a permanent line.
+    this.hooks.onStatus?.(summary);
+    const result = await this.host.execute(req.tool, req.args);
+    this.hooks.onStatus?.(null);
+    if (result.ok) {
+      this.hooks.onActivity(`✓ ${summary}${detailSuffix(req.tool, result.result)}`);
+      this.respond(req, true, result.result ?? "");
+    } else {
+      this.hooks.onActivity(`✗ ${summary} — ${result.error}`);
+      this.respond(req, false, undefined, result.error);
+    }
+  }
+}
+
+/**
+ * Stable permission key for a request. For MCP, gate on the specific server +
+ * tool/resource so approvals are fine-grained; for everything else, the tool name.
+ */
+export function permissionKey(req: ToolRequest): string {
+  if (req.tool !== "mcp") return req.tool;
+  const a = req.args;
+  const server = String(a.server || "?");
+  const action = String(a.action || "call");
+  if (action === "read_resource") return `mcp:${server}/resource`;
+  if (action === "list_tools") return `mcp:${server}/list`;
+  return `mcp:${server}/${String(a.tool || "?")}`;
+}
+
+/** One-line human summary of a tool request for the activity feed. */
+export function describe(req: ToolRequest): string {
+  const a = req.args;
+  switch (req.tool) {
+    case "mcp": {
+      const server = String(a.server || "?");
+      const action = String(a.action || "call");
+      if (action === "list_tools") return `mcp ${server}: list tools`;
+      if (action === "read_resource") return `mcp ${server}: read ${a.uri}`;
+      return `mcp ${server}: ${a.tool}`;
+    }
+    case "read_file":
+      return `read ${a.path}`;
+    case "list_dir":
+      return `list ${a.path || "."}`;
+    case "grep":
+      return `grep "${a.pattern}"${a.glob ? ` in ${a.glob}` : ""}`;
+    case "glob":
+      return `find ${a.pattern}`;
+    case "write_file":
+      return `write ${a.path}`;
+    case "edit_file":
+      return `edit ${a.path}`;
+    case "delete":
+      return `delete ${a.path}`;
+    case "bash":
+      return `bash: ${String(a.command).slice(0, 80)}`;
+    default:
+      return `${req.tool} ${JSON.stringify(a).slice(0, 80)}`;
+  }
+}
+
+/** A short parenthetical hint appended to a finished read-style tool line. */
+function detailSuffix(tool: string, result?: string): string {
+  if (!result) return "";
+  // Mutations already read clearly from their summary; don't pile on.
+  if (tool === "write_file" || tool === "edit_file" || tool === "delete") return "";
+  if (tool === "bash") {
+    const m = result.match(/\[exit code (\d+)\]\s*$/);
+    return m ? ` (exit ${m[1]})` : "";
+  }
+  const lines = result.split("\n").length;
+  return ` (${lines} line${lines === 1 ? "" : "s"})`;
+}

package/src/credentials.ts

@@ -0,0 +1,49 @@
+/** Read/write ~/.standardagents/credentials. */
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import type { CredentialsFile, InstanceCredential } from "./types.ts";
+
+const DIR = path.join(os.homedir(), ".standardagents");
+const FILE = path.join(DIR, "credentials");
+
+export function normalizeEndpoint(endpoint: string): string {
+  let e = endpoint.trim();
+  if (!/^https?:\/\//i.test(e)) e = "http://" + e;
+  return e.replace(/\/+$/, "");
+}
+
+export function loadCredentials(): CredentialsFile {
+  try {
+    const raw = fs.readFileSync(FILE, "utf8");
+    const parsed = JSON.parse(raw) as CredentialsFile;
+    if (!parsed.instances) parsed.instances = {};
+    return parsed;
+  } catch {
+    return { instances: {} };
+  }
+}
+
+export function getCredential(endpoint: string): InstanceCredential | null {
+  const creds = loadCredentials();
+  return creds.instances[normalizeEndpoint(endpoint)] ?? null;
+}
+
+export function saveCredential(cred: InstanceCredential): void {
+  const creds = loadCredentials();
+  const endpoint = normalizeEndpoint(cred.endpoint);
+  creds.instances[endpoint] = { ...cred, endpoint };
+  creds.default_endpoint = endpoint;
+  fs.mkdirSync(DIR, { recursive: true });
+  // Credentials contain a bearer token — keep them private.
+  fs.writeFileSync(FILE, JSON.stringify(creds, null, 2), { mode: 0o600 });
+  try {
+    fs.chmodSync(FILE, 0o600);
+  } catch {
+    // best effort on platforms without chmod
+  }
+}
+
+export function defaultEndpoint(): string | null {
+  return loadCredentials().default_endpoint ?? null;
+}

package/src/events-stream.ts

@@ -0,0 +1,99 @@
+/**
+ * Subscribes to the instance-wide system events channel (`GET /api/events`) to
+ * learn when threads are created, updated, or terminated. We use it to track
+ * *subagents*: a subagent runs in its own child thread, so the only live signal
+ * of "a subagent is working" is its child thread appearing here with our thread
+ * as its `parent` (and disappearing/terminating when it finishes).
+ */
+import type { ApiClient } from "./api.ts";
+
+/** The subset of a thread registry entry we care about. */
+export interface ThreadEntry {
+  id: string;
+  agent_name?: string | null;
+  tags?: string[] | null;
+  parent?: string | null;
+  terminated?: number | null;
+  created_at?: number;
+}
+
+export interface SystemEventHooks {
+  onThreadCreated(thread: ThreadEntry): void;
+  onThreadUpdated(thread: ThreadEntry): void;
+  onThreadDeleted(threadId: string): void;
+}
+
+export class SystemEvents {
+  private ws: WebSocket | null = null;
+  private closed = false;
+  private reconnectAttempt = 0;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+
+  constructor(
+    private api: ApiClient,
+    private hooks: SystemEventHooks
+  ) {}
+
+  connect(): void {
+    this.openSocket();
+  }
+
+  private openSocket(): void {
+    if (this.closed) return;
+    const url = `${this.api.wsEndpoint}/api/events?token=${encodeURIComponent(this.api.bearer)}`;
+    let ws: WebSocket;
+    try {
+      ws = new WebSocket(url);
+    } catch {
+      this.scheduleReconnect();
+      return;
+    }
+    this.ws = ws;
+    ws.addEventListener("open", () => {
+      this.reconnectAttempt = 0;
+    });
+    ws.addEventListener("message", (ev) => this.onMessage(String((ev as MessageEvent).data)));
+    ws.addEventListener("error", () => this.handleDrop(ws));
+    ws.addEventListener("close", () => this.handleDrop(ws));
+  }
+
+  private onMessage(raw: string): void {
+    let msg: any;
+    try {
+      msg = JSON.parse(raw);
+    } catch {
+      return;
+    }
+    if (msg?.type === "thread_created" && msg.thread) this.hooks.onThreadCreated(msg.thread);
+    else if (msg?.type === "thread_updated" && msg.thread) this.hooks.onThreadUpdated(msg.thread);
+    else if (msg?.type === "thread_deleted" && typeof msg.threadId === "string") {
+      this.hooks.onThreadDeleted(msg.threadId);
+    }
+  }
+
+  private handleDrop(ws: WebSocket): void {
+    if (this.ws !== ws) return;
+    this.ws = null;
+    this.scheduleReconnect();
+  }
+
+  private scheduleReconnect(): void {
+    if (this.closed || this.reconnectTimer) return;
+    this.reconnectAttempt++;
+    const base = Math.min(500 * 2 ** (this.reconnectAttempt - 1), 15000);
+    const delay = base + Math.floor(Math.random() * 400);
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = null;
+      this.openSocket();
+    }, delay);
+  }
+
+  close(): void {
+    this.closed = true;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    this.ws?.close();
+  }
+}