@vellumai/assistant 0.5.16 → 0.6.0

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

@@ -0,0 +1,207 @@
+/**
+ * Route handlers for conversation group management.
+ *
+ * GET    /v1/groups              — list all groups
+ * POST   /v1/groups              — create a custom group
+ * PATCH  /v1/groups/:groupId     — update a group
+ * DELETE /v1/groups/:groupId     — delete a group
+ * POST   /v1/groups/reorder      — reorder groups
+ */
+
+import { z } from "zod";
+
+import {
+  createGroup,
+  deleteGroup,
+  getGroup,
+  listGroups,
+  reorderGroups,
+  updateGroup,
+} from "../../memory/group-crud.js";
+import { httpError } from "../http-errors.js";
+import type { RouteDefinition } from "../http-router.js";
+
+function serializeGroup(group: ReturnType<typeof getGroup>) {
+  if (!group) return null;
+  return {
+    id: group.id,
+    name: group.name,
+    sortPosition: group.sortPosition,
+    isSystemGroup: group.isSystemGroup,
+  };
+}
+
+export function groupRouteDefinitions(): RouteDefinition[] {
+  return [
+    {
+      endpoint: "groups",
+      method: "GET",
+      policyKey: "groups",
+      summary: "List groups",
+      description: "Return all conversation groups.",
+      tags: ["groups"],
+      handler: () => {
+        const groups = listGroups();
+        return Response.json({
+          groups: groups.map(serializeGroup),
+        });
+      },
+    },
+    {
+      endpoint: "groups",
+      method: "POST",
+      policyKey: "groups",
+      summary: "Create group",
+      description:
+        "Create a new custom conversation group. Server assigns sort_position.",
+      tags: ["groups"],
+      requestBody: z.object({
+        name: z.string().describe("Group name"),
+      }),
+      handler: async ({ req }) => {
+        const body = (await req.json()) as { name?: string };
+        if (!body.name || typeof body.name !== "string") {
+          return httpError("BAD_REQUEST", "Missing or invalid name", 400);
+        }
+        const group = createGroup(body.name);
+        return Response.json(serializeGroup(group), { status: 201 });
+      },
+    },
+    {
+      endpoint: "groups/:groupId",
+      method: "PATCH",
+      policyKey: "groups",
+      summary: "Update group",
+      description: "Update a conversation group's name or sort position.",
+      tags: ["groups"],
+      requestBody: z.object({
+        name: z.string().optional(),
+        sortPosition: z.number().optional(),
+      }),
+      handler: async ({ req, params }) => {
+        const groupId = params.groupId;
+        const existing = getGroup(groupId);
+        if (!existing) {
+          return httpError("NOT_FOUND", "Group not found", 404);
+        }
+        const body = (await req.json()) as {
+          name?: string;
+          sortPosition?: number;
+        };
+        if (body.name !== undefined && typeof body.name !== "string") {
+          return httpError("BAD_REQUEST", "name must be a string", 400);
+        }
+        if (
+          body.sortPosition !== undefined &&
+          typeof body.sortPosition !== "number"
+        ) {
+          return httpError("BAD_REQUEST", "sortPosition must be a number", 400);
+        }
+        // System groups allow name changes but block sortPosition/delete.
+        if (existing.isSystemGroup && body.sortPosition !== undefined) {
+          return httpError(
+            "FORBIDDEN",
+            "System group sort position cannot be changed",
+            403,
+          );
+        }
+        // Custom group sort_position must be >= 3
+        if (
+          body.sortPosition !== undefined &&
+          (typeof body.sortPosition !== "number" ||
+            !isFinite(body.sortPosition) ||
+            body.sortPosition < 3)
+        ) {
+          return httpError(
+            "BAD_REQUEST",
+            "Custom group sort_position must be >= 3",
+            400,
+          );
+        }
+        const updated = updateGroup(groupId, {
+          name: body.name,
+          sortPosition: body.sortPosition,
+        });
+        if (!updated) {
+          return httpError("NOT_FOUND", "Group not found", 404);
+        }
+        return Response.json(serializeGroup(updated));
+      },
+    },
+    {
+      endpoint: "groups/:groupId",
+      method: "DELETE",
+      policyKey: "groups",
+      summary: "Delete group",
+      description: "Delete a custom conversation group.",
+      tags: ["groups"],
+      handler: ({ params }) => {
+        const groupId = params.groupId;
+        const existing = getGroup(groupId);
+        if (!existing) {
+          return httpError("NOT_FOUND", "Group not found", 404);
+        }
+        // System groups cannot be deleted
+        if (existing.isSystemGroup) {
+          return httpError("FORBIDDEN", "System groups cannot be deleted", 403);
+        }
+        deleteGroup(groupId);
+        return new Response(null, { status: 204 });
+      },
+    },
+    {
+      endpoint: "groups/reorder",
+      method: "POST",
+      policyKey: "groups/reorder",
+      summary: "Reorder groups",
+      description: "Batch-update sort positions for conversation groups.",
+      tags: ["groups"],
+      requestBody: z.object({
+        updates: z
+          .array(
+            z.object({
+              groupId: z.string(),
+              sortPosition: z.number(),
+            }),
+          )
+          .describe("Array of { groupId, sortPosition } objects"),
+      }),
+      handler: async ({ req }) => {
+        const body = (await req.json()) as {
+          updates?: Array<{
+            groupId: string;
+            sortPosition: number;
+          }>;
+        };
+        if (!Array.isArray(body.updates)) {
+          return httpError("BAD_REQUEST", "Missing updates array", 400);
+        }
+        // Validate: no system group reordering, no sort_position < 3 for custom groups
+        for (const update of body.updates) {
+          const group = getGroup(update.groupId);
+          if (!group) continue;
+          if (group.isSystemGroup) {
+            return httpError(
+              "FORBIDDEN",
+              `Cannot reorder system group: ${update.groupId}`,
+              403,
+            );
+          }
+          if (
+            typeof update.sortPosition !== "number" ||
+            !isFinite(update.sortPosition) ||
+            update.sortPosition < 3
+          ) {
+            return httpError(
+              "BAD_REQUEST",
+              `Custom group sort_position must be >= 3 (got ${update.sortPosition} for ${update.groupId})`,
+              400,
+            );
+          }
+        }
+        reorderGroups(body.updates);
+        return Response.json({ ok: true });
+      },
+    },
+  ];
+}

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

@@ -23,7 +23,10 @@ import { requireBoundGuardian } from "../auth/require-bound-guardian.js";
 import type { AuthContext } from "../auth/types.js";
 import { processGuardianDecision } from "../guardian-action-service.js";
 import type { GuardianDecisionPrompt } from "../guardian-decision-types.js";
-import { buildDecisionActions } from "../guardian-decision-types.js";
+import {
+  buildDecisionActions,
+  GUARDIAN_DECISION_ACTIONS,
+} from "../guardian-decision-types.js";
 import { httpError } from "../http-errors.js";
 import type { RouteDefinition } from "../http-router.js";
 
@@ -190,13 +193,15 @@ export function listGuardianDecisionPrompts(params: {
  * Map a canonical guardian request to the client-facing prompt format.
  *
  * Generates kind-specific questionText and action sets:
- * - `tool_approval`: "Approve tool: <name>" with approve/reject actions
- * - `pending_question`: voice-originated question with approve/reject actions
- * - `access_request`: explicit "Access Request" label with approve/reject actions
- *   and text fallback instructions (request code + "open invite flow")
+ * - `tool_approval`: temporal modes (approve_once, approve_10m, approve_conversation) + reject
+ * - `pending_question`: approve_once + reject only
+ * - `access_request`: approve_once + reject only, with text fallback instructions
+ *   (request code + "open invite flow")
+ * - `tool_grant_request`: approve_once + reject only
  *
- * All kinds use `forGuardianOnBehalf: true` (no approve_always) since the
- * guardian is acting on behalf of a requester.
+ * Only `tool_approval` receives temporal modes because time-scoped grants
+ * are meaningful only for tool execution. All other kinds get a simple
+ * approve_once/reject pair.
  */
 function mapCanonicalRequestToPrompt(
   req: CanonicalGuardianRequest,
@@ -204,9 +209,15 @@ function mapCanonicalRequestToPrompt(
 ): GuardianDecisionPrompt {
   const questionText = buildKindAwareQuestionText(req);
 
-  // Guardian-on-behalf prompts include approve_once, temporal modes
-  // (approve_10m, approve_conversation), and reject — but not approve_always.
-  const actions = buildDecisionActions({ forGuardianOnBehalf: true });
+  // Only tool_approval gets temporal modes (approve_10m, approve_conversation);
+  // all other kinds get a simple approve_once + reject pair.
+  const actions =
+    req.kind === "tool_approval"
+      ? buildDecisionActions({ forGuardianOnBehalf: true })
+      : [
+          GUARDIAN_DECISION_ACTIONS.approve_once,
+          GUARDIAN_DECISION_ACTIONS.reject,
+        ];
 
   const expiresAt = req.expiresAt
     ? new Date(req.expiresAt).getTime()

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

@@ -19,7 +19,7 @@ import { getLogger } from "../../util/logger.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "../assistant-scope.js";
 import { mintCredentialPair } from "../auth/credential-service.js";
 import { httpError } from "../http-errors.js";
-import { isPrivateAddress } from "../middleware/auth.js";
+import { isLoopbackAddress, isPrivateAddress } from "../middleware/auth.js";
 
 /** Bun server shape needed for requestIP -- avoids importing the full Bun type. */
 type ServerWithRequestIP = {
@@ -87,30 +87,34 @@ export async function handleGuardianBootstrap(
   req: Request,
   server: ServerWithRequestIP,
 ): Promise<Response> {
-  // Reject non-private-network peers (allows loopback, Docker bridge, etc.)
+  // In non-containerized (bare-metal) mode, restrict to loopback only —
+  // the runtime binds to localhost and LAN peers should not be able to
+  // bootstrap even if they somehow reach the endpoint.
+  // In containerized (Docker) mode, accept any private-network peer because
+  // the gateway connects over the Docker bridge (e.g. 172.17.0.1) and the
+  // GUARDIAN_BOOTSTRAP_SECRET enforced at the gateway layer provides the
+  // real authentication.
   const peerIp = server.requestIP(req)?.address;
-  if ((!peerIp || !isPrivateAddress(peerIp)) && !isHttpAuthDisabled()) {
+  const containerized = getIsContainerized();
+  const peerAllowed = containerized
+    ? isPrivateAddress(peerIp ?? "")
+    : isLoopbackAddress(peerIp ?? "");
+  if (!peerAllowed && !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.
+  // In non-containerized mode, any x-forwarded-for header means the request
+  // came through the gateway from a non-loopback client. Legitimate bare-metal
+  // bootstrap clients connect from localhost; the gateway does not inject
+  // x-forwarded-for for loopback peers (see gateway/src/index.ts). Reject
+  // forwarded requests to prevent LAN-adjacent clients from bootstrapping.
   //
-  // 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.
+  // In containerized mode, skip this check: the peer IP was already validated
+  // above (Docker bridge network = private), and the x-forwarded-for header
+  // reflects the original external client which 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() &&
-    !getIsContainerized()
-  ) {
+  if (forwarded && !isHttpAuthDisabled() && !getIsContainerized()) {
     return httpError("FORBIDDEN", "Bootstrap endpoint is local-only", 403);
   }
 

package/src/runtime/routes/inbound-message-handler.ts

@@ -44,6 +44,7 @@ import { processChannelMessageInBackground } from "./inbound-stages/background-d
 import { handleBootstrapIntercept } from "./inbound-stages/bootstrap-intercept.js";
 import { handleEditIntercept } from "./inbound-stages/edit-intercept.js";
 import { handleEscalationIntercept } from "./inbound-stages/escalation-intercept.js";
+import { handleGuardianActivationIntercept } from "./inbound-stages/guardian-activation-intercept.js";
 import { handleGuardianReplyIntercept } from "./inbound-stages/guardian-reply-intercept.js";
 import { runSecretIngressCheck } from "./inbound-stages/secret-ingress-check.js";
 import { tryTranscribeAudioAttachments } from "./inbound-stages/transcribe-audio.js";
@@ -199,6 +200,24 @@ export async function handleChannelInbound(
   // ACL deny path rather than bypassing it.
   const hasSenderIdentityClaim = rawSenderId !== undefined;
 
+  // ── Guardian channel activation ──
+  // When a bare /start arrives on a channel with no guardian, auto-initiate
+  // guardian verification so the first user can claim the channel.
+  const guardianActivationResponse = await handleGuardianActivationIntercept({
+    sourceChannel,
+    conversationExternalId,
+    rawSenderId,
+    canonicalSenderId,
+    actorDisplayName: body.actorDisplayName,
+    actorUsername: body.actorUsername,
+    sourceMetadata: body.sourceMetadata,
+    replyCallbackUrl: body.replyCallbackUrl,
+    mintBearerToken,
+    assistantId,
+    externalMessageId,
+  });
+  if (guardianActivationResponse) return guardianActivationResponse;
+
   // ── Ingress ACL enforcement ──
   const aclResult = await enforceIngressAcl({
     canonicalSenderId,

package/src/runtime/routes/inbound-stages/guardian-activation-intercept.test.ts

@@ -0,0 +1,292 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
+
+// ---------------------------------------------------------------------------
+// Mocks — must be set up before importing the module under test
+// ---------------------------------------------------------------------------
+
+let mockGuardian: { contact: unknown; channel: unknown } | null = null;
+let mockActiveSession: Record<string, unknown> | null = null;
+let mockSessionResult = {
+  sessionId: "sess-1",
+  secret: "123456",
+  challengeHash: "hash-1",
+  expiresAt: Date.now() + 600_000,
+  ttlSeconds: 600,
+};
+
+// Track calls manually to avoid TypeScript issues with mock() generics
+let createOutboundSessionCalls: unknown[] = [];
+let deliverChannelReplyCalls: unknown[][] = [];
+let emitNotificationSignalCalls: unknown[] = [];
+let messageIdCounter = 0;
+
+mock.module("../../../contacts/contact-store.js", () => ({
+  findGuardianForChannel: () => mockGuardian,
+}));
+
+mock.module("../../channel-verification-service.js", () => ({
+  createOutboundSession: (params: unknown) => {
+    createOutboundSessionCalls.push(params);
+    return mockSessionResult;
+  },
+  findActiveSession: () => mockActiveSession,
+}));
+
+mock.module("../../gateway-client.js", () => ({
+  deliverChannelReply: (url: unknown, payload: unknown, token: unknown) => {
+    deliverChannelReplyCalls.push([url, payload, token]);
+    return Promise.resolve({ ok: true });
+  },
+}));
+
+mock.module("../../../notifications/emit-signal.js", () => ({
+  emitNotificationSignal: (params: unknown) => {
+    emitNotificationSignalCalls.push(params);
+    return Promise.resolve({
+      signalId: "sig-1",
+      deduplicated: false,
+      dispatched: true,
+      reason: "ok",
+      deliveryResults: [],
+    });
+  },
+}));
+
+mock.module("../../../util/logger.js", () => ({
+  getLogger: () => ({
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+  }),
+}));
+
+// Import after mocks are installed
+const { handleGuardianActivationIntercept } =
+  await import("./guardian-activation-intercept.js");
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeParams(
+  overrides: Partial<
+    Parameters<typeof handleGuardianActivationIntercept>[0]
+  > = {},
+) {
+  messageIdCounter++;
+  return {
+    sourceChannel: "telegram" as const,
+    conversationExternalId: "chat-123",
+    rawSenderId: "user-42",
+    canonicalSenderId: "user-42",
+    actorDisplayName: "Alice",
+    actorUsername: "alice",
+    sourceMetadata: { commandIntent: { type: "start" } },
+    replyCallbackUrl: "https://gateway/reply",
+    mintBearerToken: () => "token-123",
+    assistantId: "self",
+    externalMessageId: `msg-${messageIdCounter}`,
+    ...overrides,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("handleGuardianActivationIntercept", () => {
+  beforeEach(() => {
+    mockGuardian = null;
+    mockActiveSession = null;
+    mockSessionResult = {
+      sessionId: "sess-1",
+      secret: "123456",
+      challengeHash: "hash-1",
+      expiresAt: Date.now() + 600_000,
+      ttlSeconds: 600,
+    };
+    createOutboundSessionCalls = [];
+    deliverChannelReplyCalls = [];
+    emitNotificationSignalCalls = [];
+  });
+
+  afterEach(() => {
+    createOutboundSessionCalls = [];
+    deliverChannelReplyCalls = [];
+    emitNotificationSignalCalls = [];
+  });
+
+  test("bare /start with no guardian creates session and returns early", async () => {
+    const result = await handleGuardianActivationIntercept(makeParams());
+
+    expect(result).not.toBeNull();
+    const body = await result!.json();
+    expect(body).toEqual({ accepted: true, guardianActivation: true });
+
+    // Verify createOutboundSession was called with correct params
+    expect(createOutboundSessionCalls).toHaveLength(1);
+    expect(createOutboundSessionCalls[0]).toEqual({
+      channel: "telegram",
+      expectedExternalUserId: "user-42",
+      expectedChatId: "chat-123",
+      identityBindingStatus: "bound",
+      destinationAddress: "chat-123",
+      verificationPurpose: "guardian",
+    });
+
+    // Verify deliverChannelReply was called with the welcome/verify message
+    expect(deliverChannelReplyCalls).toHaveLength(1);
+    expect(deliverChannelReplyCalls[0][0]).toBe("https://gateway/reply");
+    expect(deliverChannelReplyCalls[0][1]).toEqual({
+      chatId: "chat-123",
+      text: "Welcome! To verify your identity as guardian, check your assistant app for a verification code and enter it here.",
+      assistantId: "self",
+    });
+
+    // Verify emitNotificationSignal was called with guardian.channel_activation
+    expect(emitNotificationSignalCalls).toHaveLength(1);
+    const signalArgs = emitNotificationSignalCalls[0] as Record<string, any>;
+    expect(signalArgs.sourceEventName).toBe("guardian.channel_activation");
+    expect(signalArgs.contextPayload.verificationCode).toBe("123456");
+    expect(signalArgs.contextPayload.sourceChannel).toBe("telegram");
+    expect(signalArgs.contextPayload.actorExternalId).toBe("user-42");
+    expect(signalArgs.contextPayload.sessionId).toBe("sess-1");
+    expect(signalArgs.dedupeKey).toBe("guardian-activation:sess-1");
+  });
+
+  test("bare /start with existing guardian returns null", async () => {
+    mockGuardian = {
+      contact: { id: "contact-1", role: "guardian" },
+      channel: { id: "ch-1", type: "telegram" },
+    };
+
+    const result = await handleGuardianActivationIntercept(makeParams());
+    expect(result).toBeNull();
+    expect(createOutboundSessionCalls).toHaveLength(0);
+  });
+
+  test("/start with payload returns null", async () => {
+    const result = await handleGuardianActivationIntercept(
+      makeParams({
+        sourceMetadata: {
+          commandIntent: { type: "start", payload: "gv_token" },
+        },
+      }),
+    );
+    expect(result).toBeNull();
+    expect(createOutboundSessionCalls).toHaveLength(0);
+  });
+
+  test("non-/start message returns null", async () => {
+    const result = await handleGuardianActivationIntercept(
+      makeParams({
+        sourceMetadata: { commandIntent: { type: "other" } },
+      }),
+    );
+    expect(result).toBeNull();
+    expect(createOutboundSessionCalls).toHaveLength(0);
+  });
+
+  test("no commandIntent returns null", async () => {
+    const result = await handleGuardianActivationIntercept(
+      makeParams({ sourceMetadata: {} }),
+    );
+    expect(result).toBeNull();
+
+    const result2 = await handleGuardianActivationIntercept(
+      makeParams({ sourceMetadata: undefined }),
+    );
+    expect(result2).toBeNull();
+    expect(createOutboundSessionCalls).toHaveLength(0);
+  });
+
+  test("non-telegram channel returns null", async () => {
+    const result = await handleGuardianActivationIntercept(
+      makeParams({ sourceChannel: "slack" as any }),
+    );
+    expect(result).toBeNull();
+    expect(createOutboundSessionCalls).toHaveLength(0);
+  });
+
+  test("missing sender ID returns null", async () => {
+    const result = await handleGuardianActivationIntercept(
+      makeParams({ rawSenderId: undefined }),
+    );
+    expect(result).toBeNull();
+    expect(createOutboundSessionCalls).toHaveLength(0);
+  });
+
+  test("existing active session from same sender sends 'already in progress' reply", async () => {
+    mockActiveSession = {
+      id: "existing-sess",
+      channel: "telegram",
+      status: "awaiting_response",
+      expectedExternalUserId: "user-42",
+      expectedChatId: "chat-123",
+    };
+
+    const result = await handleGuardianActivationIntercept(makeParams());
+
+    expect(result).not.toBeNull();
+    const body = await result!.json();
+    expect(body).toEqual({ accepted: true, guardianActivationPending: true });
+
+    // createOutboundSession should NOT be called
+    expect(createOutboundSessionCalls).toHaveLength(0);
+
+    // deliverChannelReply should be called with the "already in progress" message
+    expect(deliverChannelReplyCalls).toHaveLength(1);
+    expect(deliverChannelReplyCalls[0][1]).toEqual({
+      chatId: "chat-123",
+      text: "A verification is already in progress. Check your assistant app for the code and enter it here.",
+      assistantId: "self",
+    });
+
+    // emitNotificationSignal should NOT be called
+    expect(emitNotificationSignalCalls).toHaveLength(0);
+  });
+
+  test("existing active session from different sender allows superseding", async () => {
+    mockActiveSession = {
+      id: "existing-sess",
+      channel: "telegram",
+      status: "awaiting_response",
+      expectedExternalUserId: "user-OTHER",
+      expectedChatId: "chat-OTHER",
+    };
+
+    const result = await handleGuardianActivationIntercept(makeParams());
+
+    // Should proceed and create a new session (superseding the stale one)
+    expect(result).not.toBeNull();
+    const body = await result!.json();
+    expect(body).toEqual({ accepted: true, guardianActivation: true });
+    expect(createOutboundSessionCalls).toHaveLength(1);
+    expect(emitNotificationSignalCalls).toHaveLength(1);
+  });
+
+  test("duplicate webhook retry is silently deduped", async () => {
+    const params = makeParams({ externalMessageId: "dedup-test-msg" });
+
+    // First call should process normally
+    const result1 = await handleGuardianActivationIntercept(params);
+    expect(result1).not.toBeNull();
+    const body1 = await result1!.json();
+    expect(body1).toEqual({ accepted: true, guardianActivation: true });
+    expect(createOutboundSessionCalls).toHaveLength(1);
+    expect(deliverChannelReplyCalls).toHaveLength(1);
+    expect(emitNotificationSignalCalls).toHaveLength(1);
+
+    // Second call with same externalMessageId should be deduped
+    const result2 = await handleGuardianActivationIntercept(params);
+    expect(result2).not.toBeNull();
+    const body2 = await result2!.json();
+    expect(body2).toEqual({ accepted: true, guardianActivation: true });
+
+    // No additional session/reply/signal calls
+    expect(createOutboundSessionCalls).toHaveLength(1);
+    expect(deliverChannelReplyCalls).toHaveLength(1);
+    expect(emitNotificationSignalCalls).toHaveLength(1);
+  });
+});