@desplega.ai/agent-swarm 1.78.1 → 1.79.1

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

@@ -0,0 +1,194 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAgentById, upsertKv } from "@/be/db";
+import { createToolRegistrar } from "@/tools/utils";
+import { KvEntrySchema, KvKeySchema, KvNamespaceSchema, KvValueTypeSchema } from "@/types";
+import { resolveNamespace } from "./resolve-namespace";
+
+// 2 MiB cap — mirrors the HTTP enforcement.
+const MAX_KV_BODY_BYTES = 2 * 1024 * 1024;
+
+function authError(namespace: string, info: { agentId: string | undefined }): string | null {
+  if (namespace.startsWith("task:page:")) {
+    // MCP requests don't carry an X-Page-Id; page writes must go through the
+    // browser SDK + page proxy.
+    return "task:page:* writes require a page-proxy request, not an MCP call";
+  }
+  if (namespace.startsWith("task:agent:")) {
+    const target = namespace.slice("task:agent:".length);
+    if (info.agentId && target === info.agentId) return null;
+    if (info.agentId) {
+      const agent = getAgentById(info.agentId);
+      if (agent?.isLead) return null;
+    }
+    return "writes to another agent's namespace require lead";
+  }
+  return null;
+}
+
+export const registerKvSetTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "kv-set",
+    {
+      title: "KV Set",
+      description:
+        "Write a key in the swarm KV store. Upserts atomically. Namespace defaults to your current context. Use `expiresInSec` for opt-in TTL (default: never expires). 2 MiB body cap.",
+      annotations: { idempotentHint: true },
+
+      inputSchema: z.object({
+        key: KvKeySchema.describe("KV key (≤512 chars, [a-zA-Z0-9._:/-])."),
+        value: z
+          .unknown()
+          .describe(
+            "Value. Stored as JSON by default; pass `valueType: 'string'` or `'integer'` to skip JSON wrapping.",
+          ),
+        valueType: KvValueTypeSchema.optional().describe(
+          "How to encode `value`. Defaults to 'json'. 'integer' is required for INCR.",
+        ),
+        expiresInSec: z
+          .number()
+          .int()
+          .positive()
+          .optional()
+          .describe("Optional TTL in seconds. Omit for no expiry."),
+        namespace: KvNamespaceSchema.optional().describe(
+          "Optional explicit namespace. Defaults to the caller's contextKey.",
+        ),
+      }),
+      outputSchema: z.object({
+        yourAgentId: z.string().uuid().optional(),
+        success: z.boolean(),
+        message: z.string(),
+        namespace: z.string().optional(),
+        entry: KvEntrySchema.optional(),
+      }),
+    },
+    async ({ key, value, valueType, expiresInSec, namespace }, requestInfo) => {
+      const resolved = resolveNamespace(namespace, requestInfo);
+      if ("error" in resolved) {
+        return {
+          content: [{ type: "text", text: resolved.error }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: resolved.error,
+          },
+        };
+      }
+
+      const authErr = authError(resolved.namespace, { agentId: requestInfo.agentId });
+      if (authErr) {
+        return {
+          content: [{ type: "text", text: authErr }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: authErr,
+            namespace: resolved.namespace,
+          },
+        };
+      }
+
+      const finalValueType = valueType ?? "json";
+      // Pre-flight encode to surface validation errors as a structured tool
+      // response (rather than letting `upsertKv` throw).
+      let encodedSize: number;
+      try {
+        if (finalValueType === "json") {
+          const stringified = JSON.stringify(value);
+          if (stringified === undefined) {
+            const msg = "value is not JSON-encodable";
+            return {
+              content: [{ type: "text", text: msg }],
+              structuredContent: {
+                yourAgentId: requestInfo.agentId,
+                success: false,
+                message: msg,
+                namespace: resolved.namespace,
+              },
+            };
+          }
+          encodedSize = Buffer.byteLength(stringified, "utf8");
+        } else if (finalValueType === "integer") {
+          if (typeof value === "number") {
+            if (!Number.isInteger(value) || !Number.isSafeInteger(value)) {
+              throw new Error("integer value must be a JS-safe integer");
+            }
+            encodedSize = String(value).length;
+          } else if (typeof value === "string" && /^-?\d+$/.test(value)) {
+            encodedSize = value.length;
+          } else {
+            throw new Error("integer value must be a JS-safe integer");
+          }
+        } else {
+          if (typeof value !== "string") {
+            throw new Error("string value must be a string");
+          }
+          encodedSize = Buffer.byteLength(value, "utf8");
+        }
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : "encoding error";
+        return {
+          content: [{ type: "text", text: msg }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: msg,
+            namespace: resolved.namespace,
+          },
+        };
+      }
+
+      if (encodedSize > MAX_KV_BODY_BYTES) {
+        const msg = `Payload too large (max ${MAX_KV_BODY_BYTES} bytes)`;
+        return {
+          content: [{ type: "text", text: msg }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: msg,
+            namespace: resolved.namespace,
+          },
+        };
+      }
+
+      const expiresAt = expiresInSec !== undefined ? Date.now() + expiresInSec * 1000 : null;
+
+      try {
+        const entry = upsertKv({
+          namespace: resolved.namespace,
+          key,
+          value,
+          valueType: finalValueType,
+          expiresAt,
+        });
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Set "${key}" in "${resolved.namespace}".`,
+            },
+          ],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: true,
+            message: "ok",
+            namespace: resolved.namespace,
+            entry,
+          },
+        };
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : "upsert failed";
+        return {
+          content: [{ type: "text", text: msg }],
+          structuredContent: {
+            yourAgentId: requestInfo.agentId,
+            success: false,
+            message: msg,
+            namespace: resolved.namespace,
+          },
+        };
+      }
+    },
+  );
+};

package/src/tools/kv/resolve-namespace.ts

@@ -0,0 +1,58 @@
+import { getTaskById } from "@/be/db";
+import { agentContextKey } from "@/tasks/context-key";
+import type { RequestInfo } from "@/tools/utils";
+
+/**
+ * Resolve the KV namespace for an MCP tool call.
+ *
+ * Tools call this when the user didn't pass an explicit `namespace`. The MCP
+ * `RequestInfo` exposes `sourceTaskId` (from `X-Source-Task-Id` header) and
+ * `agentId` (from `X-Agent-ID`), mirroring the HTTP-layer precedence:
+ *
+ *   1. explicit `namespace` (handled by the tool, not us)
+ *   2. `sourceTaskId` → that task's `contextKey`
+ *   3. `agentId` → `task:agent:<id>`
+ *   4. nothing — caller is told to pass `namespace`
+ *
+ * Note: MCP doesn't carry `X-Page-Id` (pages call the REST surface directly
+ * via the browser SDK, not MCP), so page-scoped resolution is HTTP-only.
+ */
+export interface ResolvedNamespace {
+  namespace: string;
+  source: "explicit" | "task" | "agent";
+}
+
+export function resolveNamespace(
+  explicit: string | undefined,
+  info: RequestInfo,
+): ResolvedNamespace | { error: string } {
+  if (explicit && explicit.length > 0) {
+    return { namespace: explicit, source: "explicit" };
+  }
+
+  if (info.sourceTaskId) {
+    const task = getTaskById(info.sourceTaskId);
+    if (task?.contextKey) {
+      return { namespace: task.contextKey, source: "task" };
+    }
+    if (task?.agentId) {
+      try {
+        return { namespace: agentContextKey({ agentId: task.agentId }), source: "agent" };
+      } catch {
+        // fall through
+      }
+    }
+  }
+
+  if (info.agentId) {
+    try {
+      return { namespace: agentContextKey({ agentId: info.agentId }), source: "agent" };
+    } catch {
+      // fall through to error
+    }
+  }
+
+  return {
+    error: "namespace could not be resolved — pass `namespace` or run with X-Agent-ID set",
+  };
+}

package/src/tools/skills/skill-update.ts

@@ -16,6 +16,12 @@ export const registerSkillUpdateTool = (server: McpServer) => {
         skillId: z.string().optional().describe("Skill ID to update"),
         content: z.string().optional().describe("New SKILL.md content (re-parses frontmatter)"),
         isEnabled: z.boolean().optional().describe("Toggle enabled/disabled"),
+        scope: z
+          .enum(["agent", "swarm"])
+          .optional()
+          .describe(
+            "Scope: agent (personal) or swarm (shared). Only leads can promote a skill to swarm scope (used by the skill-approval flow).",
+          ),
       }),
       outputSchema: z.object({
         yourAgentId: z.string().uuid().optional(),
@@ -91,6 +97,26 @@ export const registerSkillUpdateTool = (server: McpServer) => {
           updates.isEnabled = args.isEnabled;
         }
 
+        if (args.scope !== undefined && args.scope !== existing.scope) {
+          // Promoting to swarm scope is the skill-approval path — only leads may do it.
+          if (args.scope === "swarm" && !agent?.isLead) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: 'Only lead agents can promote a skill to "swarm" scope. Use "skill-publish" to request approval.',
+                },
+              ],
+              structuredContent: {
+                yourAgentId: requestInfo.agentId,
+                success: false,
+                message: "Only lead agents can promote a skill to swarm scope.",
+              },
+            };
+          }
+          updates.scope = args.scope;
+        }
+
         const skill = updateSkill(args.skillId, updates);
         if (!skill) {
           return {

package/src/tools/tool-config.ts

@@ -144,6 +144,16 @@ export const DEFERRED_TOOLS = new Set([
   "resolve-user",
   "manage-user",
 
+  // Pages (1)
+  "create_page",
+
+  // KV store (5)
+  "kv-get",
+  "kv-set",
+  "kv-delete",
+  "kv-incr",
+  "kv-list",
+
   // Other (3)
   "cancel-task",
   "inject-learning",

package/src/types.ts

@@ -1087,6 +1087,61 @@ export const WorkflowVersionSchema = z.object({
 });
 export type WorkflowVersion = z.infer<typeof WorkflowVersionSchema>;
 
+// ---------------------------------------------------------------------------
+// Pages — DB-backed lightweight artifacts (HTML or JSON spec) stored in
+// SQLite and served at /p/:id. See plan: thoughts/taras/plans/2026-05-12-db-backed-pages/.
+// PageContentTypeSchema + PageAuthModeSchema MUST stay in sync with the SQL
+// CHECK constraints in src/be/migrations/059_pages.sql.
+// ---------------------------------------------------------------------------
+
+export const PageContentTypeSchema = z.enum(["text/html", "application/json"]);
+export type PageContentType = z.infer<typeof PageContentTypeSchema>;
+
+export const PageAuthModeSchema = z.enum(["public", "authed", "password"]);
+export type PageAuthMode = z.infer<typeof PageAuthModeSchema>;
+
+// PageSnapshot captures the mutable content fields frozen per-version in
+// page_versions.snapshot. Omits id / agentId / slug / timestamps (these are
+// invariant across versions for a given page id; the slug is a parent-only
+// identifier).
+export const PageSnapshotSchema = z.object({
+  title: z.string(),
+  description: z.string().optional(),
+  contentType: PageContentTypeSchema,
+  authMode: PageAuthModeSchema,
+  passwordHash: z.string().optional(),
+  body: z.string(),
+  needsCredentials: z.array(z.string()).optional(),
+});
+export type PageSnapshot = z.infer<typeof PageSnapshotSchema>;
+
+export const PageSchema = z.object({
+  id: z.string(),
+  agentId: z.string(),
+  slug: z.string(),
+  title: z.string(),
+  description: z.string().optional(),
+  contentType: PageContentTypeSchema,
+  authMode: PageAuthModeSchema,
+  passwordHash: z.string().optional(),
+  body: z.string(),
+  needsCredentials: z.array(z.string()).optional(),
+  viewCount: z.number().int().min(0).default(0),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type Page = z.infer<typeof PageSchema>;
+
+export const PageVersionSchema = z.object({
+  id: z.string(),
+  pageId: z.string(),
+  version: z.number().int().min(1),
+  snapshot: PageSnapshotSchema,
+  changedByAgentId: z.string().optional(),
+  createdAt: z.string(),
+});
+export type PageVersion = z.infer<typeof PageVersionSchema>;
+
 // --- Workflow Run ---
 
 export const WorkflowRunStatusSchema = z.enum([
@@ -1426,3 +1481,55 @@ export const BudgetRefusedTriggerSchema = z.object({
   resetAt: z.string(), // ISO 8601, next UTC midnight
 });
 export type BudgetRefusedTrigger = z.infer<typeof BudgetRefusedTriggerSchema>;
+
+// ─── KV store ────────────────────────────────────────────────────────────────
+
+/**
+ * `value_type` of a KV entry.
+ *
+ *  - `'json'`    — `value` is JSON-encoded; default.
+ *  - `'string'`  — `value` is the raw UTF-8 string verbatim.
+ *  - `'integer'` — `value` is the decimal-string form of a JS-safe integer.
+ *                  Required by INCR; mixing with 'json'/'string' returns 409.
+ */
+export const KvValueTypeSchema = z.enum(["json", "string", "integer"]);
+export type KvValueType = z.infer<typeof KvValueTypeSchema>;
+
+/** Shared regex for both namespace and key — keeps colons/slashes welcome for
+ * sub-namespacing inside a single key. Matches the `contextKey` schema in
+ * `src/tasks/context-key.ts`; we don't enforce it parses as a known family.
+ *
+ * `%` is accepted because path-segment params arrive percent-encoded on the
+ * REST surface (e.g. `:` → `%3A` after `encodeURIComponent`); the kv handler
+ * decodes the segment before persisting, and the decoded form is itself a
+ * subset of this regex (no `%` chars in legal contextKeys).
+ */
+export const KV_NAME_REGEX = /^[a-zA-Z0-9._:/%-]{1,512}$/;
+
+export const KvNamespaceSchema = z
+  .string()
+  .min(1)
+  .max(512)
+  .regex(KV_NAME_REGEX, "namespace must match [a-zA-Z0-9._:/%-]{1,512}");
+
+export const KvKeySchema = z
+  .string()
+  .min(1)
+  .max(512)
+  .regex(KV_NAME_REGEX, "key must match [a-zA-Z0-9._:/%-]{1,512}");
+
+/**
+ * A single KV row, as returned by the API. `value` is decoded per
+ * `valueType`: `'json'` returns the parsed JS value, `'string'` returns the
+ * raw string, `'integer'` returns a number.
+ */
+export const KvEntrySchema = z.object({
+  namespace: z.string(),
+  key: z.string(),
+  value: z.unknown(),
+  valueType: KvValueTypeSchema,
+  expiresAt: z.number().int().nullable(),
+  createdAt: z.number().int(),
+  updatedAt: z.number().int(),
+});
+export type KvEntry = z.infer<typeof KvEntrySchema>;

package/src/utils/internal-ai/complete-structured.ts

@@ -15,8 +15,8 @@
  * Worker-safe: uses fetch() only, no bun:sqlite import.
  */
 
-import type { ToolCall } from "@mariozechner/pi-ai";
-import { complete, getModel } from "@mariozechner/pi-ai";
+import type { ToolCall } from "@earendil-works/pi-ai";
+import { complete, getModel } from "@earendil-works/pi-ai";
 import type { TSchema } from "typebox";
 import { z } from "zod";
 import { type ResolvedCredential, resolveCredential } from "./credentials.js";

package/src/utils/internal-ai/credentials.ts

@@ -15,9 +15,9 @@
  * Worker-safe: uses fetch() only, no bun:sqlite import.
  */
 
-import type { OAuthCredentials } from "@mariozechner/pi-ai";
-import { getEnvApiKey } from "@mariozechner/pi-ai";
-import { getOAuthApiKey } from "@mariozechner/pi-ai/oauth";
+import type { OAuthCredentials } from "@earendil-works/pi-ai";
+import { getEnvApiKey } from "@earendil-works/pi-ai";
+import { getOAuthApiKey } from "@earendil-works/pi-ai/oauth";
 import { getValidCodexOAuth, persistCodexOAuth } from "../../providers/codex-oauth/storage.js";
 import { type CredentialKind, DEFAULT_MODEL, resolveModelString } from "./models.js";