@vellumai/assistant 0.4.55 → 0.4.57

package/src/acp/session-manager.ts

@@ -0,0 +1,348 @@
+/**
+ * ACP session manager — orchestrates ACP agent process lifecycles with
+ * concurrency control, permission resolution, and session state tracking.
+ */
+
+import { randomUUID } from "node:crypto";
+
+import type { ServerMessage } from "../daemon/message-protocol.js";
+import { getLogger } from "../util/logger.js";
+import { AcpAgentProcess } from "./agent-process.js";
+import { resolvePermission, VellumAcpClientHandler } from "./client-handler.js";
+import type { AcpAgentConfig, AcpSessionState } from "./types.js";
+
+const log = getLogger("acp:session-manager");
+
+interface SessionEntry {
+  process: AcpAgentProcess;
+  state: AcpSessionState;
+  clientHandler: VellumAcpClientHandler;
+  pendingPermissions: Map<string, { resolve: (optionId: string) => void }>;
+  sendToVellum: (msg: ServerMessage) => void;
+  currentPrompt: Promise<unknown> | null;
+  parentConversationId: string;
+  cwd: string;
+}
+
+export class AcpSessionManager {
+  private sessions = new Map<string, SessionEntry>();
+
+  /**
+   * Optional callback to inject a completion/failure message into the parent
+   * conversation so the LLM sees the agent's output.
+   * Wired by DaemonServer at startup.
+   */
+  onAcpSessionFinished:
+    | ((
+        parentConversationId: string,
+        message: string,
+        sendToClient: (msg: ServerMessage) => void,
+      ) => Promise<void>)
+    | null = null;
+
+  constructor(private readonly maxConcurrent: number) {}
+
+  /**
+   * Spawns a new ACP agent session. Returns the generated acpSessionId.
+   *
+   * The prompt is fired in the background — results stream via sessionUpdate
+   * callbacks and completion/error messages are sent when the prompt finishes.
+   */
+  async spawn(
+    agentId: string,
+    agentConfig: AcpAgentConfig,
+    task: string,
+    cwd: string,
+    parentConversationId: string,
+    sendToVellum: (msg: ServerMessage) => void,
+  ): Promise<{ acpSessionId: string; protocolSessionId: string }> {
+    if (this.sessions.size >= this.maxConcurrent) {
+      throw new Error(
+        `ACP concurrency limit reached (max ${this.maxConcurrent}). ` +
+          `Close an existing session before spawning a new one.`,
+      );
+    }
+
+    const acpSessionId = randomUUID();
+    log.info(
+      {
+        acpSessionId,
+        agentId,
+        task: task.slice(0, 200),
+        cwd,
+        parentConversationId,
+      },
+      "ACP spawn requested",
+    );
+
+    const pendingPermissions = new Map<
+      string,
+      { resolve: (optionId: string) => void }
+    >();
+
+    const clientHandler = new VellumAcpClientHandler(
+      acpSessionId,
+      sendToVellum,
+      pendingPermissions,
+    );
+
+    const agentProcess = new AcpAgentProcess(
+      agentId,
+      agentConfig,
+      (_agent) => clientHandler,
+    );
+
+    // Reserve a slot in the map before any async work to enforce the
+    // concurrency limit even when multiple spawn() calls race.
+    const state: AcpSessionState = {
+      id: acpSessionId,
+      agentId,
+      acpSessionId: "", // placeholder until createSession resolves
+      status: "initializing",
+      startedAt: Date.now(),
+    };
+
+    const entry: SessionEntry = {
+      process: agentProcess,
+      state,
+      clientHandler,
+      pendingPermissions,
+      sendToVellum,
+      currentPrompt: null,
+      parentConversationId,
+      cwd,
+    };
+
+    this.sessions.set(acpSessionId, entry);
+
+    try {
+      log.info({ acpSessionId, agentId }, "ACP spawning child process");
+      agentProcess.spawn(cwd);
+      log.info(
+        { acpSessionId, agentId },
+        "ACP initializing protocol connection",
+      );
+      await agentProcess.initialize();
+      log.info({ acpSessionId, agentId }, "ACP creating session");
+      const acpProtocolSessionId = await agentProcess.createSession(cwd);
+      state.acpSessionId = acpProtocolSessionId;
+      state.status = "running";
+      log.info(
+        { acpSessionId, agentId, acpProtocolSessionId },
+        "ACP session running",
+      );
+    } catch (err) {
+      log.error({ acpSessionId, agentId, err }, "ACP spawn failed");
+      // Kill the orphaned child process and remove the reserved slot.
+      agentProcess.kill();
+      this.sessions.delete(acpSessionId);
+      throw err;
+    }
+
+    sendToVellum({
+      type: "acp_session_spawned",
+      acpSessionId,
+      agent: agentId,
+      parentConversationId,
+    });
+
+    // Fire prompt in the background — don't await
+    entry.currentPrompt = this.firePromptInBackground(
+      acpSessionId,
+      entry,
+      state.acpSessionId,
+      task,
+    );
+
+    return { acpSessionId, protocolSessionId: state.acpSessionId };
+  }
+
+  /**
+   * Sends a follow-up instruction to an existing session.
+   *
+   * Cancels any in-flight prompt first, then fires the new prompt in the
+   * background with completion/error event handlers (matching spawn's pattern).
+   */
+  async steer(acpSessionId: string, instruction: string): Promise<void> {
+    const entry = this.sessions.get(acpSessionId);
+    if (!entry) {
+      throw new Error(`ACP session "${acpSessionId}" not found`);
+    }
+
+    if (entry.state.status !== "running") {
+      throw new Error(
+        `ACP session "${acpSessionId}" is not running (status: ${entry.state.status})`,
+      );
+    }
+
+    // Cancel any in-flight prompt before starting a new one
+    if (entry.currentPrompt) {
+      try {
+        await entry.process.cancel(entry.state.acpSessionId);
+      } catch (err) {
+        log.warn(
+          { acpSessionId, err },
+          "Failed to cancel in-flight prompt before steer",
+        );
+      }
+      entry.currentPrompt = null;
+    }
+
+    // Fire new prompt in the background with event handlers
+    entry.currentPrompt = this.firePromptInBackground(
+      acpSessionId,
+      entry,
+      entry.state.acpSessionId,
+      instruction,
+    );
+  }
+
+  /**
+   * Cancels an ongoing prompt in the specified session.
+   */
+  async cancel(acpSessionId: string): Promise<void> {
+    const entry = this.sessions.get(acpSessionId);
+    if (!entry) {
+      throw new Error(`ACP session "${acpSessionId}" not found`);
+    }
+    await entry.process.cancel(entry.state.acpSessionId);
+    entry.state.status = "cancelled";
+    entry.state.completedAt = Date.now();
+  }
+
+  /**
+   * Kills the agent process and removes the session from tracking.
+   */
+  close(acpSessionId: string): void {
+    const entry = this.sessions.get(acpSessionId);
+    if (!entry) {
+      throw new Error(`ACP session "${acpSessionId}" not found`);
+    }
+    entry.process.kill();
+    this.sessions.delete(acpSessionId);
+  }
+
+  /**
+   * Kills all agent processes and clears the session map.
+   */
+  closeAll(): void {
+    for (const entry of this.sessions.values()) {
+      entry.process.kill();
+    }
+    this.sessions.clear();
+  }
+
+  /**
+   * Returns session state(s). If acpSessionId is provided, returns that
+   * session's state; otherwise returns all session states.
+   */
+  getStatus(acpSessionId?: string): AcpSessionState | AcpSessionState[] {
+    if (acpSessionId) {
+      const entry = this.sessions.get(acpSessionId);
+      if (!entry) {
+        throw new Error(`ACP session "${acpSessionId}" not found`);
+      }
+      return entry.state;
+    }
+    return Array.from(this.sessions.values()).map((e) => e.state);
+  }
+
+  /**
+   * Resolves a pending permission request in any session that holds it.
+   */
+  resolvePermission(requestId: string, optionId: string): void {
+    for (const entry of this.sessions.values()) {
+      if (entry.pendingPermissions.has(requestId)) {
+        resolvePermission(entry.pendingPermissions, requestId, optionId);
+        return;
+      }
+    }
+    log.warn({ requestId }, "No pending permission found for request ID");
+  }
+
+  /**
+   * Fires a prompt in the background and wires up completion/error event
+   * handlers. Returns the promise so callers can track in-flight state.
+   */
+  private firePromptInBackground(
+    acpSessionId: string,
+    entry: SessionEntry,
+    acpProtocolSessionId: string,
+    message: string,
+  ): Promise<unknown> {
+    log.info({ acpSessionId, messageLen: message.length }, "ACP firing prompt");
+    const promptPromise = entry.process
+      .prompt(acpProtocolSessionId, message)
+      .then((response) => {
+        const current = this.sessions.get(acpSessionId);
+        // Only mutate state if the session still exists, this is still the
+        // current prompt (not stale from a previous steer), and the status
+        // hasn't been set to "cancelled" already.
+        if (current && current.currentPrompt === promptPromise) {
+          if (current.state.status !== "cancelled") {
+            current.state.status = "completed";
+            current.state.completedAt = Date.now();
+            current.state.stopReason = response.stopReason;
+          }
+          current.currentPrompt = null;
+          log.info(
+            { acpSessionId, stopReason: response.stopReason },
+            "ACP prompt completed",
+          );
+          current.sendToVellum({
+            type: "acp_session_completed",
+            acpSessionId,
+            stopReason: response.stopReason,
+          });
+
+          // Notify parent session so the LLM sees the agent's output
+          if (this.onAcpSessionFinished) {
+            const agentLabel = current.state.agentId;
+            const responseText = current.clientHandler.responseText;
+            const sessionId = current.state.acpSessionId;
+            const notifyMessage =
+              `[ACP agent "${agentLabel}" completed]\n\n${responseText}\n\n` +
+              `To resume: cd ${current.cwd} && claude --resume ${sessionId}`;
+            this.onAcpSessionFinished(
+              current.parentConversationId,
+              notifyMessage,
+              current.sendToVellum,
+            ).catch((notifyErr) => {
+              log.error(
+                { acpSessionId, notifyErr },
+                "Failed to notify parent of ACP completion",
+              );
+            });
+          }
+        }
+      })
+      .catch((err: Error) => {
+        const current = this.sessions.get(acpSessionId);
+        // Same guards: entry must exist, prompt must be current, and status
+        // must not have been set to "cancelled".
+        if (current && current.currentPrompt === promptPromise) {
+          if (current.state.status !== "cancelled") {
+            current.state.status = "failed";
+            current.state.completedAt = Date.now();
+            current.state.error = err.message;
+          }
+          current.currentPrompt = null;
+          log.error({ acpSessionId, error: err.message }, "ACP prompt failed");
+          current.sendToVellum({
+            type: "acp_session_error",
+            acpSessionId,
+            error: err.message,
+          });
+        }
+      });
+
+    return promptPromise;
+  }
+
+  /**
+   * Kills all processes on shutdown.
+   */
+  dispose(): void {
+    this.closeAll();
+  }
+}

package/src/acp/types.ts

@@ -0,0 +1,79 @@
+/**
+ * ACP (Agent Client Protocol) types for agent session management and configuration.
+ */
+
+// Import StopReason for use in AcpSessionState
+import type { StopReason } from "@agentclientprotocol/sdk";
+
+// Re-export relevant types from the ACP SDK for convenience
+export type {
+  AgentCapabilities,
+  ClientCapabilities,
+  InitializeRequest,
+  InitializeResponse,
+  NewSessionRequest,
+  NewSessionResponse,
+  PromptRequest,
+  PromptResponse,
+  SessionId,
+  SessionInfo,
+  SessionNotification,
+  SessionUpdate,
+  StopReason,
+  ToolCall,
+  ToolCallContent,
+  ToolCallId,
+  ToolCallStatus,
+} from "@agentclientprotocol/sdk";
+export {
+  AgentSideConnection,
+  ClientSideConnection,
+} from "@agentclientprotocol/sdk";
+
+/**
+ * Configuration for a single ACP agent process.
+ */
+export interface AcpAgentConfig {
+  command: string;
+  args: string[];
+  description?: string;
+  env?: Record<string, string>;
+}
+
+/**
+ * Top-level ACP configuration.
+ */
+export interface AcpConfig {
+  enabled: boolean;
+  maxConcurrentSessions: number;
+  agents: Record<string, AcpAgentConfig>;
+}
+
+/**
+ * Runtime state of an ACP session.
+ */
+export interface AcpSessionState {
+  id: string;
+  agentId: string;
+  acpSessionId: string;
+  status: "initializing" | "running" | "completed" | "failed" | "cancelled";
+  startedAt: number;
+  completedAt?: number;
+  error?: string;
+  stopReason?: StopReason;
+}
+
+/**
+ * Classification of a tool call's operation kind.
+ */
+export type ToolCallKind =
+  | "read"
+  | "edit"
+  | "delete"
+  | "move"
+  | "search"
+  | "execute"
+  | "think"
+  | "fetch"
+  | "switch_mode"
+  | "other";

package/src/approvals/AGENTS.md

@@ -16,11 +16,11 @@ Conversational guardian verification control-plane invocation is guardian-only.
 
 ## Memory Provenance Invariant
 
-All memory retrieval decisions must consider actor-role provenance. Untrusted actors (non-guardian, unverified_channel) must not receive memory recall results. This invariant is enforced in `indexer.ts` (write gate) and `session-memory.ts` (read gate).
+All memory retrieval decisions must consider actor-role provenance. Untrusted actors (non-guardian, unverified_channel) must not receive memory recall results. This invariant is enforced in `indexer.ts` (write gate) and `conversation-memory.ts` (read gate).
 
 ## Guardian Privilege Isolation Invariant
 
 Untrusted actors (`non-guardian`, `unverified_channel`) must never receive privileged host/tool capabilities or privileged conversation context directly.
 
 - Tool execution gate: untrusted actors cannot execute host-target tools or side-effect tools in-band. These actions require guardian-mediated approval flow. Enforcement lives in `assistant/src/tools/tool-approval-handler.ts`.
-- History view gate: when loading session history for untrusted actors, only untrusted-provenance messages are included and compacted summaries are suppressed. This prevents replay of guardian-era context after trust downgrades. Enforcement lives in `assistant/src/daemon/session-lifecycle.ts` and actor-scoped reload wiring in `assistant/src/daemon/session.ts`.
+- History view gate: when loading conversation history for untrusted actors, only untrusted-provenance messages are included and compacted summaries are suppressed. This prevents replay of guardian-era context after trust downgrades. Enforcement lives in `assistant/src/daemon/conversation-lifecycle.ts` and actor-scoped reload wiring in `assistant/src/daemon/conversation.ts`.

package/src/approvals/approval-primitive.ts

@@ -43,7 +43,7 @@ export interface MintGrantParams {
   callSessionId?: string | null;
   requesterExternalUserId?: string | null;
   guardianExternalUserId?: string | null;
-  expiresAt: string;
+  expiresAt: number;
 }
 
 export type MintGrantResult =
@@ -156,7 +156,7 @@ export function mintGrantFromDecision(
 export interface ConsumeByRequestIdParams {
   requestId: string;
   consumingRequestId: string;
-  now?: string;
+  now?: number;
 }
 
 export interface ConsumeByToolSignatureParams {
@@ -167,7 +167,7 @@ export interface ConsumeByToolSignatureParams {
   conversationId?: string;
   callSessionId?: string;
   requesterExternalUserId?: string;
-  now?: string;
+  now?: number;
 }
 
 export type ConsumeGrantResult =
@@ -191,7 +191,7 @@ export interface ConsumeGrantParams {
   conversationId?: string;
   callSessionId?: string;
   requesterExternalUserId?: string;
-  now?: string;
+  now?: number;
 }
 
 /**

package/src/approvals/guardian-decision-primitive.ts

@@ -116,7 +116,7 @@ export function tryMintToolApprovalGrant(params: {
     callSessionId: null,
     guardianExternalUserId,
     requesterExternalUserId: approval.requesterExternalUserId,
-    expiresAt: new Date(Date.now() + GRANT_TTL_MS).toISOString(),
+    expiresAt: Date.now() + GRANT_TTL_MS,
   });
 
   if (result.ok) {
@@ -190,7 +190,7 @@ export function applyGuardianDecision(
   const effectiveDecision: ApprovalDecisionResult =
     decision.action === "approve_always" ||
     decision.action === "approve_10m" ||
-    decision.action === "approve_thread"
+    decision.action === "approve_conversation"
       ? { ...decision, action: "approve_once" }
       : decision;
 
@@ -285,7 +285,7 @@ export function mintCanonicalRequestGrant(params: {
     callSessionId: request.callSessionId ?? null,
     guardianExternalUserId: guardianExternalUserId ?? null,
     requesterExternalUserId: request.requesterExternalUserId ?? null,
-    expiresAt: new Date(Date.now() + GRANT_TTL_MS).toISOString(),
+    expiresAt: Date.now() + GRANT_TTL_MS,
   });
 
   if (result.ok) {
@@ -321,7 +321,7 @@ export function mintCanonicalRequestGrant(params: {
 const VALID_CANONICAL_ACTIONS: ReadonlySet<ApprovalAction> = new Set([
   "approve_once",
   "approve_10m",
-  "approve_thread",
+  "approve_conversation",
   "approve_always",
   "reject",
 ]);
@@ -479,7 +479,7 @@ export async function applyCanonicalGuardianDecision(
   }
 
   // 2d. Check expiry
-  if (request.expiresAt && new Date(request.expiresAt).getTime() < Date.now()) {
+  if (request.expiresAt && request.expiresAt < Date.now()) {
     log.info(
       {
         event: "canonical_decision_expired",
@@ -493,11 +493,11 @@ export async function applyCanonicalGuardianDecision(
 
   // 3. Downgrade approve_always and temporary modes to approve_once for
   // guardian-on-behalf requests. Guardians cannot grant broad allow modes
-  // (permanent, timed, or thread-scoped) on behalf of requesters.
+  // (permanent, timed, or conversation-scoped) on behalf of requesters.
   const effectiveAction: ApprovalAction =
     action === "approve_always" ||
     action === "approve_10m" ||
-    action === "approve_thread"
+    action === "approve_conversation"
       ? "approve_once"
       : action;
 

package/src/approvals/guardian-request-resolvers.ts

@@ -217,7 +217,7 @@ const pendingInteractionResolver: GuardianRequestResolver = {
     // Map action to the permission system's UserDecision type and notify session.
     const userDecision =
       decision.action === "reject" ? ("deny" as const) : ("allow" as const);
-    resolved.session.handleConfirmationResponse(
+    resolved.conversation.handleConfirmationResponse(
       request.id,
       userDecision,
       undefined,
@@ -399,7 +399,7 @@ const accessRequestResolver: GuardianRequestResolver = {
         void emitNotificationSignal({
           sourceEventName: "ingress.trusted_contact.guardian_decision",
           sourceChannel: channel,
-          sourceSessionId: request.conversationId ?? "",
+          sourceContextId: request.conversationId ?? "",
           attentionHints: {
             requiresAction: false,
             urgency: "medium",
@@ -413,7 +413,7 @@ const accessRequestResolver: GuardianRequestResolver = {
         void emitNotificationSignal({
           sourceEventName: "ingress.trusted_contact.denied",
           sourceChannel: channel,
-          sourceSessionId: request.conversationId ?? "",
+          sourceContextId: request.conversationId ?? "",
           attentionHints: {
             requiresAction: false,
             urgency: "low",
@@ -590,7 +590,7 @@ const accessRequestResolver: GuardianRequestResolver = {
         void emitNotificationSignal({
           sourceEventName: "ingress.trusted_contact.verification_sent",
           sourceChannel: channel,
-          sourceSessionId: request.conversationId ?? "",
+          sourceContextId: request.conversationId ?? "",
           attentionHints: {
             requiresAction: false,
             urgency: "low",

package/src/avatar/ascii-renderer.ts

@@ -0,0 +1,63 @@
+import { getResvg } from "./resvg-lazy.js";
+import { composeSvg } from "./svg-compositor.js";
+
+const RAMP = " .·:;+=xX$&@";
+
+/**
+ * Render a character avatar as ASCII art suitable for terminal display.
+ *
+ * Composes the SVG, rasterizes it via Resvg, then maps each pixel cell to a
+ * brightness character. The ramp is dark-background-friendly: spaces for
+ * transparent/dark areas, dense characters for bright areas.
+ *
+ * @param bodyShapeId - ID of the body shape (e.g. "blob")
+ * @param eyeStyleId - ID of the eye style (e.g. "curious")
+ * @param colorId - ID of the body color (e.g. "green")
+ * @param width - Output width in characters (default 60)
+ * @returns A multi-line ASCII art string
+ */
+export function renderCharacterAscii(
+  bodyShapeId: string,
+  eyeStyleId: string,
+  colorId: string,
+  width: number = 60,
+): string {
+  const renderSize = width * 2;
+  const svg = composeSvg(bodyShapeId, eyeStyleId, colorId, renderSize);
+  const Resvg = getResvg();
+  const resvg = new Resvg(svg, {
+    fitTo: { mode: "width", value: renderSize },
+  });
+  const renderedImage = resvg.render();
+  const pixels = renderedImage.pixels;
+  const imgWidth = renderedImage.width;
+  const imgHeight = renderedImage.height;
+
+  // Each terminal cell is roughly 2x taller than wide, so we sample a
+  // rectangular region per cell: cellW pixels wide, cellH = cellW * 2 tall.
+  const cellW = imgWidth / width;
+  const cellH = cellW * 2;
+  const outHeight = Math.floor(imgHeight / cellH);
+
+  const rows: string[] = [];
+  for (let r = 0; r < outHeight; r++) {
+    let row = "";
+    for (let c = 0; c < width; c++) {
+      const px = (Math.floor(r * cellH) * imgWidth + Math.floor(c * cellW)) * 4;
+      const R = pixels[px];
+      const G = pixels[px + 1];
+      const B = pixels[px + 2];
+      const A = pixels[px + 3];
+
+      const brightness = (0.299 * R + 0.587 * G + 0.114 * B) * (A / 255);
+      const idx = Math.min(
+        Math.floor((brightness / 256) * RAMP.length),
+        RAMP.length - 1,
+      );
+      row += RAMP[idx];
+    }
+    rows.push(row);
+  }
+
+  return rows.join("\n");
+}