@vellumai/assistant 0.7.1 → 0.7.2

package/src/runtime/routes/gateway-log-routes.ts

@@ -0,0 +1,79 @@
+/**
+ * Gateway log tail route — gateway HTTP proxy.
+ *
+ * The handler makes a single HTTP call to the gateway's log-tail API
+ * and surfaces the body's `.error` message on non-OK responses.
+ */
+import { z } from "zod";
+
+import { getGatewayInternalBaseUrl } from "../../config/env.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+
+// ── Shared helper ───────────────────────────────────────────────────────
+
+async function gatewayFetch(
+  path: string,
+  init?: RequestInit,
+): Promise<unknown> {
+  const base = getGatewayInternalBaseUrl();
+  const res = await fetch(`${base}${path}`, init);
+  if (!res.ok) {
+    let message = `Gateway request failed (${res.status})`;
+    try {
+      const body = (await res.json()) as { error?: unknown };
+      if (typeof body.error === "string") {
+        message = body.error;
+      }
+    } catch {
+      // ignore JSON parse failures
+    }
+    throw new Error(message);
+  }
+  return res.json();
+}
+
+// ── Schemas ─────────────────────────────────────────────────────────────
+
+const LEVEL_NAMES = ["trace", "debug", "info", "warn", "error", "fatal"] as const;
+
+const GatewayLogsTailParams = z
+  .object({
+    n: z.coerce.number().int().min(1).max(1000).optional(),
+    level: z.enum(LEVEL_NAMES).optional(),
+    module: z.string().optional(),
+  })
+  .strict();
+
+// ── Handlers ────────────────────────────────────────────────────────────
+
+async function handleGatewayLogsTail({ queryParams = {}, body = {} }: RouteHandlerArgs) {
+  // HTTP GET delivers filters via queryParams; CLI IPC puts them in body.
+  const source = Object.keys(queryParams).length > 0 ? queryParams : body;
+  const p = GatewayLogsTailParams.parse(source);
+  const qs = new URLSearchParams();
+  if (p.n !== undefined) qs.set("n", String(p.n));
+  if (p.level !== undefined) qs.set("level", p.level);
+  if (p.module !== undefined) qs.set("module", p.module);
+  const query = qs.toString();
+  return gatewayFetch(`/v1/logs/tail${query ? `?${query}` : ""}`);
+}
+
+// ── Route definitions ───────────────────────────────────────────────────
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "gateway_logs_tail",
+    method: "GET",
+    endpoint: "gateway/logs/tail",
+    handler: handleGatewayLogsTail,
+    summary: "Tail gateway log entries",
+    description:
+      "Return the last N structured log entries from the gateway log files.",
+    tags: ["gateway-logs"],
+    queryParams: [
+      { name: "n", description: "Number of lines to return (1–1000, default: 10)" },
+      { name: "level", description: "Minimum pino level name (default: info)" },
+      { name: "module", description: "Filter to exact pino module name" },
+    ],
+  },
+];

package/src/runtime/routes/guardian-approval-interception.ts

@@ -71,14 +71,8 @@ export interface ApprovalInterceptionParams {
   approvalMessageTs?: string;
 }
 
-export interface ApprovalInterceptionResult {
-  handled: boolean;
-  type?:
-    | "decision_applied"
-    | "assistant_turn"
-    | "guardian_decision_applied"
-    | "stale_ignored";
-}
+import type { ApprovalInterceptionResult } from "./approval-interception-types.js";
+export type { ApprovalInterceptionResult } from "./approval-interception-types.js";
 
 /**
  * Check for pending approvals and handle inbound messages accordingly.

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

@@ -8,13 +8,16 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 
-import { desc, eq } from "drizzle-orm";
 import { z } from "zod";
 
-import { getConfig, saveConfig } from "../../config/loader.js";
+import {
+  getConfig,
+  invalidateConfigCache,
+  loadRawConfig,
+  saveRawConfig,
+} from "../../config/loader.js";
+import { listHeartbeatRuns } from "../../heartbeat/heartbeat-run-store.js";
 import { HeartbeatService } from "../../heartbeat/heartbeat-service.js";
-import { getDb } from "../../memory/db-connection.js";
-import { conversations } from "../../memory/schema/conversations.js";
 import { readTextFileSync } from "../../util/fs.js";
 import { getLogger } from "../../util/logger.js";
 import { getWorkspacePromptPath } from "../../util/platform.js";
@@ -32,25 +35,20 @@ function handleListRuns(queryParams: Record<string, string>) {
   const limit = Number.isFinite(rawLimit)
     ? Math.min(Math.max(Math.floor(rawLimit), 1), 100)
     : 20;
-  const db = getDb();
-  const rows = db
-    .select({
-      id: conversations.id,
-      title: conversations.title,
-      createdAt: conversations.createdAt,
-    })
-    .from(conversations)
-    .where(eq(conversations.source, "heartbeat"))
-    .orderBy(desc(conversations.createdAt))
-    .limit(limit)
-    .all();
 
+  const runs = listHeartbeatRuns(limit);
   return {
-    runs: rows.map((r) => ({
+    runs: runs.map((r) => ({
       id: r.id,
-      title: r.title ?? "Heartbeat",
+      scheduledFor: r.scheduledFor,
+      startedAt: r.startedAt,
+      finishedAt: r.finishedAt,
+      durationMs: r.durationMs,
+      status: r.status,
+      skipReason: r.skipReason,
+      error: r.error,
+      conversationId: r.conversationId,
       createdAt: r.createdAt,
-      result: "ok",
     })),
   };
 }
@@ -102,7 +100,22 @@ export const ROUTES: RouteDefinition[] = [
       },
     ],
     responseBody: z.object({
-      runs: z.array(z.unknown()).describe("Heartbeat run records"),
+      runs: z
+        .array(
+          z.object({
+            id: z.string(),
+            scheduledFor: z.number(),
+            startedAt: z.number().nullable(),
+            finishedAt: z.number().nullable(),
+            durationMs: z.number().nullable(),
+            status: z.string(),
+            skipReason: z.string().nullable(),
+            error: z.string().nullable(),
+            conversationId: z.string().nullable(),
+            createdAt: z.number(),
+          }),
+        )
+        .describe("Heartbeat run records"),
     }),
     handler: ({ queryParams }: RouteHandlerArgs) =>
       handleListRuns(queryParams ?? {}),
@@ -135,8 +148,7 @@ export const ROUTES: RouteDefinition[] = [
     responseBody: z.object({
       success: z.boolean(),
     }),
-    handler: ({ body }: RouteHandlerArgs) =>
-      handleWriteChecklist(body ?? {}),
+    handler: ({ body }: RouteHandlerArgs) => handleWriteChecklist(body ?? {}),
   },
   {
     operationId: "getHeartbeatConfig",
@@ -152,6 +164,8 @@ export const ROUTES: RouteDefinition[] = [
       intervalMs: z.number(),
       activeHoursStart: z.number().nullable(),
       activeHoursEnd: z.number().nullable(),
+      cronExpression: z.string().nullable(),
+      timezone: z.string().nullable(),
       nextRunAt: z.number().nullable(),
       lastRunAt: z.number().nullable(),
       success: z.boolean(),
@@ -164,6 +178,8 @@ export const ROUTES: RouteDefinition[] = [
         intervalMs: config.intervalMs,
         activeHoursStart: config.activeHoursStart ?? null,
         activeHoursEnd: config.activeHoursEnd ?? null,
+        cronExpression: config.cronExpression ?? null,
+        timezone: config.timezone ?? null,
         nextRunAt: svc?.nextRunAt ?? null,
         lastRunAt: svc?.lastRunAt ?? null,
         success: true,
@@ -180,46 +196,95 @@ export const ROUTES: RouteDefinition[] = [
     description: "Update the heartbeat schedule configuration.",
     tags: ["heartbeat"],
     requestBody: z.object({
-      enabled: z.boolean().describe("Enable or disable heartbeat"),
-      intervalMs: z.number().describe("Heartbeat interval in ms"),
-      activeHoursStart: z.number().describe("Active hours start (0–23)"),
-      activeHoursEnd: z.number().describe("Active hours end (0–23)"),
+      enabled: z.boolean().optional().describe("Enable or disable heartbeat"),
+      intervalMs: z.number().optional().describe("Heartbeat interval in ms"),
+      activeHoursStart: z
+        .number()
+        .nullable()
+        .optional()
+        .describe("Active hours start (0–23)"),
+      activeHoursEnd: z
+        .number()
+        .nullable()
+        .optional()
+        .describe("Active hours end (0–23)"),
+      cronExpression: z
+        .string()
+        .nullable()
+        .optional()
+        .describe(
+          "Cron expression for heartbeat timing, or null for fixed interval",
+        ),
+      timezone: z
+        .string()
+        .nullable()
+        .optional()
+        .describe("Timezone for cron evaluation"),
     }),
     responseBody: z.object({
       enabled: z.boolean(),
       intervalMs: z.number(),
       activeHoursStart: z.number().nullable(),
       activeHoursEnd: z.number().nullable(),
+      cronExpression: z.string().nullable(),
+      timezone: z.string().nullable(),
       nextRunAt: z.number().nullable(),
       lastRunAt: z.number().nullable(),
       success: z.boolean(),
     }),
     handler: async ({ body = {} }: RouteHandlerArgs) => {
-      const config = getConfig();
-      const heartbeat = { ...config.heartbeat };
-
-      if (typeof body.enabled === "boolean") heartbeat.enabled = body.enabled;
-      if (typeof body.intervalMs === "number")
-        heartbeat.intervalMs = body.intervalMs;
-      if (typeof body.activeHoursStart === "number")
-        heartbeat.activeHoursStart = body.activeHoursStart;
-      if (typeof body.activeHoursEnd === "number")
-        heartbeat.activeHoursEnd = body.activeHoursEnd;
+      // Build a patch containing only the fields the caller actually set.
+      // Writing back the full Zod-defaulted heartbeat object would bake
+      // defaults onto disk, masking later schema changes from the user.
+      // Use "key in body" checks for nullable fields so explicit null clears them.
+      const heartbeatPatch: Record<string, unknown> = {};
+      if ("enabled" in body && typeof body.enabled === "boolean")
+        heartbeatPatch.enabled = body.enabled;
+      if ("intervalMs" in body && typeof body.intervalMs === "number")
+        heartbeatPatch.intervalMs = body.intervalMs;
+      if ("activeHoursStart" in body)
+        heartbeatPatch.activeHoursStart =
+          typeof body.activeHoursStart === "number"
+            ? body.activeHoursStart
+            : null;
+      if ("activeHoursEnd" in body)
+        heartbeatPatch.activeHoursEnd =
+          typeof body.activeHoursEnd === "number" ? body.activeHoursEnd : null;
+      if ("cronExpression" in body)
+        heartbeatPatch.cronExpression =
+          typeof body.cronExpression === "string" ? body.cronExpression : null;
+      if ("timezone" in body)
+        heartbeatPatch.timezone =
+          typeof body.timezone === "string" ? body.timezone : null;
 
       try {
-        saveConfig({ ...config, heartbeat });
-        log.info({ heartbeat }, "Heartbeat config updated");
+        const raw = loadRawConfig();
+        raw.heartbeat = {
+          ...((raw.heartbeat as Record<string, unknown>) ?? {}),
+          ...heartbeatPatch,
+        };
+        saveRawConfig(raw);
+        invalidateConfigCache();
+        log.info({ heartbeat: heartbeatPatch }, "Heartbeat config updated");
       } catch (err) {
         log.error({ err }, "Failed to save heartbeat config");
         throw new InternalError("Failed to save config");
       }
 
+      // Read effective values back through the schema-defaulting loader so
+      // callers that only set a subset of fields still see the resolved
+      // (post-default) shape in the response.
+      const heartbeat = getConfig().heartbeat;
       const svc = HeartbeatService.getInstance();
+      svc?.reconfigure();
+
       return {
         enabled: heartbeat.enabled,
         intervalMs: heartbeat.intervalMs,
         activeHoursStart: heartbeat.activeHoursStart ?? null,
         activeHoursEnd: heartbeat.activeHoursEnd ?? null,
+        cronExpression: heartbeat.cronExpression ?? null,
+        timezone: heartbeat.timezone ?? null,
         nextRunAt: svc?.nextRunAt ?? null,
         lastRunAt: svc?.lastRunAt ?? null,
         success: true,

package/src/runtime/routes/host-app-control-routes.ts

@@ -0,0 +1,134 @@
+/**
+ * Route handler for host app-control result submissions.
+ *
+ * Resolves pending host app-control proxy requests by requestId when the
+ * desktop client returns observation/action results via HTTP. App-control
+ * sessions are per-conversation (not a singleton like host-browser), so we
+ * look up the owning conversation through the pending-interactions tracker
+ * and forward the payload to that conversation's `hostAppControlProxy`.
+ *
+ * Late-delivery tolerance: returns 200 even when no pending interaction
+ * matches (e.g. the conversation was disposed before the client reported
+ * back). The proxy is best-effort — there is no consumer to notify, so a
+ * 4xx would only confuse a client that already executed the action.
+ */
+import { z } from "zod";
+
+import { findConversation } from "../../daemon/conversation-store.js";
+import type {
+  HostAppControlResultPayload,
+  HostAppControlState,
+} from "../../daemon/message-types/host-app-control.js";
+import * as pendingInteractions from "../pending-interactions.js";
+import { BadRequestError } from "./errors.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+
+const VALID_STATES: ReadonlySet<HostAppControlState> = new Set([
+  "running",
+  "missing",
+  "minimized",
+]);
+
+// ---------------------------------------------------------------------------
+// POST /v1/host-app-control-result
+// ---------------------------------------------------------------------------
+
+function handleHostAppControlResult({ body }: RouteHandlerArgs) {
+  if (!body || typeof body !== "object") {
+    throw new BadRequestError("Request body is required");
+  }
+
+  const {
+    requestId,
+    state,
+    pngBase64,
+    windowBounds,
+    executionResult,
+    executionError,
+  } = body as {
+    requestId?: string;
+    state?: string;
+    pngBase64?: string;
+    windowBounds?: { x: number; y: number; width: number; height: number };
+    executionResult?: string;
+    executionError?: string;
+  };
+
+  if (!requestId || typeof requestId !== "string") {
+    throw new BadRequestError("requestId is required");
+  }
+
+  if (!state || !VALID_STATES.has(state as HostAppControlState)) {
+    throw new BadRequestError(
+      "state must be one of: running, missing, minimized",
+    );
+  }
+
+  // Late-delivery tolerance: if the pending interaction is already gone (the
+  // proxy timed out, the conversation was disposed, etc.), accept the post
+  // and move on. There is no consumer left to fail loudly to.
+  const peeked = pendingInteractions.get(requestId);
+  if (!peeked || peeked.kind !== "host_app_control") {
+    return { accepted: true };
+  }
+
+  const interaction = pendingInteractions.resolve(requestId)!;
+  const conversation = findConversation(interaction.conversationId);
+  if (!conversation) {
+    return { accepted: true };
+  }
+
+  const payload: HostAppControlResultPayload = {
+    requestId,
+    state: state as HostAppControlState,
+    ...(pngBase64 !== undefined ? { pngBase64 } : {}),
+    ...(windowBounds !== undefined ? { windowBounds } : {}),
+    ...(executionResult !== undefined ? { executionResult } : {}),
+    ...(executionError !== undefined ? { executionError } : {}),
+  };
+
+  conversation.hostAppControlProxy?.resolve(requestId, payload);
+
+  return { accepted: true };
+}
+
+// ---------------------------------------------------------------------------
+// Route definitions (shared HTTP + IPC)
+// ---------------------------------------------------------------------------
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "host_app_control_result",
+    endpoint: "host-app-control-result",
+    method: "POST",
+    requireGuardian: true,
+    summary: "Submit host app-control result",
+    description:
+      "Resolve a pending host app-control request by requestId. Returns 200 even when no pending interaction matches (late delivery is tolerated).",
+    tags: ["host"],
+    requestBody: z.object({
+      requestId: z.string().describe("Pending app-control request ID"),
+      state: z
+        .enum(["running", "missing", "minimized"])
+        .describe("Lifecycle state of the targeted application"),
+      pngBase64: z
+        .string()
+        .describe("Base64 PNG screenshot of the targeted app window")
+        .optional(),
+      windowBounds: z
+        .object({
+          x: z.number(),
+          y: z.number(),
+          width: z.number(),
+          height: z.number(),
+        })
+        .optional(),
+      executionResult: z.string().optional(),
+      executionError: z.string().optional(),
+    }),
+    responseBody: z.object({
+      accepted: z.boolean(),
+    }),
+    handler: handleHostAppControlResult,
+  },
+];

package/src/runtime/routes/host-bash-routes.ts

@@ -11,6 +11,7 @@ import * as pendingInteractions from "../pending-interactions.js";
 import {
   BadRequestError,
   ConflictError,
+  ForbiddenError,
   NotFoundError,
 } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
@@ -19,7 +20,7 @@ import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 // POST /v1/host-bash-result
 // ---------------------------------------------------------------------------
 
-function handleHostBashResult({ body }: RouteHandlerArgs) {
+function handleHostBashResult({ body, headers }: RouteHandlerArgs) {
   if (!body || typeof body !== "object") {
     throw new BadRequestError("Request body is required");
   }
@@ -36,11 +37,11 @@ function handleHostBashResult({ body }: RouteHandlerArgs) {
     throw new BadRequestError("requestId is required");
   }
 
+  const submittingClientId = headers?.["x-vellum-client-id"]?.trim() || undefined;
+
   const peeked = pendingInteractions.get(requestId);
   if (!peeked) {
-    throw new NotFoundError(
-      "No pending interaction found for this requestId",
-    );
+    throw new NotFoundError("No pending interaction found for this requestId");
   }
 
   if (peeked.kind !== "host_bash") {
@@ -49,9 +50,21 @@ function handleHostBashResult({ body }: RouteHandlerArgs) {
     );
   }
 
-  pendingInteractions.resolve(requestId);
+  const { targetClientId } = peeked;
+  if (targetClientId) {
+    if (!submittingClientId) {
+      throw new BadRequestError(
+        "x-vellum-client-id header is required for targeted host bash requests",
+      );
+    }
+    if (submittingClientId !== targetClientId) {
+      throw new ForbiddenError(
+        `Client "${submittingClientId}" is not the target for this request (expected "${targetClientId}"). The targeted client must submit the result.`,
+      );
+    }
+  }
 
-  HostBashProxy.instance.resolve(requestId, {
+  HostBashProxy.instance.resolveResult(requestId, {
     stdout: stdout ?? "",
     stderr: stderr ?? "",
     exitCode: exitCode ?? null,
@@ -84,6 +97,23 @@ export const ROUTES: RouteDefinition[] = [
     responseBody: z.object({
       accepted: z.boolean(),
     }),
+    additionalResponses: {
+      "400": {
+        description:
+          "x-vellum-client-id header is missing for a targeted host bash request.",
+      },
+      "403": {
+        description:
+          "Submitting client does not match the targeted client for this request.",
+      },
+      "404": {
+        description: "No pending interaction found for the given requestId.",
+      },
+      "409": {
+        description:
+          "Pending interaction exists but is of a different kind (e.g. host_file, host_cu).",
+      },
+    },
     handler: handleHostBashResult,
   },
 ];