@vellumai/assistant 0.5.3 → 0.5.4

package/src/memory/reducer-scheduler.ts

@@ -0,0 +1,242 @@
+/**
+ * Reducer scheduler — synchronous pre-switch/create reduction of the most
+ * recently updated dirty conversation.
+ *
+ * When the user switches conversations or starts a new one, we want the
+ * *previous* conversation's memory to be reduced before the next memory
+ * read. This module exposes {@link reduceBeforeSwitch} which:
+ *
+ *   1. Finds the single most recently updated dirty conversation (excluding
+ *      the target conversation).
+ *   2. Runs the same reduction pipeline the background job uses (load
+ *      unreduced messages, call {@link runReducer}, apply via
+ *      {@link applyReducerResult}).
+ *   3. Awaits the result so the caller can proceed knowing memory is fresh.
+ *
+ * If no eligible dirty conversation exists, the function returns immediately.
+ */
+
+import { and, asc, desc, eq, gte, isNotNull, ne } from "drizzle-orm";
+
+import { getLogger } from "../util/logger.js";
+import { type ConversationRow, getConversation } from "./conversation-crud.js";
+import { getDb } from "./db.js";
+import { type ReducerPromptInput, runReducer } from "./reducer.js";
+import {
+  applyReducerResult,
+  getActiveOpenLoops,
+  getActiveTimeContexts,
+} from "./reducer-store.js";
+import { EMPTY_REDUCER_RESULT } from "./reducer-types.js";
+import { conversations, messages } from "./schema.js";
+
+const log = getLogger("reducer-scheduler");
+
+// ── Internal helpers ────────────────────────────────────────────────
+
+interface MessageRow {
+  id: string;
+  role: string;
+  content: string;
+  createdAt: number;
+}
+
+/**
+ * Find the single most recently updated dirty conversation, excluding
+ * the target conversation. Returns the conversation ID or null if none.
+ */
+export function findMostRecentDirtyConversation(
+  excludeConversationId: string,
+): string | null {
+  const db = getDb();
+  const row = db
+    .select({ id: conversations.id })
+    .from(conversations)
+    .where(
+      and(
+        isNotNull(conversations.memoryDirtyTailSinceMessageId),
+        ne(conversations.id, excludeConversationId),
+      ),
+    )
+    .orderBy(desc(conversations.updatedAt))
+    .limit(1)
+    .get();
+
+  return row?.id ?? null;
+}
+
+/**
+ * Load messages from `dirtyTailMessageId` onward (inclusive), ordered by
+ * createdAt ascending.
+ */
+function loadUnreducedMessages(
+  conversationId: string,
+  dirtyTailMessageId: string,
+): MessageRow[] {
+  const db = getDb();
+
+  const tailMessage = db
+    .select({ createdAt: messages.createdAt })
+    .from(messages)
+    .where(eq(messages.id, dirtyTailMessageId))
+    .get();
+
+  if (!tailMessage) {
+    return [];
+  }
+
+  return db
+    .select({
+      id: messages.id,
+      role: messages.role,
+      content: messages.content,
+      createdAt: messages.createdAt,
+    })
+    .from(messages)
+    .where(
+      and(
+        eq(messages.conversationId, conversationId),
+        gte(messages.createdAt, tailMessage.createdAt),
+      ),
+    )
+    .orderBy(asc(messages.createdAt))
+    .all();
+}
+
+/**
+ * Build the `newMessages` array for the reducer input, optionally
+ * prepending the conversation's contextSummary as a synthetic system message.
+ */
+function buildNewMessages(
+  conversation: ConversationRow,
+  unreducedMessages: MessageRow[],
+): Array<{ role: string; content: string }> {
+  const result: Array<{ role: string; content: string }> = [];
+
+  if (conversation.contextSummary) {
+    result.push({
+      role: "system",
+      content: `[Prior context summary] ${conversation.contextSummary}`,
+    });
+  }
+
+  for (const msg of unreducedMessages) {
+    result.push({ role: msg.role, content: msg.content });
+  }
+
+  return result;
+}
+
+// ── Public API ──────────────────────────────────────────────────────
+
+/**
+ * Reduce the most recently updated dirty conversation (excluding
+ * `targetConversationId`) before a conversation switch or create.
+ *
+ * This runs the full reduction pipeline synchronously (awaiting the
+ * provider call) so the caller can proceed knowing memory is fresh.
+ *
+ * Returns the conversation ID that was reduced, or null if none were eligible.
+ */
+export async function reduceBeforeSwitch(
+  targetConversationId: string,
+): Promise<string | null> {
+  const dirtyConversationId =
+    findMostRecentDirtyConversation(targetConversationId);
+
+  if (!dirtyConversationId) {
+    return null;
+  }
+
+  const conversation = getConversation(dirtyConversationId);
+  if (!conversation) {
+    return null;
+  }
+
+  const dirtyTailMessageId = conversation.memoryDirtyTailSinceMessageId;
+  if (!dirtyTailMessageId) {
+    return null;
+  }
+
+  // ── Load unreduced messages ──────────────────────────────────
+  const unreducedMessages = loadUnreducedMessages(
+    dirtyConversationId,
+    dirtyTailMessageId,
+  );
+
+  if (unreducedMessages.length === 0) {
+    log.debug(
+      { conversationId: dirtyConversationId, dirtyTailMessageId },
+      "No messages found from dirty tail — nothing to reduce on switch",
+    );
+    return null;
+  }
+
+  // ── Load active brief-state context ──────────────────────────
+  const scopeId = conversation.memoryScopeId;
+  const now = Date.now();
+
+  const existingTimeContexts = getActiveTimeContexts(scopeId, now);
+  const existingOpenLoops = getActiveOpenLoops(scopeId);
+
+  // ── Build reducer input ──────────────────────────────────────
+  const newMessages = buildNewMessages(conversation, unreducedMessages);
+
+  const reducerInput: ReducerPromptInput = {
+    conversationId: dirtyConversationId,
+    newMessages,
+    existingTimeContexts: existingTimeContexts.map((tc) => ({
+      id: tc.id,
+      summary: tc.summary,
+    })),
+    existingOpenLoops: existingOpenLoops.map((ol) => ({
+      id: ol.id,
+      summary: ol.summary,
+      status: ol.status,
+    })),
+    nowMs: now,
+    scopeId,
+  };
+
+  // ── Run the reducer ──────────────────────────────────────────
+  try {
+    const result = await runReducer(reducerInput);
+
+    if (result === EMPTY_REDUCER_RESULT) {
+      log.debug(
+        { conversationId: dirtyConversationId },
+        "Reducer returned empty result on switch — not advancing checkpoint",
+      );
+      return null;
+    }
+
+    // ── Apply result transactionally ───────────────────────────
+    const lastMessage = unreducedMessages[unreducedMessages.length - 1];
+    applyReducerResult({
+      result,
+      conversationId: dirtyConversationId,
+      scopeId,
+      reducedThroughMessageId: lastMessage.id,
+      now,
+    });
+
+    log.info(
+      {
+        conversationId: dirtyConversationId,
+        reducedThroughMessageId: lastMessage.id,
+        messageCount: unreducedMessages.length,
+        timeContextOps: result.timeContexts.length,
+        openLoopOps: result.openLoops.length,
+      },
+      "Pre-switch memory reduction completed",
+    );
+
+    return dirtyConversationId;
+  } catch (err) {
+    log.warn(
+      { err, conversationId: dirtyConversationId },
+      "Pre-switch memory reduction failed — continuing with switch",
+    );
+    return null;
+  }
+}

package/src/memory/reducer-types.ts

@@ -86,8 +86,15 @@ export interface ReducerResult {
 }
 
 /**
- * An empty result used as fallback when the reducer output is invalid or
- * unparseable. Guarantees no side-effects on the DB.
+ * Sentinel empty result returned when the reducer output is **unparseable**
+ * (not valid JSON, not a JSON object, provider failure, etc.).
+ *
+ * Callers use identity comparison (`=== EMPTY_REDUCER_RESULT`) to detect
+ * true parse failures and skip checkpoint advancement so the job can retry.
+ *
+ * A valid-but-empty model response (e.g. `{}`) returns a normal
+ * `ReducerResult` with all empty arrays — NOT this sentinel — so the
+ * checkpoint advances and the dirty tail is cleared.
  */
 export const EMPTY_REDUCER_RESULT: Readonly<ReducerResult> = Object.freeze({
   timeContexts: Object.freeze([]) as unknown as TimeContextOp[],

package/src/memory/reducer.ts

@@ -5,7 +5,7 @@
  *   1. ReducerPromptInput — structured input for the provider call
  *   2. runReducer — send the transcript span to the LLM and return a typed result
  *   3. parseReducerOutput — raw string -> validated ReducerResult
- *   4. Fallback to EMPTY_REDUCER_RESULT on any invalid output
+ *   4. Fallback to EMPTY_REDUCER_RESULT on unparseable output (parse failures only)
  *
  * The reducer is intentionally side-effect-free: it never writes to the
  * database. Callers are responsible for applying the returned ReducerResult.
@@ -373,13 +373,19 @@ function validateArchiveEpisode(raw: unknown): ArchiveEpisodeCandidate | null {
 /**
  * Parse raw model output into a validated ReducerResult.
  *
- * On any structural error (non-JSON, missing top-level keys, wrong types)
- * the function returns EMPTY_REDUCER_RESULT rather than throwing. Individual
- * invalid operations within an otherwise valid structure are silently dropped
- * to preserve the rest of the result.
+ * On any structural error (non-JSON, not a JSON object) the function returns
+ * {@link EMPTY_REDUCER_RESULT} rather than throwing — callers use identity
+ * comparison (`=== EMPTY_REDUCER_RESULT`) to detect true parse failures and
+ * skip checkpoint advancement.
  *
- * However, if **all four** top-level arrays are absent or not arrays, the
- * entire output is treated as invalid and returns the empty result.
+ * A valid JSON object with no recognized top-level arrays (e.g. `{}`) is
+ * treated as a **valid-but-empty** response — the model simply had nothing
+ * to extract. In this case a normal `ReducerResult` with all empty arrays
+ * is returned so that callers advance the checkpoint and clear the dirty
+ * tail, avoiding an infinite retry loop.
+ *
+ * Individual invalid operations within an otherwise valid structure are
+ * silently dropped to preserve the rest of the result.
  */
 export function parseReducerOutput(raw: string): ReducerResult {
   let parsed: unknown;
@@ -399,22 +405,30 @@ export function parseReducerOutput(raw: string): ReducerResult {
 
   const obj = parsed as Record<string, unknown>;
 
-  // Check that at least one top-level array key exists
+  // Check which top-level array keys are present
   const hasTimeContexts = Array.isArray(obj.timeContexts);
   const hasOpenLoops = Array.isArray(obj.openLoops);
   const hasArchiveObservations = Array.isArray(obj.archiveObservations);
   const hasArchiveEpisodes = Array.isArray(obj.archiveEpisodes);
 
+  // A valid JSON object with no recognized arrays (e.g. `{}`) means the
+  // model had nothing to extract — return a normal (non-sentinel) empty
+  // result so the checkpoint advances.
   if (
     !hasTimeContexts &&
     !hasOpenLoops &&
     !hasArchiveObservations &&
     !hasArchiveEpisodes
   ) {
-    log.warn(
-      "reducer output has no recognized top-level arrays — falling back to empty result",
+    log.debug(
+      "reducer output is valid JSON with no extractions — advancing with empty result",
     );
-    return EMPTY_REDUCER_RESULT;
+    return {
+      timeContexts: [],
+      openLoops: [],
+      archiveObservations: [],
+      archiveEpisodes: [],
+    };
   }
 
   const timeContexts: TimeContextOp[] = [];

package/src/memory/schema/infrastructure.ts

@@ -24,6 +24,7 @@ export const cronJobs = sqliteTable("cron_jobs", {
   routingIntent: text("routing_intent").notNull().default("all_channels"), // 'single_channel' | 'multi_channel' | 'all_channels'
   routingHintsJson: text("routing_hints_json").notNull().default("{}"),
   status: text("status").notNull().default("active"), // 'active' | 'firing' | 'fired' | 'cancelled'
+  quiet: integer("quiet", { mode: "boolean" }).notNull().default(false), // suppress completion notifications
   createdAt: integer("created_at").notNull(),
   updatedAt: integer("updated_at").notNull(),
 });

package/src/runtime/auth/route-policy.ts

@@ -128,7 +128,7 @@ const ACTOR_ENDPOINTS: Array<{ endpoint: string; scopes: Scope[] }> = [
   { endpoint: "messages:POST", scopes: ["chat.write"] },
   { endpoint: "btw", scopes: ["chat.write"] },
   { endpoint: "conversations", scopes: ["chat.read"] },
-  { endpoint: "conversations:DELETE", scopes: ["chat.write"] },
+  { endpoint: "conversations:POST", scopes: ["chat.write"] },
   { endpoint: "conversations/fork", scopes: ["chat.write"] },
   { endpoint: "conversations/switch", scopes: ["chat.write"] },
   { endpoint: "conversations/name", scopes: ["chat.write"] },
@@ -348,6 +348,7 @@ const ACTOR_ENDPOINTS: Array<{ endpoint: string; scopes: Scope[] }> = [
   { endpoint: "config/embeddings:PUT", scopes: ["settings.write"] },
 
   // Conversation management
+  { endpoint: "conversations:DELETE", scopes: ["chat.write"] },
   { endpoint: "conversations/wipe", scopes: ["chat.write"] },
   { endpoint: "conversations/reorder", scopes: ["chat.write"] },
 
@@ -470,6 +471,14 @@ for (const { endpoint, scopes } of ACTOR_ENDPOINTS) {
   });
 }
 
+// Clear-all conversations: elevated to settings.write (destructive bulk operation).
+// Uses a distinct key so the single-conversation DELETE (conversations:DELETE)
+// retains the lower chat.write scope.
+registerPolicy("conversations/clear-all", {
+  requiredScopes: ["settings.write"],
+  allowedPrincipalTypes: ["actor", "svc_gateway", "svc_daemon", "local"],
+});
+
 // Channel inbound: gateway-only
 registerPolicy("channels/inbound", {
   requiredScopes: ["ingress.write"],

package/src/runtime/routes/conversation-management-routes.ts

@@ -1,6 +1,7 @@
 /**
  * Route handlers for conversation management operations.
  *
+ * POST   /v1/conversations                 — create a new conversation
  * POST   /v1/conversations/switch         — switch to an existing conversation
  * POST   /v1/conversations/fork           — fork an existing conversation
  * PATCH  /v1/conversations/:id/name       — rename a conversation
@@ -19,7 +20,9 @@ import {
   PRIVATE_CONVERSATION_FORK_ERROR,
   wipeConversation,
 } from "../../memory/conversation-crud.js";
+import { updateConversationTitle } from "../../memory/conversation-crud.js";
 import {
+  getOrCreateConversation,
   resolveConversationId,
   setConversationKeyIfAbsent,
 } from "../../memory/conversation-key-store.js";
@@ -66,6 +69,44 @@ export function conversationManagementRouteDefinitions(
   deps: ConversationManagementDeps,
 ): RouteDefinition[] {
   return [
+    {
+      endpoint: "conversations",
+      method: "POST",
+      policyKey: "conversations",
+      handler: async ({ req }) => {
+        let body: { conversationKey?: string; conversationType?: string } = {};
+        try {
+          body = (await req.json()) as typeof body;
+        } catch {
+          // Empty or malformed body — fall through with defaults.
+        }
+        const conversationKey = body.conversationKey ?? crypto.randomUUID();
+        const requestedType =
+          body.conversationType === "private" ? "private" : "standard";
+        const result = getOrCreateConversation(conversationKey, {
+          conversationType: requestedType,
+        });
+        if (result.created) {
+          updateConversationTitle(result.conversationId, "New Conversation");
+        }
+        log.info(
+          {
+            conversationId: result.conversationId,
+            conversationKey,
+            created: result.created,
+          },
+          "Created conversation via POST",
+        );
+        return Response.json(
+          {
+            id: result.conversationId,
+            conversationKey,
+            conversationType: result.conversationType,
+          },
+          { status: result.created ? 201 : 200 },
+        );
+      },
+    },
     {
       endpoint: "conversations/fork",
       method: "POST",
@@ -185,8 +226,17 @@ export function conversationManagementRouteDefinitions(
     {
       endpoint: "conversations",
       method: "DELETE",
-      policyKey: "conversations",
-      handler: () => {
+      policyKey: "conversations/clear-all",
+      handler: ({ req }) => {
+        const confirm = req.headers.get("x-confirm-destructive");
+        if (confirm !== "clear-all-conversations") {
+          return httpError(
+            "BAD_REQUEST",
+            "DELETE /v1/conversations permanently deletes ALL conversations, messages, and memory. " +
+              "To confirm, set header X-Confirm-Destructive: clear-all-conversations",
+            400,
+          );
+        }
         deps.clearAllConversations();
         return new Response(null, { status: 204 });
       },
@@ -225,6 +275,24 @@ export function conversationManagementRouteDefinitions(
             targetId: summaryId,
           });
         }
+        for (const obsId of result.deletedObservationIds) {
+          enqueueMemoryJob("delete_qdrant_vectors", {
+            targetType: "observation",
+            targetId: obsId,
+          });
+        }
+        for (const chunkId of result.deletedChunkIds) {
+          enqueueMemoryJob("delete_qdrant_vectors", {
+            targetType: "chunk",
+            targetId: chunkId,
+          });
+        }
+        for (const episodeId of result.deletedEpisodeIds) {
+          enqueueMemoryJob("delete_qdrant_vectors", {
+            targetType: "episode",
+            targetId: episodeId,
+          });
+        }
         log.info(
           {
             conversationId: resolvedId,
@@ -281,6 +349,24 @@ export function conversationManagementRouteDefinitions(
             targetId: summaryId,
           });
         }
+        for (const obsId of deleted.deletedObservationIds) {
+          enqueueMemoryJob("delete_qdrant_vectors", {
+            targetType: "observation",
+            targetId: obsId,
+          });
+        }
+        for (const chunkId of deleted.deletedChunkIds) {
+          enqueueMemoryJob("delete_qdrant_vectors", {
+            targetType: "chunk",
+            targetId: chunkId,
+          });
+        }
+        for (const episodeId of deleted.deletedEpisodeIds) {
+          enqueueMemoryJob("delete_qdrant_vectors", {
+            targetType: "episode",
+            targetId: episodeId,
+          });
+        }
         log.info({ conversationId: resolvedId }, "Deleted conversation");
         return new Response(null, { status: 204 });
       },

package/src/runtime/routes/guardian-bootstrap-routes.ts

@@ -28,6 +28,7 @@ type ServerWithRequestIP = {
   ): { address: string; family: string; port: number } | null;
 };
 import { isHttpAuthDisabled } from "../../config/env.js";
+import { getIsContainerized } from "../../config/env-registry.js";
 
 const log = getLogger("guardian-bootstrap");
 
@@ -86,19 +87,30 @@ export async function handleGuardianBootstrap(
   req: Request,
   server: ServerWithRequestIP,
 ): Promise<Response> {
+  // Reject non-private-network peers (allows loopback, Docker bridge, etc.)
+  const peerIp = server.requestIP(req)?.address;
+  if ((!peerIp || !isPrivateAddress(peerIp)) && !isHttpAuthDisabled()) {
+    return httpError("FORBIDDEN", "Bootstrap endpoint is local-only", 403);
+  }
+
   // Reject requests forwarded from public networks. The gateway sets
   // x-forwarded-for to the real client IP; if that IP is on a private
   // network (loopback, Docker bridge, RFC 1918) the request is still
   // considered local. Only reject when the forwarded IP is public.
+  //
+  // Skip this check when running in a container: the peer IP was already
+  // validated above (Docker bridge network = private), so the request
+  // reached us through a co-located gateway. The x-forwarded-for header
+  // reflects the original external client (e.g. platform proxy) and is
+  // not meaningful for local-only enforcement in this topology.
   const forwarded = req.headers.get("x-forwarded-for");
   const forwardedIp = forwarded ? forwarded.split(",")[0].trim() : null;
-  if (forwardedIp && !isPrivateAddress(forwardedIp) && !isHttpAuthDisabled()) {
-    return httpError("FORBIDDEN", "Bootstrap endpoint is local-only", 403);
-  }
-
-  // Reject non-private-network peers (allows loopback, Docker bridge, etc.)
-  const peerIp = server.requestIP(req)?.address;
-  if ((!peerIp || !isPrivateAddress(peerIp)) && !isHttpAuthDisabled()) {
+  if (
+    forwardedIp &&
+    !isPrivateAddress(forwardedIp) &&
+    !isHttpAuthDisabled() &&
+    !getIsContainerized()
+  ) {
     return httpError("FORBIDDEN", "Bootstrap endpoint is local-only", 403);
   }
 

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

@@ -182,6 +182,7 @@ export async function handleAddSecret(
           500,
         );
       }
+      clearEmbeddingBackendCache();
       invalidateConfigCache();
       await initializeProviders(getConfig());
       log.info({ provider: name }, "API key updated via HTTP");

package/src/schedule/schedule-store.ts

@@ -35,6 +35,7 @@ export interface ScheduleJob {
   mode: ScheduleMode;
   routingIntent: RoutingIntent;
   routingHints: Record<string, unknown>;
+  quiet: boolean;
   status: ScheduleStatus;
   createdAt: number;
   updatedAt: number;
@@ -91,6 +92,7 @@ export function createSchedule(params: {
   mode?: ScheduleMode;
   routingIntent?: RoutingIntent;
   routingHints?: Record<string, unknown>;
+  quiet?: boolean;
 }): ScheduleJob {
   const expression = params.expression ?? params.cronExpression ?? null;
   const isOneShot = expression == null;
@@ -118,6 +120,7 @@ export function createSchedule(params: {
   const mode = params.mode ?? "execute";
   const routingIntent = params.routingIntent ?? "all_channels";
   const routingHints = params.routingHints ?? {};
+  const quiet = params.quiet ?? false;
 
   let nextRunAt: number;
   if (isOneShot) {
@@ -144,6 +147,7 @@ export function createSchedule(params: {
     mode,
     routingIntent,
     routingHintsJson: JSON.stringify(routingHints),
+    quiet,
     status: "active" as ScheduleStatus,
     createdAt: now,
     updatedAt: now,
@@ -236,6 +240,7 @@ export function updateSchedule(
     mode?: ScheduleMode;
     routingIntent?: RoutingIntent;
     routingHints?: Record<string, unknown>;
+    quiet?: boolean;
   },
 ): ScheduleJob | null {
   const db = getDb();
@@ -290,6 +295,7 @@ export function updateSchedule(
     set.routingIntent = updates.routingIntent;
   if (updates.routingHints !== undefined)
     set.routingHintsJson = JSON.stringify(updates.routingHints);
+  if (updates.quiet !== undefined) set.quiet = updates.quiet;
 
   // Recompute nextRunAt if schedule timing may have changed (only for recurring)
   if (
@@ -771,6 +777,7 @@ function parseJobRow(row: typeof scheduleJobs.$inferSelect): ScheduleJob {
     mode: (row.mode ?? "execute") as ScheduleMode,
     routingIntent: (row.routingIntent ?? "all_channels") as RoutingIntent,
     routingHints: safeParseJson(row.routingHintsJson),
+    quiet: row.quiet ?? false,
     status: (row.status ?? "active") as ScheduleStatus,
     createdAt: row.createdAt,
     updatedAt: row.updatedAt,

package/src/schedule/scheduler.ts

@@ -206,7 +206,9 @@ async function runScheduleOnce(
           if (isOneShot) failOneShot(job.id);
         } else {
           completeScheduleRun(runId, { status: "ok" });
-          notifySchedule({ id: job.id, name: job.name });
+          if (!job.quiet) {
+            notifySchedule({ id: job.id, name: job.name });
+          }
           if (isOneShot) completeOneShot(job.id);
         }
         processed += 1;
@@ -278,7 +280,9 @@ async function runScheduleOnce(
         trustClass: "guardian",
       });
       completeScheduleRun(runId, { status: "ok" });
-      notifySchedule({ id: job.id, name: job.name });
+      if (!job.quiet) {
+        notifySchedule({ id: job.id, name: job.name });
+      }
       if (isOneShot) completeOneShot(job.id);
       processed += 1;
     } catch (err) {

package/src/telemetry/usage-telemetry-reporter.ts

@@ -193,7 +193,7 @@ export class UsageTelemetryReporter {
       const organizationId = getPlatformOrganizationId() || undefined;
       const userId = getPlatformUserId() || undefined;
       const payload = {
-        installation_id: getDeviceId(),
+        device_id: getDeviceId(),
         assistant_id: assistantId,
         app_version: APP_VERSION,
         ...(organizationId ? { organization_id: organizationId } : {}),

package/src/tools/filesystem/edit.ts

@@ -38,8 +38,13 @@ class FileEditTool implements Tool {
             description:
               "Replace all occurrences of old_string instead of requiring a unique match (default: false)",
           },
+          activity: {
+            type: "string",
+            description:
+              "Brief non-technical explanation of what you are doing and why, shown to the user as a status update.",
+          },
         },
-        required: ["path", "old_string", "new_string"],
+        required: ["path", "old_string", "new_string", "activity"],
       },
     };
   }

package/src/tools/filesystem/read.ts

@@ -38,8 +38,13 @@ class FileReadTool implements Tool {
             type: "number",
             description: "Maximum number of lines to read",
           },
+          activity: {
+            type: "string",
+            description:
+              "Brief non-technical explanation of what you are doing and why, shown to the user as a status update.",
+          },
         },
-        required: ["path"],
+        required: ["path", "activity"],
       },
     };
   }