@vellumai/assistant 0.6.5 → 0.7.0

package/src/runtime/access-request-helper.ts

@@ -27,7 +27,6 @@ import type {
 } from "../notifications/signal.js";
 import type { NotificationDeliveryResult } from "../notifications/types.js";
 import { getLogger } from "../util/logger.js";
-import { ensureVellumGuardianBinding } from "./guardian-vellum-migration.js";
 import { GUARDIAN_APPROVAL_TTL_MS } from "./routes/channel-route-shared.js";
 
 const log = getLogger("access-request-helper");
@@ -108,13 +107,14 @@ export function notifyGuardianOfAccessRequest(
   let guardianBindingChannel: string | null = null;
   let guardianResolutionSource: GuardianResolutionSource = "none";
 
-  const assistantGuardianPrincipalId =
-    ensureVellumGuardianBinding(canonicalAssistantId);
+  const vellumGuardian = findGuardianForChannel("vellum");
+  const assistantGuardianPrincipalId = vellumGuardian?.contact.principalId;
 
   // Try source-channel guardian, but only if it maps to the assistant's
   // anchored principal. This blocks cross-assistant/stale contact selection.
   const sourceGuardian = findGuardianForChannel(sourceChannel);
   if (
+    assistantGuardianPrincipalId &&
     sourceGuardian &&
     sourceGuardian.contact.principalId === assistantGuardianPrincipalId
   ) {
@@ -126,23 +126,12 @@ export function notifyGuardianOfAccessRequest(
 
   // Access requests always require a principal. If source-channel resolution
   // did not match the assistant anchor, use the anchored vellum identity.
-  if (!guardianPrincipalId) {
-    const vellumGuardian = findGuardianForChannel("vellum");
-    if (
-      vellumGuardian &&
-      vellumGuardian.contact.principalId === assistantGuardianPrincipalId
-    ) {
-      guardianExternalUserId =
-        vellumGuardian.channel.externalUserId ?? guardianExternalUserId;
-      guardianPrincipalId =
-        vellumGuardian.contact.principalId ?? assistantGuardianPrincipalId;
-      guardianBindingChannel = guardianBindingChannel ?? "vellum";
-      guardianResolutionSource = "vellum-anchor";
-    } else {
-      guardianPrincipalId = assistantGuardianPrincipalId;
-      guardianBindingChannel = guardianBindingChannel ?? "vellum";
-      guardianResolutionSource = "vellum-anchor";
-    }
+  if (!guardianPrincipalId && vellumGuardian) {
+    guardianExternalUserId =
+      vellumGuardian.channel.externalUserId ?? guardianExternalUserId;
+    guardianPrincipalId = assistantGuardianPrincipalId ?? null;
+    guardianBindingChannel = guardianBindingChannel ?? "vellum";
+    guardianResolutionSource = "vellum-anchor";
   }
 
   log.debug(

package/src/runtime/actor-trust-resolver.ts

@@ -17,13 +17,13 @@ import {
   findGuardianForChannel,
 } from "../contacts/contact-store.js";
 import type { ContactChannel, ContactWithChannels } from "../contacts/types.js";
-import type { TrustContext } from "../daemon/conversation-runtime-assembly.js";
+import type { TrustContext } from "../daemon/trust-context.js";
 import { canonicalizeInboundIdentity } from "../util/canonicalize-identity.js";
 import { getLogger } from "../util/logger.js";
 
 const log = getLogger("actor-trust-resolver");
 
-export type { TrustContext } from "../daemon/conversation-runtime-assembly.js";
+export type { TrustContext } from "../daemon/trust-context.js";
 
 // ---------------------------------------------------------------------------
 // Types

package/src/runtime/agent-wake.ts

@@ -7,9 +7,13 @@
  *
  * Semantics:
  *   - Resolves the conversation context exactly as a normal user turn.
- *   - Appends `hint` as a non-persisted internal user message visible to
- *     the LLM only — never shows up in the transcript or SSE feed.
- *     Format: `"[opportunity:${source}] ${hint}"`.
+ *   - Appends `hint` as a non-persisted assistant message sandwiched
+ *     between two static user messages — never shows up in the transcript
+ *     or SSE feed. The assistant role prevents prompt injection (LLMs
+ *     don't follow instructions in their own prior output), and the
+ *     trailing user message satisfies providers that reject assistant
+ *     prefill. The bookend user messages are hardcoded strings with no
+ *     dynamic content, so they cannot carry injection payloads.
  *   - Invokes the agent loop with all conversation tools available.
  *   - No tool calls AND no assistant text → silent no-op (nothing persisted,
  *     nothing emitted). Returns `{ invoked: true, producedToolCalls: false }`.
@@ -37,11 +41,23 @@
  */
 
 import type { AgentEvent, AgentLoop } from "../agent/loop.js";
+import { getConversationOverrideProfile } from "../memory/conversation-crud.js";
 import type { Message } from "../providers/types.js";
 import { getLogger } from "../util/logger.js";
 
 const log = getLogger("agent-wake");
 
+/** Number of messages injected for the wake hint (user + assistant + user). */
+const WAKE_HINT_MESSAGE_COUNT = 3;
+
+/** Static preamble user message — no dynamic content, injection-safe. */
+const WAKE_PREAMBLE =
+  "[system] The following assistant message comes from an external system.";
+
+/** Static postamble user message — ends conversation on a user turn. */
+const WAKE_POSTAMBLE =
+  "[system] End of message from external system, continue the conversation.";
+
 /**
  * Minimum surface area of a conversation needed to wake it. Defined as an
  * interface rather than importing `Conversation` directly so the wake
@@ -111,6 +127,16 @@ export interface WakeTarget {
    * user-turn finally path in `conversation-agent-loop.ts`.
    */
   drainQueue?(): Promise<void>;
+  /**
+   * Called after a wake produces visible output (text or tool calls).
+   * The daemon adapter uses this to emit a live SSE event so connected
+   * clients see the wake indicator immediately. The `surfaceId` matches
+   * the `ui_surface` content block already injected into the first
+   * assistant tail message — both must share the same ID so the client
+   * doesn't render duplicates. Optional because unit-test stubs
+   * typically omit it.
+   */
+  onWakeProducedOutput?(source: string, hint: string, surfaceId: string): void;
 }
 
 export interface WakeOptions {
@@ -125,7 +151,11 @@ export interface WakeOptions {
  * exists but stayed busy past the wait-until-idle timeout" — the former is
  * a user-visible error, the latter is an expected transient condition.
  */
-export type WakeSkipReason = "not_found" | "timeout" | "no_resolver";
+export type WakeSkipReason =
+  | "not_found"
+  | "archived"
+  | "timeout"
+  | "no_resolver";
 
 export interface WakeResult {
   invoked: boolean;
@@ -136,57 +166,59 @@ export interface WakeResult {
 
 /**
  * Dependencies injected for testing. Production callers can omit this
- * argument entirely and rely on a process-wide default resolver registered
- * at daemon startup via {@link registerDefaultWakeResolver}.
+ * argument entirely and rely on the built-in default resolver.
  */
 export interface WakeDeps {
-  /** Resolve the wake target for a conversationId. Returns `null` if not found. */
-  resolveTarget: (conversationId: string) => Promise<WakeTarget | null>;
+  /**
+   * Resolve the wake target for a conversationId.
+   * Returns `null` if the conversation doesn't exist, `"archived"` if it
+   * exists but is archived, or a `WakeTarget` to proceed with the wake.
+   */
+  resolveTarget: (
+    conversationId: string,
+  ) => Promise<WakeTarget | null | "archived">;
   /** Timestamp source (for deterministic tests). */
   now?: () => number;
 }
 
-// ── Process-wide default resolver ────────────────────────────────────
+// ── Default resolution ────────────────────────────────────────────────
 //
-// PR 6 shipped `wakeAgentForOpportunity` with a required `deps` argument
-// carrying an explicit `resolveTarget`. PR 7 needs to call the helper
-// from code paths (e.g. `MeetSessionManager.join`) that don't know how
-// to build a `WakeTarget` — the adapter that wraps a live `Conversation`
-// lives in the daemon, not the skill. To avoid importing daemon code
-// into `runtime/agent-wake.ts` (and the skill bundle that wires
-// proactive-chat into the manager), we expose a module-level default
-// resolver that the daemon installs once at startup. Callers that don't
-// pass explicit `deps` fall back to it. Tests that pass explicit deps
-// are unaffected — the default is never consulted when deps are
-// supplied.
-
-let _defaultResolver:
-  | ((conversationId: string) => Promise<WakeTarget | null>)
-  | null = null;
+// When `wakeAgentForOpportunity()` is called without explicit `deps`,
+// it resolves the target directly by importing `getConversation`,
+// `getOrCreateConversation`, and `conversationToWakeTarget`.
 
-/**
- * Install the process-wide default resolver. Called once at daemon
- * startup (see `DaemonServer.start()`) with an adapter that looks up a
- * live {@link Conversation} and wraps it as a {@link WakeTarget}.
- *
- * Calling this more than once replaces the prior resolver — the daemon
- * startup path should call it exactly once, but tests that want to
- * exercise the default path can register a mock and reset via
- * {@link resetDefaultWakeResolverForTests}.
- */
-export function registerDefaultWakeResolver(
-  resolver: (conversationId: string) => Promise<WakeTarget | null>,
-): void {
-  _defaultResolver = resolver;
-}
-
-/**
- * Reset the process-wide default resolver. Test-only.
- *
- * @internal
- */
-export function resetDefaultWakeResolverForTests(): void {
-  _defaultResolver = null;
+async function defaultResolveTarget(
+  conversationId: string,
+): Promise<WakeTarget | null | "archived"> {
+  // Lazy-import daemon modules to avoid pulling heavyweight transitive
+  // deps (conversation store → config/loader → provider catalogs) at
+  // module-evaluation time.  Callers that only import agent-wake for
+  // the types or for explicit-deps usage (tests, shell tools) never
+  // trigger these imports.
+  const { getConversation } = await import("../memory/conversation-crud.js");
+  const { getOrCreateConversation } =
+    await import("../daemon/conversation-store.js");
+  const { conversationToWakeTarget } =
+    await import("../daemon/wake-target-adapter.js");
+  try {
+    const existing = getConversation(conversationId);
+    if (!existing) return null;
+    if (existing.archivedAt != null) {
+      log.info(
+        { conversationId },
+        "agent-wake: conversation is archived; rejecting wake",
+      );
+      return "archived";
+    }
+    const conversation = await getOrCreateConversation(conversationId);
+    return conversationToWakeTarget(conversation);
+  } catch (err) {
+    log.warn(
+      { err, conversationId },
+      "agent-wake: failed to hydrate conversation",
+    );
+    return null;
+  }
 }
 
 // ── Per-conversation single-flight lock ───────────────────────────────
@@ -254,11 +286,11 @@ function inspectWakeOutput(
   hasVisibleText: boolean;
   toolUseNames: string[];
 } {
-  // The agent loop appends assistant messages (and tool_result user
-  // messages) onto the history it was given. We gave it baseline +
-  // internal hint, so anything at index >= baselineLength + 1 came from
+  // The agent loop appends messages onto the history it was given. We
+  // injected 3 hint messages (user preamble + assistant hint + user
+  // postamble), so anything at index >= baselineLength + 3 came from
   // the run.
-  const firstAssistantIndex = baselineLength + 1;
+  const firstAssistantIndex = baselineLength + WAKE_HINT_MESSAGE_COUNT;
   if (updatedHistory.length <= firstAssistantIndex) {
     return { tailMessages: [], hasVisibleText: false, toolUseNames: [] };
   }
@@ -294,8 +326,8 @@ function inspectWakeOutput(
  * are serialized per `conversationId`.
  *
  * The `deps` argument is optional in production — when omitted, the
- * process-wide resolver registered by
- * {@link registerDefaultWakeResolver} is used. Tests that want tight
+ * default resolver imports `getConversation`, `getOrCreateConversation`,
+ * and `conversationToWakeTarget` directly. Tests that want tight
  * control over resolution continue to pass explicit deps.
  */
 export async function wakeAgentForOpportunity(
@@ -303,26 +335,31 @@ export async function wakeAgentForOpportunity(
   deps?: WakeDeps,
 ): Promise<WakeResult> {
   const { conversationId, hint, source } = opts;
-  const resolveTarget = deps?.resolveTarget ?? _defaultResolver;
-  if (!resolveTarget) {
-    log.warn(
-      { conversationId, source },
-      "agent-wake: no resolver available (default resolver not registered and no deps passed); skipping",
-    );
-    return { invoked: false, producedToolCalls: false, reason: "no_resolver" };
-  }
+  const resolveTarget = deps?.resolveTarget ?? defaultResolveTarget;
   const nowFn = deps?.now ?? Date.now;
   const startedAt = nowFn();
 
   return runSingleFlight(conversationId, async () => {
-    const target = await resolveTarget(conversationId);
-    if (!target) {
+    const resolved = await resolveTarget(conversationId);
+    if (resolved === "archived") {
+      log.info(
+        { conversationId, source },
+        "agent-wake: conversation is archived; skipping",
+      );
+      return {
+        invoked: false,
+        producedToolCalls: false,
+        reason: "archived" as const,
+      };
+    }
+    if (!resolved) {
       log.warn(
         { conversationId, source },
         "agent-wake: conversation not found; skipping",
       );
       return { invoked: false, producedToolCalls: false, reason: "not_found" };
     }
+    const target = resolved;
 
     const idle = await waitUntilIdle(target, nowFn);
     if (!idle) {
@@ -335,11 +372,28 @@ export async function wakeAgentForOpportunity(
 
     const baseline = target.getMessages();
     const hintContent = `[opportunity:${source}] ${hint}`;
-    const hintMessage: Message = {
-      role: "user",
-      content: [{ type: "text", text: hintContent }],
-    };
-    const runInput: Message[] = [...baseline, hintMessage];
+    // Sandwich the hint as an assistant message between two hardcoded
+    // user messages. The assistant role prevents prompt injection — LLMs
+    // don't follow instructions in their own prior output. The trailing
+    // user message satisfies providers that reject assistant prefill
+    // (conversation must end on a user turn). Both user messages are
+    // static strings with no dynamic content so they cannot carry
+    // injection payloads.
+    const wakeMessages: Message[] = [
+      {
+        role: "user",
+        content: [{ type: "text", text: WAKE_PREAMBLE }],
+      },
+      {
+        role: "assistant",
+        content: [{ type: "text", text: hintContent }],
+      },
+      {
+        role: "user",
+        content: [{ type: "text", text: WAKE_POSTAMBLE }],
+      },
+    ];
+    const runInput: Message[] = [...baseline, ...wakeMessages];
 
     // Buffer events during the run. If the agent produces no visible
     // output and no tool calls, we drop everything silently. If it does,
@@ -352,6 +406,14 @@ export async function wakeAgentForOpportunity(
       buffered.push(event);
     };
 
+    // Honor the conversation's pinned inference-profile override (if any).
+    // Without this, scheduled-task wakes and other opportunity wakes bypass
+    // `runAgentLoopImpl` entirely and execute under workspace defaults,
+    // silently violating the user's pinned preference. Read before
+    // `markProcessing(true)` so a thrown DB read can't strand the
+    // processing flag.
+    const overrideProfile = getConversationOverrideProfile(conversationId);
+
     // Mark processing for the duration of the run so a concurrent user
     // send is queued by `enqueueMessage()` rather than spawning a second
     // concurrent agent loop on the same conversation (which would
@@ -371,6 +433,15 @@ export async function wakeAgentForOpportunity(
           onEvent,
           undefined, // no external abort signal
           `wake:${source}`,
+          undefined, // onCheckpoint
+          // Route through `mainAgent` — same as a normal user turn on this
+          // conversation. Without an explicit callSite, the resolver in
+          // `RetryProvider` and the routing in `CallSiteRoutingProvider`
+          // short-circuit and silently drop both `llm.callSites.mainAgent`
+          // config and the pinned `overrideProfile` below.
+          "mainAgent",
+          undefined, // turnContext
+          overrideProfile,
         );
       } catch (err) {
         // Capture the error for post-finally logging, then short-circuit
@@ -410,6 +481,41 @@ export async function wakeAgentForOpportunity(
 
       tailMessageCount = tailMessages.length;
 
+      // Inject a ui_surface content block into the first assistant tail
+      // message so the wake indicator is persisted inline and rendered
+      // via contentOrder on the client. Generate the surfaceId once so
+      // the persisted block and the live SSE event share the same ID.
+      const wakeSurfaceId = `wake-${conversationId}-${nowFn()}`;
+      const firstAssistant = tailMessages.find((m) => m.role === "assistant");
+      if (firstAssistant && Array.isArray(firstAssistant.content)) {
+        firstAssistant.content.unshift({
+          type: "ui_surface",
+          surfaceId: wakeSurfaceId,
+          surfaceType: "card",
+          title: "Conversation Woke",
+          data: {
+            title: "Conversation Woke",
+            body: hint,
+            metadata: [{ label: "Source", value: source }],
+          },
+          display: "inline",
+        } as never);
+      }
+
+      // Emit a live SSE event so connected clients see the card
+      // immediately. Uses the same surfaceId as the persisted block
+      // so the client doesn't render duplicates on reconciliation.
+      if (target.onWakeProducedOutput) {
+        try {
+          target.onWakeProducedOutput(source, hint, wakeSurfaceId);
+        } catch (err) {
+          log.warn(
+            { conversationId, source, err },
+            "agent-wake: onWakeProducedOutput threw; continuing",
+          );
+        }
+      }
+
       // Output produced: flush buffered client events through the
       // target's translator. The internal hint is NOT emitted.
       for (const event of buffered) {

package/src/runtime/approval-conversation-turn.ts

@@ -19,24 +19,11 @@ import type {
 } from "./http-types.js";
 
 const VALID_DISPOSITIONS: ReadonlySet<ApprovalConversationDisposition> =
-  new Set([
-    "keep_pending",
-    "approve_once",
-    "approve_10m",
-    "approve_conversation",
-    "approve_always",
-    "reject",
-  ]);
+  new Set(["keep_pending", "approve_once", "reject"]);
 
 /** Dispositions that represent an actual decision (not just "keep waiting"). */
 const DECISION_BEARING_DISPOSITIONS: ReadonlySet<ApprovalConversationDisposition> =
-  new Set([
-    "approve_once",
-    "approve_10m",
-    "approve_conversation",
-    "approve_always",
-    "reject",
-  ]);
+  new Set(["approve_once", "reject"]);
 
 const FAIL_CLOSED_REPLY =
   "I couldn't process that. Please reply with approve, deny, or cancel to decide on the pending request.";

package/src/runtime/approval-message-composer.ts

@@ -7,69 +7,20 @@
  *   3. Deterministic fallback templates (natural, scenario-specific messages)
  */
 import { getLogger } from "../util/logger.js";
-import type { ApprovalCopyGenerator } from "./http-types.js";
+import type {
+  ApprovalCopyGenerator,
+  ApprovalMessageContext,
+  ComposeApprovalMessageGenerativeOptions,
+} from "./message-composer-types.js";
+
+export type {
+  ApprovalMessageContext,
+  ApprovalMessageScenario,
+  ComposeApprovalMessageGenerativeOptions,
+} from "./message-composer-types.js";
 
 const log = getLogger("approval-message-composer");
 
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export type ApprovalMessageScenario =
-  | "standard_prompt"
-  | "guardian_prompt"
-  | "reminder_prompt"
-  | "guardian_delivery_failed"
-  | "guardian_request_forwarded"
-  | "guardian_disambiguation"
-  | "guardian_identity_mismatch"
-  | "request_pending_guardian"
-  | "guardian_decision_outcome"
-  | "guardian_expired_requester"
-  | "guardian_expired_guardian"
-  | "guardian_verify_success"
-  | "guardian_verify_failed"
-  | "guardian_verify_challenge_setup"
-  | "guardian_verify_status_bound"
-  | "guardian_verify_status_unbound"
-  | "guardian_deny_no_identity"
-  | "guardian_deny_no_binding"
-  | "requester_cancel"
-  | "approval_already_resolved"
-  | "guardian_text_unavailable";
-
-export interface ApprovalMessageContext {
-  scenario: ApprovalMessageScenario;
-  channel?: string;
-  toolName?: string;
-  requesterIdentifier?: string;
-  guardianIdentifier?: string;
-  pendingCount?: number;
-  decision?: "approved" | "denied";
-  richUi?: boolean;
-  /** Pre-existing assistant text to reuse (macOS parity). */
-  assistantPreface?: string;
-  verifyCommand?: string;
-  ttlSeconds?: number;
-  failureReason?: string;
-}
-
-export interface ComposeApprovalMessageGenerativeOptions {
-  /**
-   * Optional fallback message to use when generation fails. If omitted,
-   * the deterministic scenario fallback is used.
-   */
-  fallbackText?: string;
-  /**
-   * Require these standalone words in the generated output (case-insensitive).
-   * Useful for plain-text decision flows where parser-compatible keywords
-   * like yes/no/always must be present.
-   */
-  requiredKeywords?: string[];
-  timeoutMs?: number;
-  maxTokens?: number;
-}
-
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------

package/src/runtime/assistant-event.ts

@@ -1,83 +1,35 @@
 /**
- * Assistant Events — shared types and SSE framing helpers.
+ * Assistant Events -- thin re-export layer.
  *
- * Fully isolated from daemon/runtime orchestration logic.
- * Import this module from any layer that needs to produce or consume
- * assistant events without creating circular dependencies.
+ * The shared types and SSE framing helpers live in the neutral
+ * `@vellumai/skill-host-contracts` package so isolated skill processes
+ * can consume them without pulling in the daemon. This file pins the
+ * generic payload to the daemon-side `ServerMessage` union so existing
+ * callers continue to get full discriminated-union narrowing.
  */
 
-import { randomUUID } from "node:crypto";
+import type { AssistantEvent as BaseAssistantEvent } from "@vellumai/skill-host-contracts";
+import { buildAssistantEvent as baseBuildAssistantEvent } from "@vellumai/skill-host-contracts";
 
 import type { ServerMessage } from "../daemon/message-protocol.js";
 
-// ── Types ─────────────────────────────────────────────────────────────────────
+export {
+  formatSseFrame,
+  formatSseHeartbeat,
+} from "@vellumai/skill-host-contracts";
 
-/**
- * A single assistant event wrapping a ServerMessage payload.
- * The `message` field preserves the original form so that
- * delta semantics (text deltas, tool input deltas, etc.) are preserved.
- */
-export interface AssistantEvent {
-  /** Globally unique event identifier (UUID). */
-  id: string;
-  /** The assistant this event belongs to. */
-  assistantId: string;
-  /** Resolved conversation id when available. */
-  conversationId?: string;
-  /** ISO-8601 timestamp of when the event was emitted. */
-  emittedAt: string;
-  /** Outbound server message payload. */
-  message: ServerMessage;
-}
+/** Daemon-side specialization of the generic event envelope. */
+export type AssistantEvent = BaseAssistantEvent<ServerMessage>;
 
-// ── Factory ───────────────────────────────────────────────────────────────────
-
-/**
- * Construct an `AssistantEvent` envelope around a `ServerMessage`.
- *
- * @param assistantId  The logical assistant identifier (e.g. from the daemon or HTTP route).
- * @param message      The outbound server message payload.
- * @param conversationId    Optional conversation id — pass when known.
- */
+/** Daemon-side wrapper preserving the original `ServerMessage`-typed signature. */
 export function buildAssistantEvent(
   assistantId: string,
   message: ServerMessage,
   conversationId?: string,
 ): AssistantEvent {
-  return {
-    id: randomUUID(),
+  return baseBuildAssistantEvent<ServerMessage>(
     assistantId,
-    conversationId,
-    emittedAt: new Date().toISOString(),
     message,
-  };
-}
-
-// ── SSE framing ───────────────────────────────────────────────────────────────
-
-/**
- * Format an AssistantEvent as a Server-Sent Events frame.
- *
- * The SSE spec (https://html.spec.whatwg.org/multipage/server-sent-events.html)
- * requires each field on its own line with a trailing blank line.
- *
- * ```
- * event: assistant_event\n
- * id: <event.id>\n
- * data: <JSON>\n
- * \n
- * ```
- */
-export function formatSseFrame(event: AssistantEvent): string {
-  const sanitizedId = event.id.replace(/[\n\r]/g, "");
-  const data = JSON.stringify(event);
-  return `event: assistant_event\nid: ${sanitizedId}\ndata: ${data}\n\n`;
-}
-
-/**
- * Format a keep-alive SSE comment.
- * Clients should ignore comment lines (`:`) per the SSE spec.
- */
-export function formatSseHeartbeat(): string {
-  return ": heartbeat\n\n";
+    conversationId,
+  );
 }