@a-t-h-i/bot-lobby 0.6.55 → 0.6.56

package/src/harness/claude-sdk.ts

@@ -0,0 +1,169 @@
+/**
+ * Claude Code through the Claude Agent SDK, Anthropic's supported way for an
+ * app to drive it (and to run on a Claude plan's Agent SDK credit). The SDK
+ * starts the installed `claude` when there is one (or the one set in
+ * Settings > Harnesses), else its own bundled build, and hands back the same
+ * messages as `claude -p --output-format stream-json`, so `claudeEvents`
+ * maps them. When the SDK is not installed, Bot Lobby falls back to the CLI.
+ *
+ * The options follow T3 Code's Claude adapter (`apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts`):
+ * the `claude_code` system prompt preset with Bot Lobby's instructions
+ * appended, the effort, the executable path, extra arguments and the
+ * permission mode.
+ */
+import type { Options, Query, SDKUserMessage } from "@anthropic-ai/claude-agent-sdk";
+import type { PiStreamEvent } from "../execution/pi-runner.ts";
+import { claudeCompactSettings, claudeEnv, claudeEvents, claudeTools, type ClaudeEvent } from "./claude.ts";
+import type { HarnessOutcome, HarnessProcessOptions } from "./process.ts";
+import type { HarnessAccess, HarnessCollector, HarnessPlan } from "./runner.ts";
+import { findCommand } from "./status.ts";
+
+type QueryFn = (params: { prompt: AsyncIterable<SDKUserMessage>; options?: Options }) => Query;
+
+let loader: () => Promise<QueryFn | undefined> = async () => {
+  try {
+    return (await import("@anthropic-ai/claude-agent-sdk")).query as QueryFn;
+  } catch {
+    return undefined;
+  }
+};
+
+/** The SDK's `query`, or undefined when the package is not installed. */
+export function loadClaudeSdk(): Promise<QueryFn | undefined> {
+  return loader();
+}
+
+/** Tests swap the SDK for a fake. */
+export function setClaudeSdkLoader(next: () => Promise<QueryFn | undefined>): void {
+  loader = next;
+}
+
+/** Launch arguments as the SDK's `extraArgs`: `--flag value` pairs, a bare flag as null. */
+export function extraArgsOf(tokens: readonly string[]): Record<string, string | null> {
+  const out: Record<string, string | null> = {};
+  for (let index = 0; index < tokens.length; index++) {
+    const token = tokens[index]!;
+    if (!token.startsWith("-")) continue;
+    const [name, inline] = token.replace(/^-+/, "").split(/=(.*)/s, 2) as [string, string | undefined];
+    const next = tokens[index + 1];
+    if (inline !== undefined) out[name] = inline;
+    else if (next !== undefined && !next.startsWith("-")) {
+      out[name] = next;
+      index++;
+    } else out[name] = null;
+  }
+  return out;
+}
+
+export function claudeSdkOptions(plan: HarnessPlan, access: HarnessAccess, input: { cwd: string; env: Record<string, string | undefined>; launchArgs: string[]; abort: AbortController; stderr: (data: string) => void }): Options {
+  const { settings } = plan.harness;
+  const executable = settings.binaryPath || findCommand("claude");
+  const options: Options = {
+    cwd: input.cwd,
+    abortController: input.abort,
+    persistSession: false,
+    env: { ...input.env, ...claudeEnv(plan), CLAUDE_AGENT_SDK_CLIENT_APP: "bot-lobby" },
+    stderr: input.stderr,
+    ...(executable ? { pathToClaudeCodeExecutable: executable } : {}),
+    ...(plan.model ? { model: plan.model } : {}),
+    ...(plan.effort ? { effort: plan.effort as NonNullable<Options["effort"]> } : {}),
+    ...(plan.instructions ? { systemPrompt: { type: "preset", preset: "claude_code", append: plan.instructions } } : {}),
+    ...(input.launchArgs.length > 0 ? { extraArgs: extraArgsOf(input.launchArgs) } : {}),
+  };
+  const compact = claudeCompactSettings(plan);
+  if (compact) options.settings = compact as Options["settings"];
+  if (access.writes) {
+    options.permissionMode = "bypassPermissions";
+    options.allowDangerouslySkipPermissions = true;
+  } else {
+    const tools = claudeTools(access.tools ?? []);
+    options.tools = tools;
+    options.allowedTools = tools;
+    options.permissionMode = "dontAsk";
+  }
+  return options;
+}
+
+/** The user's messages as the SDK takes them: the prompt, then any steer, until the turn's result. */
+function inputQueue(): { stream: AsyncIterable<SDKUserMessage>; push(text: string): void; end(): void } {
+  const waiting: Array<(result: IteratorResult<SDKUserMessage>) => void> = [];
+  const queued: SDKUserMessage[] = [];
+  let ended = false;
+  const message = (text: string): SDKUserMessage => ({ type: "user", message: { role: "user", content: [{ type: "text", text }] }, parent_tool_use_id: null });
+  return {
+    stream: {
+      [Symbol.asyncIterator]: () => ({
+        next: () => {
+          const item = queued.shift();
+          if (item) return Promise.resolve({ value: item, done: false });
+          if (ended) return Promise.resolve({ value: undefined, done: true });
+          return new Promise((resolve) => waiting.push(resolve));
+        },
+      }),
+    },
+    push(text) {
+      if (ended) return;
+      const item = message(text);
+      const resolve = waiting.shift();
+      if (resolve) resolve({ value: item, done: false });
+      else queued.push(item);
+    },
+    end() {
+      ended = true;
+      for (const resolve of waiting.splice(0)) resolve({ value: undefined, done: true });
+    },
+  };
+}
+
+const MAX_STDERR = 64_000;
+
+/** One turn on Claude Code through the SDK, watched like a harness process (stall, cancel, steer). */
+export async function runClaudeSdk(query: QueryFn, plan: HarnessPlan, access: HarnessAccess, input: { cwd: string; env: Record<string, string | undefined>; launchArgs: string[]; prompt: string }, collected: HarnessCollector, options: HarnessProcessOptions): Promise<HarnessOutcome> {
+  const abort = new AbortController();
+  const queue = inputQueue();
+  let stderr = "";
+  let lastOutput = Date.now();
+  let toolsInFlight = 0;
+  let killed = false;
+  let stalled = false;
+  const emit = (event: PiStreamEvent) => {
+    lastOutput = Date.now();
+    if (event.type === "tool_execution_start") toolsInFlight += 1;
+    if (event.type === "tool_execution_end") toolsInFlight = Math.max(0, toolsInFlight - 1);
+    options.onEvent?.(event);
+  };
+  const handle = claudeEvents({ emit, closeInput: () => queue.end() }, collected);
+  const onAbort = () => {
+    killed = true;
+    queue.end();
+    abort.abort();
+  };
+  const watch = setInterval(() => {
+    const limit = toolsInFlight > 0 ? options.toolStallTimeoutMs : options.stallTimeoutMs;
+    if (!killed && limit && limit > 0 && Date.now() - lastOutput >= limit) {
+      stalled = true;
+      onAbort();
+    }
+  }, 1000);
+  watch.unref();
+  if (options.signal?.aborted) onAbort();
+  else options.signal?.addEventListener("abort", onAbort, { once: true });
+  queue.push(input.prompt);
+  options.onStart?.({ steer: (text) => queue.push(text) });
+  let exitCode = 0;
+  try {
+    const sdkOptions = claudeSdkOptions(plan, access, { ...input, abort, stderr: (data) => { lastOutput = Date.now(); if (stderr.length < MAX_STDERR) stderr += data; } });
+    for await (const message of query({ prompt: queue.stream, options: sdkOptions })) {
+      lastOutput = Date.now();
+      handle(message as unknown as ClaudeEvent);
+    }
+  } catch (error) {
+    exitCode = 1;
+    if (!killed && !collected.error) collected.error = (error as Error).message;
+  } finally {
+    clearInterval(watch);
+    queue.end();
+    options.signal?.removeEventListener("abort", onAbort);
+  }
+  return { exitCode, stderr, killed, stalled };
+}

package/src/harness/claude.ts

@@ -0,0 +1,188 @@
+/**
+ * Claude Code: `claude -p` with stream-json in and out, so a steering message
+ * can be sent while the agent works. Bot Lobby's instructions are appended to
+ * Claude Code's own system prompt from a file; read-only roles get only the
+ * matching tools and `dontAsk`, so anything else is refused.
+ *
+ * The flag set follows T3 Code's `apps/server/src/textGeneration/ClaudeTextGeneration.ts`
+ * (`--tools`, `--allowedTools`, `--permission-mode dontAsk`, `--effort`,
+ * `--settings`) and the auto-compact window of
+ * `apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts`.
+ */
+import type { HarnessDriver, HarnessIO } from "./process.ts";
+import type { HarnessAccess, HarnessCollector, HarnessPlan } from "./runner.ts";
+
+/** pi's tool names and Claude Code's for the same job. */
+const CLAUDE_TOOLS: Record<string, string> = {
+  read: "Read",
+  grep: "Grep",
+  find: "Glob",
+  ls: "Glob",
+  bash: "Bash",
+  edit: "Edit",
+  write: "Write",
+  web_search: "WebSearch",
+  fetch_content: "WebFetch",
+};
+
+/** Claude Code's tool names as pi's, for the activity line and the edit log. */
+const PI_NAMES: Record<string, string> = {
+  Read: "read",
+  Grep: "grep",
+  Glob: "find",
+  LS: "ls",
+  Bash: "bash",
+  Edit: "edit",
+  MultiEdit: "edit",
+  Write: "write",
+  NotebookEdit: "edit",
+  WebSearch: "web_search",
+  WebFetch: "fetch_content",
+};
+
+/** The Claude Code tools a read-only role may use, from its pi allowlist. */
+export function claudeTools(tools: readonly string[]): string[] {
+  return [...new Set(tools.map((tool) => CLAUDE_TOOLS[tool]).filter((tool): tool is string => Boolean(tool)))];
+}
+
+export function claudeArgs(plan: HarnessPlan, access: HarnessAccess, launchArgs: string[], promptFile: string | undefined): { args: string[]; env: Record<string, string> } {
+  const args = ["-p", "--output-format", "stream-json", "--input-format", "stream-json", "--verbose", "--no-session-persistence", ...launchArgs];
+  if (plan.model) args.push("--model", plan.model);
+  if (plan.effort) args.push("--effort", plan.effort);
+  if (promptFile) args.push("--append-system-prompt-file", promptFile);
+  if (access.writes) args.push("--permission-mode", "bypassPermissions");
+  else {
+    const tools = claudeTools(access.tools ?? []).join(",");
+    args.push("--tools", tools, "--allowedTools", tools, "--permission-mode", "dontAsk");
+  }
+  const compact = claudeCompactSettings(plan);
+  if (compact) args.push("--settings", JSON.stringify(compact));
+  return { args, env: claudeEnv(plan) };
+}
+
+/** Claude Code's compaction window, when the settings give one and the agent compacts. */
+export function claudeCompactSettings(plan: HarnessPlan): { autoCompactWindow: number } | undefined {
+  return plan.autoCompact !== false && plan.harness.settings.compactAt > 0 ? { autoCompactWindow: plan.harness.settings.compactAt } : undefined;
+}
+
+/** The environment Claude Code runs with: compaction off and the model provider. */
+export function claudeEnv(plan: HarnessPlan): Record<string, string> {
+  const { settings } = plan.harness;
+  const env: Record<string, string> = {};
+  if (plan.autoCompact === false) env.DISABLE_AUTO_COMPACT = "1";
+  if (settings.modelProvider === "bedrock") env.CLAUDE_CODE_USE_BEDROCK = "1";
+  if (settings.modelProvider === "vertex") env.CLAUDE_CODE_USE_VERTEX = "1";
+  return env;
+}
+
+interface ContentBlock {
+  type?: string;
+  text?: string;
+  thinking?: string;
+  id?: string;
+  name?: string;
+  input?: Record<string, unknown>;
+  tool_use_id?: string;
+  is_error?: boolean;
+}
+
+export interface ClaudeEvent {
+  type?: string;
+  subtype?: string;
+  model?: string;
+  message?: { id?: string; model?: string; content?: ContentBlock[] | string };
+  result?: string;
+  is_error?: boolean;
+  total_cost_usd?: number;
+  usage?: { input_tokens?: number; output_tokens?: number; cache_read_input_tokens?: number; cache_creation_input_tokens?: number };
+  errors?: string[];
+}
+
+function userMessage(text: string): string {
+  return JSON.stringify({ type: "user", message: { role: "user", content: [{ type: "text", text }] } });
+}
+
+function toolArgs(input: Record<string, unknown> | undefined): Record<string, unknown> {
+  if (!input) return {};
+  const path = input.file_path ?? input.notebook_path ?? input.path;
+  return { ...input, ...(typeof path === "string" ? { path } : {}) };
+}
+
+/** What the Claude Code event handler needs: the stream to emit on, and how to end the turn's input. */
+export interface ClaudeSink {
+  emit: HarnessIO["emit"];
+  closeInput(): void;
+}
+
+/**
+ * Claude Code's messages as pi's stream events. The CLI's stream-json lines
+ * and the Agent SDK's messages are the same objects.
+ */
+export function claudeEvents(io: ClaudeSink, collector: HarnessCollector): (event: ClaudeEvent) => void {
+  const tools = new Map<string, string>();
+  let message: string | undefined;
+  return (event) => {
+    if (event.type === "system" && event.subtype === "init" && event.model) collector.model = event.model;
+    else if (event.type === "system" && event.subtype === "compact_boundary") {
+      io.emit({ type: "compaction" });
+      io.emit({ type: "compaction_end" });
+    } else if (event.type === "assistant" && Array.isArray(event.message?.content)) {
+      if (event.message.id && event.message.id !== message) {
+        message = event.message.id;
+        io.emit({ type: "turn_start" });
+      }
+      if (event.message.model) collector.model = event.message.model;
+      for (const block of event.message.content) {
+        if (block.type === "thinking" && block.thinking?.trim()) io.emit({ type: "thought", text: block.thinking.trim().slice(0, 1500) });
+        else if (block.type === "text" && block.text?.trim()) {
+          io.emit({ type: "writing" });
+          collector.text = block.text;
+        } else if (block.type === "tool_use" && block.id && block.name) {
+          const name = PI_NAMES[block.name] ?? block.name;
+          tools.set(block.id, name);
+          io.emit({ type: "tool_execution_start", toolName: name, args: toolArgs(block.input) });
+        }
+      }
+    } else if (event.type === "user" && Array.isArray(event.message?.content)) {
+      for (const block of event.message.content) {
+        if (block.type !== "tool_result" || !block.tool_use_id) continue;
+        const name = tools.get(block.tool_use_id);
+        if (!name) continue;
+        tools.delete(block.tool_use_id);
+        io.emit({ type: "tool_execution_end", toolName: name, isError: block.is_error === true });
+      }
+    } else if (event.type === "result") {
+      const usage = event.usage ?? {};
+      const input = (usage.input_tokens ?? 0) + (usage.cache_read_input_tokens ?? 0) + (usage.cache_creation_input_tokens ?? 0);
+      const output = usage.output_tokens ?? 0;
+      const cost = event.total_cost_usd ?? 0;
+      collector.addUsage(input, output, cost, collector.model);
+      io.emit({ type: "usage", input, output, cost, ...(collector.model ? { model: collector.model } : {}) });
+      if (event.is_error || (event.subtype && event.subtype !== "success")) collector.error = event.result?.trim() || event.errors?.join("; ") || `Claude Code stopped: ${event.subtype ?? "error"}`;
+      else if (typeof event.result === "string" && event.result.trim()) collector.text = event.result;
+      // Claude Code exits once its input is closed and nothing it was sent is left to answer.
+      io.closeInput();
+    }
+  };
+}
+
+export function claudeDriver(io: HarnessIO, prompt: string, collector: HarnessCollector): HarnessDriver {
+  const handle = claudeEvents(io, collector);
+  return {
+    start() {
+      io.write(userMessage(prompt));
+    },
+    steer(text) {
+      io.write(userMessage(text));
+    },
+    line(text) {
+      let event: ClaudeEvent;
+      try {
+        event = JSON.parse(text) as ClaudeEvent;
+      } catch {
+        return;
+      }
+      handle(event);
+    },
+  };
+}

package/src/harness/cli-args.ts

@@ -0,0 +1,62 @@
+/**
+ * Splits a launch-arguments setting into argv the way a POSIX shell would
+ * (quotes, backslash escapes), without running a shell.
+ *
+ * Adapted from T3 Code, `packages/shared/src/cliArgs.ts` (`tokenizeCliArgs`).
+ */
+export function tokenizeCliArgs(args?: string): ReadonlyArray<string> {
+  const input = args?.trim();
+  if (!input) return [];
+
+  const tokens: string[] = [];
+  let current = "";
+  let quote: "'" | '"' | undefined;
+  let quoted = false;
+
+  for (let index = 0; index < input.length; index++) {
+    const char = input[index];
+    if (char === undefined) continue;
+
+    if (quote) {
+      if (char === quote) {
+        quote = undefined;
+        quoted = true;
+      } else if (char === "\\" && quote === '"') {
+        const next = input[index + 1];
+        if (next !== undefined && ['"', "\\", "$", "`"].includes(next)) {
+          current += next;
+          index++;
+        } else {
+          current += char;
+        }
+      } else {
+        current += char;
+      }
+      continue;
+    }
+
+    if (char === "'" || char === '"') {
+      quote = char;
+      quoted = true;
+    } else if (/\s/.test(char)) {
+      if (current || quoted) {
+        tokens.push(current);
+        current = "";
+        quoted = false;
+      }
+    } else if (char === "\\") {
+      const next = input[index + 1];
+      if (next !== undefined && /[\s'"]/.test(next)) {
+        current += next;
+        index++;
+      } else {
+        current += char;
+      }
+    } else {
+      current += char;
+    }
+  }
+
+  if (current || quoted) tokens.push(current);
+  return tokens;
+}

package/src/harness/codex.ts

@@ -0,0 +1,155 @@
+/**
+ * Codex CLI: one `codex exec --json` run per step. The prompt goes over
+ * stdin, Bot Lobby's instructions as `developer_instructions`, and the JSONL
+ * events (`thread.started`, `item.*`, `turn.completed`) become the same
+ * stream events a pi subagent sends.
+ *
+ * The flag set follows T3 Code's `apps/server/src/textGeneration/CodexTextGeneration.ts`
+ * (`exec`, `--skip-git-repo-check`, `-s`, `--model`, `model_reasoning_effort`)
+ * and `apps/server/src/provider/codexLaunchArgs.ts`.
+ */
+import type { HarnessDriver, HarnessIO } from "./process.ts";
+import type { HarnessAccess, HarnessCollector, HarnessPlan } from "./runner.ts";
+
+/** Longest instructions passed on the command line; longer ones lead the prompt instead. */
+const MAX_ARG_BYTES = 100_000;
+/** "Never" for Codex's compaction threshold, which cannot be switched off. */
+const NO_COMPACTION = 1_000_000_000_000;
+const LOCAL_PROVIDERS = new Set(["ollama", "lmstudio"]);
+
+/** A TOML basic string: JSON's escapes are valid TOML. */
+export function tomlString(value: string): string {
+  return JSON.stringify(value);
+}
+
+export function codexArgs(plan: HarnessPlan, access: HarnessAccess, launchArgs: string[]): { args: string[]; promptPrefix: string } {
+  const { settings } = plan.harness;
+  const args = ["exec", ...launchArgs, "--json", "--skip-git-repo-check", "-s", access.writes ? "workspace-write" : "read-only", "-c", 'approval_policy="never"'];
+  if (plan.model) args.push("--model", plan.model);
+  if (plan.effort) args.push("-c", `model_reasoning_effort=${tomlString(plan.effort)}`);
+  const provider = settings.modelProvider;
+  if (LOCAL_PROVIDERS.has(provider)) args.push("--oss", "--local-provider", provider);
+  else if (provider) args.push("-c", `model_provider=${tomlString(provider)}`);
+  if (plan.autoCompact === false) args.push("-c", `model_auto_compact_token_limit=${NO_COMPACTION}`);
+  else if (settings.compactAt > 0) args.push("-c", `model_auto_compact_token_limit=${settings.compactAt}`);
+  let promptPrefix = "";
+  if (plan.instructions) {
+    if (Buffer.byteLength(plan.instructions) <= MAX_ARG_BYTES) args.push("-c", `developer_instructions=${tomlString(plan.instructions)}`);
+    else promptPrefix = plan.instructions;
+  }
+  args.push("-");
+  return { args, promptPrefix };
+}
+
+interface CodexItem {
+  id?: string;
+  type?: string;
+  text?: string;
+  command?: string;
+  exit_code?: number | null;
+  status?: string;
+  changes?: Array<{ path?: string; kind?: string }>;
+  server?: string;
+  tool?: string;
+  query?: string;
+  message?: string;
+}
+
+interface CodexEvent {
+  type?: string;
+  thread_id?: string;
+  item?: CodexItem;
+  usage?: { input_tokens?: number; cached_input_tokens?: number; output_tokens?: number };
+  error?: { message?: string };
+  message?: string;
+}
+
+function toolOf(item: CodexItem): { name: string; args: Record<string, unknown> } | undefined {
+  switch (item.type) {
+    case "command_execution":
+      return { name: "bash", args: { command: item.command ?? "" } };
+    case "mcp_tool_call":
+      return { name: `mcp__${item.server ?? "server"}__${item.tool ?? "tool"}`, args: {} };
+    case "web_search":
+      return { name: "web_search", args: { query: item.query ?? "" } };
+    default:
+      return undefined;
+  }
+}
+
+export function codexDriver(io: HarnessIO, plan: HarnessPlan, prompt: string, collector: HarnessCollector): HarnessDriver {
+  const started = new Set<string>();
+  const onItem = (phase: "started" | "updated" | "completed", item: CodexItem) => {
+    if (item.type === "agent_message" && phase === "completed") {
+      io.emit({ type: "writing" });
+      if (item.text?.trim()) collector.text = item.text;
+      return;
+    }
+    if (item.type === "reasoning" && phase === "completed") {
+      if (item.text?.trim()) io.emit({ type: "thought", text: item.text.trim().slice(0, 1500) });
+      return;
+    }
+    if (item.type === "file_change" && phase === "completed") {
+      for (const change of item.changes ?? []) {
+        if (!change.path) continue;
+        const name = change.kind === "add" ? "write" : "edit";
+        io.emit({ type: "tool_execution_start", toolName: name, args: { path: change.path } });
+        io.emit({ type: "tool_execution_end", toolName: name, isError: item.status === "failed" });
+      }
+      return;
+    }
+    if (item.type === "error" && item.message) {
+      collector.warning = item.message;
+      return;
+    }
+    const tool = toolOf(item);
+    if (!tool) return;
+    const id = item.id ?? `${tool.name}:${started.size}`;
+    if (!started.has(id)) {
+      started.add(id);
+      io.emit({ type: "tool_execution_start", toolName: tool.name, args: tool.args });
+      if (phase !== "completed") return;
+    }
+    if (phase === "completed") io.emit({ type: "tool_execution_end", toolName: tool.name, isError: item.status === "failed" || (typeof item.exit_code === "number" && item.exit_code !== 0) });
+  };
+  return {
+    start() {
+      io.write(prompt);
+      io.closeInput();
+    },
+    line(text) {
+      let event: CodexEvent;
+      try {
+        event = JSON.parse(text) as CodexEvent;
+      } catch {
+        return;
+      }
+      switch (event.type) {
+        case "thread.started":
+          collector.session = event.thread_id;
+          return;
+        case "turn.started":
+          io.emit({ type: "turn_start" });
+          return;
+        case "item.started":
+        case "item.updated":
+        case "item.completed":
+          if (event.item) onItem(event.type.slice("item.".length) as "started" | "updated" | "completed", event.item);
+          return;
+        case "turn.completed": {
+          const input = (event.usage?.input_tokens ?? 0);
+          const output = event.usage?.output_tokens ?? 0;
+          collector.addUsage(input, output, 0, plan.model || undefined);
+          io.emit({ type: "usage", input, output, cost: 0, ...(plan.model ? { model: plan.model } : {}) });
+          return;
+        }
+        case "turn.failed":
+          collector.error = event.error?.message ?? "Codex reported a failed turn";
+          return;
+        case "error":
+          if (event.message) collector.warning = event.message;
+          return;
+      }
+    },
+  };
+}

package/src/harness/instructions.ts

@@ -0,0 +1,45 @@
+/**
+ * How Bot Lobby's prompts reach a third-party harness.
+ *
+ * Codex takes them as developer instructions and Claude Code appends them to
+ * its own system prompt; ACP has no system prompt field, so they ride in the
+ * first prompt, wrapped so they cannot be mistaken for the user's words.
+ * Adapted from T3 Code, `packages/provider-core/src/server/runtimeInstructions.ts`
+ * (`buildRuntimeInstructions`) and `orchestrationInstructions.ts`
+ * (`t3AcpPromptWithInstructions`).
+ */
+import type { HarnessRun } from "../schemas/harness.ts";
+import { HARNESSES } from "./catalog.ts";
+
+/** Pi's tool names in the role prompts, and what stands in for them on another harness. */
+const HARNESS_NOTE = `## Running on another harness
+
+You run in Bot Lobby through a third-party harness, not pi. Where these instructions name pi's tools (read, edit, write, bash, grep, find, ls), use your own equivalents. Bot Lobby's own tools (ask_user_question, ask_expert, the file desk and task board tools, web_search and fetch_content) are not available here: work from the brief, use your own web tools if you have them, and put any open question or blocker in your report instead of asking.`;
+
+function toSingleLine(value: string): string {
+  return value.replaceAll(/\s+/g, " ").trim();
+}
+
+/** Who and what the agent runs as, in case it is asked. */
+export function runtimeInstructions(harness: HarnessRun, effort?: string): string {
+  const model = toSingleLine(harness.model);
+  const modelInfo = model ? `, as ${model}` : "";
+  const effortInfo = effort ? ` with ${toSingleLine(effort)} reasoning effort` : "";
+  return `<runtime_info>In case you're asked: you are running in Bot Lobby through the ${HARNESSES[harness.id].label} harness${modelInfo}${effortInfo}. No need to mention this otherwise.</runtime_info>`;
+}
+
+/**
+ * The instructions a harness run gets: the compiled role prompt and the
+ * harness note when prompts are injected, else only the report format the
+ * engine parses (`contract`), which a run cannot do without.
+ */
+export function harnessInstructions(input: { harness: HarnessRun; systemPrompt?: string; contract?: string; effort?: string }): string {
+  const body = input.harness.settings.injectPrompts ? [input.systemPrompt ?? "", HARNESS_NOTE] : [input.contract ?? ""];
+  return [...body, runtimeInstructions(input.harness, input.effort)].filter((part) => part.trim().length > 0).join("\n\n---\n\n");
+}
+
+/** ACP: the instructions go in front of the first prompt, wrapped; a native slash command stays first. */
+export function acpPromptWithInstructions(prompt: string, instructions: string): string {
+  if (prompt.trimStart().startsWith("/") || !instructions.trim()) return prompt;
+  return `<bot_lobby_instructions>\n${instructions}\n</bot_lobby_instructions>\n\n<user_request>\n${prompt}\n</user_request>`;
+}