@vellumai/assistant 0.12.0 → 0.12.1-staging.1

package/AGENTS.md

@@ -16,7 +16,7 @@ When you introduce a new env var that the assistant process needs to read at run
 
 **Default to including it.** If the var doesn't contain secrets (e.g. a URL, a feature flag, a path, a mode string), add it. Only omit it if it carries credential material (tokens, passwords, private keys) — those must stay isolated to CES.
 
-`CES_LOCAL_SOCKET` is intentionally included despite the socket exposing credential RPCs: assistant subprocesses are expected to reach CES. Credential protection is rules-based access control inside CES, not socket-path secrecy (see root `AGENTS.md`). Do not forward `CES_SERVICE_TOKEN` or `CES_CREDENTIAL_URL`: the HTTP bearer is a vault secret and must stay in the assistant process.
+`CES_LOCAL_SOCKET` is intentionally included despite the socket exposing credential RPCs: assistant subprocesses are expected to reach CES. Credential protection is rules-based access control inside CES, not socket-path secrecy (see root `AGENTS.md`). `CES_SERVICE_TOKEN` and `CES_CREDENTIAL_URL` are also forwarded: managed children still resolve connections through CES HTTP, and the socket path is not a sufficient substitute yet. See the comment on those keys in `src/tools/terminal/safe-env.ts` before attempting to strip them.
 
 ## Daemon startup philosophy
 
@@ -87,6 +87,10 @@ The module-level dependency-injection pattern (`registerFooDeps()`) used by some
 
 Telemetry event types are defined by a platform-generated wire contract (`src/telemetry/telemetry-wire.generated.ts`) that `src/telemetry/types.ts` layers over, with pre-flush validation against it. Adding a new event type starts platform-side, not here. The mechanics, the drift guards, and the cross-repo ordering are documented next to the code they govern: see [`src/telemetry/AGENTS.md`](src/telemetry/AGENTS.md).
 
+## Daemon i18n
+
+User-facing copy the daemon generates as a hardcoded constant goes through `src/i18n/`. Persist the message key. Resolve with `t(key, locale)` at the HTTP/CLI/channel edge. Never persist a translated string, and never match stored display strings back to keys. See [`src/i18n/AGENTS.md`](src/i18n/AGENTS.md).
+
 ## Code comments
 
 When writing or updating comments, **do not reference code that has been removed.** Comments should describe the current state of the codebase, not narrate its history. Avoid phrases like "no longer does X", "previously used Y", or "was removed in PR Z" — future readers should not need to understand past implementations to understand the current code.

package/ARCHITECTURE.md

@@ -609,9 +609,11 @@ Every phone call connects over Twilio Media Streams: the voice webhook emits `<C
 
 Transcription mode is selected once per session in `media-stream-stt-session.ts`:
 
-- **Streaming** (default): when `calls.voice.telephonyStreaming` is enabled and the `telephony` role resolves a streaming transcriber (`resolveStreamingTranscriber({ role: "telephony" })`), inbound audio is decoded (mu-law → PCM16, resampled 8 kHz → 16 kHz) and fed to the provider's realtime adapter. Replies trigger only on utterance-boundary finals (for Deepgram, `speech_final`/`UtteranceEnd`, never mid-sentence `is_final` segments), and barge-in fires from local energy VAD, never from transcriber partials.
+- **Streaming** (default): when `calls.voice.telephonyStreaming` is enabled and the `telephony` role resolves a streaming transcriber (`resolveStreamingTranscriber({ role: "telephony" })`), inbound audio is decoded (mu-law → PCM16, resampled 8 kHz → 16 kHz) and fed to the provider's realtime adapter. Replies trigger only on utterance-boundary finals (for Deepgram, `speech_final`/`UtteranceEnd`, never mid-sentence `is_final` segments), and barge-in fires from local energy VAD, never from transcriber partials. While something is interruptible (an assistant turn in flight, thinking or speaking, or a completed turn's tail still playing from Twilio's buffer), caller speech arms the shared sustained-speech barge-in guard (`src/calls/barge-in-guard.ts`, the same accounting live voice uses: speech accumulates toward 250 ms, short gaps are tolerated, a run that is mostly silence resets) and every inbound frame feeds it; outside that window the guard is dropped, so the caller's own utterance never carries into a turn that starts before the local VAD ends it. Only a fired guard reaches `CallController.handleBargeIn`, which interrupts a turn in either phase and ignores an idle controller (the playing tail is cleared instead).
 - **Batch fallback**: otherwise the session segments turns with the energy-based `MediaTurnDetector` and transcribes each completed turn via the same role's batch API. Both halves of a call read the `telephony` role, which is why a role names its consumer rather than a boundary.
 
+Every phone turn runs the same two-leg triage as live voice through `startVoiceTurn` (`src/calls/voice-session-bridge.ts`): `call-controller.ts` opens on a toolless front-door leg (`routingLeg: "front-door"`, the `voiceFrontDoor` call site) and drives it through the shared `createFrontDoorLegCoordinator` (`src/calls/voice-leg-coordinator.ts`), which reads the stream through the verdict machine and sequences the hand-off (pause narration, abort the leg, resolve and speak the bridge, mark it as the floor holder, start the escalated leg pinned to the conversation's own model, re-arm narration); each driver supplies only a host for how text and the bridge are spoken, how a leg is started or aborted, and (live voice only) the speculative hold and commit. Phone has no partial transcripts, so the hold verdict is never taught and routing is escalate-only. The controller also passes the bridge's turn callbacks (tool activity is recorded as `tool_use_started` / `tool_use_completed` call events, persisted row ids ride the `assistant_spoke` event), `launchedAtMs` for dispatch timing, and a `voiceTelemetry` bag keyed by the call session with a `phone_inbound` / `phone_outbound` entry. Both drivers share the spoken progress narration cadence (`src/calls/voice-progress-cadence.ts`, tuned by `voice.frontModel.progress`): the cadence owns the tool-activity log, the triggers (an ops burst, a long operation completing, a full interval of audible silence with news, the `maxSilenceMs` heartbeat) and the generated or static phrase, while each driver supplies its own view of audible silence (live voice from its TTS queue and playback-tail estimate; the media-stream transport from `isPlaybackIdle()` and a running sum of sent frame durations) and how to speak a phrase.
+
 A credential preflight (`resolveTelephonyCredentialReadiness()` in `src/calls/telephony-credential-preflight.ts`) gates every call: it requires a credentialed, telephony-capable STT provider **and** a media-stream-playable TTS provider (the configured one or a credentialed playable fallback). Inbound calls that fail the preflight receive `<Say>` setup-required copy plus `<Hangup/>` instead of a doomed stream; outbound placement fails before dialing via `preflightVoiceIngress()` with the same user-facing message.
 
 Key modules:
@@ -729,9 +731,9 @@ The assistant-side live voice module is intentionally bounded under `src/live-vo
 | `live-voice-archive.ts`         | Audio artifact creation/linking for user utterance and assistant response message IDs                                                                       |
 | `live-voice-metrics.ts`         | Per-session and per-turn latency snapshots emitted as `metrics` frames                                                                                      |
 
-Live voice STT uses the same `resolveStreamingTranscriber()` path as conversation streaming. For V1 latency-sensitive behavior, the selected `services.stt.provider` must resolve to a `daemon-streaming` transcriber whose catalog entry has `conversationStreamingMode: "realtime-ws"` and usable credentials. Providers that only support batch or incremental-batch transcription remain valid for other voice surfaces, but do not satisfy live voice's streaming STT requirement.
+Live voice STT uses the same `resolveStreamingTranscriber()` path as conversation streaming, dialed with the provider the `liveVoice` STT role resolves to after managed-speech defaulting (`resolveEffectiveSpeechProviders`, see `config/managed-speech-defaults.ts`). For V1 latency-sensitive behavior, that provider must resolve to a `daemon-streaming` transcriber whose catalog entry has `conversationStreamingMode: "realtime-ws"` and usable credentials. Providers that only support batch or incremental-batch transcription remain valid for other voice surfaces, but do not satisfy live voice's streaming STT requirement.
 
-Live voice TTS uses `streamLiveVoiceTtsAudio()` and the configured `services.tts.provider`. The selected provider must be registered, catalog-compatible, and expose `capabilities.supportsStreaming` plus `synthesizeStream()`. Providers whose catalog entry advertises `supportsStreaming` (currently all four catalog providers: ElevenLabs, Fish Audio, Deepgram, and xAI) satisfy this requirement; a buffered-only provider would remain available for buffered message playback or other supported surfaces, but live voice reports a TTS error instead of silently falling back to buffered playback.
+Live voice TTS uses `streamLiveVoiceTtsAudio()` and the TTS provider that `resolveEffectiveSpeechProviders` settles on (the configured `services.tts.provider`, or the managed `vellum` provider when the configured one has no usable credentials). The selected provider must be registered, catalog-compatible, and expose `capabilities.supportsStreaming` plus `synthesizeStream()`. Providers whose catalog entry advertises `supportsStreaming` (currently all five catalog providers: ElevenLabs, Fish Audio, Deepgram, xAI, and the managed Vellum provider) satisfy this requirement; a buffered-only provider would remain available for buffered message playback or other supported surfaces, but live voice reports a TTS error instead of silently falling back to buffered playback.
 
 The `voiceFrontDoor` prompt skips current-turn legacy and v3 memory retrieval, while prior frozen memory cards and static memory context remain available. The front-door rule escalates rather than guessing when required personal context is absent. The escalated leg runs the ordinary memory pipeline against the latest visible caller prompt before the quality model, with low selector effort. This keeps memory work off the front-door TTFT path without cross-leg speculative state.
 
@@ -1294,9 +1296,8 @@ graph TB
         RM_DIR["rmSync skill directory"]
     end
 
-    subgraph "File Watcher"
-        WATCHER["Skills directory watcher<br/>detects changes"]
-        EVICT["Session eviction<br/>+ recreation"]
+    subgraph "Capability reseed"
+        RESEED["SKILL.md mtime poll<br/>reseeds capability cards"]
     end
 
     SNIPPET --> EVAL_TOOL
@@ -1309,14 +1310,12 @@ graph TB
     SCAFFOLD --> MANAGED_STORE
     MANAGED_STORE --> SKILL_DIR
 
-    SKILL_DIR --> WATCHER
-    WATCHER --> EVICT
-
+    SKILL_DIR --> RESEED
     SKILL_DIR --> SKILL_LOAD
     SKILL_LOAD --> SESSION
 
     DELETE --> RM_DIR
-    RM_DIR --> WATCHER
+    RM_DIR --> RESEED
 ```
 
 **Key design decisions:**
@@ -1324,7 +1323,7 @@ graph TB
 - `evaluate_typescript_code` always forces `sandbox.enabled = true` regardless of global config.
 - Snippet contract: must export `default` or `run` with signature `(input: unknown) => unknown | Promise<unknown>`.
 - Managed-store writes are atomic (tmp file + rename) to prevent partial `SKILL.md` files.
-- After persist or delete, the file watcher triggers conversation eviction; the next turn runs in a fresh conversation. The model's system prompt instructs it to continue normally.
+- After persist or delete, capability cards reseed from the `SKILL.md` set. The next turn continues in the same conversation.
 - macOS UI shows Inspect and Delete controls for managed skills only (source = "managed").
 - `skill_load` resolves the recursive include graph (via `include-graph.ts`) before emitting output. Missing children are listed as suggested skills without child `<loaded_skill>` markers; cycles still produce `isError: true` with no marker. Valid includes produce an "Included Skills (immediate)" metadata section showing child ID, name, description, and path.
 
@@ -2192,7 +2191,7 @@ The `TtsUseCase` discriminator (`"phone-call"` or `"message-playback"`) lets pro
 - **`native-twilio`** — the text-token path: spoken text is sent via `sendTextToken()`, which the media-stream transport re-synthesizes through daemon TTS. Collapsing this mode into `synthesized-play` is a documented deferred follow-up.
 - **`synthesized-play`** — The assistant synthesises audio via the provider's HTTP API and streams it through the audio store / `sendPlayUrl()` path.
 
-**Phone call integration:** Phone calls run on the media-stream transport, where the daemon synthesises speech via the configured TTS provider and transcodes it to mu-law 8 kHz frames (`media-stream-output.ts`). Each catalog entry declares `mediaStreamPlayback.outputFormat` (`pcm`, `wav`, or `none`); `resolveTelephonyTtsCapability()` (`src/calls/telephony-tts-capability.ts`) combines that field with credential availability into a playable / not-playable verdict, and the call TTS resolver falls back to a credentialed playable provider rather than producing silence.
+**Phone call integration:** Phone calls run on the media-stream transport, where the daemon synthesises speech via the effective TTS provider (the configured one after managed-speech defaulting, `resolveEffectiveSpeechProviders`, the same substitution live voice makes) and transcodes it to mu-law 8 kHz frames (`media-stream-output.ts`). Each catalog entry declares `mediaStreamPlayback.outputFormat` (`pcm`, `wav`, or `none`); `resolveTelephonyTtsCapability()` (`src/calls/telephony-tts-capability.ts`) combines that field with credential availability into a playable / not-playable verdict, and the call TTS resolver falls back to a credentialed playable provider rather than producing silence.
 
 **Adding a new TTS provider (catalog-first checklist):**
 

package/docs/architecture/turn-actor.md

@@ -60,14 +60,21 @@ and restore the prior value afterwards, each guarding the restore so a turn that
 started in between is not clobbered. They are supplying the acting actor for
 their run, and are covered by this contract.
 
-A queued message commits to a run at its drain, not at its enqueue. The drains
-(`drainSingleMessage` and `drainBatch` in `conversation-process.ts`) stamp the
-queued sender the way `processMessage` stamps its committing actor, and re-scope
-the resident history to them, so a turn drained behind another actor's turn
-runs as its sender everywhere the resting actor is read, not only in the
-per-turn snapshot. A steered drain skips the re-scope: its sender owned the
-turn it cut off, and the resident history may carry the in-memory repair of the
-abandoned `tool_use`.
+The queue drains are deliberately not in that set. `drainSingleMessage` and
+`drainBatch` carry the queued sender on the per-turn field and into the run,
+and leave the resting slot alone: at the point they stamp, the drain has not
+yet proved it holds the processing lock. Its `isProcessing()` check is a
+time-of-check guard whose documented backstop is the persist that can still
+fail busy, and the requeue on that path restores the queue and the steer flag
+only. A drain that stamped the slot would therefore leave the conversation
+attributed to a sender whose turn never ran.
+
+The consequence is that a cross-actor drain runs against history scoped for the
+previous actor, because `ensureActorScopedHistory` reads the slot. That is a
+real defect and it is LUM-3344's, which owns the fix: scope the transcript at
+assembly time from the turn's actor, rather than mutating a shared transcript
+and tracking who it was scoped for. Do not close it by making the drain stamp
+the slot first.
 
 `call-controller` keeps its own `trustContext` on its own object and never reads
 the conversation's. It is outside this contract.

package/openapi.yaml

@@ -3,7 +3,7 @@
 openapi: 3.1.0
 info:
   title: Vellum Assistant API
-  version: 0.12.0
+  version: 0.12.1
   description: Auto-generated OpenAPI specification for the Vellum Assistant runtime HTTP server.
 servers:
   - url: http://127.0.0.1:7821
@@ -469,6 +469,33 @@ paths:
                           type: string
                         authErrorCode:
                           type: string
+                        model:
+                          type: string
+                        availableModels:
+                          type: array
+                          items:
+                            type: object
+                            properties:
+                              value:
+                                type: string
+                              label:
+                                type: string
+                              description:
+                                type: string
+                              group:
+                                type: string
+                            required:
+                              - value
+                              - label
+                            additionalProperties: false
+                        modelRevisionEpoch:
+                          type: string
+                          format: uuid
+                          pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
+                        modelRevision:
+                          type: integer
+                          minimum: 0
+                          maximum: 9007199254740991
                         usedTokens:
                           type: number
                         contextSize:
@@ -548,6 +575,9 @@ paths:
                 cwd:
                   type: string
                   description: Working directory
+                model:
+                  description: Optional model id or alias to request for the session.
+                  type: string
               required:
                 - agent
                 - task
@@ -566,10 +596,25 @@ paths:
                     type: string
                   agent:
                     type: string
+                  requestedModel:
+                    anyOf:
+                      - type: string
+                      - type: "null"
+                    description: The model explicitly requested for this spawn, if any.
+                  effectiveModel:
+                    anyOf:
+                      - type: string
+                      - type: "null"
+                    description: The top-level session model reported by the ACP adapter, if any.
+                  modelWarning:
+                    description: Why the requested model was not applied. The session is running on the agent's own model.
+                    type: string
                 required:
                   - acpSessionId
                   - protocolSessionId
                   - agent
+                  - requestedModel
+                  - effectiveModel
                 additionalProperties: false
   /v1/activation/dismiss:
     post:
@@ -1580,6 +1625,93 @@ paths:
                 required:
                   - published
                 additionalProperties: false
+  /v1/apps/{id}/refresh:
+    post:
+      operationId: apps_by_id_refresh_post
+      summary: Compile an app
+      description: Compile workspace or plugin app source into dist/ and refresh open surfaces.
+      tags:
+        - apps
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  ok:
+                    type: boolean
+                    const: true
+                  appId:
+                    type: string
+                  name:
+                    type: string
+                  compiled:
+                    type: boolean
+                  compile_duration_ms:
+                    type: number
+                  compile_errors:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        text:
+                          type: string
+                        location:
+                          type: object
+                          properties:
+                            file:
+                              type: string
+                            line:
+                              type: number
+                            column:
+                              type: number
+                          required:
+                            - file
+                            - line
+                            - column
+                          additionalProperties: false
+                      required:
+                        - text
+                      additionalProperties: false
+                  compile_warnings:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        text:
+                          type: string
+                        location:
+                          type: object
+                          properties:
+                            file:
+                              type: string
+                            line:
+                              type: number
+                            column:
+                              type: number
+                          required:
+                            - file
+                            - line
+                            - column
+                          additionalProperties: false
+                      required:
+                        - text
+                      additionalProperties: false
+                required:
+                  - ok
+                  - appId
+                  - name
+                  - compiled
+                  - compile_duration_ms
+                additionalProperties: false
   /v1/apps/{id}/share-cloud:
     post:
       operationId: apps_by_id_sharecloud_post
@@ -5350,6 +5482,101 @@ paths:
       responses:
         "200":
           description: Successful response
+  /v1/channels/send:
+    post:
+      operationId: channels_send_post
+      summary: Send text to a channel chat
+      description: Deliver text to a chat on a channel through the channel's transport, recorded after the channel acknowledges it.
+      tags:
+        - channels
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                channel:
+                  type: string
+                  enum:
+                    - telegram
+                    - phone
+                    - vellum
+                    - whatsapp
+                    - slack
+                    - email
+                    - platform
+                    - a2a
+                    - discord
+                    - plugin
+                  description: Channel to send on
+                target:
+                  type: object
+                  properties:
+                    kind:
+                      type: string
+                      const: chat
+                    chatId:
+                      type: string
+                      minLength: 1
+                      description: Chat id in the channel's own id space
+                    threadId:
+                      description: Thread within the chat, in the channel's own id space
+                      type: string
+                      minLength: 1
+                  required:
+                    - kind
+                    - chatId
+                text:
+                  type: string
+                  minLength: 1
+                  description: Text to send
+                renderRichly:
+                  description: Ask the channel for its rich rendering, where it has one
+                  type: boolean
+              required:
+                - channel
+                - target
+                - text
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  channel:
+                    type: string
+                    enum:
+                      - telegram
+                      - phone
+                      - vellum
+                      - whatsapp
+                      - slack
+                      - email
+                      - platform
+                      - a2a
+                      - discord
+                      - plugin
+                  chatId:
+                    type: string
+                  threadId:
+                    type: string
+                  messageIds:
+                    type: array
+                    items:
+                      type: string
+                  lastMessageId:
+                    type: string
+                  recordedIn:
+                    type: string
+                required:
+                  - channel
+                  - chatId
+                  - messageIds
+                  - lastMessageId
+                additionalProperties: false
   /v1/clients:
     get:
       operationId: clients_get
@@ -11146,7 +11373,9 @@ paths:
     post:
       operationId: credentials_list_post
       summary: List all credentials with metadata
-      description: Return all stored credentials with metadata, OAuth connection info, and platform-managed credentials.
+      description:
+        Return credentials from the live credential vault, with OAuth connection info and platform-managed
+        credentials. Fails if the vault is unreachable.
       tags:
         - credentials
       requestBody:
@@ -11732,6 +11961,67 @@ paths:
                 required:
                   - defers
                 additionalProperties: false
+  /v1/desktop/setup:
+    get:
+      operationId: desktop_setup_get
+      summary: Get desktop setup status
+      tags:
+        - desktop
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  state:
+                    type: string
+                    enum:
+                      - required
+                      - installing
+                      - ready
+                      - failed
+                      - unsupported
+                  stage:
+                    type: string
+                    enum:
+                      - packages
+                      - chrome
+                      - checking
+                required:
+                  - state
+                additionalProperties: false
+    post:
+      operationId: desktop_setup_post
+      summary: Install desktop components
+      tags:
+        - desktop
+      responses:
+        "200":
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  state:
+                    type: string
+                    enum:
+                      - required
+                      - installing
+                      - ready
+                      - failed
+                      - unsupported
+                  stage:
+                    type: string
+                    enum:
+                      - packages
+                      - chrome
+                      - checking
+                required:
+                  - state
+                additionalProperties: false
   /v1/diagnostics/env-vars:
     get:
       operationId: diagnostics_envvars_get

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.12.0",
+  "version": "0.12.1-staging.1",
   "license": "MIT",
   "type": "module",
   "exports": {