@vellumai/assistant 0.3.0

package/src/runtime/routes/run-routes.ts

@@ -0,0 +1,257 @@
+/**
+ * Route handlers for run creation, status, decisions, and trust rules.
+ */
+import { getOrCreateConversation } from '../../memory/conversation-key-store.js';
+import * as attachmentsStore from '../../memory/attachments-store.js';
+import * as runsStore from '../../memory/runs-store.js';
+import { addRule } from '../../permissions/trust-store.js';
+import { getLogger } from '../../util/logger.js';
+import type { RunOrchestrator } from '../run-orchestrator.js';
+
+const log = getLogger('runtime-http');
+
+export async function handleCreateRun(
+  req: Request,
+  runOrchestrator: RunOrchestrator,
+): Promise<Response> {
+  const body = await req.json() as {
+    conversationKey?: string;
+    content?: string;
+    attachmentIds?: string[];
+  };
+
+  const { conversationKey, content, attachmentIds } = body;
+
+  if (!conversationKey) {
+    return Response.json({ error: 'conversationKey is required' }, { status: 400 });
+  }
+
+  if (content !== undefined && content !== null && typeof content !== 'string') {
+    return Response.json({ error: 'content must be a string' }, { status: 400 });
+  }
+
+  const trimmedContent = typeof content === 'string' ? content.trim() : '';
+  const hasAttachments = Array.isArray(attachmentIds) && attachmentIds.length > 0;
+
+  if (trimmedContent.length === 0 && !hasAttachments) {
+    return Response.json({ error: 'content or attachmentIds is required' }, { status: 400 });
+  }
+
+  if (hasAttachments) {
+    const resolved = attachmentsStore.getAttachmentsByIds(attachmentIds);
+    if (resolved.length !== attachmentIds.length) {
+      const resolvedIds = new Set(resolved.map((a) => a.id));
+      const missing = attachmentIds.filter((id) => !resolvedIds.has(id));
+      return Response.json(
+        { error: `Attachment IDs not found: ${missing.join(', ')}` },
+        { status: 400 },
+      );
+    }
+  }
+
+  const mapping = getOrCreateConversation(conversationKey);
+
+  try {
+    const run = await runOrchestrator.startRun(
+      mapping.conversationId,
+      content ?? '',
+      hasAttachments ? attachmentIds : undefined,
+    );
+    return Response.json({
+      id: run.id,
+      status: run.status,
+      messageId: run.messageId,
+      createdAt: new Date(run.createdAt).toISOString(),
+    }, { status: 201 });
+  } catch (err) {
+    if (err instanceof Error && err.message === 'Session is already processing a message') {
+      return Response.json(
+        { error: 'Session is busy processing another message. Please retry.' },
+        { status: 409 },
+      );
+    }
+    throw err;
+  }
+}
+
+export function handleGetRun(
+  runId: string,
+  runOrchestrator: RunOrchestrator,
+): Response {
+  const run = runOrchestrator.getRun(runId);
+  if (!run) {
+    return Response.json({ error: 'Run not found' }, { status: 404 });
+  }
+
+  return Response.json({
+    id: run.id,
+    status: run.status,
+    messageId: run.messageId,
+    pendingConfirmation: run.pendingConfirmation,
+    pendingSecret: run.pendingSecret,
+    error: run.error,
+    createdAt: new Date(run.createdAt).toISOString(),
+    updatedAt: new Date(run.updatedAt).toISOString(),
+  });
+}
+
+export async function handleRunDecision(
+  runId: string,
+  req: Request,
+  runOrchestrator: RunOrchestrator,
+): Promise<Response> {
+  const run = runOrchestrator.getRun(runId);
+  if (!run) {
+    return Response.json({ error: 'Run not found' }, { status: 404 });
+  }
+
+  const body = await req.json() as { decision?: string };
+  const { decision } = body;
+
+  if (decision !== 'allow' && decision !== 'deny') {
+    return Response.json(
+      { error: 'decision must be "allow" or "deny"' },
+      { status: 400 },
+    );
+  }
+
+  const result = runOrchestrator.submitDecision(runId, decision);
+  if (result === 'run_not_found') {
+    return Response.json(
+      { error: 'Run not found' },
+      { status: 404 },
+    );
+  }
+  if (result === 'no_pending_decision') {
+    return Response.json(
+      { error: 'No confirmation pending for this run' },
+      { status: 409 },
+    );
+  }
+
+  return Response.json({ accepted: true });
+}
+
+/**
+ * Add a trust rule, but ONLY if there is a pending confirmation for the
+ * given run.  The caller-supplied pattern and scope are validated against
+ * the server-generated allowlist/scope options that were sent with the
+ * original confirmation_request — preventing arbitrary rule injection.
+ */
+export async function handleAddTrustRule(
+  runId: string,
+  req: Request,
+): Promise<Response> {
+  const run = runsStore.getRun(runId);
+  if (!run) {
+    return Response.json({ error: 'Run not found' }, { status: 404 });
+  }
+
+  if (run.status !== 'needs_confirmation' || !run.pendingConfirmation) {
+    return Response.json(
+      { error: 'No confirmation pending for this run' },
+      { status: 409 },
+    );
+  }
+
+  if (run.pendingConfirmation.persistentDecisionsAllowed === false) {
+    return Response.json(
+      { error: 'Persistent trust rules are not allowed for this tool invocation' },
+      { status: 403 },
+    );
+  }
+
+  const body = await req.json() as {
+    pattern?: string;
+    scope?: string;
+    decision?: string;
+  };
+
+  const { pattern, scope, decision } = body;
+
+  if (!pattern || typeof pattern !== 'string') {
+    return Response.json({ error: 'pattern is required' }, { status: 400 });
+  }
+  if (!scope || typeof scope !== 'string') {
+    return Response.json({ error: 'scope is required' }, { status: 400 });
+  }
+  if (decision !== 'allow' && decision !== 'deny') {
+    return Response.json({ error: 'decision must be "allow" or "deny"' }, { status: 400 });
+  }
+
+  const confirmation = run.pendingConfirmation;
+
+  // Validate pattern against server-provided allowlist options
+  const validPatterns = (confirmation.allowlistOptions ?? []).map((o) => o.pattern);
+  if (!validPatterns.includes(pattern)) {
+    return Response.json(
+      { error: 'pattern does not match any server-provided allowlist option' },
+      { status: 403 },
+    );
+  }
+
+  // Validate scope against server-provided scope options
+  const validScopes = (confirmation.scopeOptions ?? []).map((o) => o.scope);
+  if (!validScopes.includes(scope)) {
+    return Response.json(
+      { error: 'scope does not match any server-provided scope option' },
+      { status: 403 },
+    );
+  }
+
+  try {
+    addRule(confirmation.toolName, pattern, scope, decision, undefined, {
+      executionTarget: confirmation.executionTarget,
+    });
+    log.info(
+      { tool: confirmation.toolName, pattern, scope, decision, runId },
+      'Trust rule added via HTTP (bound to pending confirmation)',
+    );
+    return Response.json({ accepted: true });
+  } catch (err) {
+    log.error({ err }, 'Failed to add trust rule');
+    return Response.json({ error: 'Failed to add trust rule' }, { status: 500 });
+  }
+}
+
+export async function handleRunSecret(
+  runId: string,
+  req: Request,
+  runOrchestrator: RunOrchestrator,
+): Promise<Response> {
+  const run = runOrchestrator.getRun(runId);
+  if (!run) {
+    return Response.json({ error: 'Run not found' }, { status: 404 });
+  }
+
+  const body = await req.json() as {
+    value?: string;
+    delivery?: string;
+  };
+
+  const { value, delivery } = body;
+
+  if (delivery !== undefined && delivery !== 'store' && delivery !== 'transient_send') {
+    return Response.json(
+      { error: 'delivery must be "store" or "transient_send"' },
+      { status: 400 },
+    );
+  }
+
+  const result = runOrchestrator.submitSecret(
+    runId,
+    value,
+    delivery as 'store' | 'transient_send' | undefined,
+  );
+  if (result === 'run_not_found') {
+    return Response.json({ error: 'Run not found' }, { status: 404 });
+  }
+  if (result === 'no_pending_secret') {
+    return Response.json(
+      { error: 'No secret pending for this run' },
+      { status: 409 },
+    );
+  }
+
+  return Response.json({ accepted: true });
+}

package/src/runtime/routes/secret-routes.ts

@@ -0,0 +1,76 @@
+import { API_KEY_PROVIDERS, getConfig, invalidateConfigCache } from '../../config/loader.js';
+import { initializeProviders } from '../../providers/registry.js';
+import { setSecureKey } from '../../security/secure-keys.js';
+import { assertMetadataWritable, upsertCredentialMetadata } from '../../tools/credentials/metadata-store.js';
+import { getLogger } from '../../util/logger.js';
+
+const log = getLogger('runtime-http');
+
+export async function handleAddSecret(req: Request): Promise<Response> {
+  const body = await req.json() as {
+    type?: string;
+    name?: string;
+    value?: string;
+  };
+
+  const { type, name, value } = body;
+
+  if (!type || typeof type !== 'string') {
+    return Response.json({ error: 'type is required' }, { status: 400 });
+  }
+  if (!name || typeof name !== 'string') {
+    return Response.json({ error: 'name is required' }, { status: 400 });
+  }
+  if (!value || typeof value !== 'string') {
+    return Response.json({ error: 'value is required' }, { status: 400 });
+  }
+
+  try {
+    if (type === 'api_key') {
+      if (!API_KEY_PROVIDERS.includes(name as typeof API_KEY_PROVIDERS[number])) {
+        return Response.json(
+          { error: `Unknown API key provider: ${name}. Valid providers: ${API_KEY_PROVIDERS.join(', ')}` },
+          { status: 400 },
+        );
+      }
+      const stored = setSecureKey(name, value);
+      if (!stored) {
+        return Response.json({ error: 'Failed to store API key in secure storage' }, { status: 500 });
+      }
+      invalidateConfigCache();
+      initializeProviders(getConfig());
+      log.info({ provider: name }, 'API key updated via HTTP');
+      return Response.json({ success: true, type, name }, { status: 201 });
+    }
+
+    if (type === 'credential') {
+      const colonIdx = name.indexOf(':');
+      if (colonIdx < 1 || colonIdx === name.length - 1) {
+        return Response.json(
+          { error: 'For credential type, name must be in "service:field" format (e.g. "github:api_token")' },
+          { status: 400 },
+        );
+      }
+      assertMetadataWritable();
+      const service = name.slice(0, colonIdx);
+      const field = name.slice(colonIdx + 1);
+      const key = `credential:${service}:${field}`;
+      const stored = setSecureKey(key, value);
+      if (!stored) {
+        return Response.json({ error: 'Failed to store credential in secure storage' }, { status: 500 });
+      }
+      upsertCredentialMetadata(service, field, {});
+      log.info({ service, field }, 'Credential added via HTTP');
+      return Response.json({ success: true, type, name }, { status: 201 });
+    }
+
+    return Response.json(
+      { error: `Unknown secret type: ${type}. Valid types: api_key, credential` },
+      { status: 400 },
+    );
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    log.error({ err, type, name }, 'Failed to add secret via HTTP');
+    return Response.json({ error: message }, { status: 500 });
+  }
+}

package/src/runtime/run-orchestrator.ts

@@ -0,0 +1,330 @@
+/**
+ * Orchestrates run lifecycle for the HTTP runtime API.
+ *
+ * A "run" wraps a single agent-loop execution, tracking its state through:
+ *   running → needs_confirmation → running → completed | failed
+ *   running → needs_secret       → running → completed | failed
+ *
+ * When a tool needs permission, the orchestrator intercepts the
+ * confirmation_request from the session's prompter and records it in
+ * the run store.  Similarly, when a tool needs a secret (e.g.
+ * credential_store prompt), the orchestrator intercepts the
+ * secret_request and records it.  The client can then poll the run
+ * status and submit a decision or secret via the respective endpoints.
+ */
+
+import * as runsStore from '../memory/runs-store.js';
+import type { Run } from '../memory/runs-store.js';
+import type { Session } from '../daemon/session.js';
+import type { ServerMessage } from '../daemon/ipc-protocol.js';
+import { resolveChannelCapabilities } from '../daemon/session-runtime-assembly.js';
+import type { UserDecision } from '../permissions/types.js';
+import { checkIngressForSecrets } from '../security/secret-ingress.js';
+import { IngressBlockedError } from '../util/errors.js';
+import { getLogger } from '../util/logger.js';
+import { assistantEventHub } from './assistant-event-hub.js';
+import { buildAssistantEvent } from './assistant-event.js';
+
+const log = getLogger('run-orchestrator');
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+interface PendingRunState {
+  prompterRequestId: string;
+  session: Session;
+}
+
+export interface RunOrchestratorDeps {
+  getOrCreateSession: (conversationId: string) => Promise<Session>;
+  resolveAttachments: (attachmentIds: string[]) => Array<{
+    id: string;
+    filename: string;
+    mimeType: string;
+    data: string;
+  }>;
+  /**
+   * Re-derive the default `strictSideEffects` value for a conversation
+   * from its thread type (e.g. private → true, standard → false).
+   * Called when `forceStrictSideEffects` is not explicitly provided so
+   * the session never retains a stale override from a prior run.
+   */
+  deriveDefaultStrictSideEffects: (conversationId: string) => boolean;
+}
+
+export interface RunStartOptions {
+  /**
+   * When true, forces `strictSideEffects` on the session's memory policy
+   * so that all side-effect tools trigger the approval/confirmation flow,
+   * even if existing allow rules would normally auto-approve them.
+   * Used for non-guardian actors in guardian-gated channels.
+   */
+  forceStrictSideEffects?: boolean;
+  /**
+   * The originating channel (e.g. 'telegram', 'slack'). When provided,
+   * channel capabilities are resolved for this channel instead of the
+   * default 'http-api'.
+   */
+  sourceChannel?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Orchestrator
+// ---------------------------------------------------------------------------
+
+export class RunOrchestrator {
+  private pending = new Map<string, PendingRunState>();
+  private deps: RunOrchestratorDeps;
+
+  constructor(deps: RunOrchestratorDeps) {
+    this.deps = deps;
+
+    // On startup, mark any runs left in non-terminal states as failed.
+    // These are orphans from a previous daemon process that was interrupted.
+    const recovered = runsStore.failOrphanedRuns();
+    if (recovered > 0) {
+      log.info({ count: recovered }, 'Recovered orphaned runs from previous session');
+    }
+  }
+
+  /**
+   * Start a new run: persist the user message, create a run record,
+   * and fire the agent loop in the background.
+   */
+  async startRun(
+    conversationId: string,
+    content: string,
+    attachmentIds?: string[],
+    options?: RunStartOptions,
+  ): Promise<Run> {
+    // Block inbound content that contains secrets — mirrors the IPC check in sessions.ts
+    const ingressCheck = checkIngressForSecrets(content);
+    if (ingressCheck.blocked) {
+      throw new IngressBlockedError(ingressCheck.userNotice!, ingressCheck.detectedTypes);
+    }
+
+    const session = await this.deps.getOrCreateSession(conversationId);
+
+    if (session.isProcessing()) {
+      throw new Error('Session is already processing a message');
+    }
+
+    // Determine the correct strictSideEffects value for this run:
+    // - explicit true/false from the caller → use that value
+    // - undefined → re-derive from the conversation's thread type so a
+    //   prior run's forceStrictSideEffects=true doesn't stick on the
+    //   cached session (private threads → true, standard → false)
+    const strictSideEffects = options?.forceStrictSideEffects
+      ?? this.deps.deriveDefaultStrictSideEffects(conversationId);
+    session.memoryPolicy = {
+      ...session.memoryPolicy,
+      strictSideEffects,
+    };
+
+    const attachments = attachmentIds
+      ? this.deps.resolveAttachments(attachmentIds)
+      : [];
+
+    const requestId = crypto.randomUUID();
+    const messageId = session.persistUserMessage(content, attachments, requestId);
+    const run = runsStore.createRun(conversationId, messageId);
+
+    // Set channel capabilities based on the originating channel so capabilities
+    // (e.g. attachment scope) match the actual transport rather than always
+    // defaulting to 'http-api'.
+    session.setChannelCapabilities(resolveChannelCapabilities(options?.sourceChannel ?? 'http-api'));
+
+    // Serialized publish chain so hub subscribers observe events in order.
+    let hubChain: Promise<void> = Promise.resolve();
+    const publishToHub = (msg: ServerMessage): void => {
+      const msgRecord = msg as unknown as Record<string, unknown>;
+      const msgSessionId =
+        'sessionId' in msg && typeof msgRecord.sessionId === 'string'
+          ? (msgRecord.sessionId as string)
+          : undefined;
+      const resolvedSessionId = msgSessionId ?? conversationId;
+      const event = buildAssistantEvent('self', msg, resolvedSessionId);
+      hubChain = hubChain
+        .then(() => assistantEventHub.publish(event))
+        .catch((err: unknown) => {
+          log.warn({ err }, 'assistant-events hub subscriber threw during HTTP run');
+        });
+    };
+
+
+    // Hook into session to intercept confirmation_request and secret_request events.
+    // When the prompter sends one of these, we record it in the run store so
+    // the client can poll and submit a decision/secret via the respective endpoint.
+    // Do NOT set hasNoClient — run sessions have a client (the HTTP caller).
+    let lastError: string | null = null;
+    session.updateClient((msg: ServerMessage) => {
+      if (msg.type === 'confirmation_request') {
+        runsStore.setRunConfirmation(run.id, {
+          toolName: msg.toolName,
+          toolUseId: msg.requestId,
+          input: msg.input,
+          riskLevel: msg.riskLevel,
+          executionTarget: msg.executionTarget,
+          allowlistOptions: msg.allowlistOptions,
+          scopeOptions: msg.scopeOptions,
+          persistentDecisionsAllowed: msg.persistentDecisionsAllowed,
+        });
+        this.pending.set(run.id, {
+          prompterRequestId: msg.requestId,
+          session,
+        });
+      } else if (msg.type === 'secret_request') {
+        runsStore.setRunSecret(run.id, {
+          requestId: msg.requestId,
+          service: msg.service,
+          field: msg.field,
+          label: msg.label,
+          description: msg.description,
+          placeholder: msg.placeholder,
+          purpose: msg.purpose,
+          allowOneTimeSend: msg.allowOneTimeSend,
+        });
+        this.pending.set(run.id, {
+          prompterRequestId: msg.requestId,
+          session,
+        });
+      }
+      // Mirror every outbound message to the assistant-events hub so SSE
+      // subscribers receive the same payload parity as IPC clients.
+      publishToHub(msg);
+    });
+
+    // Fire-and-forget the agent loop
+    const cleanup = () => {
+      this.pending.delete(run.id);
+      // Reset channel capabilities so a subsequent IPC/desktop session on the
+      // same conversation is not incorrectly treated as an HTTP-API client.
+      session.setChannelCapabilities(null);
+      // Reset the session's client callback to a no-op so the stale
+      // closure doesn't intercept events from future runs on the same session.
+      // Set hasNoClient=true here since the run is done and no HTTP caller
+      // is actively listening — truly no client at this point.
+      session.updateClient(() => {}, true);
+    };
+
+    session.runAgentLoop(content, messageId, (msg: ServerMessage) => {
+      if (msg.type === 'error') {
+        lastError = msg.message;
+      } else if (msg.type === 'session_error') {
+        lastError = msg.userMessage;
+      }
+      // Mirror agent-loop events (assistant_text_delta, message_complete,
+      // tool_use_start, tool_result, etc.) to the hub. These travel through
+      // the onEvent path, distinct from the updateClient path used by the
+      // prompter (confirmation_request). Both paths must publish so SSE
+      // consumers receive the full response stream.
+      publishToHub(msg);
+    }).then(() => {
+      if (lastError) {
+        log.error({ runId: run.id, error: lastError }, 'Run failed (error event from agent loop)');
+        runsStore.failRun(run.id, lastError);
+      } else {
+        runsStore.completeRun(run.id);
+      }
+      cleanup();
+    }).catch((err) => {
+      const message = err instanceof Error ? err.message : String(err);
+      log.error({ err, runId: run.id }, 'Run failed');
+      runsStore.failRun(run.id, message);
+      cleanup();
+    });
+
+    return run;
+  }
+
+  /** Read current run state from the store. */
+  getRun(runId: string): Run | null {
+    return runsStore.getRun(runId);
+  }
+
+  /**
+   * Submit a permission decision for a pending confirmation.
+   *
+   * Returns:
+   * - `'applied'`         – decision was applied or already handled (idempotent)
+   * - `'run_not_found'`   – no run exists with the given ID
+   * - `'no_pending_decision'` – run exists but is not awaiting a confirmation
+   */
+  submitDecision(runId: string, decision: UserDecision): 'applied' | 'run_not_found' | 'no_pending_decision' {
+    const pendingState = this.pending.get(runId);
+    if (pendingState) {
+      runsStore.clearRunConfirmation(runId);
+      pendingState.session.handleConfirmationResponse(
+        pendingState.prompterRequestId,
+        decision,
+      );
+      this.pending.delete(runId);
+      return 'applied';
+    }
+
+    // No in-memory pending state — check if the run exists.
+    const run = runsStore.getRun(runId);
+    if (!run) return 'run_not_found';
+
+    // If the run is still needs_confirmation but there's no in-memory
+    // state, the prompter already timed out and auto-denied. Fail the
+    // run rather than clearing to 'running', since no agent loop exists
+    // to complete it.
+    if (run.status === 'needs_confirmation') {
+      runsStore.failRun(runId, 'Prompter timed out (no active handler)');
+      return 'applied';
+    }
+
+    // Terminal states (completed/failed) mean the decision was already
+    // handled (double-submit). Treat as idempotent success.
+    if (run.status === 'completed' || run.status === 'failed') {
+      return 'applied';
+    }
+
+    // Run is in 'running' state with no pending confirmation — the
+    // agent loop hasn't reached a confirmation point yet. Reject so
+    // the client doesn't mistakenly treat the decision as accepted.
+    return 'no_pending_decision';
+  }
+
+  /**
+   * Submit a secret value for a pending secret request.
+   *
+   * Returns:
+   * - `'applied'`           – secret was forwarded to the session
+   * - `'run_not_found'`     – no run exists with the given ID
+   * - `'no_pending_secret'` – run exists but is not awaiting a secret
+   */
+  submitSecret(
+    runId: string,
+    value?: string,
+    delivery?: 'store' | 'transient_send',
+  ): 'applied' | 'run_not_found' | 'no_pending_secret' {
+    const pendingState = this.pending.get(runId);
+    if (pendingState) {
+      runsStore.clearRunSecret(runId);
+      pendingState.session.handleSecretResponse(
+        pendingState.prompterRequestId,
+        value,
+        delivery,
+      );
+      this.pending.delete(runId);
+      return 'applied';
+    }
+
+    const run = runsStore.getRun(runId);
+    if (!run) return 'run_not_found';
+
+    if (run.status === 'needs_secret') {
+      runsStore.failRun(runId, 'Secret prompter timed out (no active handler)');
+      return 'applied';
+    }
+
+    if (run.status === 'completed' || run.status === 'failed') {
+      return 'applied';
+    }
+
+    return 'no_pending_secret';
+  }
+}