@vellumai/plugin-api 0.11.2-dev.202608051637.aae860e → 0.11.2-dev.202608051838.a2809c6

package/index.d.ts

@@ -2533,6 +2533,12 @@ export declare class AssistantEventHub {
      * delivery to remaining subscribers.
      */
     publish(event: AssistantEventEnvelope, options?: AssistantEventPublishOptions): Promise<void>;
+    /**
+     * Yield every active client entry with the given clientId. `subscribe`
+     * disposes any prior entries for the same clientId, so at most one entry
+     * matches.
+     */
+    private activeClientEntries;
     /**
      * Return the active client subscriber with the given clientId, or
      * `undefined` if no such subscriber exists.
@@ -2547,6 +2553,19 @@ export declare class AssistantEventHub {
      * authenticated user identity that opened the target client's SSE stream.
      */
     getActorPrincipalIdForClient(clientId: string): string | undefined;
+    /**
+     * Fill a missing `actorPrincipalId` on a live client subscription.
+     *
+     * Used by the SSE dev-bypass self-heal: when the guardian-delivery cache is
+     * cold at subscribe time, the registration lands without a principal; the
+     * route resolves it async and patches the record here. Keyed by
+     * `connectionId` (not clientId) so a reconnect race cannot patch the
+     * subscription that replaced the one being healed. No-op when the
+     * connection is gone or already carries a principal: this only fills a
+     * missing value, never overwrites one. The value must come from the
+     * daemon's own server-side guardian lookup, never from client input.
+     */
+    fillClientActorPrincipalId(connectionId: string, actorPrincipalId: string): void;
     /**
      * Returns true when at least one active subscriber would receive the given
      * event based on the same conversation matching rules as publish().
@@ -2576,6 +2595,12 @@ export declare class AssistantEventHub {
      * Touch a client subscriber — update `lastActiveAt`. Used by heartbeat.
      */
     touchClient(clientId: string): void;
+    /**
+     * Record the desktop presence state reported by a client. `reportedAt`
+     * always advances. Returns true when at least one active client entry
+     * matched.
+     */
+    setClientPresence(clientId: string, state: DesktopPresenceState): boolean;
     /**
      * Force-disconnect a client by disposing all subscribers for the given
      * `clientId`. Returns the number of disposed entries.
@@ -4031,6 +4056,17 @@ declare interface ClientEntry extends BaseSubscriberEntry {
      * service-token connections that have no principal.
      */
     actorPrincipalId?: string;
+    /**
+     * Last desktop presence reported by this client, for clients that report it.
+     * In-memory only, so consumers must fail open when it is absent.
+     */
+    presence?: ClientPresence;
+}
+
+declare interface ClientPresence {
+    state: DesktopPresenceState;
+    /** When the daemon last heard from the client. Drives staleness. */
+    reportedAt: Date;
 }
 
 declare interface CliOptionHelp {
@@ -4189,6 +4225,14 @@ export declare class CredentialResolutionError extends Error {
  */
 export declare function deleteConversation(id: string): Promise<void>;
 
+/**
+ * The presence states a desktop client may report. Single runtime source: the
+ * stored type and the route's wire enum both derive from this tuple.
+ */
+declare const DESKTOP_PRESENCE_STATES: readonly ["active", "idle", "away"];
+
+declare type DesktopPresenceState = (typeof DESKTOP_PRESENCE_STATES)[number];
+
 declare interface DiffInfo {
     filePath: string;
     oldContent: string;
@@ -4978,6 +5022,7 @@ declare const messageMetadataSchema: z.ZodObject<{
     userMessageInterface: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<"telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route" | null, string>> & z.ZodType<"telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route", string, z.core.$ZodTypeInternals<"telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route", string>>>;
     assistantMessageInterface: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<"telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route" | null, string>> & z.ZodType<"telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route", string, z.core.$ZodTypeInternals<"telegram" | "phone" | "whatsapp" | "slack" | "email" | "a2a" | "discord" | "macos" | "ios" | "cli" | "web" | "chrome-extension" | "route", string>>>;
     client: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    clientOsFromRequest: z.ZodOptional<z.ZodBoolean>;
     subagentNotification: z.ZodOptional<z.ZodObject<{
         subagentId: z.ZodString;
         label: z.ZodString;
@@ -6799,10 +6844,12 @@ export declare interface ToolContext {
     invokingCallSite?: LLMCallSite;
     /**
      * Canonical principal ID of the actor on whose behalf this tool invocation
-     * is running. Sourced from `conversation.trustContext.guardianPrincipalId`.
+     * is running — the turn's actor principal, falling back to the trust
+     * context's `guardianPrincipalId` (see `resolveTurnActorPrincipalId`).
      * Used by host proxies to bind cross-client targeted execution to the same
-     * authenticated user identity. May be undefined for legacy/internal flows
-     * with no resolved actor identity.
+     * authenticated user identity, so it must resolve to the SAME principal a
+     * desktop client registers with on its SSE stream. May be undefined for
+     * legacy/internal flows with no resolved actor identity.
      * @legacy
      */
     sourceActorPrincipalId?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/plugin-api",
-  "version": "0.11.2-dev.202608051637.aae860e",
+  "version": "0.11.2-dev.202608051838.a2809c6",
   "description": "Public TypeScript authoring contract for Vellum assistant plugins.",
   "license": "MIT",
   "type": "module",