@engineeros/connector 0.8.8 → 0.9.0

package/src/acp-client.mjs

@@ -2,7 +2,11 @@ import { spawn } from "node:child_process";
 import { Readable, Writable } from "node:stream";
 import * as acp from "@agentclientprotocol/sdk";
 
-function permissionOutcome(options = []) {
+const RUNTIME_IDLE_MS = 30 * 60 * 1_000;
+const runtimes = new Map();
+
+export function permissionOutcome(options = [], allow = false) {
+  if (!allow) return { outcome: { outcome: "cancelled" } };
   const selected =
     options.find((option) => option.kind === "allow_once") ??
     options.find((option) => option.kind === "allow_always");
@@ -11,99 +15,359 @@ function permissionOutcome(options = []) {
     : { outcome: { outcome: "cancelled" } };
 }
 
-export function launchAcpAgent(workspace, prompt, config, callbacks = {}) {
+export function launchAcpAgent(
+  workspace,
+  prompt,
+  config,
+  callbacks = {},
+  options = {},
+) {
   if (!config.agent_command) {
     throw new Error(
-      "No ACP coding agent is configured. Pair again with --agent-command and optional --agent-args JSON.",
+      "No ACP coding agent is configured. Pair again with --agent or --agent-command and optional --agent-args JSON.",
     );
   }
-  const child = spawn(
-    config.agent_command,
-    Array.isArray(config.agent_args) ? config.agent_args : [],
-    {
-      cwd: workspace,
-      env: process.env,
-      shell: false,
-      stdio: ["pipe", "pipe", "pipe"],
-    },
-  );
-  let stderr = "";
-  child.stderr.setEncoding("utf8");
-  child.stderr.on("data", (chunk) => {
-    stderr += chunk;
-    callbacks.onEvent?.({
-      type: "agent.stderr",
-      message: String(chunk).trim().slice(0, 500),
+  const persistent = options.persistent === true;
+  const runtimeKey = persistent ? acpRuntimeKey(workspace, config) : null;
+  let runtime = runtimeKey ? runtimes.get(runtimeKey) : null;
+  if (!runtime?.isRunning()) {
+    runtime = new AcpRuntime(workspace, config, () => {
+      if (runtimeKey && runtimes.get(runtimeKey) === runtime) {
+        runtimes.delete(runtimeKey);
+      }
     });
-  });
-
-  const stream = acp.ndJsonStream(
-    Writable.toWeb(child.stdin),
-    Readable.toWeb(child.stdout),
-  );
-  let finalMessage = "";
-  const completed = acp
-    .client({ name: "EngineerOS" })
-    .onRequest(acp.methods.client.session.requestPermission, (ctx) =>
-      permissionOutcome(ctx.params.options),
-    )
-    .connectWith(stream, async (ctx) => {
-      const initialized = await ctx.request(acp.methods.agent.initialize, {
-        protocolVersion: acp.PROTOCOL_VERSION,
-        clientCapabilities: {},
-      });
+    if (runtimeKey) runtimes.set(runtimeKey, runtime);
+  }
+  const sessionKey = options.sessionKey || `isolated-${crypto.randomUUID()}`;
+  const completed = runtime
+    .prompt({
+      sessionKey,
+      prompt,
+      previousSessionId: options.previousSessionId,
+      sandbox: options.sandbox,
+      profile: options.profile,
+      callbacks,
+    })
+    .finally(async () => {
+      if (!persistent) await runtime.dispose();
+    });
+  return {
+    child: runtime.child,
+    completed,
+    cancel: () => runtime.cancel(sessionKey),
+  };
+}
+
+export async function disposeAcpRuntimes() {
+  const active = [...runtimes.values()];
+  runtimes.clear();
+  await Promise.all(active.map((runtime) => runtime.dispose()));
+}
+
+export function activeAcpRuntimeCount() {
+  return runtimes.size;
+}
+
+class AcpRuntime {
+  constructor(workspace, config, onClose) {
+    this.workspace = workspace;
+    this.config = config;
+    this.onClose = onClose;
+    this.sessions = new Map();
+    this.turns = new Map();
+    this.stderr = "";
+    this.disposed = false;
+    this.idleTimer = null;
+    this.child = spawn(
+      config.agent_command,
+      Array.isArray(config.agent_args) ? config.agent_args : [],
+      {
+        cwd: workspace,
+        env: { ...process.env, ...(config.agent_env || {}) },
+        shell:
+          process.platform === "win32" &&
+          /\.(cmd|bat)$/i.test(config.agent_command),
+        stdio: ["pipe", "pipe", "pipe"],
+      },
+    );
+    this.child.stderr.setEncoding("utf8");
+    this.child.stderr.on("data", (chunk) => {
+      this.stderr = `${this.stderr}${chunk}`.slice(-4_000);
+      for (const turn of this.turns.values()) {
+        turn.callbacks.onEvent?.({
+          type: "agent.stderr",
+          message: String(chunk).trim().slice(0, 500),
+        });
+      }
+    });
+    this.child.once("error", (error) => {
+      this.spawnError = error;
+    });
+    const stream = acp.ndJsonStream(
+      Writable.toWeb(this.child.stdin),
+      Readable.toWeb(this.child.stdout),
+    );
+    this.connection = acp
+      .client({ name: "EngineerOS" })
+      .onRequest(acp.methods.client.session.requestPermission, (ctx) =>
+        this.permissionOutcome(ctx.params),
+      )
+      .onNotification(acp.methods.client.session.update, (ctx) =>
+        this.handleUpdate(ctx.params),
+      )
+      .connect(stream);
+    this.context = this.connection.agent;
+    this.ready = this.initialize();
+    void this.ready.catch(() => {
+      void this.dispose();
+    });
+    this.child.once("exit", () => this.closed());
+    void this.connection.closed.then(
+      () => this.closed(),
+      () => this.closed(),
+    );
+  }
+
+  async initialize() {
+    try {
+      const initialized = await this.context.request(
+        acp.methods.agent.initialize,
+        {
+          protocolVersion: acp.PROTOCOL_VERSION,
+          clientCapabilities: {
+            session: { configOptions: { boolean: {} } },
+          },
+        },
+      );
+      this.capabilities = initialized.agentCapabilities ?? {};
+      return initialized;
+    } catch (error) {
+      throw this.failure("could not initialize", error);
+    }
+  }
+
+  async prompt({
+    sessionKey,
+    prompt,
+    previousSessionId,
+    sandbox = "read-only",
+    profile = {},
+    callbacks,
+  }) {
+    this.clearIdleTimer();
+    const initialized = await this.ready;
+    let session = this.sessions.get(sessionKey);
+    if (!session) {
+      session = await this.openSession(
+        sessionKey,
+        previousSessionId,
+        sandbox,
+        profile,
+      );
       callbacks.onEvent?.({
         type: "agent.connected",
-        message: `ACP agent connected with protocol ${initialized.protocolVersion}`,
+        message: `Agent connected with protocol ${initialized.protocolVersion}`,
       });
-      return ctx.buildSession(workspace).withSession(async (session) => {
-        child.engineerOsCancel = () =>
-          ctx.notify(acp.methods.agent.session.cancel, {
-            sessionId: session.sessionId,
-          });
-        void session.prompt(prompt);
-        for (;;) {
-          const message = await session.nextUpdate();
-          if (message.kind === "stop") {
-            if (message.stopReason === "error") {
-              throw new Error("The ACP agent ended the task with an error.");
-            }
-            return {
-              finalMessage,
-              model: "acp-agent",
-              sessionId: session.sessionId,
-            };
-          }
-          const update = message.update;
-          if (
-            update.sessionUpdate === "agent_message_chunk" &&
-            update.content?.type === "text"
-          ) {
-            finalMessage += update.content.text;
-          }
-          callbacks.onEvent?.({
-            type: `acp.${update.sessionUpdate}`,
-            message:
-              update.title ??
-              update.content?.text ??
-              update.status ??
-              update.sessionUpdate,
-          });
-        }
+    }
+    if (this.turns.has(session.sessionId)) {
+      throw new Error(
+        "The agent is already answering another prompt in this session.",
+      );
+    }
+    const turn = { callbacks, finalMessage: "", sandbox };
+    this.turns.set(session.sessionId, turn);
+    try {
+      const response = await this.context.request(
+        acp.methods.agent.session.prompt,
+        {
+          sessionId: session.sessionId,
+          prompt: [{ type: "text", text: prompt }],
+        },
+      );
+      if (response.stopReason === "error") {
+        throw new Error("The ACP agent ended the task with an error.");
+      }
+      return {
+        finalMessage: turn.finalMessage,
+        model: profile.model || this.config.agent_name || "acp-agent",
+        sessionId: session.sessionId,
+      };
+    } catch (error) {
+      throw this.failure("failed", error);
+    } finally {
+      this.turns.delete(session.sessionId);
+      this.scheduleIdleDisposal();
+    }
+  }
+
+  async openSession(sessionKey, previousSessionId, sandbox, profile) {
+    let response;
+    let sessionId;
+    if (previousSessionId && this.capabilities?.loadSession === true) {
+      response = await this.context.request(acp.methods.agent.session.load, {
+        sessionId: previousSessionId,
+        cwd: this.workspace,
+        mcpServers: [],
       });
-    })
-    .catch((error) => {
-      const detail = stderr.trim().slice(-1_000);
+      sessionId = previousSessionId;
+    } else {
+      response = await this.context.request(acp.methods.agent.session.new, {
+        cwd: this.workspace,
+        mcpServers: [],
+      });
+      sessionId = response.sessionId;
+    }
+    await this.applyMode(sessionId, response.modes, sandbox);
+    await this.applyProfile(sessionId, response.configOptions, profile);
+    const session = { sessionId };
+    this.sessions.set(sessionKey, session);
+    return session;
+  }
+
+  async applyMode(sessionId, modes, sandbox) {
+    const modeId = this.config.agent_modes?.[sandbox];
+    if (!modeId) return;
+    if (!modes?.availableModes?.some((mode) => mode.id === modeId)) {
       throw new Error(
-        `ACP agent failed: ${error instanceof Error ? error.message : String(error)}${detail ? ` ${detail}` : ""}`,
+        `${this.config.agent_name || "This ACP agent"} does not advertise the required '${modeId}' mode for ${sandbox} prompts.`,
       );
-    })
-    .finally(() => {
-      child.kill("SIGKILL");
-      child.stdin.destroy();
-      child.stdout.destroy();
-      child.stderr.destroy();
-      child.unref();
+    }
+    await this.context.request(acp.methods.agent.session.setMode, {
+      sessionId,
+      modeId,
     });
-  return { child, completed };
+  }
+
+  async applyProfile(sessionId, configOptions = [], profile = {}) {
+    const requested = [
+      ["model", profile.model],
+      ["thought_level", profile.reasoning_effort],
+    ];
+    for (const [category, value] of requested) {
+      if (!value) continue;
+      const option = configOptions?.find(
+        (candidate) => candidate.category === category,
+      );
+      if (!option || option.type !== "select") {
+        throw new Error(
+          `This ACP agent does not advertise ${category.replace("_", " ")} selection.`,
+        );
+      }
+      const available = option.options.flatMap((candidate) =>
+        Array.isArray(candidate.options) ? candidate.options : [candidate],
+      );
+      const selected = available.find(
+        (candidate) =>
+          candidate.value === value ||
+          candidate.name?.toLowerCase() === String(value).toLowerCase(),
+      );
+      if (!selected) {
+        throw new Error(
+          `${option.name} does not offer '${value}'. Available values: ${available
+            .map((candidate) => candidate.value)
+            .join(", ")}.`,
+        );
+      }
+      await this.context.request(acp.methods.agent.session.setConfigOption, {
+        sessionId,
+        configId: option.id,
+        value: selected.value,
+      });
+    }
+  }
+
+  async handleUpdate(notification) {
+    const turn = this.turns.get(notification.sessionId);
+    if (!turn) return;
+    const update = notification.update;
+    if (
+      update.sessionUpdate === "agent_message_chunk" &&
+      update.content?.type === "text"
+    ) {
+      turn.finalMessage += update.content.text;
+    }
+    turn.callbacks.onEvent?.({
+      type: `acp.${update.sessionUpdate}`,
+      update,
+    });
+  }
+
+  permissionOutcome(request) {
+    const turn = this.turns.get(request.sessionId);
+    return permissionOutcome(
+      request.options,
+      turn?.sandbox === "workspace-write",
+    );
+  }
+
+  async cancel(sessionKey) {
+    const session = this.sessions.get(sessionKey);
+    if (!session || !this.isRunning()) return;
+    await this.context.notify(acp.methods.agent.session.cancel, {
+      sessionId: session.sessionId,
+    });
+  }
+
+  isRunning() {
+    return (
+      !this.disposed &&
+      this.child.exitCode === null &&
+      !this.connection.signal.aborted
+    );
+  }
+
+  scheduleIdleDisposal() {
+    if (this.turns.size || this.disposed) return;
+    this.clearIdleTimer();
+    this.idleTimer = setTimeout(() => void this.dispose(), RUNTIME_IDLE_MS);
+    this.idleTimer.unref?.();
+  }
+
+  clearIdleTimer() {
+    clearTimeout(this.idleTimer);
+    this.idleTimer = null;
+  }
+
+  failure(action, error) {
+    const detail = this.stderr.trim().slice(-1_000);
+    const cause = this.spawnError || error;
+    return new Error(
+      `ACP agent ${action}: ${cause instanceof Error ? cause.message : String(cause)}${detail ? ` ${detail}` : ""}`,
+    );
+  }
+
+  closed() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.clearIdleTimer();
+    this.onClose?.();
+  }
+
+  async dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.clearIdleTimer();
+    this.onClose?.();
+    this.connection.close();
+    if (this.child.exitCode === null) {
+      this.child.kill("SIGTERM");
+      await Promise.race([
+        new Promise((resolve) => this.child.once("exit", resolve)),
+        new Promise((resolve) => setTimeout(resolve, 500)),
+      ]);
+    }
+    if (this.child.exitCode === null) this.child.kill("SIGKILL");
+    this.child.stdin.destroy();
+    this.child.stdout.destroy();
+    this.child.stderr.destroy();
+  }
+}
+
+function acpRuntimeKey(workspace, config) {
+  return JSON.stringify([
+    workspace,
+    config.agent_command,
+    config.agent_args || [],
+    config.agent_env || {},
+  ]);
 }

package/src/agent-harness.mjs

@@ -0,0 +1,108 @@
+import { readFileSync } from "node:fs";
+
+const ROLE_DEFINITIONS = Object.freeze({
+  research: Object.freeze({
+    title: "Repository Research",
+    sandboxMode: "read-only",
+    skill: "codebase-research",
+    instruction:
+      "Investigate the connected workspace deeply enough to answer from observed evidence. Trace relevant relationships, distinguish facts from inference, and do not change the workspace.",
+  }),
+  planning: Object.freeze({
+    title: "Change Planning",
+    sandboxMode: "read-only",
+    skill: "change-planning",
+    instruction:
+      "Turn the request and current workspace evidence into a decision-complete change plan. Resolve discoverable questions through inspection, state consequential assumptions, and do not implement the plan.",
+  }),
+  implementation: Object.freeze({
+    title: "Goal Implementation",
+    sandboxMode: "workspace-write",
+    skill: "goal-execution",
+    instruction:
+      "Execute the bounded Goal autonomously, keep changes inside its boundary, and verify the result. EngineerOS owns the final commit and acceptance workflow.",
+  }),
+  verification: Object.freeze({
+    title: "Independent Verification",
+    sandboxMode: "read-only",
+    skill: "change-verification",
+    instruction:
+      "Independently inspect and test the supplied revision. Report only directly observed evidence and do not repair or otherwise modify the workspace.",
+  }),
+});
+
+const skillCache = new Map();
+
+export const AGENT_ROLE_IDS = Object.freeze(Object.keys(ROLE_DEFINITIONS));
+export const AGENT_SKILL_IDS = Object.freeze(
+  AGENT_ROLE_IDS.map((roleId) => ROLE_DEFINITIONS[roleId].skill),
+);
+
+export function agentHarnessCapabilities() {
+  return {
+    agent_roles: [...AGENT_ROLE_IDS],
+    agent_skills: [...AGENT_SKILL_IDS],
+  };
+}
+
+export function buildAgentHarnessPrompt({ agentRole, prompt, sandboxMode }) {
+  const role = ROLE_DEFINITIONS[agentRole];
+  if (!role) {
+    throw new Error(
+      `EngineerOS assignment has an unsupported agent_role. Expected one of: ${AGENT_ROLE_IDS.join(", ")}.`,
+    );
+  }
+  if (role.sandboxMode !== sandboxMode) {
+    throw new Error(
+      `EngineerOS ${agentRole} role requires ${role.sandboxMode} access, but the assignment requested ${sandboxMode}.`,
+    );
+  }
+  const assignment = String(prompt || "").trim();
+  if (!assignment) {
+    throw new Error("EngineerOS assignment is missing prompt_markdown.");
+  }
+
+  return [
+    "# EngineerOS Agent Assignment",
+    "",
+    "## Active Role",
+    "",
+    `- Role: ${role.title}`,
+    `- Access: ${role.sandboxMode}`,
+    `- Responsibility: ${role.instruction}`,
+    "- User-facing language: refer to yourself neutrally as the Agent. Do not expose internal role, harness, provider, or coding-agent terminology unless the user asks.",
+    "",
+    "## Interaction Contract",
+    "",
+    "- Infer the current project situation from the assignment and workspace evidence before responding.",
+    "- Lead with the useful answer or outcome. Do not narrate routine searches, tool calls, or internal work.",
+    "- When one next activity clearly follows and would help, offer exactly one short, concrete suggestion. Do not force a next step when none is useful.",
+    "- Ask a question only when a consequential choice cannot be resolved from available evidence.",
+    "",
+    "## Active Skill",
+    "",
+    bundledSkill(role.skill),
+    "",
+    "## Assignment",
+    "",
+    assignment,
+  ].join("\n");
+}
+
+function bundledSkill(skillName) {
+  const cached = skillCache.get(skillName);
+  if (cached) return cached;
+  try {
+    const content = readFileSync(
+      new URL(`./skills/${skillName}/SKILL.md`, import.meta.url),
+      "utf8",
+    ).trim();
+    skillCache.set(skillName, content);
+    return content;
+  } catch (error) {
+    throw new Error(
+      `EngineerOS bundled skill '${skillName}' is unavailable. Reinstall @engineeros/connector.`,
+      { cause: error },
+    );
+  }
+}