vellum 0.2.14 → 0.3.2

package/src/providers/stream-timeout.ts

@@ -1,38 +0,0 @@
-/**
- * Creates an AbortController that auto-aborts after `timeoutMs`, optionally
- * linked to an external AbortSignal so cancellation propagates both ways.
- *
- * Returns a `signal` to pass to the provider SDK and a `cleanup` function
- * that MUST be called in a finally block to clear the timer and detach
- * the external signal listener.
- */
-export function createStreamTimeout(
-  timeoutMs: number,
-  externalSignal?: AbortSignal,
-): { signal: AbortSignal; cleanup: () => void } {
-  const controller = new AbortController();
-
-  const handle = setTimeout(() => {
-    controller.abort(new Error(`Provider stream timed out after ${timeoutMs / 1000}s`));
-  }, timeoutMs);
-
-  const onExternalAbort = () => {
-    controller.abort(externalSignal!.reason);
-  };
-
-  if (externalSignal) {
-    if (externalSignal.aborted) {
-      clearTimeout(handle);
-      controller.abort(externalSignal.reason);
-    } else {
-      externalSignal.addEventListener('abort', onExternalAbort, { once: true });
-    }
-  }
-
-  const cleanup = () => {
-    clearTimeout(handle);
-    externalSignal?.removeEventListener('abort', onExternalAbort);
-  };
-
-  return { signal: controller.signal, cleanup };
-}

package/src/providers/types.ts

@@ -1,109 +0,0 @@
-export interface TextContent {
-  type: "text";
-  text: string;
-}
-
-export interface ImageContent {
-  type: "image";
-  source: {
-    type: "base64";
-    media_type: string;
-    data: string;
-  };
-}
-
-export interface FileContent {
-  type: "file";
-  source: {
-    type: "base64";
-    media_type: string;
-    data: string;
-    filename: string;
-  };
-  extracted_text?: string;
-}
-
-export interface ToolUseContent {
-  type: "tool_use";
-  id: string;
-  name: string;
-  input: Record<string, unknown>;
-}
-
-export interface ThinkingContent {
-  type: "thinking";
-  thinking: string;
-  signature: string;
-}
-
-export interface RedactedThinkingContent {
-  type: "redacted_thinking";
-  data: string;
-}
-
-export interface ToolResultContent {
-  type: "tool_result";
-  tool_use_id: string;
-  content: string;
-  is_error?: boolean;
-  /** Rich content blocks (e.g. images) to include alongside text in the tool result. */
-  contentBlocks?: ContentBlock[];
-}
-
-export type ContentBlock =
-  | TextContent
-  | ThinkingContent
-  | RedactedThinkingContent
-  | ImageContent
-  | FileContent
-  | ToolUseContent
-  | ToolResultContent;
-
-export interface Message {
-  role: "user" | "assistant";
-  content: ContentBlock[];
-}
-
-export interface ToolDefinition {
-  name: string;
-  description: string;
-  input_schema: object;
-}
-
-export interface ProviderResponse {
-  content: ContentBlock[];
-  model: string;
-  usage: {
-    /** Total input tokens (input_tokens + cache_creation + cache_read). */
-    inputTokens: number;
-    outputTokens: number;
-    cacheCreationInputTokens?: number;
-    cacheReadInputTokens?: number;
-  };
-  stopReason: string;
-  /** Raw JSON request body sent to the provider (for diagnostics logging). */
-  rawRequest?: unknown;
-  /** Raw JSON response body received from the provider (for diagnostics logging). */
-  rawResponse?: unknown;
-}
-
-export type ProviderEvent =
-  | { type: 'text_delta'; text: string }
-  | { type: 'thinking_delta'; thinking: string }
-  | { type: 'input_json_delta'; toolName: string; accumulatedJson: string };
-
-export interface SendMessageOptions {
-  config?: object;
-  onEvent?: (event: ProviderEvent) => void;
-  signal?: AbortSignal;
-}
-
-export interface Provider {
-  name: string;
-  sendMessage(
-    messages: Message[],
-    tools?: ToolDefinition[],
-    systemPrompt?: string,
-    options?: SendMessageOptions,
-  ): Promise<ProviderResponse>;
-}

package/src/runtime/assistant-event-hub.ts

@@ -1,157 +0,0 @@
-/**
- * In-process pub/sub hub for assistant events.
- *
- * Provides subscribe / publish primitives used by both the IPC daemon send
- * paths (PR 3) and the SSE route (PR 5). No runtime route or daemon
- * integration is wired here.
- */
-
-import type { AssistantEvent } from './assistant-event.js';
-
-// ── Types ─────────────────────────────────────────────────────────────────────
-
-/** Predicate that determines whether a subscriber wants a given event. */
-export type AssistantEventFilter = {
-  /** Only deliver events for this assistant. */
-  assistantId: string;
-  /** When set, further restrict to this session. */
-  sessionId?: string;
-};
-
-export type AssistantEventCallback = (event: AssistantEvent) => void | Promise<void>;
-
-/** Opaque handle returned by `subscribe`. Call `dispose()` to remove the subscription. */
-export interface AssistantEventSubscription {
-  dispose(): void;
-  /** True until `dispose()` has been called. */
-  readonly active: boolean;
-}
-
-// ── Hub ───────────────────────────────────────────────────────────────────────
-
-interface SubscriberEntry {
-  filter: AssistantEventFilter;
-  callback: AssistantEventCallback;
-  active: boolean;
-  /** Called by the hub when this entry is evicted to make room for a new subscriber. */
-  onEvict?: () => void;
-}
-
-/**
- * Lightweight pub/sub hub for `AssistantEvent` messages.
- *
- * Filtering is applied at subscription level — subscribers receive only
- * events that match their `assistantId` (and optionally `sessionId`).
- *
- * The hub is intentionally simple: synchronous fanout, no buffering, no
- * backpressure. Slow-consumer protection lives in the SSE route (PR 7).
- */
-export class AssistantEventHub {
-  private readonly subscribers = new Set<SubscriberEntry>();
-  private readonly maxSubscribers: number;
-
-  constructor(options?: { maxSubscribers?: number }) {
-    this.maxSubscribers = options?.maxSubscribers ?? Infinity;
-  }
-
-  /**
-   * Register a subscriber that will be called for each matching event.
-   *
-   * When the subscriber cap (`maxSubscribers`) has been reached, the **oldest**
-   * subscriber is evicted to make room: its `onEvict` callback is invoked (so
-   * it can close its SSE stream) and its entry is removed from the hub.
-   *
-   * The only case that throws is when `maxSubscribers` is 0 — there is nothing
-   * to evict and no room to add.
-   *
-   * @param options.onEvict  Called if this subscriber is later evicted by a newer one.
-   * @returns A subscription handle. Call `dispose()` to unsubscribe.
-   */
-  subscribe(
-    filter: AssistantEventFilter,
-    callback: AssistantEventCallback,
-    options?: { onEvict?: () => void },
-  ): AssistantEventSubscription {
-    if (this.subscribers.size >= this.maxSubscribers) {
-      // Evict the oldest subscriber (Sets maintain insertion order).
-      const [oldest] = this.subscribers;
-      if (!oldest) {
-        // maxSubscribers is 0 — nothing to evict, nothing to add.
-        throw new RangeError(
-          `AssistantEventHub: subscriber cap reached (${this.maxSubscribers})`,
-        );
-      }
-      oldest.active = false;
-      this.subscribers.delete(oldest);
-      try { oldest.onEvict?.(); } catch { /* ignore eviction callback errors */ }
-    }
-    const entry: SubscriberEntry = { filter, callback, active: true, onEvict: options?.onEvict };
-    this.subscribers.add(entry);
-
-    return {
-      dispose: () => {
-        if (entry.active) {
-          entry.active = false;
-          this.subscribers.delete(entry);
-        }
-      },
-      get active() {
-        return entry.active;
-      },
-    };
-  }
-
-  /**
-   * Publish an event to all matching subscribers.
-   *
-   * Matching rules:
-   * - `event.assistantId` must equal `filter.assistantId`
-   * - if `filter.sessionId` is set, `event.sessionId` must equal it
-   *
-   * Fanout is isolated: a throwing or rejecting subscriber does not abort
-   * delivery to remaining subscribers. All callbacks (sync and async) are
-   * awaited and their errors collected; any errors are re-thrown together
-   * as an `AggregateError` after all callbacks have been invoked.
-   *
-   * Subscribers are snapshotted at the start of each publish call so that
-   * callbacks adding new subscriptions do not receive the in-flight event.
-   */
-  async publish(event: AssistantEvent): Promise<void> {
-    const snapshot = Array.from(this.subscribers);
-    const errors: unknown[] = [];
-
-    for (const entry of snapshot) {
-      if (!entry.active) continue;
-      if (entry.filter.assistantId !== event.assistantId) continue;
-      if (entry.filter.sessionId != null && entry.filter.sessionId !== event.sessionId) continue;
-      try {
-        await entry.callback(event);
-      } catch (err) {
-        errors.push(err);
-      }
-    }
-
-    if (errors.length > 0) {
-      throw new AggregateError(errors, 'One or more assistant-event subscribers threw');
-    }
-  }
-
-  /** Number of currently active subscribers (useful for tests and caps). */
-  subscriberCount(): number {
-    return this.subscribers.size;
-  }
-
-  /** Returns true if the hub can accept a subscriber without evicting anyone. */
-  hasCapacity(): boolean {
-    return this.subscribers.size < this.maxSubscribers;
-  }
-}
-
-// ── Process-level singleton ───────────────────────────────────────────────────
-
-/**
- * Singleton hub shared across the entire runtime process.
- *
- * Import and use this in daemon send paths (PR 3) and the SSE route (PR 5).
- */
-export const assistantEventHub = new AssistantEventHub({ maxSubscribers: 100 });

package/src/runtime/assistant-event.ts

@@ -1,82 +0,0 @@
-/**
- * Assistant Events — shared types and SSE framing helpers.
- *
- * 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.
- */
-
-import { randomUUID } from 'node:crypto';
-import type { ServerMessage } from '../daemon/ipc-protocol.js';
-
-// ── Types ─────────────────────────────────────────────────────────────────────
-
-/**
- * A single assistant event wrapping an IPC ServerMessage payload.
- * The `message` field is intentionally unchanged from the IPC 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/session id when available. */
-  sessionId?: string;
-  /** ISO-8601 timestamp of when the event was emitted. */
-  emittedAt: string;
-  /** Unchanged IPC outbound message payload. */
-  message: 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 unchanged IPC outbound message payload.
- * @param sessionId    Optional conversation/session id — pass when known.
- */
-export function buildAssistantEvent(
-  assistantId: string,
-  message: ServerMessage,
-  sessionId?: string,
-): AssistantEvent {
-  return {
-    id: randomUUID(),
-    assistantId,
-    sessionId,
-    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';
-}

package/src/runtime/channel-approval-parser.ts

@@ -1,60 +0,0 @@
-/**
- * Channel-agnostic plain-text approval decision parser.
- *
- * Parses inbound user text to determine whether it matches an approval,
- * rejection, or "approve always" intent. This module is transport-agnostic
- * and can be used by any channel adapter (Telegram, SMS, etc.).
- */
-
-import type { ApprovalAction, ApprovalDecisionResult } from './channel-approval-types.js';
-
-// ---------------------------------------------------------------------------
-// Phrase → action mapping
-// ---------------------------------------------------------------------------
-
-const APPROVE_ONCE_PHRASES = ['yes', 'approve', 'allow', 'go ahead'];
-const APPROVE_ALWAYS_PHRASES = ['always', 'approve always', 'allow always'];
-const REJECT_PHRASES = ['no', 'reject', 'deny', 'cancel'];
-
-/**
- * Build a Map from lowercased phrase to action. "Approve always" phrases
- * are checked first (longest-match-wins) because "approve" is a prefix
- * of "approve always".
- */
-function buildPhraseMap(): Map<string, ApprovalAction> {
-  const map = new Map<string, ApprovalAction>();
-
-  // Insert longer phrases first so iteration order does not matter —
-  // we match on exact equality after normalising, not prefix matching.
-  for (const phrase of APPROVE_ALWAYS_PHRASES) {
-    map.set(phrase, 'approve_always');
-  }
-  for (const phrase of APPROVE_ONCE_PHRASES) {
-    map.set(phrase, 'approve_once');
-  }
-  for (const phrase of REJECT_PHRASES) {
-    map.set(phrase, 'reject');
-  }
-  return map;
-}
-
-const PHRASE_MAP = buildPhraseMap();
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
-/**
- * Parse a plain-text message into an approval decision.
- *
- * Returns a structured `ApprovalDecisionResult` if the text matches one
- * of the known intent phrases, or `null` if it does not match.
- *
- * Matching is case-insensitive with leading/trailing whitespace trimmed.
- */
-export function parseApprovalDecision(text: string): ApprovalDecisionResult | null {
-  const normalised = text.trim().toLowerCase();
-  const action = PHRASE_MAP.get(normalised);
-  if (!action) return null;
-  return { action, source: 'plain_text' };
-}

package/src/runtime/channel-approval-types.ts

@@ -1,71 +0,0 @@
-/**
- * Channel-agnostic approval flow types.
- *
- * These types model the approval prompt/decision lifecycle for tool-use
- * confirmations surfaced through external channels (Telegram, SMS, etc.).
- * They are intentionally decoupled from any specific channel so that the
- * same approval flow can be reused across transports.
- */
-
-// ---------------------------------------------------------------------------
-// Approval actions
-// ---------------------------------------------------------------------------
-
-/** The set of actions a user can take on an approval prompt. */
-export type ApprovalAction = 'approve_once' | 'approve_always' | 'reject';
-
-/** An action presented to the user as a tappable button or text option. */
-export interface ApprovalActionOption {
-  id: ApprovalAction;
-  label: string;
-}
-
-/** Default action options presented to users across all channels. */
-export const DEFAULT_APPROVAL_ACTIONS: readonly ApprovalActionOption[] = [
-  { id: 'approve_once', label: 'Approve once' },
-  { id: 'approve_always', label: 'Approve always' },
-  { id: 'reject', label: 'Reject' },
-] as const;
-
-// ---------------------------------------------------------------------------
-// Approval prompt
-// ---------------------------------------------------------------------------
-
-/** The approval prompt model sent to users via a channel. */
-export interface ChannelApprovalPrompt {
-  /** Human-readable description of what is being approved. */
-  promptText: string;
-  /** Available actions the user can take. */
-  actions: ApprovalActionOption[];
-  /** Instruction text for channels that only support plain text (no buttons). */
-  plainTextFallback: string;
-}
-
-// ---------------------------------------------------------------------------
-// Approval UI metadata (gateway callback payload)
-// ---------------------------------------------------------------------------
-
-/**
- * Metadata attached to gateway callback payloads so the channel adapter
- * can render approval UI and route the user's decision back to the
- * correct pending run.
- */
-export interface ApprovalUIMetadata {
-  runId: string;
-  requestId: string;
-  actions: ApprovalActionOption[];
-  plainTextFallback: string;
-}
-
-// ---------------------------------------------------------------------------
-// Decision result
-// ---------------------------------------------------------------------------
-
-/** How the user communicated their decision. */
-export type ApprovalDecisionSource = 'telegram_button' | 'plain_text';
-
-/** The structured result of a user's approval decision. */
-export interface ApprovalDecisionResult {
-  action: ApprovalAction;
-  source: ApprovalDecisionSource;
-}

package/src/runtime/channel-approvals.ts

@@ -1,145 +0,0 @@
-/**
- * Channel-agnostic approval orchestration module.
- *
- * Bridges the gap between external channel adapters (Telegram, SMS, etc.)
- * and the internal run orchestrator / permission system:
- *
- *   1. Detect pending confirmations for a conversation
- *   2. Build human-readable approval prompts with action buttons
- *   3. Consume user decisions and apply them to the underlying run
- *   4. Build reminder prompts when non-decision messages arrive
- */
-
-import { getPendingConfirmationsByConversation, getRun } from '../memory/runs-store.js';
-import type { PendingRunInfo } from '../memory/runs-store.js';
-import { addRule } from '../permissions/trust-store.js';
-import type { RunOrchestrator } from './run-orchestrator.js';
-import { DEFAULT_APPROVAL_ACTIONS } from './channel-approval-types.js';
-import type {
-  ChannelApprovalPrompt,
-  ApprovalUIMetadata,
-  ApprovalDecisionResult,
-} from './channel-approval-types.js';
-
-// ---------------------------------------------------------------------------
-// 1. Detect pending confirmations and build prompt
-// ---------------------------------------------------------------------------
-
-/**
- * Check whether a conversation has a pending tool-use confirmation and,
- * if so, build a human-readable approval prompt.
- *
- * Returns `null` when there is nothing waiting for approval.
- */
-export function getChannelApprovalPrompt(
-  conversationId: string,
-): ChannelApprovalPrompt | null {
-  const pending = getPendingConfirmationsByConversation(conversationId);
-  if (pending.length === 0) return null;
-
-  // Use the first pending run — channel UIs show one prompt at a time.
-  const info = pending[0];
-  return buildPromptFromRunInfo(info);
-}
-
-/**
- * Internal helper: turn a PendingRunInfo into a ChannelApprovalPrompt.
- */
-function buildPromptFromRunInfo(info: PendingRunInfo): ChannelApprovalPrompt {
-  const promptText = `The assistant wants to use the tool "${info.toolName}". Do you want to allow this?`;
-  const actions = [...DEFAULT_APPROVAL_ACTIONS];
-  const plainTextFallback =
-    `${promptText}\n\nReply "yes" to approve once, "always" to approve always, or "no" to reject.`;
-
-  return { promptText, actions, plainTextFallback };
-}
-
-// ---------------------------------------------------------------------------
-// 2. Build gateway-facing UI metadata
-// ---------------------------------------------------------------------------
-
-/**
- * Convert a prompt + run info into the `ApprovalUIMetadata` payload that
- * gateway adapters use to render buttons and route decisions back.
- */
-export function buildApprovalUIMetadata(
-  prompt: ChannelApprovalPrompt,
-  runInfo: PendingRunInfo,
-): ApprovalUIMetadata {
-  return {
-    runId: runInfo.runId,
-    requestId: runInfo.requestId,
-    actions: prompt.actions,
-    plainTextFallback: prompt.plainTextFallback,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// 3. Consume a user decision and apply it to the run
-// ---------------------------------------------------------------------------
-
-export interface HandleDecisionResult {
-  applied: boolean;
-  runId?: string;
-}
-
-/**
- * Find the pending run for a conversation, map the user's decision to the
- * permission system's vocabulary, and apply it.
- *
- * For `approve_always`, a trust rule is persisted using the first allowlist
- * option and first scope option from the pending confirmation (narrow
- * default). The current invocation is also approved.
- */
-export function handleChannelDecision(
-  conversationId: string,
-  decision: ApprovalDecisionResult,
-  orchestrator: RunOrchestrator,
-): HandleDecisionResult {
-  const pending = getPendingConfirmationsByConversation(conversationId);
-  if (pending.length === 0) return { applied: false };
-
-  const info = pending[0];
-
-  if (decision.action === 'approve_always') {
-    // Persist a trust rule so future invocations of this tool are auto-approved.
-    const run = getRun(info.runId);
-    const confirmation = run?.pendingConfirmation;
-    if (confirmation) {
-      const pattern = confirmation.allowlistOptions?.[0]?.pattern ?? '**';
-      const scope = confirmation.scopeOptions?.[0]?.scope ?? 'everywhere';
-      addRule(confirmation.toolName, pattern, scope, 'allow', 100, {
-        executionTarget: confirmation.executionTarget,
-      });
-    }
-  }
-
-  // Map channel-level action to the permission system's UserDecision type.
-  const userDecision = decision.action === 'reject' ? 'deny' as const : 'allow' as const;
-  const result = orchestrator.submitDecision(info.runId, userDecision);
-
-  return {
-    applied: result === 'applied',
-    runId: info.runId,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// 4. Reminder prompt for non-decision messages
-// ---------------------------------------------------------------------------
-
-/**
- * Build a reminder prompt when the user sends a non-decision message while
- * an approval is pending. Reuses the original actions and fallback text
- * but prefixes the prompt text with a reminder.
- */
-export function buildReminderPrompt(
-  pendingPrompt: ChannelApprovalPrompt,
-): ChannelApprovalPrompt {
-  const reminderPrefix = "I'm still waiting for your decision on the previous request.";
-  return {
-    promptText: `${reminderPrefix}\n\n${pendingPrompt.promptText}`,
-    actions: pendingPrompt.actions,
-    plainTextFallback: `${reminderPrefix}\n\n${pendingPrompt.plainTextFallback}`,
-  };
-}