@acprotocol/server 0.1.0

package/dist/chunk-DB5IW3GZ.js

@@ -0,0 +1,713 @@
+// @acprotocol/server — Apache 2.0
+
+// src/prompt.ts
+function buildSystemPrompt(manifest) {
+  const parts = [];
+  if (manifest.persona?.name) {
+    let identity = `You are ${manifest.persona.name}`;
+    if (manifest.persona.role) identity += `, ${manifest.persona.role}`;
+    identity += ".";
+    parts.push(identity);
+  } else {
+    parts.push(
+      "You are an AI assistant embedded in a software application."
+    );
+  }
+  if (manifest.persona?.instructions) {
+    parts.push(manifest.persona.instructions);
+  }
+  if (manifest.user) {
+    const lines = ["## User"];
+    if (manifest.user.name) lines.push(`- Name: ${manifest.user.name}`);
+    if (manifest.user.org) lines.push(`- Organization: ${manifest.user.org}`);
+    if (manifest.user.role) lines.push(`- Role: ${manifest.user.role}`);
+    if (lines.length > 1) parts.push(lines.join("\n"));
+  }
+  if (manifest.context && Object.keys(manifest.context).length > 0) {
+    parts.push(
+      "## Application Context\n" + JSON.stringify(manifest.context, null, 2)
+    );
+  }
+  const screenLines = [
+    "## Application Screens",
+    "You can control the application UI using the available tools. Here are the screens and their fields:",
+    ""
+  ];
+  for (const [id, screen] of Object.entries(manifest.screens)) {
+    screenLines.push(`### Screen: ${id} (${screen.label})`);
+    if (screen.route) screenLines.push(`Route: ${screen.route}`);
+    if (screen.fields?.length) {
+      screenLines.push("Fields:");
+      for (const f of screen.fields) {
+        const req = f.required ? " [REQUIRED]" : "";
+        screenLines.push(`  - \`${f.id}\` (${f.type}): ${f.label}${req}`);
+        if (f.options?.length) {
+          const opts = f.options.map((o) => `${o.value}=${o.label}`).join(", ");
+          screenLines.push(`    Options: ${opts}`);
+        }
+      }
+    }
+    if (screen.actions?.length) {
+      screenLines.push("Actions:");
+      for (const act of screen.actions) {
+        let flags = "";
+        if (act.requiresConfirmation) flags += " [REQUIRES_CONFIRMATION]";
+        if (act.destructive) flags += " [DESTRUCTIVE]";
+        screenLines.push(`  - \`${act.id}\`: ${act.label}${flags}`);
+      }
+    }
+    if (screen.modals?.length) {
+      screenLines.push("Modals:");
+      for (const md of screen.modals) {
+        screenLines.push(`  - \`${md.id}\`: ${md.label}`);
+      }
+    }
+    screenLines.push("");
+  }
+  parts.push(screenLines.join("\n"));
+  parts.push(
+    [
+      "## Rules",
+      '- Use `fill_field` with animate="typewriter" so the user can see values being entered.',
+      "- ALWAYS call `ask_confirm` before clicking any action marked [REQUIRES_CONFIRMATION].",
+      "- If the user's request is missing essential information, ask briefly and generically \u2014 do NOT list specific field names.",
+      "- Do NOT narrate individual fields being filled. Just confirm the action briefly when done.",
+      "- If a command fails (you'll see the error in the next message), explain and try to fix it.",
+      "- Respond in the same language the user speaks.",
+      "- Be concise. Keep responses short \u2014 prefer brief confirmations.",
+      "- Navigate to the correct screen before filling fields.",
+      "- When filling multiple fields on the same screen, combine ALL fill_field calls in a single response.",
+      "- Do NOT fill one field at a time \u2014 batch them together."
+    ].join("\n")
+  );
+  return parts.join("\n\n");
+}
+
+// src/session.ts
+var MAX_HISTORY = 40;
+var Session = class {
+  /** Unique session identifier. */
+  id;
+  /** The current ACP manifest, or `null` if not yet received. */
+  manifest = null;
+  /** The current screen ID. */
+  currentScreen = "";
+  history = [];
+  _seq = 0;
+  constructor(id) {
+    this.id = id;
+  }
+  /**
+   * Sets the manifest and rebuilds the system prompt.
+   *
+   * If the manifest includes a `currentScreen`, it is applied.
+   * The system prompt is built from the manifest and added or replaced
+   * in the message history.
+   *
+   * @param manifest - The ACP manifest message describing the application UI.
+   */
+  setManifest(manifest) {
+    this.manifest = manifest;
+    if (manifest.currentScreen) {
+      this.currentScreen = manifest.currentScreen;
+    }
+    this.updateSystemPrompt(buildSystemPrompt(manifest));
+  }
+  /**
+   * Updates the current screen ID.
+   * @param screen - The screen ID to switch to.
+   */
+  setScreen(screen) {
+    this.currentScreen = screen;
+  }
+  /**
+   * Adds a message to the conversation history.
+   *
+   * If the history exceeds {@link MAX_HISTORY} (40), the oldest messages
+   * after the system prompt are trimmed to maintain a sliding window.
+   *
+   * @param msg - An OpenAI-compatible chat message.
+   */
+  addMessage(msg) {
+    this.history.push(msg);
+    if (this.history.length > MAX_HISTORY) {
+      const system = this.history[0];
+      const start = this.history.length - MAX_HISTORY + 1;
+      this.history = [system, ...this.history.slice(start)];
+    }
+  }
+  /**
+   * Returns a shallow copy of the message history.
+   * Safe to iterate without affecting the session's internal state.
+   */
+  getHistory() {
+    return [...this.history];
+  }
+  /**
+   * Replaces the first system message in history, or prepends one.
+   * @param prompt - The new system prompt content.
+   */
+  updateSystemPrompt(prompt) {
+    const idx = this.history.findIndex((m) => m.role === "system");
+    if (idx >= 0) {
+      this.history[idx] = { role: "system", content: prompt };
+    } else {
+      this.history.unshift({ role: "system", content: prompt });
+    }
+  }
+  /**
+   * Returns and increments the sequence counter.
+   *
+   * Each command sent to the client carries a `seq` number which the client
+   * echoes back in the `result` or `confirm` message. This counter is
+   * monotonically increasing per session.
+   */
+  nextSeq() {
+    return this._seq++;
+  }
+};
+
+// src/tools.ts
+function manifestToTools(manifest) {
+  const screenIDs = [];
+  const screenLabels = [];
+  for (const [id, s] of Object.entries(manifest.screens)) {
+    screenIDs.push(id);
+    screenLabels.push(`${id} (${s.label})`);
+  }
+  const allFieldIDs = collectFieldIDs(manifest);
+  const allActionIDs = collectActionIDs(manifest);
+  const allModalIDs = collectModalIDs(manifest);
+  const tools = [
+    navigateTool(screenIDs, screenLabels),
+    fillFieldTool(allFieldIDs),
+    clearFieldTool(allFieldIDs),
+    clickActionTool(allActionIDs),
+    highlightTool(allFieldIDs),
+    focusTool(allFieldIDs),
+    askConfirmTool(),
+    showToastTool()
+  ];
+  if (allModalIDs.length > 0) {
+    tools.push(openModalTool(allModalIDs), closeModalTool());
+  }
+  return tools;
+}
+function toolCallToUIAction(name, argsJSON) {
+  let args;
+  try {
+    args = JSON.parse(argsJSON);
+  } catch {
+    args = {};
+  }
+  switch (name) {
+    case "navigate":
+      return { do: "navigate", screen: str(args.screen) };
+    case "fill_field":
+      return {
+        do: "fill",
+        field: str(args.field),
+        value: args.value,
+        animate: str(args.animate) || "typewriter",
+        speed: num(args.speed) || void 0
+      };
+    case "clear_field":
+      return { do: "clear", field: str(args.field) };
+    case "click_action":
+      return { do: "click", action: str(args.action) };
+    case "highlight":
+      return {
+        do: "highlight",
+        field: str(args.field),
+        duration: num(args.duration) || void 0
+      };
+    case "focus":
+      return { do: "focus", field: str(args.field) };
+    case "open_modal":
+      return {
+        do: "open_modal",
+        modal: str(args.modal),
+        query: str(args.query) || void 0
+      };
+    case "close_modal":
+      return { do: "close_modal" };
+    case "ask_confirm":
+      return { do: "ask_confirm", message: str(args.message) };
+    case "show_toast":
+      return {
+        do: "show_toast",
+        message: str(args.message),
+        level: str(args.level) || void 0,
+        duration: num(args.duration) || void 0
+      };
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+function makeTool(name, description, parameters) {
+  return {
+    type: "function",
+    function: { name, description, parameters }
+  };
+}
+function navigateTool(screenIDs, screenLabels) {
+  return makeTool(
+    "navigate",
+    `Navigate to a screen. Available: ${screenLabels.join(", ")}`,
+    {
+      type: "object",
+      properties: {
+        screen: { type: "string", enum: screenIDs, description: "Screen ID to navigate to" }
+      },
+      required: ["screen"]
+    }
+  );
+}
+function fillFieldTool(fieldIDs) {
+  return makeTool(
+    "fill_field",
+    `Fill a form field with a value. The field animates as the value is typed. Available fields: ${fieldIDs.join(", ")}`,
+    {
+      type: "object",
+      properties: {
+        field: { type: "string", description: "Field ID to fill" },
+        value: { description: "Value to set (string, number, or boolean depending on field type)" },
+        animate: {
+          type: "string",
+          enum: ["typewriter", "count_up", "fade_in", "none"],
+          default: "typewriter",
+          description: "Animation style for filling"
+        }
+      },
+      required: ["field", "value"]
+    }
+  );
+}
+function clearFieldTool(fieldIDs) {
+  return makeTool("clear_field", "Clear a form field value", {
+    type: "object",
+    properties: {
+      field: { type: "string", description: "Field ID to clear" }
+    },
+    required: ["field"]
+  });
+}
+function clickActionTool(actionIDs) {
+  return makeTool(
+    "click_action",
+    `Click a button or trigger an action. Available: ${actionIDs.join(", ")}. IMPORTANT: if the action has requiresConfirmation=true, you MUST call ask_confirm first and wait for the user's response before clicking.`,
+    {
+      type: "object",
+      properties: {
+        action: { type: "string", description: "Action ID to click" }
+      },
+      required: ["action"]
+    }
+  );
+}
+function highlightTool(fieldIDs) {
+  return makeTool("highlight", "Temporarily highlight a field to draw the user's attention", {
+    type: "object",
+    properties: {
+      field: { type: "string", description: "Field ID to highlight" },
+      duration: { type: "integer", default: 2e3, description: "Highlight duration in milliseconds" }
+    },
+    required: ["field"]
+  });
+}
+function focusTool(fieldIDs) {
+  return makeTool("focus", "Set keyboard focus on a field", {
+    type: "object",
+    properties: {
+      field: { type: "string", description: "Field ID to focus" }
+    },
+    required: ["field"]
+  });
+}
+function openModalTool(modalIDs) {
+  return makeTool(
+    "open_modal",
+    `Open a modal/dialog. Available: ${modalIDs.join(", ")}`,
+    {
+      type: "object",
+      properties: {
+        modal: { type: "string", description: "Modal ID to open" },
+        query: { type: "string", description: "Optional search query to pre-fill in the modal" }
+      },
+      required: ["modal"]
+    }
+  );
+}
+function closeModalTool() {
+  return makeTool("close_modal", "Close the currently open modal", {
+    type: "object",
+    properties: {}
+  });
+}
+function askConfirmTool() {
+  return makeTool(
+    "ask_confirm",
+    "Ask the user for confirmation before proceeding with a destructive or important action.",
+    {
+      type: "object",
+      properties: {
+        message: { type: "string", description: "Confirmation question to ask the user" }
+      },
+      required: ["message"]
+    }
+  );
+}
+function showToastTool() {
+  return makeTool("show_toast", "Show a temporary notification/toast message in the app", {
+    type: "object",
+    properties: {
+      message: { type: "string", description: "Toast message text" },
+      level: { type: "string", enum: ["info", "success", "warning", "error"], default: "info" },
+      duration: { type: "integer", default: 3e3 }
+    },
+    required: ["message"]
+  });
+}
+function collectFieldIDs(m) {
+  const seen = /* @__PURE__ */ new Set();
+  const ids = [];
+  for (const s of Object.values(m.screens)) {
+    for (const f of s.fields ?? []) {
+      if (!seen.has(f.id)) {
+        ids.push(f.id);
+        seen.add(f.id);
+      }
+    }
+  }
+  return ids;
+}
+function collectActionIDs(m) {
+  const seen = /* @__PURE__ */ new Set();
+  const ids = [];
+  for (const s of Object.values(m.screens)) {
+    for (const a of s.actions ?? []) {
+      if (!seen.has(a.id)) {
+        ids.push(a.id);
+        seen.add(a.id);
+      }
+    }
+  }
+  return ids;
+}
+function collectModalIDs(m) {
+  const seen = /* @__PURE__ */ new Set();
+  const ids = [];
+  for (const s of Object.values(m.screens)) {
+    for (const md of s.modals ?? []) {
+      if (!seen.has(md.id)) {
+        ids.push(md.id);
+        seen.add(md.id);
+      }
+    }
+  }
+  return ids;
+}
+function str(v) {
+  return typeof v === "string" ? v : "";
+}
+function num(v) {
+  return typeof v === "number" ? v : 0;
+}
+
+// src/agent.ts
+var MAX_ROUNDS = 5;
+async function runAgentLoop(openai, model, session, text, execute, send) {
+  session.addMessage({ role: "user", content: text });
+  const tools = session.manifest ? manifestToTools(session.manifest) : void 0;
+  let lastResponseText = "";
+  for (let round = 0; round < MAX_ROUNDS; round++) {
+    const history = session.getHistory();
+    const stream = await openai.chat.completions.create({
+      model,
+      messages: history,
+      tools: tools?.length ? tools : void 0,
+      stream: true
+    });
+    let contentBuf = "";
+    const accToolCalls = [];
+    for await (const chunk of stream) {
+      if (!chunk.choices?.length) continue;
+      const delta = chunk.choices[0].delta;
+      if (delta.content) {
+        contentBuf += delta.content;
+        send({ type: "chat_token", token: delta.content });
+      }
+      if (delta.tool_calls) {
+        for (const tc of delta.tool_calls) {
+          const idx = tc.index ?? 0;
+          while (accToolCalls.length <= idx) {
+            accToolCalls.push({ id: "", type: "", function: { name: "", arguments: "" } });
+          }
+          if (tc.id) accToolCalls[idx].id = tc.id;
+          if (tc.type) accToolCalls[idx].type = tc.type;
+          if (tc.function?.name) accToolCalls[idx].function.name = tc.function.name;
+          if (tc.function?.arguments) accToolCalls[idx].function.arguments += tc.function.arguments;
+        }
+      }
+    }
+    const assistantMsg = {
+      role: "assistant",
+      content: contentBuf || null
+    };
+    if (accToolCalls.length > 0) {
+      assistantMsg.tool_calls = accToolCalls.map((tc) => ({
+        id: tc.id,
+        type: "function",
+        function: { name: tc.function.name, arguments: tc.function.arguments }
+      }));
+    }
+    session.addMessage(assistantMsg);
+    if (accToolCalls.length === 0) {
+      if (contentBuf) {
+        send({ type: "chat", from: "agent", message: contentBuf, final: true });
+      }
+      return;
+    }
+    if (contentBuf) {
+      lastResponseText = contentBuf;
+    }
+    const roundActions = [];
+    const mappings = [];
+    for (const tc of accToolCalls) {
+      try {
+        const action = toolCallToUIAction(tc.function.name, tc.function.arguments);
+        roundActions.push(action);
+        mappings.push({ action, callId: tc.id });
+      } catch (err) {
+        session.addMessage({
+          role: "tool",
+          content: JSON.stringify({ error: String(err) }),
+          tool_call_id: tc.id
+        });
+      }
+    }
+    if (roundActions.length === 0) continue;
+    const isConfirmOnly = roundActions.length === 1 && roundActions[0].do === "ask_confirm";
+    const seq = session.nextSeq();
+    send({ type: "status", status: "executing" });
+    let resultMsg;
+    try {
+      resultMsg = await execute(seq, roundActions);
+    } catch (err) {
+      for (const m of mappings) {
+        session.addMessage({
+          role: "tool",
+          content: JSON.stringify({ success: false, error: String(err) }),
+          tool_call_id: m.callId
+        });
+      }
+      send({ type: "status", status: "thinking" });
+      continue;
+    }
+    send({ type: "status", status: "thinking" });
+    const resultsByIndex = /* @__PURE__ */ new Map();
+    for (const r of resultMsg.results) {
+      resultsByIndex.set(r.index, r);
+    }
+    for (let i = 0; i < mappings.length; i++) {
+      const m = mappings[i];
+      const result = { success: true, action: m.action.do };
+      const r = resultsByIndex.get(i);
+      if (r) {
+        result.success = r.success;
+        if (!r.success && r.error) result.error = r.error;
+      }
+      if (m.action.do === "navigate") {
+        session.setScreen(m.action.screen);
+        result.screen = m.action.screen;
+      }
+      if (m.action.do === "fill") {
+        result.field = m.action.field;
+        result.value = m.action.value;
+      }
+      if (isConfirmOnly && m.action.do === "ask_confirm") {
+        const confirmed = resultMsg.results[0]?.success ?? false;
+        result.user_response = confirmed ? "Yes" : "No";
+      }
+      session.addMessage({
+        role: "tool",
+        content: JSON.stringify(result),
+        tool_call_id: m.callId
+      });
+    }
+  }
+  if (lastResponseText) {
+    send({ type: "chat", from: "agent", message: lastResponseText, final: true });
+  } else {
+    send({ type: "chat", from: "agent", message: "Done.", final: true });
+  }
+}
+
+// src/server.ts
+import { randomUUID } from "crypto";
+import { WebSocketServer, WebSocket } from "ws";
+var EXECUTE_TIMEOUT_MS = 3e4;
+function createServer(options) {
+  const { openai, model, port } = options;
+  let wss = null;
+  return {
+    async start() {
+      wss = new WebSocketServer({ port, path: "/connect" });
+      wss.on("connection", (ws, req) => {
+        handleConnection(ws, openai, model);
+      });
+    },
+    async stop() {
+      if (!wss) return;
+      for (const ws of wss.clients) {
+        ws.close(1001, "Server shutting down");
+      }
+      await new Promise((resolve) => wss.close(() => resolve()));
+      wss = null;
+    }
+  };
+}
+function handleConnection(ws, openai, model) {
+  const sessionId = randomUUID();
+  const session = new Session(sessionId);
+  const pendingResults = /* @__PURE__ */ new Map();
+  const pendingConfirms = /* @__PURE__ */ new Map();
+  let processing = false;
+  const send = (msg) => {
+    if (ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify(msg));
+    }
+  };
+  send({
+    type: "config",
+    sessionId,
+    features: { chat: true },
+    providers: [{ id: "default", name: "Default", model }],
+    current_provider: "default"
+  });
+  const pingInterval = setInterval(() => {
+    if (ws.readyState === WebSocket.OPEN) ws.ping();
+  }, 3e4);
+  ws.on("close", () => {
+    clearInterval(pingInterval);
+    for (const [, reject] of pendingResults) {
+    }
+    pendingResults.clear();
+    pendingConfirms.clear();
+  });
+  ws.on("message", (data) => {
+    let msg;
+    try {
+      msg = JSON.parse(data.toString());
+    } catch {
+      send({ type: "error", code: "parse_error", message: "Invalid JSON" });
+      return;
+    }
+    switch (msg.type) {
+      case "manifest":
+        handleManifest(msg, session, send, openai, model);
+        break;
+      case "text":
+        if (!msg.message) return;
+        if (processing) {
+          send({ type: "error", code: "busy", message: "Already processing a request" });
+          return;
+        }
+        processing = true;
+        handleText(msg.message, session, openai, model, send, makeExecuteFn(send, session, pendingResults, pendingConfirms)).finally(() => {
+          processing = false;
+        });
+        break;
+      case "state":
+        session.setScreen(msg.screen);
+        break;
+      case "result":
+        deliverResult(msg, pendingResults);
+        break;
+      case "confirm":
+        deliverConfirm(msg, pendingConfirms, session, openai, model, send, makeExecuteFn(send, session, pendingResults, pendingConfirms));
+        break;
+      case "llm_config":
+        break;
+      case "response_lang_config":
+        break;
+    }
+  });
+}
+function handleManifest(msg, session, send, openai, model) {
+  session.setManifest(msg);
+  send({ type: "status", status: "idle" });
+  const name = msg.persona?.name ?? "assistant";
+  send({
+    type: "chat",
+    from: "agent",
+    message: `Connected. How can I help?`,
+    final: true
+  });
+}
+async function handleText(text, session, openai, model, send, execute) {
+  send({ type: "status", status: "thinking" });
+  try {
+    await runAgentLoop(openai, model, session, text, execute, send);
+  } catch (err) {
+    console.error("[acp-server] Agent error:", err);
+    send({ type: "error", code: "agent_error", message: String(err) });
+  }
+  send({ type: "status", status: "idle" });
+}
+function deliverResult(msg, pendingResults) {
+  const resolver = pendingResults.get(msg.seq);
+  if (resolver) {
+    pendingResults.delete(msg.seq);
+    resolver(msg);
+  }
+}
+function deliverConfirm(msg, pendingConfirms, session, openai, model, send, execute) {
+  const resolver = pendingConfirms.get(msg.seq);
+  if (resolver) {
+    pendingConfirms.delete(msg.seq);
+    resolver(msg.confirmed);
+  }
+}
+function makeExecuteFn(send, session, pendingResults, pendingConfirms) {
+  return (seq, actions) => {
+    const isConfirmOnly = actions.length === 1 && actions[0].do === "ask_confirm";
+    send({ type: "command", seq, actions });
+    if (isConfirmOnly) {
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          pendingConfirms.delete(seq);
+          reject(new Error(`Timeout waiting for confirm seq=${seq}`));
+        }, EXECUTE_TIMEOUT_MS);
+        pendingConfirms.set(seq, (confirmed) => {
+          clearTimeout(timer);
+          resolve({
+            type: "result",
+            seq,
+            results: [{ index: 0, success: confirmed }]
+          });
+        });
+      });
+    }
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        pendingResults.delete(seq);
+        reject(new Error(`Timeout waiting for result seq=${seq}`));
+      }, EXECUTE_TIMEOUT_MS);
+      pendingResults.set(seq, (result) => {
+        clearTimeout(timer);
+        resolve(result);
+      });
+    });
+  };
+}
+
+export {
+  buildSystemPrompt,
+  Session,
+  manifestToTools,
+  toolCallToUIAction,
+  runAgentLoop,
+  createServer
+};
+//# sourceMappingURL=chunk-DB5IW3GZ.js.map