@desplega.ai/agent-swarm 1.164.1 → 1.166.0

package/src/tools/db-query.ts

@@ -26,7 +26,7 @@ export const registerDbQueryTool = (server: McpServer) => {
     {
       title: "Execute database query",
       description:
-        "Execute a read-only SQL query against the swarm database (SQLite). Available to all authenticated agents — be aware results may include secrets (oauth_tokens, configs). Runs in a short-lived child process with a wall-clock budget by default (fails gracefully with a timeout or a 429-style concurrency error rather than freezing); results capped at a default row count (operator-configurable via `DB_QUERY_MCP_MAX_ROWS`) regardless of how many the query matched. See the sql parameter's description for which tables are unsafe to read whole, and the db-query-guidance skill for config knobs.",
+        "Execute a read-only SQL query against the swarm database (SQLite). Available to all authenticated agents. Queries that read credential tables (OAuth authorizations, apps and pending flows, user and session tokens, script API bearers, Codex device-login state) are rejected, and secret-shaped values in results are redacted. Runs in a short-lived child process with a wall-clock budget by default (fails gracefully with a timeout or a 429-style concurrency error rather than freezing); results capped at a default row count (operator-configurable via `DB_QUERY_MCP_MAX_ROWS`) regardless of how many the query matched. See the sql parameter's description for which tables are unsafe to read whole, and the db-query-guidance skill for config knobs.",
       annotations: { readOnlyHint: true },
       inputSchema: DbQueryToolInputSchema,
       outputSchema: swarmToolOutputSchema({

package/src/tools/inject-learning.ts

@@ -73,7 +73,7 @@ export const registerInjectLearningTool = (server: McpServer) => {
       // Generate and store embedding (async, best-effort)
       try {
         const provider = getEmbeddingProvider();
-        const embedding = await provider.embed(content);
+        const embedding = await provider.embed(memory.content);
         if (embedding) {
           await store.updateEmbedding(memory.id, embedding, provider.name);
         }

package/src/tools/kv/kv-get.ts

@@ -1,8 +1,25 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import { getKv } from "@/be/db";
-import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
-import { KvKeySchema, KvNamespaceSchema, KvValueTypeSchema } from "@/types";
+import {
+  hasKvViewArgs,
+  joinKvPath,
+  KV_PATH_MAX_CHARS,
+  type KvView,
+  resolveKvTarget,
+  resolveKvView,
+  sliceKvTarget,
+} from "@/kv-view";
+import {
+  createToolRegistrar,
+  MCP_RESULT_WIRE_LIMIT_BYTES,
+  type SwarmToolResult,
+  swarmToolOutputSchema,
+  swarmToolResultBytes,
+  toolErr,
+  toolOk,
+} from "@/tools/utils";
+import { type KvEntry, KvKeySchema, KvNamespaceSchema, KvValueTypeSchema } from "@/types";
 import { kvReadAuthError } from "./kv-read-auth";
 import { resolveNamespace } from "./resolve-namespace";
 
@@ -28,13 +45,102 @@ function renderKvEntry(entry: {
   return `value (${entry.valueType}): ${valueText}${expiry}`;
 }
 
+const kvViewOutputSchema = z.looseObject({
+  path: z.string().optional(),
+  type: z.string().optional(),
+  total: z.number().optional(),
+  offset: z.number().optional(),
+  returned: z.number().optional(),
+  nextOffset: z.number().nullable().optional(),
+});
+
+function describeView(view: KvView): string {
+  const target = view.path ? `"${view.path}"` : "the value";
+  if (view.total === undefined) return `${target} (${view.type})`;
+  const unit =
+    view.type === "array" ? "items" : view.type === "object" ? "keys" : "chars (JSON-encoded)";
+  const offset = view.offset ?? 0;
+  return `${target} ${unit} ${offset}..${offset + (view.returned ?? 0)} of ${view.total}`;
+}
+
+/**
+ * A targeted read shrunk to the per-channel MCP budget. kv-get is spill-exempt,
+ * so the tool bounds its own views: the page shrinks (binary search on items,
+ * keys, or chars) and `view.nextOffset` says where to resume.
+ */
+function boundedView(
+  entry: KvEntry,
+  agentId: string | undefined,
+  args: { path?: string; offset?: number; limit?: number },
+): SwarmToolResult {
+  const { namespace, key } = entry;
+  const failed = (error: string) => toolErr(error, { data: { yourAgentId: agentId, namespace } });
+  // Validates path and offset/limit applicability; the page itself is sized below.
+  const checked = resolveKvView(entry.value, args);
+  if (!checked.ok) return failed(checked.error);
+  const target = resolveKvTarget(entry.value, args.path ?? "");
+  if (!target.ok) return failed(target.error);
+
+  const { value: _value, ...meta } = entry;
+  // Strings go out JSON-encoded too: the wire composer trims `details`, which
+  // would drop a slice's edge whitespace and erase a whitespace-only slice.
+  const render = (value: unknown, view: KvView) =>
+    toolOk(`Read ${describeView(view)} from "${key}" in "${namespace}".`, {
+      details: JSON.stringify(value),
+      data: { yourAgentId: agentId, namespace, entry: meta, view },
+    });
+  const baseView = checked.view;
+  if (baseView.total === undefined) return render(checked.value, baseView);
+
+  const offset = baseView.offset ?? 0;
+  const wanted = Math.min(args.limit ?? baseView.total, Math.max(0, baseView.total - offset));
+  const firstKey =
+    baseView.type === "array"
+      ? String(offset)
+      : baseView.type === "object"
+        ? Object.keys(target.value as object)[offset]
+        : undefined;
+  // An empty key or an over-long path cannot be passed back as `path`.
+  const firstPath =
+    firstKey === undefined || firstKey === ""
+      ? undefined
+      : `${baseView.path ? `${baseView.path}.` : ""}${joinKvPath([firstKey])}`;
+  const narrowTo = firstPath !== undefined && firstPath.length <= KV_PATH_MAX_CHARS;
+  // A shrunk page carries its note, so the note is part of what gets sized.
+  const page = (count: number) => {
+    const sliced = sliceKvTarget(target.value, offset, count);
+    const result = render(sliced?.value, {
+      ...baseView,
+      returned: sliced?.returned ?? 0,
+      nextOffset: sliced?.nextOffset ?? null,
+    });
+    if (count >= wanted) return result;
+    const note =
+      count === 0 && narrowTo
+        ? ` The entry at offset ${offset} alone exceeds the ${MCP_RESULT_WIRE_LIMIT_BYTES}-byte cap; narrow the path to "${firstPath}".`
+        : ` Page shrunk to fit the ${MCP_RESULT_WIRE_LIMIT_BYTES}-byte cap; continue at view.nextOffset.`;
+    return { ...result, message: `${result.message}${note}` };
+  };
+  const fits = (count: number) => swarmToolResultBytes(page(count)) <= MCP_RESULT_WIRE_LIMIT_BYTES;
+  if (fits(wanted)) return page(wanted);
+
+  let low = 0;
+  let high = wanted;
+  while (low < high) {
+    const mid = Math.ceil((low + high) / 2);
+    if (fits(mid)) low = mid;
+    else high = mid - 1;
+  }
+  return page(low);
+}
+
 export const registerKvGetTool = (server: McpServer) => {
   createToolRegistrar(server)(
     "kv-get",
     {
       title: "KV Get",
       description:
-        "Read a key from the swarm KV store. Returns the entry or null if missing/expired. Namespace defaults to your current context (Slack thread / PR / Linear issue when invoked from a task; otherwise your agent scratchpad).",
+        "Read a key from the swarm KV store. Returns the entry or null if missing/expired. Namespace defaults to your current context (Slack thread / PR / Linear issue when invoked from a task; otherwise your agent scratchpad). Without path/offset/limit the whole value comes back unbounded. With any of them you get a bounded view (≤10KB per channel): `path` is a dot path into a JSON value (string entries holding JSON, such as spilled tool results, count as JSON; numeric segments index arrays, e.g. `outcome.data.rows` or `rows.3`; escape a dot inside a key as `\\.`), and `offset`/`limit` page the array items, object keys, or string characters found there. The result's `view.nextOffset` says where the next page starts.",
       annotations: { readOnlyHint: true },
 
       inputSchema: z.object({
@@ -42,14 +148,34 @@ export const registerKvGetTool = (server: McpServer) => {
         namespace: KvNamespaceSchema.optional().describe(
           "Optional explicit namespace. Defaults to the caller's contextKey.",
         ),
+        path: z
+          .string()
+          .max(KV_PATH_MAX_CHARS)
+          .optional()
+          .describe(
+            'Dot path into the JSON value, e.g. "outcome.data.rows" or "rows.3". "" is the whole value. A dot inside a key is escaped as "\\.".',
+          ),
+        offset: z
+          .number()
+          .int()
+          .nonnegative()
+          .optional()
+          .describe("First array item / object key / string char to return. Default 0."),
+        limit: z
+          .number()
+          .int()
+          .positive()
+          .optional()
+          .describe("Max items / keys / chars to return; the page also shrinks to fit the cap."),
       }),
       outputSchema: swarmToolOutputSchema({
         yourAgentId: z.string().optional(),
         namespace: z.string().optional(),
         entry: kvEntryOutputSchema.nullable().optional(),
+        view: kvViewOutputSchema.optional(),
       }),
     },
-    async ({ key, namespace }, requestInfo) => {
+    async ({ key, namespace, path, offset, limit }, requestInfo) => {
       const resolved = await resolveNamespace(namespace, requestInfo);
       if ("error" in resolved) {
         return toolErr(resolved.error, { data: { yourAgentId: requestInfo.agentId } });
@@ -62,9 +188,13 @@ export const registerKvGetTool = (server: McpServer) => {
       }
 
       // kv-get is exempt from the ctx-control spill (see CTX_CONTROL_EXEMPT_TOOLS):
-      // it is the retrieval path for spilled values, so oversized entries go out
-      // whole and the harness applies its own truncation.
+      // it is the retrieval path for spilled values. Without view args oversized
+      // entries go out whole and the harness applies its own truncation; with
+      // path/offset/limit the tool bounds the page itself.
       const entry = await getKv(resolved.namespace, key);
+      if (entry && hasKvViewArgs({ path, offset, limit })) {
+        return boundedView(entry, requestInfo.agentId, { path, offset, limit });
+      }
       return toolOk(
         entry
           ? `Found "${key}" in "${resolved.namespace}".`

package/src/tools/send-task.ts

@@ -11,6 +11,7 @@ import {
   getActiveTaskCount,
   getAgentById,
   getDbClient,
+  getLeadAgent,
   getTaskById,
   getUserById,
   hasCapacity,
@@ -289,11 +290,28 @@ export async function sendTaskHandler(
     outputSchema,
   }: SendTaskArgs,
 ): Promise<SwarmToolResult> {
+  const userLead = ctx.kind === "user" ? await getLeadAgent() : null;
+  if (ctx.kind === "user" && (!userLead || userLead.status === "offline")) {
+    return toolErr("No online Lead is available. Start or register a Lead before sending a task.");
+  }
+
+  const requestedAgentId = ctx.kind === "user" ? userLead!.id : agentId;
+  const requestedRoutingReason = ctx.kind === "user" ? "skill" : routingReason;
+  const requestedRoutingNote =
+    ctx.kind === "user"
+      ? "User MCP ingress assigns new work to the Lead for delegation."
+      : routingNote;
+  const requestedOfferMode = ctx.kind === "user" ? false : offerMode;
+  const requestedLeadOnly = ctx.kind === "user" ? false : leadOnly;
+  const requestedCapabilities = ctx.kind === "user" ? undefined : requiredCapabilities;
+  const requestedAllowDuplicate = ctx.kind === "user" ? false : allowDuplicate;
+  const requestedOverrideSlackContext = ctx.kind === "user" ? false : overrideSlackContext;
+
   // Defense in depth for direct TypeScript callers that bypass MCP schema parsing.
-  if (agentId !== undefined && routingReason === undefined) {
+  if (requestedAgentId !== undefined && requestedRoutingReason === undefined) {
     return toolErr("routingReason is required when agentId is supplied.");
   }
-  if (agentId !== undefined && (routingNote?.trim().length ?? 0) < 10) {
+  if (requestedAgentId !== undefined && (requestedRoutingNote?.trim().length ?? 0) < 10) {
     return toolErr(
       "routingNote is required when agentId is supplied (at least 10 characters after trim).",
     );
@@ -337,7 +355,7 @@ export async function sendTaskHandler(
     });
   }
 
-  if (ctx.kind === "owner" && agentId === ctx.agentId) {
+  if (ctx.kind === "owner" && requestedAgentId === ctx.agentId) {
     return toolErr("Cannot send a task to yourself, are you drunk?", {
       data: { yourAgentId: ctx.agentId },
     });
@@ -358,7 +376,10 @@ export async function sendTaskHandler(
   }
   // A public continuation cannot accidentally declassify its parent before
   // createTaskExtended performs the authoritative merge.
-  const effectiveLeadOnly = leadOnly || effectiveParentTask?.routingAffinity?.leadOnly === true;
+  const effectiveLeadOnly =
+    ctx.kind === "user"
+      ? false
+      : requestedLeadOnly || effectiveParentTask?.routingAffinity?.leadOnly === true;
 
   // Slack-routing coherence guard: reject a hand-typed slackChannelId/slackThreadTs
   // that disagrees with the parent task or the contextKey this child will inherit.
@@ -367,7 +388,7 @@ export async function sendTaskHandler(
   // dispatch-slack-channel-must-match-parent-context-2026-07-10). Omitting the
   // three Slack fields lets inheritance do the right thing; overrideSlackContext
   // opts into a deliberate cross-channel dispatch.
-  if (!overrideSlackContext) {
+  if (!requestedOverrideSlackContext) {
     // send-task never passes contextKey explicitly, so the child inherits the
     // parent's contextKey verbatim (createTaskExtended, src/be/db.ts:3556-3558).
     const inheritedContextKey = effectiveParentTask?.contextKey;
@@ -406,8 +427,8 @@ export async function sendTaskHandler(
   }
 
   // Auto-route to parent's worker if parentTaskId is set and no explicit agentId
-  let effectiveAgentId = agentId;
-  if (effectiveParentTaskId && !agentId) {
+  let effectiveAgentId = requestedAgentId;
+  if (effectiveParentTaskId && !requestedAgentId) {
     if (effectiveParentTask?.agentId) {
       effectiveAgentId = effectiveParentTask.agentId;
     }
@@ -421,15 +442,25 @@ export async function sendTaskHandler(
   });
   if (modelError) return toolErr(modelError, { data: { yourAgentId: creatorAgentId } });
   const effectiveRoutingReason =
-    agentId !== undefined ? routingReason : effectiveAgentId ? "continuity" : undefined;
-  const effectiveRoutingNote = effectiveRoutingReason ? routingNote : undefined;
+    requestedAgentId !== undefined
+      ? requestedRoutingReason
+      : effectiveAgentId
+        ? "continuity"
+        : undefined;
+  const effectiveRoutingNote = effectiveRoutingReason ? requestedRoutingNote : undefined;
   const effectiveRoutingSource =
-    agentId !== undefined ? "declared" : effectiveAgentId ? "engine_default" : undefined;
+    ctx.kind === "user"
+      ? "engine_default"
+      : requestedAgentId !== undefined
+        ? "declared"
+        : effectiveAgentId
+          ? "engine_default"
+          : undefined;
 
   const requestedTaskOptions: CreateTaskOptions = {
     key: assetKey,
-    agentId: offerMode ? undefined : effectiveAgentId,
-    offeredTo: offerMode ? effectiveAgentId : undefined,
+    agentId: requestedOfferMode ? undefined : effectiveAgentId,
+    offeredTo: requestedOfferMode ? effectiveAgentId : undefined,
     creatorAgentId,
     requestedByUserId,
     source: "mcp",
@@ -447,7 +478,7 @@ export async function sendTaskHandler(
     slackChannelId,
     slackThreadTs,
     slackUserId,
-    overrideSlackContext,
+    overrideSlackContext: requestedOverrideSlackContext,
     followUpConfig,
     // A delegation with parentTaskId is new work and starts without the
     // parent's followUpConfig. A `resume` re-delegation (the reroute-decision
@@ -458,8 +489,8 @@ export async function sendTaskHandler(
     routingSource: effectiveRoutingSource,
     routingNote: effectiveRoutingNote,
     routingAffinity:
-      effectiveLeadOnly || requiredCapabilities?.length
-        ? { leadOnly: effectiveLeadOnly, capabilities: requiredCapabilities ?? [] }
+      effectiveLeadOnly || requestedCapabilities?.length
+        ? { leadOnly: effectiveLeadOnly, capabilities: requestedCapabilities ?? [] }
         : undefined,
   };
   const preCreate = await applyPreTaskCreate({
@@ -477,6 +508,12 @@ export async function sendTaskHandler(
   }
   const taskDescription = preCreate.description;
   const taskOptions = preCreate.options;
+  if (
+    ctx.kind === "user" &&
+    (taskOptions.agentId !== userLead!.id || taskOptions.offeredTo !== undefined)
+  ) {
+    return toolErr("A pre.task.create extension cannot change the user task's Lead assignment.");
+  }
 
   // The three dedup guards are pure reads, so they run twice: once here as a
   // fast path (keeping this tool's existing early-exit responses), and once
@@ -500,7 +537,7 @@ export async function sendTaskHandler(
     }
 
     // Dedup guard: check for similar recent tasks
-    if (!allowDuplicate && creatorAgentId) {
+    if (!requestedAllowDuplicate && creatorAgentId) {
       const duplicate = await findDuplicateTask({
         taskDescription,
         creatorAgentId: taskOptions.creatorAgentId ?? creatorAgentId,
@@ -616,6 +653,13 @@ export async function sendTaskHandler(
       };
     }
 
+    if (ctx.kind === "user" && (!agent.isLead || agent.status === "offline")) {
+      return {
+        success: false,
+        message: "The Lead is no longer online. No task was created.",
+      };
+    }
+
     if (isExtensionAgent(agent)) {
       return { success: false, message: extensionAgentAssignmentError(agent) };
     }
@@ -628,7 +672,7 @@ export async function sendTaskHandler(
     }
 
     // For direct assignment (not offer), check if agent has capacity
-    if (!taskOptions.offeredTo && !(await hasCapacity(targetAgentId))) {
+    if (ctx.kind !== "user" && !taskOptions.offeredTo && !(await hasCapacity(targetAgentId))) {
       const activeCount = await getActiveTaskCount(targetAgentId);
       return {
         success: false,