@vellumai/assistant 0.10.7 → 0.10.8-dev.202607102228.5945895

package/src/channels/__tests__/gateway-invites.test.ts

@@ -0,0 +1,257 @@
+/**
+ * Tests for the gateway-backed invite client.
+ *
+ * The IPC transport is stubbed; each wrapper is exercised for wire-method +
+ * param mapping, contract-schema validation of responses, malformed-response
+ * rejection, and unchanged propagation of transport errors (fail-closed —
+ * an `IpcCallError` keeps its gateway statusCode for the relay routes).
+ */
+
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+
+import { INVITES_IPC_METHODS } from "@vellumai/gateway-client";
+import { IpcCallError } from "@vellumai/gateway-client/ipc-client";
+
+type IpcCall = { method: string; params?: Record<string, unknown> };
+
+let ipcCalls: IpcCall[] = [];
+let ipcResponse: unknown;
+let ipcError: Error | null = null;
+
+const ipcCallPersistentMock = mock(
+  async (method: string, params?: Record<string, unknown>) => {
+    ipcCalls.push({ method, params });
+    if (ipcError) {
+      throw ipcError;
+    }
+    return ipcResponse;
+  },
+);
+const actualGatewayClient = await import("../../ipc/gateway-client.js");
+mock.module("../../ipc/gateway-client.js", () => ({
+  ...actualGatewayClient,
+  ipcCallPersistent: ipcCallPersistentMock,
+}));
+
+const client = await import("../gateway-invites.js");
+
+const inviteRow = {
+  id: "inv-1",
+  sourceChannel: "telegram",
+  status: "active",
+  maxUses: 1,
+  useCount: 0,
+};
+
+beforeEach(() => {
+  ipcCalls = [];
+  ipcResponse = undefined;
+  ipcError = null;
+});
+
+describe("listInvites", () => {
+  test("relays invites_list with only the provided filters", async () => {
+    ipcResponse = { invites: [inviteRow] };
+
+    const invites = await client.listInvites({
+      sourceChannel: "telegram",
+      status: "active",
+    });
+
+    expect(ipcCalls).toEqual([
+      {
+        method: INVITES_IPC_METHODS.list,
+        params: { sourceChannel: "telegram", status: "active" },
+      },
+    ]);
+    expect(invites).toEqual([inviteRow]);
+  });
+
+  test("sends empty params when no filters are given", async () => {
+    ipcResponse = { invites: [] };
+
+    await client.listInvites();
+
+    expect(ipcCalls).toEqual([
+      { method: INVITES_IPC_METHODS.list, params: {} },
+    ]);
+  });
+
+  test("rejects a malformed response", async () => {
+    ipcResponse = { invites: [{ sourceChannel: "telegram" }] };
+
+    await expect(client.listInvites()).rejects.toThrow(
+      "malformed invites_list response",
+    );
+  });
+});
+
+describe("createInvite", () => {
+  test("relays invites_create and returns the one-time payload", async () => {
+    ipcResponse = {
+      invite: { ...inviteRow, token: "raw-tok" },
+      rawToken: "raw-tok",
+    };
+
+    const result = await client.createInvite({
+      contactId: "c1",
+      sourceChannel: "telegram",
+      note: "hi",
+      maxUses: 2,
+    });
+
+    expect(ipcCalls).toEqual([
+      {
+        method: INVITES_IPC_METHODS.create,
+        params: {
+          contactId: "c1",
+          sourceChannel: "telegram",
+          note: "hi",
+          maxUses: 2,
+        },
+      },
+    ]);
+    expect(result).toEqual({
+      invite: { ...inviteRow, token: "raw-tok" },
+      rawToken: "raw-tok",
+    });
+  });
+
+  test("tolerates an absent rawToken (voice invites)", async () => {
+    ipcResponse = { invite: { ...inviteRow, sourceChannel: "phone" } };
+
+    const result = await client.createInvite({
+      contactId: "c1",
+      sourceChannel: "phone",
+    });
+
+    expect(result.rawToken).toBeUndefined();
+  });
+
+  test("rejects a malformed response", async () => {
+    ipcResponse = { invite: { id: "inv-1" } };
+
+    await expect(
+      client.createInvite({ contactId: "c1", sourceChannel: "telegram" }),
+    ).rejects.toThrow("malformed invites_create response");
+  });
+});
+
+describe("revokeInvite", () => {
+  test("relays invites_revoke and returns the sanitized row", async () => {
+    ipcResponse = { invite: { ...inviteRow, status: "revoked" } };
+
+    const invite = await client.revokeInvite("inv-1");
+
+    expect(ipcCalls).toEqual([
+      { method: INVITES_IPC_METHODS.revoke, params: { id: "inv-1" } },
+    ]);
+    expect(invite).toEqual({ ...inviteRow, status: "revoked" });
+  });
+
+  test("rejects a malformed response", async () => {
+    ipcResponse = { ok: true };
+
+    await expect(client.revokeInvite("inv-1")).rejects.toThrow(
+      "malformed invites_revoke response",
+    );
+  });
+});
+
+describe("redeemInviteByToken", () => {
+  test("relays the token branch and returns the parsed payload", async () => {
+    ipcResponse = {
+      ok: true,
+      invite: { ...inviteRow, status: "redeemed" },
+      type: "redeemed",
+    };
+
+    const result = await client.redeemInviteByToken({
+      token: "raw-tok",
+      sourceChannel: "telegram",
+      externalUserId: "u1",
+      displayName: "Alice",
+    });
+
+    expect(ipcCalls).toEqual([
+      {
+        method: INVITES_IPC_METHODS.redeem,
+        params: {
+          token: "raw-tok",
+          sourceChannel: "telegram",
+          externalUserId: "u1",
+          displayName: "Alice",
+        },
+      },
+    ]);
+    expect(result.type).toBe("redeemed");
+  });
+
+  test("rejects a response with an off-contract type", async () => {
+    ipcResponse = { ok: true, invite: inviteRow, type: "maybe" };
+
+    await expect(
+      client.redeemInviteByToken({ token: "t", sourceChannel: "telegram" }),
+    ).rejects.toThrow("malformed invites_redeem response");
+  });
+});
+
+describe("redeemInviteByVoiceCode", () => {
+  test("relays the voice branch with the assistantId passthrough", async () => {
+    ipcResponse = {
+      ok: true,
+      type: "already_member",
+      memberId: "ct-1",
+    };
+
+    const result = await client.redeemInviteByVoiceCode({
+      callerExternalUserId: "+15555550100",
+      code: "123456",
+      assistantId: "asst-1",
+    });
+
+    expect(ipcCalls).toEqual([
+      {
+        method: INVITES_IPC_METHODS.redeem,
+        params: {
+          callerExternalUserId: "+15555550100",
+          code: "123456",
+          assistantId: "asst-1",
+        },
+      },
+    ]);
+    expect(result).toEqual({
+      ok: true,
+      type: "already_member",
+      memberId: "ct-1",
+    });
+  });
+
+  test("rejects a malformed response", async () => {
+    ipcResponse = { ok: true };
+
+    await expect(
+      client.redeemInviteByVoiceCode({
+        callerExternalUserId: "+15555550100",
+        code: "123456",
+      }),
+    ).rejects.toThrow("malformed invites_redeem response");
+  });
+});
+
+describe("transport failures", () => {
+  test("an IpcCallError propagates unchanged (statusCode preserved)", async () => {
+    ipcError = new IpcCallError("Invite not found", {
+      statusCode: 404,
+      errorCode: "NOT_FOUND",
+    });
+
+    try {
+      await client.revokeInvite("missing");
+      throw new Error("expected revokeInvite to throw");
+    } catch (err) {
+      expect(err).toBeInstanceOf(IpcCallError);
+      expect((err as IpcCallError).statusCode).toBe(404);
+    }
+  });
+});

package/src/channels/gateway-invites.ts

@@ -0,0 +1,142 @@
+/**
+ * Gateway-backed invite client.
+ *
+ * Typed async wrappers over the gateway's invite IPC routes
+ * (`gateway/src/ipc/invite-handlers.ts`). The gateway owns the canonical
+ * invite lifecycle — mint, list, revoke, redemption — against
+ * `ingress_invites`; the daemon relays its CLI/HTTP invite surfaces here and
+ * layers presentation fields on afterwards. Responses are validated against
+ * the shared contract schemas in `@vellumai/gateway-client` — the same
+ * schemas the gateway routes are pinned to.
+ *
+ * Error posture (fail-closed — there is no local fallback): every wrapper
+ * THROWS on transport failure or a malformed response. An `IpcCallError`
+ * keeps the gateway's statusCode/errorCode so relay routes surface 4xx
+ * engine reasons as 4xx. Voice-call invite detection/redemption does NOT
+ * live here: the hot call-setup path uses `calls/gateway-invite-reader.ts`
+ * (one-shot `ipcCall`, explicit short timeouts, fail-soft detection) instead
+ * of the persistent client these control-plane relays share.
+ */
+
+import {
+  CreateInviteIpcResponseSchema,
+  INVITES_IPC_METHODS,
+  type InvitesIpcMethod,
+  type InviteWire,
+  ListInvitesIpcResponseSchema,
+  type RedeemInviteByTokenRequest,
+  type RedeemInviteTokenIpcResponse,
+  RedeemInviteTokenIpcResponseSchema,
+  type RedeemInviteVoiceIpcResponse,
+  RedeemInviteVoiceIpcResponseSchema,
+  type RedeemVoiceInviteRequest,
+  RevokeInviteIpcResponseSchema,
+} from "@vellumai/gateway-client";
+import type { ZodType } from "zod";
+
+import { ipcCallPersistentValidated } from "../ipc/gateway-validated-call.js";
+
+export type { InviteWire } from "@vellumai/gateway-client";
+
+/**
+ * Call a gateway invite route and validate the response against its contract
+ * schema (typed to the invite method union).
+ */
+async function callGateway<T>(
+  method: InvitesIpcMethod,
+  params: Record<string, unknown>,
+  responseSchema: ZodType<T>,
+): Promise<T> {
+  return ipcCallPersistentValidated(method, params, responseSchema);
+}
+
+export interface ListInvitesFilters {
+  sourceChannel?: string;
+  status?: string;
+}
+
+/** List sanitized gateway invite rows, optionally filtered. */
+export async function listInvites(
+  filters: ListInvitesFilters = {},
+): Promise<InviteWire[]> {
+  const response = await callGateway(
+    INVITES_IPC_METHODS.list,
+    {
+      ...(filters.sourceChannel
+        ? { sourceChannel: filters.sourceChannel }
+        : {}),
+      ...(filters.status ? { status: filters.status } : {}),
+    },
+    ListInvitesIpcResponseSchema,
+  );
+  return response.invites;
+}
+
+/**
+ * Create-invite params. Field validation is gateway-owned
+ * (`gateway/src/http/routes/invite-validation.ts`) — invalid input surfaces
+ * as a relayed 400.
+ */
+export interface CreateInviteParams {
+  contactId: string;
+  sourceChannel?: string;
+  note?: string;
+  maxUses?: number;
+  expiresInMs?: number;
+  expectedExternalUserId?: string;
+  guardianName?: string;
+  sourceConversationId?: string;
+}
+
+/**
+ * Mint an invite. Returns the gateway's one-time payload — row fields plus
+ * the plaintext secrets (`rawToken` for link invites), never fetchable later.
+ */
+export async function createInvite(
+  params: CreateInviteParams,
+): Promise<{ invite: InviteWire; rawToken?: string }> {
+  return callGateway(
+    INVITES_IPC_METHODS.create,
+    { ...params },
+    CreateInviteIpcResponseSchema,
+  );
+}
+
+/** Revoke an invite (idempotent for already-terminal invites). */
+export async function revokeInvite(id: string): Promise<InviteWire> {
+  const response = await callGateway(
+    INVITES_IPC_METHODS.revoke,
+    { id },
+    RevokeInviteIpcResponseSchema,
+  );
+  return response.invite;
+}
+
+/**
+ * Redeem a link-token invite (`invites_redeem`, token branch — selected by
+ * the absence of `code`). Engine failures throw a relayed 400 with the
+ * engine reason.
+ */
+export async function redeemInviteByToken(
+  params: RedeemInviteByTokenRequest,
+): Promise<RedeemInviteTokenIpcResponse> {
+  return callGateway(
+    INVITES_IPC_METHODS.redeem,
+    params as unknown as Record<string, unknown>,
+    RedeemInviteTokenIpcResponseSchema,
+  );
+}
+
+/**
+ * Redeem a spoken voice code (`invites_redeem`, voice branch — selected by
+ * the presence of `code`). `assistantId` is a daemon passthrough.
+ */
+export async function redeemInviteByVoiceCode(
+  params: RedeemVoiceInviteRequest & { assistantId?: string },
+): Promise<RedeemInviteVoiceIpcResponse> {
+  return callGateway(
+    INVITES_IPC_METHODS.redeem,
+    params as unknown as Record<string, unknown>,
+    RedeemInviteVoiceIpcResponseSchema,
+  );
+}

package/src/channels/gateway-verification-sessions.ts

@@ -36,7 +36,7 @@ import {
 } from "@vellumai/gateway-client";
 import type { ZodType } from "zod";
 
-import { ipcCallPersistent } from "../ipc/gateway-client.js";
+import { ipcCallPersistentValidated } from "../ipc/gateway-validated-call.js";
 import { composeApprovalMessage } from "../runtime/approval-message-composer.js";
 
 export type { VerificationSessionWire } from "@vellumai/gateway-client";
@@ -57,19 +57,15 @@ export type ValidateVerificationResult = ValidateConsumeSessionIpcResponse;
 
 /**
  * Call a gateway session route and validate the response against its
- * contract schema. Throws on transport failure or a malformed response.
+ * contract schema. Throws on transport failure or a malformed response
+ * (shared helper; typed to the session method union).
  */
 async function callGateway<T>(
   method: VerificationSessionsIpcMethod,
   params: Record<string, unknown>,
   responseSchema: ZodType<T>,
 ): Promise<T> {
-  const result = await ipcCallPersistent(method, params);
-  const parsed = responseSchema.safeParse(result);
-  if (!parsed.success) {
-    throw new Error(`Gateway returned a malformed ${method} response`);
-  }
-  return parsed.data;
+  return ipcCallPersistentValidated(method, params, responseSchema);
 }
 
 /** Call a mutation route; throws unless the gateway acks `{ ok: true }`. */

package/src/cli/AGENTS.md

@@ -30,7 +30,7 @@ Every namespace that manages a resource (schedules, contacts, tasks, …) must e
 
 CLI commands use one of two transport patterns depending on whether they need a running daemon:
 
-- **`ipc`-tagged commands** call `cliIpcCall` from `../../ipc/cli-client.js`. They are thin wrappers that forward requests to the daemon over the IPC socket and never import daemon-internal modules.
+- **`ipc`-tagged commands** call `cliIpcCall` from `../../ipc/cli-client.js`. They forward requests to the daemon over the IPC socket for state the daemon owns.
 - **`local`-tagged commands** read or write workspace files directly (config, autonomy, completions, etc.) using the same config/store helpers the daemon uses internally. They do not require the daemon to be running.
 
 Both transport classes avoid proxying through the gateway HTTP API. `ipc` commands reach the daemon directly via the socket; `local` commands bypass the daemon entirely. The transport tag is declared via `registerCommand({ transport, ... })` — see the "Transport tagging" section below.
@@ -40,19 +40,22 @@ Both transport classes avoid proxying through the gateway HTTP API. `ipc` comman
 Every command file declares its transport class via `registerCommand({ transport, ... })`
 from `../lib/register-command.ts`. The three transport classes are:
 
-| Class | Rule | When to use |
-|---|---|---|
-| `ipc` | Wraps exactly one IPC method per subcommand. No daemon-internal imports. | Commands that call the daemon |
-| `local` | Touches only static workspace files / shell artifacts. | Commands that work without a running daemon |
-| `bootstrap` | Runs before the daemon is up (e.g. `assistant config init`). | Pre-daemon setup |
+| Class       | Rule                                                            | When to use                                 |
+| ----------- | --------------------------------------------------------------- | ------------------------------------------- |
+| `ipc`       | Reaches the daemon (over IPC, or in-process via a lazy import). | Commands that call the daemon               |
+| `local`     | Touches only static workspace files / shell artifacts.          | Commands that work without a running daemon |
+| `bootstrap` | Runs before the daemon is up (e.g. `assistant config init`).    | Pre-daemon setup                            |
 
-The ESLint rule `cli/no-daemon-internals` enforces import allowlists per class.
+The tag is descriptive metadata; keep it accurate so readers can tell at a
+glance whether a command needs a running daemon.
 
 ## Anatomy of an `ipc` command
 
-The thin-wrapper pattern. Every `ipc`-tagged subcommand action does three
-things: parse argv → call one IPC method → format output. The business
-logic lives in the daemon route, not the CLI.
+An `ipc`-tagged subcommand action parses argv, reaches the daemon — over
+IPC for daemon-owned state, or by running a lazily-imported helper
+in-process — and formats output. Prefer in-process where it saves an IPC
+round-trip; prefer IPC when the daemon owns the state or a running
+instance must do the work.
 
 ### Required shape
 
@@ -100,41 +103,52 @@ registerFooCommand(program);
 
 ### Rules
 
-1. **One `registerCommand` call per file.** The options object MUST be
-   passed inline as an object literal; `name` and `transport` MUST be
-   string literals. Hoisted variables and `as const` casts break the
-   static analysis tools rely on.
-
-2. **No daemon-internal imports.** An `ipc` command file can import:
-
-   - the IPC client (`../../ipc/cli-client`)
-   - the Commander framework + Node stdlib (`commander`, `node:*`)
-   - shared CLI helpers (`../logger`, `../output`, `../lib/*`,
-     `../../utils/*`)
-   - sibling subcommand modules (`./connect`, etc. — for namespace
-     parents like `oauth/index.ts`)
-
-   It **cannot** import anything under `runtime/`, `services/`,
-   `agents/`, `llm/`, `skills/`, or any other daemon-internal namespace.
-   The `cli/no-daemon-internals` ESLint rule enforces this at `"error"`
-   severity. See `assistant/eslint-rules/cli-no-daemon-internals.js` for
-   the per-transport allowlist (including per-command escape hatches for
-   things like the `keys` security helpers and `credential-execution`
-   bridge).
-
-3. **One IPC call per subcommand action.** A thin wrapper does not
-   compose multiple IPC methods, does not validate beyond Commander's
-   argument parsing, and does not reshape the daemon response.
-   Composition belongs on the daemon side, in a route.
-
-4. **Always check `r.ok` before reading `r.result`.** `cliIpcCall`
+1. **Keep hoisted imports inside the CLI.** A command module's top-level
+   (hoisted) imports are loaded on every `assistant …` invocation, so
+   they must stay light. You may hoist Node/npm packages, modules within
+   `assistant/src/cli`, and the shared non-daemon leaf zones `util/`,
+   `ipc/` (the IPC client + socket path), `types/`, and `version`.
+   Type-only imports (`import type …`) are always fine — they are erased
+   and cost nothing at runtime.
+
+   **Do not hoist imports of daemon functionality** — anything else
+   outside `assistant/src/cli` (`runtime/`, `daemon/`, `persistence/`,
+   `providers/`, `platform/`, `security/`, …). Hoisting it pulls the
+   daemon's module graph into every CLI process and inflates its memory
+   footprint. This is enforced by the `cli/no-daemon-internals` ESLint
+   rule (`error`): a hoisted import that resolves outside the CLI tree and
+   the leaf zones above fails lint. Lazy-import it instead (rule 2).
+
+   Rare exception: an execution-free data leaf that is needed
+   _synchronously_ at command registration (so it can't be a lazy
+   `import()`) may stay hoisted behind a scoped
+   `// eslint-disable-next-line cli/no-daemon-internals` with a comment
+   explaining why. The only current case is `browser/operation-meta`, in
+   `commands/browser.ts` (it drives synchronous subcommand generation and
+   deliberately pulls no Playwright graph) and `commands/browser.help.ts`
+   (which derives the declarative help from the same contract).
+
+2. **Lazy-import daemon functionality inside the action.** Running daemon
+   logic in-process is encouraged where it avoids an IPC round-trip (which
+   otherwise adds main-process event-loop congestion). Reach that code
+   with a dynamic import inside the action, so it loads only when the
+   command actually runs:
+
+   ```ts
+   .action(async (opts) => {
+     const { doTheThing } = await import("../../runtime/foo.js");
+     await doTheThing(opts);
+   });
+   ```
+
+3. **Always check `r.ok` before reading `r.result`.** `cliIpcCall`
    returns `CliIpcCallResult<T>` — either `{ ok: true, result }` or
    `{ ok: false, error, statusCode?, errorCode?, errorDetails? }`. Use
    `exitFromIpcResult(r)` to surface failure: it writes the error to
    stderr and exits with a code derived from the daemon-side
    `statusCode` (10 connect failure, 3 5xx, 2 4xx, 1 other).
 
-5. **Output via `writeOutput(cmd, payload)`.** The shared helper writes
+4. **Output via `writeOutput(cmd, payload)`.** The shared helper writes
    JSON to stdout — compact with `--json`, pretty otherwise — and
    respects `--json` inherited from parent commands. Don't
    `console.log` results directly; that bypasses the convention and
@@ -142,21 +156,15 @@ registerFooCommand(program);
 
 ### Anti-patterns
 
-- ❌ `import { something } from "../../runtime/foo.js"` from an
-  `ipc`-tagged command. The ESLint rule rejects this at `"error"`.
-- ❌ `registerCommand(program, opts)` where `opts` is a hoisted
-  variable. Inline the literal so the transport tag is statically
-  visible.
-- ❌ Multiple `registerCommand` calls in one file.
-- ❌ Reshaping `r.result` to differ from what the route returns. If the
-  CLI shape needs to diverge from the daemon response, change the
-  route — the CLI is just a transport.
+- ❌ Hoisting a daemon import — `import { x } from "../../runtime/foo.js"`
+  at module top (caught by `cli/no-daemon-internals`). Lazy-import it
+  inside the action instead so it loads only when the command runs.
 - ❌ Bypassing `exitFromIpcResult` to format your own error output.
   The shared helper gives consistent exit codes across the surface so
   scripts can branch on them.
 - ❌ Calling the gateway HTTP API (`fetch`, `axios`) from a CLI
-  command. All daemon work goes through IPC; the gateway is for
-  external clients.
+  command. Reach the daemon over IPC or via a lazily-imported in-process
+  helper; the gateway is for external clients.
 
 ## IPC operation IDs and routes
 
@@ -174,7 +182,7 @@ served by the daemon's IPC server. Two route surfaces exist:
   shouldn't be exposed over HTTP — when in doubt, default to the
   shared surface.
 
-Operation IDs are snake_case. The conventional shape is
+Operation IDs are `snake_case`. The conventional shape is
 `<command>_<subcommand>` (`pending_list`, `oauth_connect`,
 `cache_get`), but verb-first names are also used where they read more
 naturally (`upsert_contact`, `wake_conversation`, `conversations_import`).
@@ -189,6 +197,7 @@ response. When you add a new CLI verb you're almost always also adding
 
 `commands/pending.ts` is the reference implementation. Read it first
 when migrating a legacy command or unsure about a pattern.
+
 - Clean error handling via `exitFromIpcResult`
 - No daemon-internal imports