@vellumai/assistant 0.9.0 → 0.9.1-staging.1

package/node_modules/@vellumai/gateway-client/src/index.ts

@@ -19,20 +19,26 @@ export * from "./gateway-ipc-contracts.js";
 
 export { ipcCall, IpcCallError, PersistentIpcClient } from "./ipc-client.js";
 
+// Outbound delivery contract (daemon → gateway) — Zod schemas + derived types
+export {
+  ApprovalActionOptionSchema,
+  ApprovalUIMetadataSchema,
+  AttachmentMetadataSchema,
+  ChannelDeliveryResultSchema,
+  ChannelReplyPayloadSchema,
+  PermissionRequestDetailsSchema,
+} from "./outbound-contract.js";
+
 export type {
   ApprovalActionOption,
   ApprovalUIMetadata,
   AttachmentMetadata,
   ChannelDeliveryResult,
   ChannelReplyPayload,
-  IpcRequest,
-  IpcResponse,
-  Logger,
   PermissionRequestDetails,
-} from "./types.js";
-
-export { noopLogger } from "./types.js";
+} from "./outbound-contract.js";
 
+// Inbound contract (gateway → daemon) — Zod schemas + derived types
 export {
   CommandIntentSchema,
   RuntimeInboundPayloadSchema,
@@ -44,3 +50,8 @@ export type {
   RuntimeInboundPayload,
   SourceMetadata,
 } from "./inbound-contract.js";
+
+// IPC, logger, and utility types
+export type { IpcRequest, IpcResponse, Logger } from "./types.js";
+
+export { noopLogger } from "./types.js";

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

@@ -0,0 +1,119 @@
+/**
+ * Daemon → gateway outbound delivery contract.
+ *
+ * Zod schemas defining the wire format for channel replies delivered from
+ * the daemon to the gateway via `POST /deliver/{channel}`. Both services
+ * import from here so the contract is enforced at compile time.
+ *
+ * The daemon constructs these payloads in `deliverChannelReply()` and
+ * `deliverApprovalPrompt()`; the gateway validates and dispatches them
+ * to the target channel provider.
+ */
+
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Attachment metadata
+// ---------------------------------------------------------------------------
+
+export const AttachmentMetadataSchema = z.object({
+  id: z.string(),
+  filename: z.string(),
+  mimeType: z.string(),
+  sizeBytes: z.number(),
+  kind: z.string(),
+  data: z.string().optional(),
+  thumbnailData: z.string().optional(),
+  fileBacked: z.boolean().optional(),
+});
+
+export type AttachmentMetadata = z.infer<typeof AttachmentMetadataSchema>;
+
+// ---------------------------------------------------------------------------
+// Approval UI types
+// ---------------------------------------------------------------------------
+
+export const ApprovalActionOptionSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+});
+
+export type ApprovalActionOption = z.infer<typeof ApprovalActionOptionSchema>;
+
+export const PermissionRequestDetailsSchema = z.object({
+  toolName: z.string(),
+  riskLevel: z.string(),
+  toolInput: z.record(z.string(), z.unknown()),
+  requesterIdentifier: z.string().optional(),
+});
+
+export type PermissionRequestDetails = z.infer<
+  typeof PermissionRequestDetailsSchema
+>;
+
+export const ApprovalUIMetadataSchema = z.object({
+  requestId: z.string(),
+  actions: z.array(ApprovalActionOptionSchema),
+  plainTextFallback: z.string(),
+  permissionDetails: PermissionRequestDetailsSchema.optional(),
+});
+
+export type ApprovalUIMetadata = z.infer<typeof ApprovalUIMetadataSchema>;
+
+// ---------------------------------------------------------------------------
+// Channel reply payload — the full outbound wire format
+// ---------------------------------------------------------------------------
+
+export const ChannelReplyPayloadSchema = z.object({
+  chatId: z.string(),
+  text: z.string().optional(),
+  /** Pre-formatted Block Kit blocks for Slack delivery. */
+  blocks: z.array(z.unknown()).optional(),
+  assistantId: z.string().optional(),
+  attachments: z.array(AttachmentMetadataSchema).optional(),
+  approval: ApprovalUIMetadataSchema.optional(),
+  chatAction: z.literal("typing").optional(),
+  /**
+   * When true, deliver via `chat.postEphemeral` so only the target `user`
+   * sees the message.
+   */
+  ephemeral: z.boolean().optional(),
+  /** Slack user ID — required when `ephemeral` is true. */
+  user: z.string().optional(),
+  /** When provided, update an existing message instead of posting a new one. */
+  messageTs: z.string().optional(),
+  /** When true, auto-generate Block Kit blocks from text via textToBlocks(). */
+  useBlocks: z.boolean().optional(),
+  /** When provided, add or remove an emoji reaction on a message. */
+  reaction: z
+    .object({
+      action: z.enum(["add", "remove"]),
+      name: z.string(),
+      messageTs: z.string(),
+    })
+    .optional(),
+  /** When provided, set or clear the Slack Assistants API thread status. */
+  assistantThreadStatus: z
+    .object({
+      channel: z.string(),
+      threadTs: z.string(),
+      status: z.string(),
+      /** Serialized to Slack as `loading_messages`. */
+      loadingMessages: z.array(z.string()).optional(),
+    })
+    .optional(),
+});
+
+export type ChannelReplyPayload = z.infer<typeof ChannelReplyPayloadSchema>;
+
+// ---------------------------------------------------------------------------
+// Channel delivery result — gateway response
+// ---------------------------------------------------------------------------
+
+export const ChannelDeliveryResultSchema = z.object({
+  ok: z.boolean(),
+  /** The message timestamp returned by the delivery endpoint. */
+  ts: z.string().optional(),
+});
+
+export type ChannelDeliveryResult = z.infer<typeof ChannelDeliveryResultSchema>;

package/node_modules/@vellumai/gateway-client/src/types.ts

@@ -4,92 +4,23 @@
  * Type definitions for assistant-to-gateway communication. These are
  * intentionally decoupled from the assistant's internal types so the
  * package can be consumed without importing assistant internals.
+ *
+ * HTTP delivery types (ChannelReplyPayload, ApprovalUIMetadata, etc.)
+ * are defined as Zod schemas in `outbound-contract.ts` and re-exported
+ * from the barrel `index.ts`. This file retains only IPC and utility
+ * types that don't cross an HTTP wire boundary.
  */
 
-// ---------------------------------------------------------------------------
-// HTTP delivery types
-// ---------------------------------------------------------------------------
-
-/** Metadata for a file attachment delivered alongside a channel reply. */
-export interface AttachmentMetadata {
-  id: string;
-  filename: string;
-  mimeType: string;
-  sizeBytes: number;
-  kind: string;
-  data?: string;
-  thumbnailData?: string;
-  fileBacked?: boolean;
-}
-
-/** An action option presented to the user in an approval prompt. */
-export interface ApprovalActionOption {
-  id: string;
-  label: string;
-}
-
-/**
- * Tool-permission-specific details carried alongside the approval payload.
- * Channels that support rich UI (e.g. Slack Block Kit) use these fields
- * to render a detailed permission request card.
- */
-export interface PermissionRequestDetails {
-  toolName: string;
-  riskLevel: string;
-  toolInput: Record<string, unknown>;
-  requesterIdentifier?: string;
-}
-
-/**
- * Metadata attached to gateway callback payloads for rendering approval
- * UI and routing decisions back to the correct pending interaction.
- */
-export interface ApprovalUIMetadata {
-  requestId: string;
-  actions: ApprovalActionOption[];
-  plainTextFallback: string;
-  permissionDetails?: PermissionRequestDetails;
-}
-
-/** Payload for a channel reply delivered via the gateway. */
-export interface ChannelReplyPayload {
-  chatId: string;
-  text?: string;
-  /** Pre-formatted Block Kit blocks for Slack delivery. */
-  blocks?: unknown[];
-  assistantId?: string;
-  attachments?: AttachmentMetadata[];
-  approval?: ApprovalUIMetadata;
-  chatAction?: "typing";
-  /**
-   * When true, deliver via `chat.postEphemeral` so only the target `user`
-   * sees the message.
-   */
-  ephemeral?: boolean;
-  /** Slack user ID — required when `ephemeral` is true. */
-  user?: string;
-  /** When provided, update an existing message instead of posting a new one. */
-  messageTs?: string;
-  /** When true, auto-generate Block Kit blocks from text via textToBlocks(). */
-  useBlocks?: boolean;
-  /** When provided, add or remove an emoji reaction on a message. */
-  reaction?: { action: "add" | "remove"; name: string; messageTs: string };
-  /** When provided, set or clear the Slack Assistants API thread status. */
-  assistantThreadStatus?: {
-    channel: string;
-    threadTs: string;
-    status: string;
-    /** Serialized to Slack as `loading_messages`. */
-    loadingMessages?: string[];
-  };
-}
-
-/** Result from a channel delivery attempt. */
-export interface ChannelDeliveryResult {
-  ok: boolean;
-  /** The message timestamp returned by the delivery endpoint. */
-  ts?: string;
-}
+// Re-export outbound delivery types for backward compatibility — consumers
+// that import from "./types.js" continue to work.
+export type {
+  ApprovalActionOption,
+  ApprovalUIMetadata,
+  AttachmentMetadata,
+  ChannelDeliveryResult,
+  ChannelReplyPayload,
+  PermissionRequestDetails,
+} from "./outbound-contract.js";
 
 // ---------------------------------------------------------------------------
 // IPC types

package/openapi.yaml

@@ -13030,60 +13030,6 @@ paths:
                   - home
                   - version
                 additionalProperties: false
-  /v1/identity/intro:
-    get:
-      operationId: identity_intro_get
-      summary: Get identity greetings
-      description:
-        Returns greetings sourced from SOUL.md, the generated cache, or generic fallbacks while background
-        generation refreshes the cache.
-      tags:
-        - identity
-      parameters:
-        - name: localHour
-          in: query
-          required: false
-          schema:
-            type: integer
-            minimum: 0
-            maximum: 23
-          description: Optional client-local hour of day used only when refreshing generated greetings.
-        - name: localMinute
-          in: query
-          required: false
-          schema:
-            type: integer
-            minimum: 0
-            maximum: 59
-          description: Optional client-local minute used only when refreshing generated greetings.
-      responses:
-        "200":
-          description: Successful response
-          content:
-            application/json:
-              schema:
-                type: object
-                properties:
-                  greetings:
-                    type: array
-                    items:
-                      type: string
-                  text:
-                    type: string
-                  source:
-                    type: string
-                    enum:
-                      - workspace
-                      - cache
-                      - fallback
-                  refreshing:
-                    type: boolean
-                required:
-                  - greetings
-                  - text
-                  - source
-                  - refreshing
-                additionalProperties: false
   /v1/image-generation/generate:
     post:
       operationId: imagegeneration_generate_post
@@ -19245,6 +19191,109 @@ paths:
           description: The plugin name failed sanitization (e.g. contained slashes, dots, or uppercase letters).
         "404":
           description: No installed copy and no catalog entry claims the given name.
+  /v1/plugins/{name}/diff:
+    post:
+      operationId: plugins_by_name_diff_post
+      summary: Diff a plugin against its install commit
+      description:
+        "Show a unified diff of local edits to an installed plugin against the exact commit it was installed at
+        (recorded in its `install-meta.json`). Computing the diff re-materializes the baseline through the install
+        pipeline — a network clone plus a temp-dir write — so this is a POST: it is not a safe, cacheable GET even
+        though it leaves persistent state untouched (requires only `settings.read`). Drift is classified against the
+        install-time fingerprint so an adapter overlay that moved since install never reads as a local change. Returns
+        the baseline `commit`, a `clean` flag, and a `files` array of `{ path, status, diff, binary, reconstructed }`
+        for each modified/added/removed file. The baseline is the install commit, not the marketplace pin — comparing
+        against the current pin is `POST /v1/plugins/:name/upgrade` with `dryRun`. A name with no installed copy returns
+        404; an install that recorded no commit or fingerprint returns 409; an unreachable source returns 503. Mirrors
+        the CLI's `assistant plugins diff <name>`."
+      tags:
+        - plugins
+      parameters:
+        - name: name
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  name:
+                    type: string
+                    description: Install name. Matches `assistant plugins install <name>`.
+                  target:
+                    type: string
+                    description: Absolute path to the installed plugin directory on the host.
+                  commit:
+                    type: string
+                    description: Commit the baseline was re-materialized from (the recorded install SHA).
+                  committedAt:
+                    anyOf:
+                      - type: string
+                      - type: "null"
+                    description: ISO-8601 committer timestamp (UTC) of `commit`; null when not recorded.
+                  clean:
+                    type: boolean
+                    description: True when the on-disk tree exactly matches the re-materialized baseline.
+                  files:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        path:
+                          type: string
+                          description: POSIX-relative path within the plugin root.
+                        status:
+                          type: string
+                          enum:
+                            - modified
+                            - added
+                            - removed
+                          description: Whether the file was edited, newly added, or deleted since install.
+                        diff:
+                          type: string
+                          description:
+                            Unified diff (`--- a/… / +++ b/…`) of the file. A short `Binary files differ` marker for binary files, or a
+                            `Baseline unavailable` marker when `reconstructed` is false.
+                        binary:
+                          type: boolean
+                          description: True when either side was detected as binary (NUL byte present).
+                        reconstructed:
+                          type: boolean
+                          description:
+                            True when the install-time baseline for this file was faithfully recovered (re-materialized bytes
+                            hash-match the install fingerprint). False when it could not be reconstructed (e.g. the
+                            curated adapter overlay changed since install), in which case `diff` is a marker, not a
+                            patch. Always true for added files.
+                      required:
+                        - path
+                        - status
+                        - diff
+                        - binary
+                        - reconstructed
+                      additionalProperties: false
+                      description: Unified diff of a single drifted file.
+                    description: One entry per drifted file, sorted by path. Empty when `clean`.
+                required:
+                  - name
+                  - target
+                  - commit
+                  - committedAt
+                  - clean
+                  - files
+                additionalProperties: false
+        "400":
+          description: The plugin name failed sanitization (e.g. contained slashes, dots, or uppercase letters).
+        "404":
+          description: No copy of the plugin is installed, or its recorded commit resolves to nothing.
+        "409":
+          description: The install recorded no commit or no fingerprint to re-materialize and verify a baseline from.
+        "503":
+          description: The plugin source (GitHub) was temporarily unavailable; the diff is retryable.
   /v1/plugins/{name}/inspect:
     get:
       operationId: plugins_by_name_inspect_get
@@ -19481,9 +19530,12 @@ paths:
         mirroring `plugins install`''s curation boundary. A no-op (`outcome: "already-up-to-date"`) when the installed
         commit already equals the pin; pass `dryRun` to preview the move (`outcome: "would-upgrade"`) without touching
         the install. Installs lacking provenance are re-pinned to the current SHA. The assistant must be restarted to
-        load the upgraded code. This does not gate on local edits — callers should consult `GET
-        /v1/plugins/:name/inspect` (`local.localChanges`) first and confirm before overwriting. Mirrors the CLI''s
-        `assistant plugins upgrade <name>`.'
+        load the upgraded code. `strategy` controls how local edits are reconciled: `overwrite` (default) discards them
+        and re-installs the pin wholesale; `ours`/`theirs` perform a three-way merge against the re-materialized install
+        commit, carrying non-conflicting edits from both sides forward and resolving conflicting hunks toward the local
+        edit or the pin respectively; `assistant` is not yet supported (400). A merge strategy whose install-time
+        baseline cannot be reconstructed returns 409. Mirrors the CLI''s `assistant plugins upgrade <name> [--strategy
+        <s>]`.'
       tags:
         - plugins
       parameters:
@@ -19502,6 +19554,17 @@ paths:
                 dryRun:
                   description: Report what would change without modifying the install. Defaults to false.
                   type: boolean
+                strategy:
+                  description:
+                    How to reconcile local edits with the pin. `overwrite` (default) discards local edits and re-installs the
+                    pin; `ours`/`theirs` three-way merge, resolving conflicting hunks toward the local edit or the pin
+                    respectively; `assistant` is not yet supported.
+                  type: string
+                  enum:
+                    - ours
+                    - theirs
+                    - overwrite
+                    - assistant
       responses:
         "200":
           description: Successful response
@@ -19553,6 +19616,14 @@ paths:
                   dryRun:
                     type: boolean
                     description: Whether this was a dry run (no changes made).
+                  strategy:
+                    type: string
+                    enum:
+                      - ours
+                      - theirs
+                      - overwrite
+                      - assistant
+                    description: Conflict-resolution strategy the upgrade applied.
                   provenanceWasUnknown:
                     type: boolean
                     description:
@@ -19568,14 +19639,19 @@ paths:
                   - target
                   - fileCount
                   - dryRun
+                  - strategy
                   - provenanceWasUnknown
                 additionalProperties: false
         "400":
-          description: The plugin name failed sanitization (e.g. contained slashes, dots, or uppercase letters).
+          description:
+            The plugin name failed sanitization (e.g. contained slashes, dots, or uppercase letters), or the
+            `assistant` strategy was requested (not yet supported).
         "404":
           description: No copy of the plugin is installed, or its source resolves to nothing.
         "409":
-          description: The install exists but has no marketplace entry to advance to.
+          description:
+            The install exists but has no marketplace entry to advance to, or a merge strategy was requested whose
+            install-time baseline cannot be reconstructed.
         "503":
           description: The plugin source (GitHub) was temporarily unavailable; the upgrade is retryable.
   /v1/plugins/install:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.9.0",
+  "version": "0.9.1-staging.1",
   "license": "MIT",
   "type": "module",
   "exports": {
@@ -53,6 +53,7 @@
     "@vellumai/twilio-client": "file:../packages/twilio-client",
     "commander": "13.1.0",
     "croner": "10.0.1",
+    "diff": "8.0.4",
     "dotenv": "17.3.1",
     "drizzle-orm": "0.45.2",
     "jszip": "3.10.1",

package/scripts/sync-llm-catalog.ts

@@ -3,19 +3,13 @@
  * Generate `llm-provider-catalog.json` from the canonical
  * `PROVIDER_CATALOG` in `assistant/src/providers/model-catalog.ts`.
  *
- * The JSON file is the client-facing catalog bundled into native clients
- * (macOS, web). Keeping it generated — rather than hand-mirrored — eliminates
- * the recurring "I edited model-catalog.ts and forgot the JSON" failure mode
- * that the parity test only catches after push.
+ * The JSON file is the client-facing catalog. Keeping it generated — rather
+ * than hand-mirrored — eliminates the recurring "I edited model-catalog.ts and
+ * forgot the JSON" failure mode that the parity test only catches after push.
  *
- * Two byte-identical copies are written:
+ * Output:
  *   - `meta/llm-provider-catalog.json` — primary checked-in artifact, read
- *      by web codegen (§D) and any non-Swift consumer.
- *   - `clients/shared/Resources/llm-provider-catalog.json` — SwiftPM resource
- *      bundled into `VellumAssistantShared`. SwiftPM cannot reach files
- *      outside a target's source directory, so this mirror is necessary;
- *      both files are produced by the same generator and asserted equal by
- *      the parity test, making drift impossible.
+ *      by web codegen (§D) and any downstream consumer.
  *
  * The projection drops daemon-only fields (today: `apiKeyUrl`, which clients
  * read from `credentialsGuide.url` instead) and pins field order so the
@@ -37,10 +31,7 @@ import {
 } from "../src/providers/model-catalog.js";
 
 const ROOT = resolve(import.meta.dir, "../..");
-const OUTPUT_PATHS = [
-  join(ROOT, "meta/llm-provider-catalog.json"),
-  join(ROOT, "clients/shared/Resources/llm-provider-catalog.json"),
-] as const;
+const OUTPUT_PATHS = [join(ROOT, "meta/llm-provider-catalog.json")] as const;
 
 /**
  * Bumped when the *shape* of the client catalog JSON changes in a way native

package/scripts/sync-web-search-catalog.ts

@@ -4,7 +4,7 @@
  * canonical `SEARCH_PROVIDER_CATALOG` in
  * `assistant/src/providers/search-provider-catalog.ts`.
  *
- * Two byte-identical copies are written:
+ * Output:
  *   - `meta/web-search-provider-catalog.json` — primary checked-in artifact,
  *      consumed by:
  *        - `cli/src/__tests__/search-provider-env-var-parity.test.ts`
@@ -12,13 +12,8 @@
  *        - Downstream `vellum-assistant-platform/web/src/lib/generated/
  *          web-search-provider-catalog.json` (manually sync'd today; the
  *          scheduled sync workflow is a planned follow-up).
- *   - `clients/shared/Resources/web-search-provider-catalog.json` — SwiftPM
- *      resource bundled into `VellumAssistantShared`. SwiftPM cannot reach
- *      files outside a target's source directory, so this mirror is
- *      necessary; both files are produced by the same generator and
- *      asserted equal by the parity test, making drift impossible.
  *
- * Companion to `sync-llm-catalog.ts`; same dual-write pattern.
+ * Companion to `sync-llm-catalog.ts`.
  *
  * Usage:
  *   cd assistant && bun run scripts/sync-web-search-catalog.ts
@@ -37,7 +32,6 @@ import {
 const ROOT = resolve(import.meta.dir, "../..");
 const OUTPUT_PATHS = [
   join(ROOT, "meta/web-search-provider-catalog.json"),
-  join(ROOT, "clients/shared/Resources/web-search-provider-catalog.json"),
 ] as const;
 
 /**
@@ -108,9 +102,7 @@ async function main(): Promise<void> {
         continue;
       }
       if (existing !== next) {
-        console.error(
-          `${rel} is stale. Run: bun run sync:web-search-catalog`,
-        );
+        console.error(`${rel} is stale. Run: bun run sync:web-search-catalog`);
         anyStale = true;
         continue;
       }