@vellumai/assistant 0.11.2 → 0.11.3-staging.2

package/src/runtime/routes/__tests__/plugins-routes.test.ts

@@ -38,6 +38,9 @@
  *     `plugins:list` tag via the canonical resource-sync publisher (enable and
  *     disable emit the SAME invalidation)
  *   - Threads `x-vellum-client-id` into the published event's `originClientId`
+ *   - Pokes the plugin-declared schedule reconcile on a successful toggle (and
+ *     not on a failed one), so the plugin's rows disarm / re-arm immediately
+ *     instead of at the reconciler's next backstop sweep
  *   - A broadcast failure does not fail a successful toggle (the publisher
  *     swallows hub errors)
  *   - Maps `InvalidPluginNameError` → BadRequestError (400)
@@ -311,6 +314,15 @@ mock.module("../../../cli/lib/toggle-plugin.js", () => ({
   enablePlugin: enablePluginSpy,
 }));
 
+// Spy on the plugin-schedule reconcile the toggle handlers poke. The handlers
+// import it lazily at call time, so this mock intercepts the dynamic import
+// and keeps the reconciler's persistence graph out of the test.
+const reconcilePluginSchedulesSpy = mock(() => Promise.resolve());
+
+mock.module("../../../schedule/plugin-schedule-reconciler.js", () => ({
+  reconcilePluginSchedules: reconcilePluginSchedulesSpy,
+}));
+
 // Spy on broadcastMessage so we can assert the sync_changed invalidation the
 // enable/disable handlers emit. The handlers publish through the canonical
 // `publishPluginsChanged` → `publishSyncInvalidation` path (both left real), so
@@ -1883,7 +1895,14 @@ function inspection(
     remoteError: overrides.remoteError ?? null,
     surfaces:
       overrides.surfaces === undefined
-        ? { skills: [], hooks: ["post-model-call"], tools: [] }
+        ? {
+            skills: [],
+            hooks: ["post-model-call"],
+            tools: [],
+            schedules: [
+              { name: "digest", cadence: "0 9 * * *", mode: "execute" },
+            ],
+          }
         : overrides.surfaces,
   };
 }
@@ -1913,6 +1932,26 @@ describe("GET /v1/plugins/:name/inspect", () => {
     expect(inspectSpy.mock.calls[0]?.[0]).toEqual({ name: "level-up" });
   });
 
+  test("the inspect wire schema carries the schedules surface", async () => {
+    // GIVEN an inspection whose surfaces declare a schedule
+    inspectSpy.mockImplementation(async () => inspection());
+    const result = await invokeInspect({ pathParams: { name: "level-up" } });
+
+    // WHEN the handler result is parsed through the route's response schema
+    // (zod strips undeclared keys, so an omission would drop the field)
+    const route = PLUGINS_ROUTES.find(
+      (r) => r.operationId === "plugins_inspect",
+    )!;
+    const parsed = (
+      route.responseBody as { parse: (v: unknown) => PluginInspection }
+    ).parse(result);
+
+    // THEN the declared schedules survive the wire contract
+    expect(parsed.surfaces?.schedules).toEqual([
+      { name: "digest", cadence: "0 9 * * *", mode: "execute" },
+    ]);
+  });
+
   test("a captured marketplace error is returned as 200 with remote-unavailable, not thrown", async () => {
     // GIVEN the catalog was unreachable but a local copy exists, so the lib
     // returns a status rather than throwing
@@ -2139,6 +2178,90 @@ describe("POST /v1/plugins/:name/upgrade", () => {
     });
   });
 
+  test("refuses a concurrent upgrade of the same plugin with ConflictError (409)", async () => {
+    // Two upgrades of one plugin derive the same staging path in this
+    // process, so the second would delete the first's tree mid-swap. It is
+    // refused instead \u2014 the monitor's auto-update sweep and a user clicking
+    // Upgrade can now land at the same moment.
+    let releaseFirst: () => void = () => {};
+    const firstStarted = Promise.withResolvers<void>();
+    upgradeSpy.mockImplementation(async () => {
+      firstStarted.resolve();
+      await new Promise<void>((resolve) => {
+        releaseFirst = resolve;
+      });
+      return upgradeResult();
+    });
+
+    const first = invokeUpgrade({ pathParams: { name: "level-up" } });
+    await firstStarted.promise;
+
+    await expect(
+      invokeUpgrade({ pathParams: { name: "level-up" } }),
+    ).rejects.toBeInstanceOf(ConflictError);
+
+    releaseFirst();
+    await expect(first).resolves.toMatchObject({ outcome: "upgraded" });
+
+    // The guard is released once the first settles, so the next one runs.
+    upgradeSpy.mockImplementation(async () => upgradeResult());
+    await expect(
+      invokeUpgrade({ pathParams: { name: "level-up" } }),
+    ).resolves.toMatchObject({ outcome: "upgraded" });
+  });
+
+  test("a different plugin is not blocked by an in-flight upgrade", async () => {
+    let releaseFirst: () => void = () => {};
+    const firstStarted = Promise.withResolvers<void>();
+    upgradeSpy.mockImplementation(async (opts) => {
+      if (opts.name === "level-up") {
+        firstStarted.resolve();
+        await new Promise<void>((resolve) => {
+          releaseFirst = resolve;
+        });
+      }
+      return upgradeResult({ name: opts.name });
+    });
+
+    const first = invokeUpgrade({ pathParams: { name: "level-up" } });
+    await firstStarted.promise;
+
+    await expect(
+      invokeUpgrade({ pathParams: { name: "other-plugin" } }),
+    ).resolves.toMatchObject({ name: "other-plugin" });
+
+    releaseFirst();
+    await first;
+  });
+
+  test("a dry run neither takes nor respects the in-flight guard", async () => {
+    // Dry runs return before the swap boundary, so they never stage.
+    let releaseFirst: () => void = () => {};
+    const firstStarted = Promise.withResolvers<void>();
+    upgradeSpy.mockImplementation(async (opts) => {
+      if (!opts.dryRun) {
+        firstStarted.resolve();
+        await new Promise<void>((resolve) => {
+          releaseFirst = resolve;
+        });
+      }
+      return upgradeResult();
+    });
+
+    const first = invokeUpgrade({ pathParams: { name: "level-up" } });
+    await firstStarted.promise;
+
+    await expect(
+      invokeUpgrade({
+        pathParams: { name: "level-up" },
+        body: { dryRun: true },
+      }),
+    ).resolves.toMatchObject({ outcome: "upgraded" });
+
+    releaseFirst();
+    await first;
+  });
+
   test("PluginMergeBaselineError \u2192 ConflictError (409)", async () => {
     // A merge strategy whose install-time baseline can't be reconstructed: a
     // well-formed request that isn't actionable in the current state.
@@ -2414,6 +2537,21 @@ function invokeDisable(args: RouteHandlerArgs = {}): { ok: boolean } {
   return disableHandler(args) as { ok: boolean };
 }
 
+/**
+ * Wait for the toggle handlers' fire-and-forget reconcile poke to land. The
+ * lazy `import()` resolves off the microtask queue, so the assertion cannot
+ * run on the handler's synchronous return.
+ */
+async function waitForScheduleReconcile(): Promise<void> {
+  for (let i = 0; i < 50; i++) {
+    if (reconcilePluginSchedulesSpy.mock.calls.length > 0) {
+      return;
+    }
+    await new Promise((resolve) => setTimeout(resolve, 2));
+  }
+  throw new Error("plugin schedule reconcile was never triggered");
+}
+
 /** Assert the spy received exactly one sync_changed carrying `plugins:list`. */
 function expectPluginsListBroadcast(): void {
   expect(broadcastMessageSpy.mock.calls).toHaveLength(1);
@@ -2426,6 +2564,15 @@ describe("POST /v1/plugins/:name/enable", () => {
   beforeEach(() => {
     enablePluginSpy.mockReset();
     broadcastMessageSpy.mockReset();
+    reconcilePluginSchedulesSpy.mockClear();
+  });
+
+  test("reconciles plugin-declared schedules so the plugin's rows re-arm now", async () => {
+    enablePluginSpy.mockImplementation((name) => toggleResult(name, "enable"));
+
+    invokeEnable({ pathParams: { name: "simple-memory" } });
+
+    await waitForScheduleReconcile();
   });
 
   test("enables the plugin and broadcasts sync_changed(plugins:list)", () => {
@@ -2504,6 +2651,31 @@ describe("POST /v1/plugins/:name/disable", () => {
   beforeEach(() => {
     disablePluginSpy.mockReset();
     broadcastMessageSpy.mockReset();
+    reconcilePluginSchedulesSpy.mockClear();
+  });
+
+  test("reconciles plugin-declared schedules so the plugin's rows disarm now", async () => {
+    disablePluginSpy.mockImplementation((name) =>
+      toggleResult(name, "disable"),
+    );
+
+    invokeDisable({ pathParams: { name: "simple-memory" } });
+
+    // Without this poke the rows stay armed until the reconciler's next
+    // backstop sweep.
+    await waitForScheduleReconcile();
+  });
+
+  test("a failed toggle does not poke the schedule reconcile", async () => {
+    disablePluginSpy.mockImplementation((name) => {
+      throw new PluginDirectoryNotFoundError(name);
+    });
+
+    expect(() => invokeDisable({ pathParams: { name: "ghost" } })).toThrow(
+      NotFoundError,
+    );
+    await new Promise((resolve) => setTimeout(resolve, 10));
+    expect(reconcilePluginSchedulesSpy).not.toHaveBeenCalled();
   });
 
   test("disables the plugin and broadcasts sync_changed(plugins:list)", () => {

package/src/runtime/routes/__tests__/question-routes.test.ts

@@ -394,4 +394,68 @@ describe("POST /v1/question-response", () => {
     // Pending interaction left in place.
     expect(pendingInteractions.get("req-legacy-multi")).toBeDefined();
   });
+
+  // A gone interaction must read as 404 for every body shape. Clients treat
+  // 404 as the terminal signal that retires a stale card; a 400 leaves the
+  // card on screen and surfaces a body-validation string the user cannot act
+  // on. The legacy shapes are the ones that matter here: the web client sends
+  // them for every single-question answer, which is the common prompt.
+  test("legacy option against a gone interaction is 404, not a validation 400", async () => {
+    let thrown: unknown;
+    try {
+      await call({
+        body: { requestId: "req-gone", kind: "option", optionId: "yes" },
+      });
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeInstanceOf(NotFoundError);
+  });
+
+  test("legacy free-text against a gone interaction is 404, not a validation 400", async () => {
+    let thrown: unknown;
+    try {
+      await call({
+        body: { requestId: "req-gone", kind: "free_text", text: "maybe" },
+      });
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeInstanceOf(NotFoundError);
+  });
+
+  test("close against a gone interaction is 404", async () => {
+    let thrown: unknown;
+    try {
+      await call({ body: { requestId: "req-gone", kind: "close" } });
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeInstanceOf(NotFoundError);
+  });
+
+  test("legacy option against a confirmation requestId is 404, not a validation 400", async () => {
+    // Cross-talk safety has to hold for the legacy shapes too: the wrong-kind
+    // interaction carries no question metadata for the shim to read.
+    pendingInteractions.register("req-confirm-legacy", {
+      conversationId: "conv-1",
+      kind: "confirmation",
+    });
+
+    let thrown: unknown;
+    try {
+      await call({
+        body: {
+          requestId: "req-confirm-legacy",
+          kind: "option",
+          optionId: "y",
+        },
+      });
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeInstanceOf(NotFoundError);
+    // The confirmation is left intact rather than consumed.
+    expect(pendingInteractions.get("req-confirm-legacy")).toBeDefined();
+  });
 });

package/src/runtime/routes/__tests__/retrospective-routes.test.ts

@@ -413,6 +413,26 @@ describe("getRetrospectiveConfig handler", () => {
     expect(result.success).toBe(true);
   });
 
+  test("available but not enabled when only the retrospective switch is off", async () => {
+    writeFileSync(
+      configPath,
+      JSON.stringify(
+        { memory: { retrospective: { enabled: false } } },
+        null,
+        2,
+      ) + "\n",
+    );
+
+    const handler = findHandler("getRetrospectiveConfig");
+    const result = (await handler({})) as ConfigResponse;
+
+    // `available` stays true so the Settings row still renders. It reads
+    // "Paused" rather than disappearing as it would with memory off.
+    expect(result.available).toBe(true);
+    expect(result.enabled).toBe(false);
+    expect(result.success).toBe(true);
+  });
+
   test("stays available when memory v2 is disabled (retrospectives do not gate on v2)", async () => {
     writeFileSync(
       configPath,

package/src/runtime/routes/__tests__/skill-history-route.test.ts

@@ -0,0 +1,116 @@
+/**
+ * Tests for the `getSkillHistory` route's current-resource boundary.
+ *
+ * The service layer reads retained git history, which outlives the skill it
+ * describes: a deleted skill's commits stay in the workspace repository
+ * forever. The route is therefore the only place that can decide whether an id
+ * still names something, and it must reach the same answer as the sibling file
+ * routes rather than serving history for a resource the rest of the API
+ * reports as gone.
+ *
+ * Both collaborators are mocked, because what is under test is the ordering
+ * between them: the existence check has to gate the history read, not run
+ * alongside it.
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+const skillExistsLocallyMock = mock((_id: string): boolean => true);
+const getSkillHistoryMock = mock(async (_id: string, _opts?: unknown) => ({
+  skillId: _id,
+  revisions: [{ id: "abc1234", changedAt: "", files: ["SKILL.md"], diff: "" }],
+  truncatedByCompaction: false,
+}));
+
+mock.module("../../../daemon/handlers/skills.js", () => ({
+  skillExistsLocally: skillExistsLocallyMock,
+  // The route module imports the whole handler surface; the rest is unused
+  // here and only needs to exist.
+  checkSkillUpdates: mock(),
+  configureSkill: mock(),
+  createSkill: mock(),
+  disableSkill: mock(),
+  draftSkill: mock(),
+  enableSkill: mock(),
+  getSkill: mock(),
+  getSkillFileContent: mock(),
+  getSkillFiles: mock(),
+  getSkillLocalDetail: mock(),
+  inspectSkill: mock(),
+  installSkill: mock(),
+  listSkills: mock(),
+  listSkillsFiltered: mock(),
+  searchSkills: mock(),
+  uninstallSkill: mock(),
+  updateSkill: mock(),
+}));
+
+mock.module("../../../skills/skill-history.js", () => ({
+  getSkillHistory: getSkillHistoryMock,
+}));
+
+const { ROUTES } = await import("../skills-routes.js");
+
+const handler = ROUTES.find(
+  (r) => r.operationId === "getSkillHistory",
+)!.handler;
+
+beforeEach(() => {
+  skillExistsLocallyMock.mockClear();
+  getSkillHistoryMock.mockClear();
+  skillExistsLocallyMock.mockImplementation(() => true);
+});
+
+describe("getSkillHistory route", () => {
+  test("returns history for a skill that currently exists", async () => {
+    const result = (await handler({
+      pathParams: { id: "release-triage" },
+    })) as {
+      revisions: unknown[];
+    };
+
+    expect(result.revisions).toHaveLength(1);
+    expect(getSkillHistoryMock).toHaveBeenCalledTimes(1);
+  });
+
+  test("404s for a deleted skill whose commits are still in the repository", async () => {
+    // The skill is gone from the resolver, but git would still answer.
+    skillExistsLocallyMock.mockImplementation(() => false);
+
+    await expect(
+      handler({ pathParams: { id: "release-triage" } }),
+    ).rejects.toThrow(/not found/i);
+  });
+
+  test("does not read history at all when the skill is gone", async () => {
+    skillExistsLocallyMock.mockImplementation(() => false);
+
+    await Promise.resolve(
+      handler({ pathParams: { id: "release-triage" } }),
+    ).catch(() => {});
+
+    // Ordering is the point: a check that ran after the read would still
+    // reject, but would have spent the git traversal to do it.
+    expect(getSkillHistoryMock).not.toHaveBeenCalled();
+  });
+
+  test("rejects a malformed id as the caller's error, not a server fault", async () => {
+    getSkillHistoryMock.mockImplementation(() => {
+      throw new Error("Invalid skill id: contains a path separator");
+    });
+
+    await expect(handler({ pathParams: { id: "bad" } })).rejects.toMatchObject({
+      statusCode: 400,
+    });
+  });
+
+  test("surfaces an unexpected service failure as a server error", async () => {
+    getSkillHistoryMock.mockImplementation(() => {
+      throw new Error("git exploded");
+    });
+
+    await expect(handler({ pathParams: { id: "ok" } })).rejects.toMatchObject({
+      statusCode: 500,
+    });
+  });
+});

package/src/runtime/routes/__tests__/wake-conversation-routes.test.ts

@@ -2,8 +2,10 @@
  * Asserts the `wake_conversation` route elevates trust from the caller's
  * verified principal type, never the request body: a `local` (CLI/IPC) caller
  * runs the woken turn as a non-interactive guardian (clientless + guardian
- * trustContext) and may attribute cost to a body-supplied `cronRunId`; a remote
- * `actor` stays `unknown`/interactive and its body `cronRunId` is ignored.
+ * trustContext) and may attribute cost to a body-supplied `cronRunId` and run
+ * on a body-supplied schedule's pinned inference profile; a remote `actor`
+ * stays `unknown`/interactive and its body `cronRunId` and `scheduleId` are
+ * ignored.
  */
 
 import { describe, expect, mock, test } from "bun:test";
@@ -13,6 +15,7 @@ interface CapturedWake {
   hint: string;
   trustContext?: { sourceChannel: string; trustClass: string };
   cronRunId?: string;
+  forceOverrideProfile?: string;
   clientless?: boolean;
   persistTriggerAsEvent?: boolean;
   untrustedOutput?: { content: string; source: string };
@@ -25,6 +28,14 @@ mock.module("../../agent-wake.js", () => ({
   },
 }));
 
+const schedules = new Map<string, { inferenceProfile: string | null }>([
+  ["sched-pinned", { inferenceProfile: "profile-cheap" }],
+  ["sched-unpinned", { inferenceProfile: null }],
+]);
+mock.module("../../../schedule/schedule-store.js", () => ({
+  getSchedule: (id: string) => schedules.get(id) ?? null,
+}));
+
 import { createConversation } from "../../../persistence/conversation-crud.js";
 import { initializeDb } from "../../../persistence/db-init.js";
 import { ROUTES } from "../wake-conversation-routes.js";
@@ -85,6 +96,53 @@ describe("wake_conversation principal-gated elevation", () => {
   });
 });
 
+describe("wake_conversation schedule profile pin", () => {
+  test("local principal → woken turn runs on the schedule's pinned profile", async () => {
+    wakeCalls.length = 0;
+    const conversationId = makeConversation();
+    await handler({
+      body: { conversationId, hint: "poll result", scheduleId: "sched-pinned" },
+      headers: { "x-vellum-principal-type": "local" },
+    });
+    expect(wakeCalls[0].forceOverrideProfile).toBe("profile-cheap");
+  });
+
+  test("schedule with no pinned profile leaves resolution unchanged", async () => {
+    wakeCalls.length = 0;
+    const conversationId = makeConversation();
+    await handler({
+      body: {
+        conversationId,
+        hint: "poll result",
+        scheduleId: "sched-unpinned",
+      },
+      headers: { "x-vellum-principal-type": "local" },
+    });
+    expect(wakeCalls[0].forceOverrideProfile).toBeUndefined();
+  });
+
+  test("unknown scheduleId resolves as an ordinary wake", async () => {
+    wakeCalls.length = 0;
+    const conversationId = makeConversation();
+    const result = await handler({
+      body: { conversationId, hint: "poll result", scheduleId: "sched-gone" },
+      headers: { "x-vellum-principal-type": "local" },
+    });
+    expect(result).toEqual({ invoked: true, producedToolCalls: false });
+    expect(wakeCalls[0].forceOverrideProfile).toBeUndefined();
+  });
+
+  test("actor principal → body scheduleId is ignored", async () => {
+    wakeCalls.length = 0;
+    const conversationId = makeConversation();
+    await handler({
+      body: { conversationId, hint: "poll result", scheduleId: "sched-pinned" },
+      headers: { "x-vellum-principal-type": "actor" },
+    });
+    expect(wakeCalls[0].forceOverrideProfile).toBeUndefined();
+  });
+});
+
 describe("wake_conversation fencing", () => {
   test("persist + externalContent fence untrusted data, keep hint trusted", async () => {
     wakeCalls.length = 0;

package/src/runtime/routes/archive-utils.ts

@@ -3,7 +3,10 @@
  * log export and profiler export routes.
  */
 
-import { spawnSync } from "node:child_process";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
 
 /** Maximum compressed archive size (50 MB). */
 export const MAX_ARCHIVE_BYTES = 50 * 1024 * 1024;
@@ -13,19 +16,20 @@ export const MAX_ARCHIVE_BYTES = 50 * 1024 * 1024;
  * Returns the Buffer on success, or `undefined` if the archive exceeds
  * the size limit or tar otherwise fails.
  */
-export function createTarGz(
+export async function createTarGz(
   staging: string,
   maxBytes: number = MAX_ARCHIVE_BYTES,
-): ArrayBuffer | undefined {
-  const proc = spawnSync("tar", ["czf", "-", "-C", staging, "."], {
-    maxBuffer: maxBytes,
-    timeout: 30_000,
-  });
-  if (proc.status !== 0) {
+): Promise<ArrayBuffer | undefined> {
+  try {
+    // Exceeding maxBuffer rejects, which maps to the undefined failure return.
+    const { stdout } = await execFileAsync(
+      "tar",
+      ["czf", "-", "-C", staging, "."],
+      { maxBuffer: maxBytes, timeout: 30_000, encoding: "buffer" },
+    );
+    const buf = Buffer.isBuffer(stdout) ? stdout : Buffer.from(stdout);
+    return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
+  } catch {
     return undefined;
   }
-  const buf = Buffer.isBuffer(proc.stdout)
-    ? proc.stdout
-    : Buffer.from(proc.stdout);
-  return buf.buffer.slice(buf.byteOffset, buf.byteOffset + buf.byteLength);
 }

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

@@ -238,7 +238,7 @@ async function handleMultipartUpload(
 
   const bytes = new Uint8Array(await file.arrayBuffer());
 
-  const attachment = uploadAttachmentFromBytes(filename, mimeType, bytes);
+  const attachment = await uploadAttachmentFromBytes(filename, mimeType, bytes);
   return attachmentPayload(attachment);
 }
 
@@ -248,7 +248,7 @@ async function handleMultipartUpload(
  *
  * See `handleMultipartUpload` for `gatewayTrustedSource` semantics.
  */
-function handleOctetStreamUpload(
+async function handleOctetStreamUpload(
   rawBody: Uint8Array,
   headers: Record<string, string>,
   queryParams: Record<string, string>,
@@ -287,7 +287,11 @@ function handleOctetStreamUpload(
     throw new UnsupportedMediaTypeError(validation.error);
   }
 
-  const attachment = uploadAttachmentFromBytes(filename, mimeType, rawBody);
+  const attachment = await uploadAttachmentFromBytes(
+    filename,
+    mimeType,
+    rawBody,
+  );
   return attachmentPayload(attachment);
 }
 
@@ -296,7 +300,7 @@ function handleOctetStreamUpload(
  *
  * See `handleMultipartUpload` for `gatewayTrustedSource` semantics.
  */
-function handleJsonUpload(
+async function handleJsonUpload(
   body: Record<string, unknown>,
   rawBody: Uint8Array | undefined,
   gatewayTrustedSource: boolean,
@@ -369,7 +373,10 @@ function handleJsonUpload(
       // non-HEIF files (e.g. large videos) from being read into memory.
       try {
         if (isHeifImage(readFileHead(destPath, 12))) {
-          const norm = normalizeImageBytes(mimeType, readFileSync(destPath));
+          const norm = await normalizeImageBytes(
+            mimeType,
+            readFileSync(destPath),
+          );
           if (
             norm.converted &&
             norm.bytes.length <= MAX_FILE_BACKED_UPLOAD_BYTES
@@ -407,7 +414,7 @@ function handleJsonUpload(
     }
 
     try {
-      attachment = uploadAttachment(
+      attachment = await uploadAttachment(
         filename,
         mimeType,
         data,

package/src/runtime/routes/canned-reply-release.ts

@@ -0,0 +1,54 @@
+/**
+ * Deferred release for the canned-reply routes (canned first greeting, unknown
+ * slash command).
+ *
+ * These routes answer without an agent loop, so they hold the processing lock
+ * themselves and are the only thing that will ever clear it. They publish their
+ * client events on the next tick so the HTTP 202 reaches the client first and
+ * its `serverToLocalConversationMap` is populated before any SSE arrives, and
+ * they release only after that burst so the next queued message cannot start
+ * processing ahead of the reply the client is still being told about.
+ *
+ * The release therefore has to be unconditional: a throw from any broadcast in
+ * the burst would otherwise latch the conversation "processing" with no agent
+ * loop, no `finally`, and no later path left to clear it, so every subsequent
+ * send is queued behind an idle conversation for the life of the daemon.
+ */
+
+import type { Conversation } from "../../daemon/conversation.js";
+import { getLogger } from "../../util/logger.js";
+
+const log = getLogger("canned-reply-release");
+
+/** The conversation surface {@link scheduleCannedReplyRelease} touches. */
+export type CannedReplyReleaseTarget = Pick<
+  Conversation,
+  "setProcessing" | "kickDrainQueue"
+>;
+
+export function scheduleCannedReplyRelease(params: {
+  conversation: CannedReplyReleaseTarget;
+  /** Names the release site in drain logs (e.g. `"canned_greeting"`). */
+  origin: string;
+  /** The deferred client event burst. Runs before the release. */
+  emit: () => void;
+  /** Optional work that only makes sense once the lock is free. */
+  afterRelease?: () => void;
+}): void {
+  const { conversation, origin, emit, afterRelease } = params;
+  setTimeout(() => {
+    try {
+      emit();
+    } catch (err) {
+      // Swallowed rather than rethrown: this runs from a timer with no caller
+      // left to handle it, so an escaping error is an uncaught exception in
+      // the daemon process. The reply is already persisted, and clients
+      // reconcile a missed event burst on their next fetch.
+      log.error({ err, origin }, "Canned reply event burst failed");
+    } finally {
+      conversation.setProcessing(false);
+      void conversation.kickDrainQueue("loop_complete", origin);
+    }
+    afterRelease?.();
+  }, 0);
+}