@vellumai/assistant 0.11.5 → 0.11.6-staging.1

package/node_modules/@vellumai/gateway-client/src/outbound-contract.ts

@@ -86,95 +86,155 @@ export const SlackStreamTaskSchema = z.object({
 
 export type SlackStreamTask = z.infer<typeof SlackStreamTaskSchema>;
 
+// ---------------------------------------------------------------------------
+// Audience
+// ---------------------------------------------------------------------------
+
 /**
- * A single Slack streaming operation, mapping directly onto the
- * `chat.startStream` / `chat.appendStream` / `chat.stopStream` Web API methods.
+ * Restricts a message to a single reader in a room that has more.
  *
- * `start` opens a streamed reply on a thread and returns the stream `ts`;
- * `append` adds markdown (and optional task cards) to that stream; `stop`
- * finalizes it, optionally rendering rich Block Kit blocks below the streamed
- * body. Blocks are only accepted on `stop` — during the stream, Slack renders
- * the `markdownText` natively.
+ * A single object rather than a flag beside an id, because the two are only
+ * meaningful together: a channel cannot address one reader without knowing
+ * which. Slack reads this as `chat.postEphemeral`; a channel whose rooms hold
+ * one reader already has nothing to do.
+ */
+export const MessageAudienceSchema = z.object({
+  kind: z.literal("oneReader"),
+  /** The reader, in the channel's own id space. */
+  userId: z.string(),
+  /**
+   * The organization the reader belongs to, for a channel whose user ids are
+   * only unique within one.
+   *
+   * Not every channel federates. Telegram and Discord user ids are global and
+   * ignore this; Slack ids are scoped to a workspace, and a guest reaching a
+   * shared channel from another one is only identified by the pair. A channel
+   * that needs it and does not get it cannot address the reader, so it treats
+   * the audience as unexpressible rather than guessing.
+   */
+  userOrgId: z.string().optional(),
+});
+
+export type MessageAudience = z.infer<typeof MessageAudienceSchema>;
+
+// ---------------------------------------------------------------------------
+// Streaming a reply that grows
+// ---------------------------------------------------------------------------
+
+/**
+ * One step of a plan carried alongside a growing reply: an ordered,
+ * status-bearing unit of work the assistant reports while a turn runs.
  *
- * @see https://docs.slack.dev/reference/methods/chat.startStream/
- * @see https://docs.slack.dev/reference/methods/chat.appendStream/
- * @see https://docs.slack.dev/reference/methods/chat.stopStream/
+ * The vocabulary is the assistant's own `task_progress` surface rather than any
+ * channel's, so a channel that renders plans natively converts on its way out
+ * and a channel that cannot writes them as text. Slack's `task_update` chunk
+ * spells two of these statuses differently and its transport translates.
+ */
+export const StreamPlanStepSchema = z.object({
+  label: z.string(),
+  status: z.enum(["pending", "in_progress", "completed", "failed"]),
+  detail: z.string().optional(),
+});
+
+export type StreamPlanStep = z.infer<typeof StreamPlanStepSchema>;
+
+/** A plan shown with a growing reply: an optional title over ordered steps. */
+export const StreamPlanSchema = z.object({
+  title: z.string().optional(),
+  steps: z.array(StreamPlanStepSchema),
+});
+
+export type StreamPlan = z.infer<typeof StreamPlanSchema>;
+
+/**
+ * One operation on a reply that grows while the turn runs.
+ *
+ * Channels that can do this disagree on what the growing thing *is*, and the
+ * split is preview versus persist. Slack streams the reply itself:
+ * `chat.startStream` opens the message that will remain, and `chat.stopStream`
+ * finalizes it in place. Telegram streams a live draft, which is ephemeral,
+ * expires on its own, and never becomes the reply; the reply is persisted
+ * afterwards by an ordinary send. Discord has no primitive for either and
+ * omits `streamReply`, so the caller sends the finished reply and nothing is
+ * simulated on its behalf.
+ *
+ * That is why every operation carries both `text`, the whole of what the reply
+ * now reads as, and `appended`, only what is new since the last operation.
+ * Slack's append takes the delta; Telegram's draft takes the partial text and
+ * lets its clients animate the difference. Neither channel has to know which
+ * kind the other is, and a third can read whichever it needs.
+ *
+ * `text` is required on every operation because a channel that rewrites needs
+ * it on every one, and it is what the reply reads as rather than what this
+ * operation changed: absent is never the right answer, where empty can be.
+ * `appended` is what moved, so it is absent when only the plan did.
+ *
+ * `start` opens the growing reply and returns a `streamId` in the channel's
+ * own id space; `append` advances it; `stop` ends it. What `stop` leaves
+ * behind differs by channel, which is why it carries the complete reply rather
+ * than a remainder: a channel that finalized in place has already shown it,
+ * and a channel whose preview evaporates needs it to send the real message.
  */
-export const SlackStreamOpSchema = z
+export const StreamOpSchema = z
   .discriminatedUnion("action", [
     z.object({
       action: z.literal("start"),
-      threadTs: z.string(),
-      markdownText: z.string().optional(),
-      taskDisplayMode: z.literal("plan").optional(),
-      /** Title of the plan block, serialized as a `plan_update` chunk. */
-      planTitle: z.string().optional(),
-      tasks: z.array(SlackStreamTaskSchema).optional(),
       /**
-       * Slack user ID of the reader the stream targets. Required by
-       * `chat.startStream` when streaming into a channel; omitted for DMs.
+       * The message this reply grows under, in the channel's own id space.
+       *
+       * Slack requires one: `chat.startStream` streams into a thread, and
+       * omitting it is only accepted where a whole channel is one session. A
+       * channel that threads nothing ignores it.
        */
-      recipientUserId: z.string().optional(),
+      anchorMessageId: z.string().optional(),
+      text: z.string(),
+      appended: z.string().optional(),
+      plan: StreamPlanSchema.optional(),
       /**
-       * Slack team ID the recipient belongs to. Required alongside
-       * `recipientUserId` when streaming into a channel; omitted for DMs.
+       * Who may see the growing reply. Absent means everyone in the room, the
+       * same reading the finished reply gives it.
        */
-      recipientTeamId: z.string().optional(),
+      audience: MessageAudienceSchema.optional(),
     }),
     z.object({
       action: z.literal("append"),
-      streamTs: z.string(),
-      markdownText: z.string().optional(),
-      /** Title of the plan block, serialized as a `plan_update` chunk. */
-      planTitle: z.string().optional(),
-      tasks: z.array(SlackStreamTaskSchema).optional(),
+      /** The open reply, in the channel's own id space. */
+      streamId: z.string(),
+      text: z.string(),
+      appended: z.string().optional(),
+      plan: StreamPlanSchema.optional(),
     }),
     z.object({
       action: z.literal("stop"),
-      streamTs: z.string(),
-      markdownText: z.string().optional(),
-      blocks: z.array(z.custom<KnownBlock>()).optional(),
-      /** Title of the plan block, serialized as a `plan_update` chunk. */
-      planTitle: z.string().optional(),
-      tasks: z.array(SlackStreamTaskSchema).optional(),
+      streamId: z.string(),
+      /**
+       * The complete reply, not the remainder. A channel whose preview
+       * evaporates sends this as the message that stays; one that finalizes
+       * its stream in place has already shown it and appends `appended`.
+       */
+      text: z.string(),
+      appended: z.string().optional(),
+      plan: StreamPlanSchema.optional(),
     }),
   ])
   .superRefine((op, ctx) => {
-    // Slack requires either `markdown_text` or `chunks` on `start`/`append`; a
-    // task-only operation advances the plan block without new body text.
+    // An operation has to move something: new words, or the plan beside them.
+    // `text` alone cannot, since it restates what the reply already reads as.
+    // Slack rejects a start or append carrying neither, and a channel that
+    // rewrites would spend an edit redrawing what is already on screen.
     if (
       (op.action === "start" || op.action === "append") &&
-      op.markdownText === undefined &&
-      op.tasks === undefined
+      op.appended === undefined &&
+      op.plan === undefined
     ) {
       ctx.addIssue({
         code: z.ZodIssueCode.custom,
-        message: `${op.action} requires markdownText or tasks`,
+        message: `${op.action} requires appended or plan`,
       });
     }
   });
 
-export type SlackStreamOp = z.infer<typeof SlackStreamOpSchema>;
-
-// ---------------------------------------------------------------------------
-// Audience
-// ---------------------------------------------------------------------------
-
-/**
- * Restricts a message to a single reader in a room that has more.
- *
- * A single object rather than a flag beside an id, because the two are only
- * meaningful together: a channel cannot address one reader without knowing
- * which. Slack reads this as `chat.postEphemeral`; a channel whose rooms hold
- * one reader already has nothing to do.
- */
-export const MessageAudienceSchema = z.object({
-  kind: z.literal("oneReader"),
-  /** The reader, in the channel's own id space. */
-  userId: z.string(),
-});
-
-export type MessageAudience = z.infer<typeof MessageAudienceSchema>;
+export type StreamOp = z.infer<typeof StreamOpSchema>;
 
 // ---------------------------------------------------------------------------
 // Channel reply payload — the full outbound wire format
@@ -197,7 +257,7 @@ export const ChannelReplyPayloadSchema = z.object({
    * Each channel decides what that means, and one that cannot ignores it.
    * Slack is the only channel acting on it today, where it becomes Block Kit.
    */
-  useBlocks: z.boolean().optional(),
+  renderRichly: z.boolean().optional(),
 });
 
 export type ChannelReplyPayload = z.infer<typeof ChannelReplyPayloadSchema>;

package/node_modules/@vellumai/service-contracts/src/__tests__/ingress.test.ts

@@ -2,7 +2,12 @@ import { describe, expect, test } from "bun:test";
 
 import {
   normalizeHttpPublicBaseUrl,
+  normalizeHttpPublicBaseUrlWithoutTrailingSlash,
   normalizePublicBaseUrl,
+  parseRecordedAssistantId,
+  parseTunnelRecord,
+  trimmedNonEmptyString,
+  TUNNEL_PROVIDERS,
   velayHostForPlatformHost,
 } from "../ingress.js";
 import {
@@ -85,6 +90,35 @@ describe("normalizeHttpPublicBaseUrl", () => {
   });
 });
 
+describe("normalizeHttpPublicBaseUrlWithoutTrailingSlash", () => {
+  test("drops the root path its sibling always emits", () => {
+    expect(
+      normalizeHttpPublicBaseUrlWithoutTrailingSlash("https://x.test"),
+    ).toBe("https://x.test");
+    expect(
+      normalizeHttpPublicBaseUrlWithoutTrailingSlash("https://x.test/"),
+    ).toBe("https://x.test");
+    expect(
+      normalizeHttpPublicBaseUrlWithoutTrailingSlash(" https://x.test/api/// "),
+    ).toBe("https://x.test/api");
+  });
+
+  test("rejects everything its sibling rejects", () => {
+    for (const value of [
+      "",
+      "   ",
+      "notaurl",
+      "ftp://x.test",
+      "https://x.test?a=b",
+      42,
+    ]) {
+      expect(
+        normalizeHttpPublicBaseUrlWithoutTrailingSlash(value),
+      ).toBeUndefined();
+    }
+  });
+});
+
 describe("Twilio ingress helpers", () => {
   test("resolves public base URL with fallback", () => {
     expect(
@@ -123,3 +157,87 @@ describe("Twilio ingress helpers", () => {
     });
   });
 });
+
+describe("parseTunnelRecord", () => {
+  const TUNNEL_URL = "https://assistant-1.example.ts.net";
+
+  test("accepts every provider in the registry", () => {
+    for (const provider of TUNNEL_PROVIDERS) {
+      expect(
+        parseTunnelRecord({ provider, publicBaseUrl: TUNNEL_URL }),
+      ).toEqual({ provider, publicBaseUrl: TUNNEL_URL });
+    }
+  });
+
+  test("returns the URL in the shape its own validator produces", () => {
+    // Padding and trailing slashes are normalized away rather than handed
+    // back, so readers never re-normalize what they were given.
+    for (const publicBaseUrl of [
+      ` ${TUNNEL_URL} `,
+      `${TUNNEL_URL}/`,
+      `${TUNNEL_URL}///`,
+    ]) {
+      expect(
+        parseTunnelRecord({ provider: "ngrok", publicBaseUrl }),
+      ).toEqual({ provider: "ngrok", publicBaseUrl: TUNNEL_URL });
+    }
+  });
+
+  test("rejects values that are not a record", () => {
+    for (const value of [undefined, null, "nonsense", 42, []]) {
+      expect(parseTunnelRecord(value)).toBeNull();
+    }
+  });
+
+  test("rejects a record missing either field", () => {
+    expect(parseTunnelRecord({ provider: "ngrok" })).toBeNull();
+    expect(parseTunnelRecord({ publicBaseUrl: TUNNEL_URL })).toBeNull();
+  });
+
+  test("rejects a provider outside the registry", () => {
+    // Readers render the provider into a `vellum tunnel --provider <name>`
+    // command, so a hand-edited config must not reach a terminal.
+    for (const provider of ["wireguard", "; rm -rf /", "", 42]) {
+      expect(
+        parseTunnelRecord({ provider, publicBaseUrl: TUNNEL_URL }),
+      ).toBeNull();
+    }
+  });
+
+  test("rejects a URL that is not absolute HTTP(S)", () => {
+    for (const publicBaseUrl of [
+      "",
+      "   ",
+      "not-a-url",
+      "example.ts.net",
+      "ftp://x.test",
+      "https://one.ngrok.app?token=x",
+      42,
+    ]) {
+      expect(
+        parseTunnelRecord({ provider: "ngrok", publicBaseUrl }),
+      ).toBeNull();
+    }
+  });
+});
+
+describe("trimmedNonEmptyString", () => {
+  test("trims and rejects blank or non-string values", () => {
+    expect(trimmedNonEmptyString(" assistant-1 ")).toBe("assistant-1");
+    for (const value of ["", "   ", undefined, null, 42]) {
+      expect(trimmedNonEmptyString(value)).toBeUndefined();
+    }
+  });
+});
+
+describe("parseRecordedAssistantId", () => {
+  test("trims a recorded id", () => {
+    expect(parseRecordedAssistantId(" assistant-1 ")).toBe("assistant-1");
+  });
+
+  test("rejects blank and non-string values", () => {
+    for (const value of ["", "   ", undefined, null, 42]) {
+      expect(parseRecordedAssistantId(value)).toBeNull();
+    }
+  });
+});

package/node_modules/@vellumai/service-contracts/src/ingress.ts

@@ -48,3 +48,106 @@ export function normalizeHttpPublicBaseUrl(value: unknown): string | undefined {
     return undefined;
   }
 }
+
+/**
+ * The same validation as `normalizeHttpPublicBaseUrl`, minus the root path it
+ * always emits (`https://x` becomes `https://x/`). Callers that append a path
+ * or persist the result want this shape, so they neither join through a double
+ * slash nor re-strip what the normalizer just added.
+ */
+export function normalizeHttpPublicBaseUrlWithoutTrailingSlash(
+  value: unknown,
+): string | undefined {
+  return normalizePublicBaseUrl(normalizeHttpPublicBaseUrl(value));
+}
+
+/**
+ * A trimmed string, or undefined when the value is not a non-blank string.
+ *
+ * Exported because the identity check in the daemon's tunnel probe compares an
+ * id recorded here against one an edge serves, and the two sides have to trim
+ * alike: a padded served id must read as a match, not as a different
+ * assistant.
+ */
+export function trimmedNonEmptyString(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+// Records `vellum tunnel` leaves in the workspace config's `ingress` section.
+// The CLI writes them and the daemon reads them, and the two are separate
+// build units that cannot import each other, so the key names, the provider
+// allowlist, and the validation all live here rather than in a copy on each
+// side.
+
+/** Key under `ingress` holding the tunnel that most recently ran. */
+export const INGRESS_LAST_TUNNEL_KEY = "lastTunnel";
+
+/**
+ * Key under `ingress` holding a tunnel published for device pairing alone.
+ *
+ * A tailnet-only tunnel started while webhook integrations are configured
+ * cannot carry their callbacks, so it leaves `publicBaseUrl` (the callback
+ * base) as it is and records itself here. Readers that answer the pairing card
+ * prefer this address over `publicBaseUrl`; teardown drops the key.
+ */
+export const INGRESS_PAIRING_TUNNEL_KEY = "pairingTunnel";
+
+/** Key under `ingress` holding the assistant id that tunnel fronted. */
+export const INGRESS_ASSISTANT_ID_KEY = "assistantId";
+
+/**
+ * The local tunnel providers the CLI can start, in the order they are offered.
+ * `vellum tunnel`'s accepted `--provider` values and the persisted-record
+ * validation below both derive from it.
+ */
+export const TUNNEL_PROVIDERS = ["ngrok", "cloudflare", "tailscale"] as const;
+
+export type TunnelProviderName = (typeof TUNNEL_PROVIDERS)[number];
+
+/** A recorded tunnel, kept after teardown so UIs can name the command to restart. */
+export interface TunnelRecord {
+  provider: TunnelProviderName;
+  publicBaseUrl: string;
+}
+
+function isTunnelProviderName(value: unknown): value is TunnelProviderName {
+  return (
+    typeof value === "string" &&
+    (TUNNEL_PROVIDERS as readonly string[]).includes(value)
+  );
+}
+
+/**
+ * Parse an `ingress.lastTunnel` or `ingress.pairingTunnel` value, or null when
+ * it is absent or malformed.
+ *
+ * A hand-edited config must not hand callers an unusable address or a provider
+ * name no command accepts: the provider is checked against the allowlist
+ * because readers render it into a restart command, and the URL faces the same
+ * absolute HTTP(S) constraint as every other public base URL. The URL comes
+ * back in the shape the validator produced, so readers never re-normalize it.
+ */
+export function parseTunnelRecord(value: unknown): TunnelRecord | null {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return null;
+  }
+  const { provider, publicBaseUrl } = value as Record<string, unknown>;
+  if (!isTunnelProviderName(provider)) {
+    return null;
+  }
+  const normalized =
+    normalizeHttpPublicBaseUrlWithoutTrailingSlash(publicBaseUrl);
+  if (normalized === undefined) {
+    return null;
+  }
+  return { provider, publicBaseUrl: normalized };
+}
+
+/** Parse an `ingress.assistantId` value, or null when it is absent or blank. */
+export function parseRecordedAssistantId(value: unknown): string | null {
+  return trimmedNonEmptyString(value) ?? null;
+}