@vellumai/assistant 0.8.8-dev.202606071441.cfe7f13 → 0.8.8-dev.202606071734.db66b83

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.8.8-dev.202606071441.cfe7f13",
+  "version": "0.8.8-dev.202606071734.db66b83",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/conversation-agent-loop.test.ts

@@ -810,7 +810,7 @@ describe("session-agent-loop", () => {
       });
     });
 
-    test("freezes the timestamp and client timezone snapshot on the conversation, not the options bag", async () => {
+    test("freezes the client timezone snapshot on the conversation, not the options bag", async () => {
       mockUiConfig = {
         userTimezone: "US/Eastern",
         detectedTimezone: "US/Central",
@@ -827,24 +827,19 @@ describe("session-agent-loop", () => {
 
       await runAgentLoopImpl(ctx, "hello", "msg-1", () => {});
 
-      // The loop resolves the effective timezone to format the turn timestamp.
-      expect(formatTurnTimestampMock).toHaveBeenCalledWith({
-        timeZone: "America/New_York",
-      });
-      // The formatted timestamp, the turn-start client timezone, and the
-      // long-absence gap are frozen on the conversation as
-      // `currentTurnTemporalSnapshot` so every post-compaction re-injection
-      // reuses the same instant; the live `clientTimezone` would otherwise be
-      // clobbered mid-turn.
+      // The turn-start client timezone and the long-absence gap are frozen on
+      // the conversation as `currentTurnTemporalSnapshot`; the live
+      // `clientTimezone` would otherwise be clobbered mid-turn. `current_time`
+      // is not frozen — it is computed fresh at each injection inside
+      // `applyRuntimeInjections`.
       expect(ctx.currentTurnTemporalSnapshot).toEqual({
-        timestamp: "2026-01-01 (Thursday) 00:00:00 +00:00 (UTC)",
         clientTimezone: "America/Los_Angeles",
         timeSinceLastMessage: null,
       });
-      // Neither the timestamp, the timezones, nor the long-absence gap are
-      // threaded through the options bag — `applyRuntimeInjections` sources the
-      // timestamp, client timezone, and gap from the snapshot and the config
-      // timezones from config (`ui.userTimezone`, `ui.detectedTimezone`).
+      // Neither the timezones nor the long-absence gap are threaded through the
+      // options bag — `applyRuntimeInjections` sources the client timezone and
+      // gap from the snapshot and the config timezones from config
+      // (`ui.userTimezone`, `ui.detectedTimezone`).
       const injectionOptions = applyRuntimeInjectionsMock.mock.calls[0]?.[1];
       expect(injectionOptions).not.toHaveProperty("timestamp");
       expect(injectionOptions).not.toHaveProperty("clientTimezone");

package/src/__tests__/conversation-runtime-assembly.test.ts

@@ -48,6 +48,18 @@ mock.module("../memory/pkb/pkb-search.js", () => ({
   },
 }));
 
+// `applyRuntimeInjections` computes the `<turn_context>` `current_time` live via
+// `formatTurnTimestamp`; pin it so the rendered block matches the deterministic
+// `buildUnifiedTurnContextBlock` expectations below. The rest of the module
+// (timezone canonicalization/resolution) keeps its real behavior.
+const FIXED_TURN_TIMESTAMP = "2026-04-02T12:00:00Z";
+const realDateContextForAssemblyTest =
+  await import("../daemon/date-context.js");
+mock.module("../daemon/date-context.js", () => ({
+  ...realDateContextForAssemblyTest,
+  formatTurnTimestamp: () => FIXED_TURN_TIMESTAMP,
+}));
+
 import {
   clearConversations,
   setConversation,
@@ -148,7 +160,6 @@ function seedActiveSurfaceConversation(
   channelCapabilities?: ChannelCapabilities,
   commandIntent?: { type: string; payload?: string; languageCode?: string },
   currentTurnTemporalSnapshot?: {
-    timestamp: string;
     clientTimezone: string | null;
   },
 ): void {
@@ -886,7 +897,6 @@ describe("applyRuntimeInjections — injection mode", () => {
       channelCapabilities,
       { type: "start" },
       {
-        timestamp: "2026-03-04 (Tuesday) 12:00:00 +00:00 (UTC)",
         clientTimezone: null,
       },
     );
@@ -1806,20 +1816,19 @@ describe("applyRuntimeInjections with unifiedTurnContext", () => {
     },
   ];
 
-  const sampleTimestamp = "2026-04-02T12:00:00Z";
   const sampleOptions = {
     interfaceName: "macos",
   };
-  // The block reflects both the options-bag interface and the timestamp the
-  // loop freezes on the conversation; assembly merges the two.
+  // The block reflects the options-bag interface and the `current_time` the
+  // injector computes live (pinned to `FIXED_TURN_TIMESTAMP` for this suite).
   const sampleBlock = buildUnifiedTurnContextBlock({
-    timestamp: sampleTimestamp,
+    timestamp: FIXED_TURN_TIMESTAMP,
     ...sampleOptions,
   });
 
   // Seed the live fallback conversation with the per-turn temporal snapshot
-  // (so `applyRuntimeInjections` sources the `<turn_context>` timestamp from it)
-  // and the turn interface context (so it sources the interface label to match
+  // (its presence gates the `<turn_context>` block) and the turn interface
+  // context (so the injector sources the interface label to match
   // `sampleOptions.interfaceName`).
   function seedTemporalSnapshot(): void {
     setConversation("runtime-assembly-fallback", {
@@ -1829,7 +1838,6 @@ describe("applyRuntimeInjections with unifiedTurnContext", () => {
       workspaceTopLevelDirty: false,
       surfaceState: new Map(),
       currentTurnTemporalSnapshot: {
-        timestamp: sampleTimestamp,
         clientTimezone: null,
       },
       currentTurnInterfaceContext: {
@@ -1910,13 +1918,10 @@ describe("applyRuntimeInjections timezone resolution", () => {
     { role: "user", content: [{ type: "text", text: "Hello there" }] },
   ];
 
-  const sampleTimestamp =
-    "2026-04-02 (Thursday) 08:00:00 -04:00 (America/New_York)";
-
   // Seed the live fallback conversation with the per-turn temporal snapshot the
   // loop freezes after memory retrieval. `applyRuntimeInjections` sources the
-  // `<turn_context>` timestamp, the client timezone, and the long-absence gap
-  // from it, so the turn-context block only emits when this snapshot is present.
+  // client timezone and the long-absence gap from it, so the turn-context block
+  // only emits when this snapshot is present.
   function seedTemporalSnapshot(
     clientTimezone: string | null,
     timeSinceLastMessage: string | null = null,
@@ -1928,7 +1933,6 @@ describe("applyRuntimeInjections timezone resolution", () => {
       workspaceTopLevelDirty: false,
       surfaceState: new Map(),
       currentTurnTemporalSnapshot: {
-        timestamp: sampleTimestamp,
         clientTimezone,
         timeSinceLastMessage,
       },
@@ -2058,20 +2062,19 @@ describe("applyRuntimeInjections blocks.unifiedTurnContext", () => {
     },
   ];
 
-  const sampleTimestamp = "2026-04-02T12:00:00Z";
   const sampleOptions = {
     interfaceName: "macos",
   };
-  // The block reflects both the options-bag interface and the timestamp the
-  // loop freezes on the conversation; assembly merges the two.
+  // The block reflects the options-bag interface and the `current_time` the
+  // injector computes live (pinned to `FIXED_TURN_TIMESTAMP` for this suite).
   const sampleBlock = buildUnifiedTurnContextBlock({
-    timestamp: sampleTimestamp,
+    timestamp: FIXED_TURN_TIMESTAMP,
     ...sampleOptions,
   });
 
   // Seed the live fallback conversation with the per-turn temporal snapshot
-  // (so `applyRuntimeInjections` sources the `<turn_context>` timestamp from it)
-  // and the turn interface context (so it sources the interface label to match
+  // (its presence gates the `<turn_context>` block) and the turn interface
+  // context (so the injector sources the interface label to match
   // `sampleOptions.interfaceName`).
   function seedTemporalSnapshot(): void {
     setConversation("runtime-assembly-fallback", {
@@ -2081,7 +2084,6 @@ describe("applyRuntimeInjections blocks.unifiedTurnContext", () => {
       workspaceTopLevelDirty: false,
       surfaceState: new Map(),
       currentTurnTemporalSnapshot: {
-        timestamp: sampleTimestamp,
         clientTimezone: null,
       },
       currentTurnInterfaceContext: {

package/src/__tests__/injector-chain.test.ts

@@ -38,6 +38,17 @@ mock.module("../config/loader.js", () => ({
   },
 }));
 
+// `applyRuntimeInjections` computes the `<turn_context>` `current_time` live
+// via `formatTurnTimestamp`; pin it so the rendered block matches the
+// deterministic `buildUnifiedTurnContextBlock` expectations below. The rest of
+// the module (timezone canonicalization/resolution) keeps its real behavior.
+const FIXED_TURN_TIMESTAMP = "2026-04-22";
+const realDateContext = await import("../daemon/date-context.js");
+mock.module("../daemon/date-context.js", () => ({
+  ...realDateContext,
+  formatTurnTimestamp: () => FIXED_TURN_TIMESTAMP,
+}));
+
 const {
   applyRuntimeInjections,
   buildSubagentStatusBlock,
@@ -130,7 +141,6 @@ function clearNowScratchpad(): void {
 function seedWorkspaceContext(
   text: string,
   currentTurnTemporalSnapshot?: {
-    timestamp: string;
     clientTimezone: string | null;
   },
   interfaceName?: string,
@@ -150,17 +160,18 @@ function seedWorkspaceContext(
   } as never);
 }
 
-// `applyRuntimeInjections` sources the `<turn_context>` timestamp from the live
-// conversation's frozen `currentTurnTemporalSnapshot`. Tests that drive the
-// chain without a caller-supplied `turnContext` fall back to the
-// runtime-assembly fallback conversation, so seed the snapshot there.
-function seedFallbackTemporalSnapshot(timestamp: string): void {
+// `applyRuntimeInjections` gates the `<turn_context>` block on the live
+// conversation's frozen `currentTurnTemporalSnapshot` (computing `current_time`
+// live). Tests that drive the chain without a caller-supplied `turnContext`
+// fall back to the runtime-assembly fallback conversation, so seed the snapshot
+// there.
+function seedFallbackTemporalSnapshot(): void {
   setConversation("runtime-assembly-fallback", {
     conversationId: "runtime-assembly-fallback",
     workingDir: "/sandbox",
     workspaceTopLevelContext: "",
     workspaceTopLevelDirty: false,
-    currentTurnTemporalSnapshot: { timestamp, clientTimezone: null },
+    currentTurnTemporalSnapshot: { clientTimezone: null },
   } as never);
 }
 
@@ -387,10 +398,10 @@ describe("injector chain", () => {
     // unified-turn-context injector resolves the interface label to the `web`
     // default.
     const synthesizedBlock = buildUnifiedTurnContextBlock({
-      timestamp: "synthesized",
+      timestamp: FIXED_TURN_TIMESTAMP,
       interfaceName: "web",
     });
-    seedFallbackTemporalSnapshot("synthesized");
+    seedFallbackTemporalSnapshot();
     const result = await applyRuntimeInjections(runMessages, {});
 
     // The unified-turn-context injector fires even without a caller-supplied
@@ -429,9 +440,9 @@ describe("injector chain", () => {
     const workspaceText =
       "<workspace>\nRoot: /sandbox\nDirectories: src, lib\n</workspace>";
     // The interface label flows through the options bag; the timestamp is
-    // frozen on the conversation's temporal snapshot.
+    // computed live at injection time.
     const unifiedTurn = buildUnifiedTurnContextBlock({
-      timestamp: "2026-04-22",
+      timestamp: FIXED_TURN_TIMESTAMP,
       interfaceName: "macos",
     });
     // A completed child renders deterministically (no elapsed clock), so the
@@ -440,11 +451,7 @@ describe("injector chain", () => {
     seedSubagentChild(TEST_CONVERSATION_ID, subagentChild);
     const subagentBlock = buildSubagentStatusBlock([subagentChild])!;
 
-    seedWorkspaceContext(
-      workspaceText,
-      { timestamp: "2026-04-22", clientTimezone: null },
-      "macos",
-    );
+    seedWorkspaceContext(workspaceText, { clientTimezone: null }, "macos");
     const result = await applyRuntimeInjections(runMessages, {
       turnContext: makeTurnContext(),
     });
@@ -571,10 +578,10 @@ describe("injector chain", () => {
     // `web` default. A live child subagent is seeded so the subagent-status
     // injector has a block to skip.
     const minimalTurnBlock = buildUnifiedTurnContextBlock({
-      timestamp: "2026-04-22",
+      timestamp: FIXED_TURN_TIMESTAMP,
       interfaceName: "web",
     });
-    seedWorkspaceContext("", { timestamp: "2026-04-22", clientTimezone: null });
+    seedWorkspaceContext("", { clientTimezone: null });
     seedSubagentChild(
       TEST_CONVERSATION_ID,
       makeSubagentState("sub-1", "worker", "running"),

package/src/__tests__/injector-disk-pressure.test.ts

@@ -1,7 +1,19 @@
-import { beforeEach, describe, expect, test } from "bun:test";
+import { beforeEach, describe, expect, mock, test } from "bun:test";
 
 import { eq } from "drizzle-orm";
 
+import * as dateContext from "../daemon/date-context.js";
+
+// `applyRuntimeInjections` computes the `<turn_context>` `current_time` live via
+// `formatTurnTimestamp`; pin it so the rendered block matches the deterministic
+// `buildUnifiedTurnContextBlock` expectation below. The rest of the module
+// (timezone canonicalization/resolution) keeps its real behavior.
+const FIXED_TURN_TIMESTAMP = "2026-04-02T12:00:00Z";
+mock.module("../daemon/date-context.js", () => ({
+  ...dateContext,
+  formatTurnTimestamp: () => FIXED_TURN_TIMESTAMP,
+}));
+
 import {
   clearConversations,
   setConversation,
@@ -84,7 +96,6 @@ let liveConversation: {
   channelCapabilities?: ChannelCapabilities;
   trustContext?: { trustClass: string };
   currentTurnTemporalSnapshot?: {
-    timestamp: string;
     clientTimezone: string | null;
   };
   currentTurnInterfaceContext?: {
@@ -110,12 +121,11 @@ function resetLiveConversation(): void {
   };
 }
 
-// `applyRuntimeInjections` sources the `<turn_context>` timestamp from the live
-// conversation's frozen temporal snapshot, so seed it for tests that assert the
-// unified-turn-context block is present.
-function seedTemporalSnapshot(timestamp: string): void {
+// `applyRuntimeInjections` gates the `<turn_context>` block on the live
+// conversation's frozen temporal snapshot (computing `current_time` live), so
+// seed it for tests that assert the unified-turn-context block is present.
+function seedTemporalSnapshot(): void {
   liveConversation.currentTurnTemporalSnapshot = {
-    timestamp,
     clientTimezone: null,
   };
   setConversation(TEST_CONVERSATION_ID, liveConversation as never);
@@ -240,7 +250,7 @@ Do not work on unrelated tasks until enough space is freed to clear the lock or
 
     seedWorkspaceContext(workspace);
     seedDiskPressure(true);
-    seedTemporalSnapshot("2026-04-02T12:00:00Z");
+    seedTemporalSnapshot();
     const result = await applyRuntimeInjections(runMessages, {
       turnContext: makeContext(),
     });
@@ -264,7 +274,7 @@ Do not work on unrelated tasks until enough space is freed to clear the lock or
       interfaceName: "macos",
     });
     seedDiskPressure(true);
-    seedTemporalSnapshot("2026-04-02T12:00:00Z");
+    seedTemporalSnapshot();
     const result = await applyRuntimeInjections(
       [{ role: "user", content: [{ type: "text", text: "status" }] }],
       {

package/src/__tests__/plugin-api-shim.test.ts

@@ -34,19 +34,19 @@ describe("buildShimSource", () => {
   test("emits a globalThis trampoline + one binding per export", () => {
     const source = buildShimSource(
       ["foo", "bar"],
-      Symbol.for("vellum.plugin-api.v1"),
+      Symbol.for("vellum.plugin-api"),
     );
     expect(source).toBe(
-      `const api = globalThis[Symbol.for("vellum.plugin-api.v1")];\n` +
+      `const api = globalThis[Symbol.for("vellum.plugin-api")];\n` +
         `export const foo = api.foo;\n` +
         `export const bar = api.bar;\n`,
     );
   });
 
   test("handles an empty export list (today's types-only surface)", () => {
-    const source = buildShimSource([], Symbol.for("vellum.plugin-api.v1"));
+    const source = buildShimSource([], Symbol.for("vellum.plugin-api"));
     expect(source).toBe(
-      `const api = globalThis[Symbol.for("vellum.plugin-api.v1")];\n`,
+      `const api = globalThis[Symbol.for("vellum.plugin-api")];\n`,
     );
   });
 });

package/src/agent/loop.ts

@@ -834,6 +834,12 @@ export class AgentLoop {
     let lastLlmCallTime = 0;
     let exitReason: ExitReason | null = null;
     let appendedNewMessages = false;
+    // Armed at the end of a tool-use iteration so the budget gate runs at the
+    // top of the NEXT iteration — before that iteration's provider call —
+    // instead of after the current one. The first call and stop-hook re-query
+    // continues re-enter without arming, so the gate fires on exactly the same
+    // occasions as the prior post-call placement.
+    let budgetGateArmed = false;
     const rlog = requestId ? log.child({ requestId }) : log;
 
     // Resolve the inference-profile override that applies right now. The
@@ -874,6 +880,89 @@ export class AgentLoop {
       let toolUseBlocks: Extract<ContentBlock, { type: "tool_use" }>[] = [];
 
       try {
+        // Per-turn pipeline context. Real call sites thread a full
+        // `turnContext` into `run()` and it is used directly; standalone
+        // unit-test instantiations that never plumb a context through fall
+        // back to a synthesized placeholder scoped to the tool-use iteration.
+        const turnCtx =
+          turnContext ?? buildLoopTurnContext(requestId, toolUseTurns);
+
+        // ── Pre-call budget gate ─────────────────────────────────────
+        // When overflow recovery is enabled, estimate the running context
+        // size as it approaches the preflight budget before issuing the
+        // provider call. With `compactInPlace` the loop compacts in place and
+        // proceeds with the call; otherwise it yields (`exitReason =
+        // "budget"`) so the orchestrator can recover before the call risks a
+        // hard context-too-large rejection. Keyed off the loop's own
+        // `history.length` (the messages actually in context this turn,
+        // including tool iterations) rather than the durable conversation
+        // count. Gated on `budgetGateArmed` so it skips the first call and
+        // stop-hook re-query continues.
+        if (budgetGateArmed) {
+          budgetGateArmed = false;
+          const contextWindow = resolveContextWindow?.();
+          if (contextWindow?.overflowRecovery.enabled) {
+            const { maxInputTokens, overflowRecovery } = contextWindow;
+            const safetyMargin =
+              history.length > LONG_HISTORY_MESSAGE_THRESHOLD
+                ? Math.max(
+                    overflowRecovery.safetyMarginRatio,
+                    LONG_HISTORY_SAFETY_MARGIN_FLOOR,
+                  )
+                : overflowRecovery.safetyMarginRatio;
+            const preflightBudget = Math.floor(
+              maxInputTokens * (1 - safetyMargin),
+            );
+            const midLoopThreshold =
+              preflightBudget * MID_LOOP_YIELD_THRESHOLD_RATIO;
+            const estimated = this.estimateTokens(history);
+            if (estimated > midLoopThreshold) {
+              let compactedInPlace = false;
+              if (compactInPlace) {
+                rlog.info(
+                  {
+                    phase: "mid-loop",
+                    estimated,
+                    threshold: midLoopThreshold,
+                  },
+                  "Token estimate approaching budget — compacting in place",
+                );
+                const compacted = await this.compact(
+                  history,
+                  turnCtx,
+                  contextWindowManager,
+                  signal,
+                  onEvent,
+                  resolveEffectiveOverrideProfile() ?? null,
+                  isNonInteractive,
+                  modelProfile,
+                  actorContext,
+                );
+                if (compacted) {
+                  history = compacted;
+                  // The compacted, re-injected array is the new base; output
+                  // produced after this point is what the orchestrator
+                  // persists.
+                  newMessagesStart = history.length;
+                  compactedInPlace = true;
+                }
+              }
+              if (!compactedInPlace) {
+                rlog.warn(
+                  {
+                    phase: "mid-loop",
+                    estimated,
+                    threshold: midLoopThreshold,
+                  },
+                  "Token estimate approaching budget — yielding for compaction",
+                );
+                exitReason = "budget";
+                break;
+              }
+            }
+          }
+        }
+
         // Resolve tools for this turn: use the dynamic resolver if provided,
         // otherwise fall back to the static tool list.
         const currentTools = this.resolveTools
@@ -1095,13 +1184,6 @@ export class AgentLoop {
           signal,
         };
 
-        // Per-turn pipeline context. Real call sites thread a full
-        // `turnContext` into `run()` and it is used directly; standalone
-        // unit-test instantiations that never plumb a context through fall
-        // back to a synthesized placeholder scoped to the tool-use iteration.
-        const turnCtx =
-          turnContext ?? buildLoopTurnContext(requestId, toolUseTurns);
-
         // Let plugins edit the outbound request and opt this call into deferred
         // output streaming. Runs for every provider call; hooks self-gate on
         // call site / conversation. Fail-open: a throwing hook leaves the
@@ -1611,8 +1693,9 @@ export class AgentLoop {
         history.push({ role: "user", content: resultBlocks });
 
         // Invoke checkpoint callback after tool results are in history.
-        // Handoff is offered first so a queued message takes precedence over
-        // the mid-loop budget yield below.
+        // Handoff takes precedence over the budget gate: a handoff decision
+        // breaks here and leaves `budgetGateArmed` false, so a queued message
+        // is processed before the next iteration's pre-call budget gate.
         if (onCheckpoint) {
           const decision = await onCheckpoint({
             turnIndex: toolUseTurns - 1, // 0-based (toolUseTurns was already incremented)
@@ -1626,64 +1709,11 @@ export class AgentLoop {
           }
         }
 
-        // Mid-loop budget gate: when overflow recovery is enabled, estimate
-        // the running context size as it approaches the preflight budget.
-        // With `compactInPlace` the loop compacts in place and continues;
-        // without it it yields (`exitReason = "budget"`) so the orchestrator
-        // can recover before the next provider call risks a hard
-        // context-too-large rejection. Keyed off the loop's own
-        // `history.length` (the messages actually in context this turn,
-        // including tool iterations) rather than the durable conversation
-        // count.
-        const contextWindow = resolveContextWindow?.();
-        if (contextWindow?.overflowRecovery.enabled) {
-          const { maxInputTokens, overflowRecovery } = contextWindow;
-          const safetyMargin =
-            history.length > LONG_HISTORY_MESSAGE_THRESHOLD
-              ? Math.max(
-                  overflowRecovery.safetyMarginRatio,
-                  LONG_HISTORY_SAFETY_MARGIN_FLOOR,
-                )
-              : overflowRecovery.safetyMarginRatio;
-          const preflightBudget = Math.floor(
-            maxInputTokens * (1 - safetyMargin),
-          );
-          const midLoopThreshold =
-            preflightBudget * MID_LOOP_YIELD_THRESHOLD_RATIO;
-          const estimated = this.estimateTokens(history);
-          if (estimated > midLoopThreshold) {
-            if (compactInPlace) {
-              rlog.info(
-                { phase: "mid-loop", estimated, threshold: midLoopThreshold },
-                "Token estimate approaching budget — compacting in place",
-              );
-              const compacted = await this.compact(
-                history,
-                turnCtx,
-                contextWindowManager,
-                signal,
-                onEvent,
-                resolveEffectiveOverrideProfile() ?? null,
-                isNonInteractive,
-                modelProfile,
-                actorContext,
-              );
-              if (compacted) {
-                history = compacted;
-                // The compacted, re-injected array is the new base; output
-                // produced after this point is what the orchestrator persists.
-                newMessagesStart = history.length;
-                continue;
-              }
-            }
-            rlog.warn(
-              { phase: "mid-loop", estimated, threshold: midLoopThreshold },
-              "Token estimate approaching budget — yielding for compaction",
-            );
-            exitReason = "budget";
-            break;
-          }
-        }
+        // Arm the pre-call budget gate for the next iteration. Placed after
+        // the checkpoint so a handoff yield (which breaks above) leaves it
+        // disarmed; the gate then runs at the top of the next iteration,
+        // before that iteration's provider call.
+        budgetGateArmed = true;
       } catch (error) {
         // Abort errors are expected when user cancels — synthesize
         // cancellation tool_results so the history stays valid for the

package/src/cli/commands/plugins.ts

@@ -62,45 +62,51 @@ Examples:
           "--ref <ref>",
           `Git ref to fetch from (default: ${DEFAULT_PLUGIN_REF})`,
         )
-        .action(async (name: string, opts: { force?: boolean; ref?: string }) => {
-          try {
-            const result = await installPlugin(
-              {
-                name,
-                force: opts.force ?? false,
-                ref: opts.ref ?? DEFAULT_PLUGIN_REF,
-              },
-              { fetch: globalThis.fetch.bind(globalThis) },
-            );
-            log.info(
-              {
-                name: result.name,
-                target: result.target,
-                fileCount: result.fileCount,
-                ref: result.ref,
-              },
-              "external plugin installed",
-            );
-            console.log(
-              `Installed plugin "${result.name}" (${result.fileCount} file${result.fileCount === 1 ? "" : "s"}) → ${result.target}`,
-            );
-            console.log("Restart the assistant to pick up the new plugin.");
-          } catch (err) {
-            if (err instanceof PluginAlreadyInstalledError) {
-              console.error(`${err.message}\nPass --force to overwrite.`);
-              process.exitCode = 1;
-              return;
-            }
-            if (err instanceof PluginNotFoundError) {
-              console.error(err.message);
+        .action(
+          async (name: string, opts: { force?: boolean; ref?: string }) => {
+            try {
+              const result = await installPlugin(
+                {
+                  name,
+                  force: opts.force ?? false,
+                  ref: opts.ref ?? DEFAULT_PLUGIN_REF,
+                },
+                { fetch: globalThis.fetch.bind(globalThis) },
+              );
+              log.info(
+                {
+                  name: result.name,
+                  target: result.target,
+                  fileCount: result.fileCount,
+                  ref: result.ref,
+                  commit: result.commit,
+                },
+                "external plugin installed",
+              );
+              const pinned = result.commit
+                ? ` at ${result.commit.slice(0, 7)}`
+                : "";
+              console.log(
+                `Installed plugin "${result.name}" (${result.fileCount} file${result.fileCount === 1 ? "" : "s"})${pinned} → ${result.target}`,
+              );
+              console.log("Restart the assistant to pick up the new plugin.");
+            } catch (err) {
+              if (err instanceof PluginAlreadyInstalledError) {
+                console.error(`${err.message}\nPass --force to overwrite.`);
+                process.exitCode = 1;
+                return;
+              }
+              if (err instanceof PluginNotFoundError) {
+                console.error(err.message);
+                process.exitCode = 1;
+                return;
+              }
+              const message = err instanceof Error ? err.message : String(err);
+              console.error(`Plugin install failed: ${message}`);
               process.exitCode = 1;
-              return;
             }
-            const message = err instanceof Error ? err.message : String(err);
-            console.error(`Plugin install failed: ${message}`);
-            process.exitCode = 1;
-          }
-        });
+          },
+        );
 
       plugins
         .command("list")