@vellumai/plugin-api 0.11.2-staging.3 → 0.11.3-staging.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/index.d.ts +286 -18
  2. package/index.js +2 -0
  3. package/package.json +1 -1
package/index.d.ts CHANGED
@@ -76,6 +76,37 @@ export declare type AgentLoopExitReason =
76
76
  /** An unhandled error ended the turn. */
77
77
  | "error";
78
78
 
79
+ declare type AnsweredQuestion = z.infer<typeof AnsweredQuestionSchema>;
80
+
81
+ declare const AnsweredQuestionSchema: z.ZodObject<{
82
+ requestId: z.ZodString;
83
+ questions: z.ZodArray<z.ZodObject<{
84
+ id: z.ZodString;
85
+ question: z.ZodString;
86
+ description: z.ZodOptional<z.ZodString>;
87
+ options: z.ZodArray<z.ZodObject<{
88
+ id: z.ZodString;
89
+ label: z.ZodString;
90
+ description: z.ZodOptional<z.ZodString>;
91
+ }, z.core.$strip>>;
92
+ freeTextPlaceholder: z.ZodOptional<z.ZodString>;
93
+ }, z.core.$strip>>;
94
+ responses: z.ZodArray<z.ZodObject<{
95
+ questionId: z.ZodString;
96
+ decision: z.ZodEnum<{
97
+ option: "option";
98
+ free_text: "free_text";
99
+ skipped: "skipped";
100
+ }>;
101
+ optionId: z.ZodOptional<z.ZodString>;
102
+ text: z.ZodOptional<z.ZodString>;
103
+ }, z.core.$strip>>;
104
+ overall: z.ZodEnum<{
105
+ completed: "completed";
106
+ closed: "closed";
107
+ }>;
108
+ }, z.core.$strip>;
109
+
79
110
  /**
80
111
  * How {@link listConversations} (and friends) treats archived rows.
81
112
  *
@@ -120,7 +151,7 @@ declare const AssistantConfigSchema: z.ZodObject<{
120
151
  "openai-whisper": "openai-whisper";
121
152
  xai: "xai";
122
153
  }>>;
123
- language: z.ZodOptional<z.ZodString>;
154
+ language: z.ZodDefault<z.ZodString>;
124
155
  providers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>>>;
125
156
  }, z.core.$strip>>;
126
157
  tts: z.ZodDefault<z.ZodObject<{
@@ -484,6 +515,11 @@ declare const AssistantConfigSchema: z.ZodObject<{
484
515
  }, z.core.$strip>>;
485
516
  }, z.core.$strip>>;
486
517
  retrospective: z.ZodDefault<z.ZodObject<{
518
+ enabled: z.ZodDefault<z.ZodBoolean>;
519
+ forkStrategy: z.ZodDefault<z.ZodEnum<{
520
+ cloning: "cloning";
521
+ reference: "reference";
522
+ }>>;
487
523
  timeThresholdMs: z.ZodDefault<z.ZodNumber>;
488
524
  messageThreshold: z.ZodDefault<z.ZodNumber>;
489
525
  minCooldownMs: z.ZodDefault<z.ZodNumber>;
@@ -1070,6 +1106,7 @@ declare const AssistantConfigSchema: z.ZodObject<{
1070
1106
  botId: z.ZodDefault<z.ZodString>;
1071
1107
  botUsername: z.ZodDefault<z.ZodString>;
1072
1108
  apiBaseUrl: z.ZodDefault<z.ZodString>;
1109
+ registeredWebhookUrl: z.ZodOptional<z.ZodString>;
1073
1110
  deliverAuthBypass: z.ZodDefault<z.ZodBoolean>;
1074
1111
  timeoutMs: z.ZodDefault<z.ZodNumber>;
1075
1112
  maxRetries: z.ZodDefault<z.ZodNumber>;
@@ -1162,6 +1199,18 @@ declare const AssistantConfigSchema: z.ZodObject<{
1162
1199
  journalRetentionDays: z.ZodDefault<z.ZodNumber>;
1163
1200
  }, z.core.$strip>>;
1164
1201
  plugins: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
1202
+ pluginUpdates: z.ZodDefault<z.ZodObject<{
1203
+ mode: z.ZodDefault<z.ZodEnum<{
1204
+ auto: "auto";
1205
+ manual: "manual";
1206
+ }>>;
1207
+ strategy: z.ZodDefault<z.ZodEnum<{
1208
+ theirs: "theirs";
1209
+ ours: "ours";
1210
+ overwrite: "overwrite";
1211
+ }>>;
1212
+ checkIntervalMs: z.ZodDefault<z.ZodNumber>;
1213
+ }, z.core.$strip>>;
1165
1214
  legacyTelemetryOptOut: z.ZodOptional<z.ZodBoolean>;
1166
1215
  legacyDiagnosticsOptOut: z.ZodOptional<z.ZodBoolean>;
1167
1216
  maxStepsPerSession: z.ZodDefault<z.ZodNumber>;
@@ -1306,8 +1355,8 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
1306
1355
  id: z.ZodString;
1307
1356
  conversationId: z.ZodString;
1308
1357
  status: z.ZodEnum<{
1309
- cancelled: "cancelled";
1310
1358
  completed: "completed";
1359
+ cancelled: "cancelled";
1311
1360
  failed: "failed";
1312
1361
  }>;
1313
1362
  exitCode: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
@@ -2258,6 +2307,34 @@ declare const AssistantEventEnvelopeSchema: z.ZodObject<{
2258
2307
  mayRequireJavaScript: z.ZodOptional<z.ZodBoolean>;
2259
2308
  }, z.core.$strip>>;
2260
2309
  }, z.core.$strip>>;
2310
+ answeredQuestion: z.ZodOptional<z.ZodObject<{
2311
+ requestId: z.ZodString;
2312
+ questions: z.ZodArray<z.ZodObject<{
2313
+ id: z.ZodString;
2314
+ question: z.ZodString;
2315
+ description: z.ZodOptional<z.ZodString>;
2316
+ options: z.ZodArray<z.ZodObject<{
2317
+ id: z.ZodString;
2318
+ label: z.ZodString;
2319
+ description: z.ZodOptional<z.ZodString>;
2320
+ }, z.core.$strip>>;
2321
+ freeTextPlaceholder: z.ZodOptional<z.ZodString>;
2322
+ }, z.core.$strip>>;
2323
+ responses: z.ZodArray<z.ZodObject<{
2324
+ questionId: z.ZodString;
2325
+ decision: z.ZodEnum<{
2326
+ option: "option";
2327
+ free_text: "free_text";
2328
+ skipped: "skipped";
2329
+ }>;
2330
+ optionId: z.ZodOptional<z.ZodString>;
2331
+ text: z.ZodOptional<z.ZodString>;
2332
+ }, z.core.$strip>>;
2333
+ overall: z.ZodEnum<{
2334
+ completed: "completed";
2335
+ closed: "closed";
2336
+ }>;
2337
+ }, z.core.$strip>>;
2261
2338
  errorCode: z.ZodOptional<z.ZodString>;
2262
2339
  completedAt: z.ZodOptional<z.ZodNumber>;
2263
2340
  }, z.core.$strip>, z.ZodObject<{
@@ -2474,6 +2551,12 @@ export declare class AssistantEventHub {
2474
2551
  * delivery to remaining subscribers.
2475
2552
  */
2476
2553
  publish(event: AssistantEventEnvelope, options?: AssistantEventPublishOptions): Promise<void>;
2554
+ /**
2555
+ * Yield every active client entry with the given clientId. `subscribe`
2556
+ * disposes any prior entries for the same clientId, so at most one entry
2557
+ * matches.
2558
+ */
2559
+ private activeClientEntries;
2477
2560
  /**
2478
2561
  * Return the active client subscriber with the given clientId, or
2479
2562
  * `undefined` if no such subscriber exists.
@@ -2488,6 +2571,19 @@ export declare class AssistantEventHub {
2488
2571
  * authenticated user identity that opened the target client's SSE stream.
2489
2572
  */
2490
2573
  getActorPrincipalIdForClient(clientId: string): string | undefined;
2574
+ /**
2575
+ * Fill a missing `actorPrincipalId` on a live client subscription.
2576
+ *
2577
+ * Used by the SSE dev-bypass self-heal: when the guardian-delivery cache is
2578
+ * cold at subscribe time, the registration lands without a principal; the
2579
+ * route resolves it async and patches the record here. Keyed by
2580
+ * `connectionId` (not clientId) so a reconnect race cannot patch the
2581
+ * subscription that replaced the one being healed. No-op when the
2582
+ * connection is gone or already carries a principal: this only fills a
2583
+ * missing value, never overwrites one. The value must come from the
2584
+ * daemon's own server-side guardian lookup, never from client input.
2585
+ */
2586
+ fillClientActorPrincipalId(connectionId: string, actorPrincipalId: string): void;
2491
2587
  /**
2492
2588
  * Returns true when at least one active subscriber would receive the given
2493
2589
  * event based on the same conversation matching rules as publish().
@@ -2517,6 +2613,12 @@ export declare class AssistantEventHub {
2517
2613
  * Touch a client subscriber — update `lastActiveAt`. Used by heartbeat.
2518
2614
  */
2519
2615
  touchClient(clientId: string): void;
2616
+ /**
2617
+ * Record the desktop presence state reported by a client. `reportedAt`
2618
+ * always advances. Returns true when at least one active client entry
2619
+ * matched.
2620
+ */
2621
+ setClientPresence(clientId: string, state: DesktopPresenceState): boolean;
2520
2622
  /**
2521
2623
  * Force-disconnect a client by disposing all subscribers for the given
2522
2624
  * `clientId`. Returns the number of disposed entries.
@@ -2694,8 +2796,8 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
2694
2796
  id: z.ZodString;
2695
2797
  conversationId: z.ZodString;
2696
2798
  status: z.ZodEnum<{
2697
- cancelled: "cancelled";
2698
2799
  completed: "completed";
2800
+ cancelled: "cancelled";
2699
2801
  failed: "failed";
2700
2802
  }>;
2701
2803
  exitCode: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
@@ -3646,6 +3748,34 @@ declare const AssistantEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
3646
3748
  mayRequireJavaScript: z.ZodOptional<z.ZodBoolean>;
3647
3749
  }, z.core.$strip>>;
3648
3750
  }, z.core.$strip>>;
3751
+ answeredQuestion: z.ZodOptional<z.ZodObject<{
3752
+ requestId: z.ZodString;
3753
+ questions: z.ZodArray<z.ZodObject<{
3754
+ id: z.ZodString;
3755
+ question: z.ZodString;
3756
+ description: z.ZodOptional<z.ZodString>;
3757
+ options: z.ZodArray<z.ZodObject<{
3758
+ id: z.ZodString;
3759
+ label: z.ZodString;
3760
+ description: z.ZodOptional<z.ZodString>;
3761
+ }, z.core.$strip>>;
3762
+ freeTextPlaceholder: z.ZodOptional<z.ZodString>;
3763
+ }, z.core.$strip>>;
3764
+ responses: z.ZodArray<z.ZodObject<{
3765
+ questionId: z.ZodString;
3766
+ decision: z.ZodEnum<{
3767
+ option: "option";
3768
+ free_text: "free_text";
3769
+ skipped: "skipped";
3770
+ }>;
3771
+ optionId: z.ZodOptional<z.ZodString>;
3772
+ text: z.ZodOptional<z.ZodString>;
3773
+ }, z.core.$strip>>;
3774
+ overall: z.ZodEnum<{
3775
+ completed: "completed";
3776
+ closed: "closed";
3777
+ }>;
3778
+ }, z.core.$strip>>;
3649
3779
  errorCode: z.ZodOptional<z.ZodString>;
3650
3780
  completedAt: z.ZodOptional<z.ZodNumber>;
3651
3781
  }, z.core.$strip>, z.ZodObject<{
@@ -3944,6 +4074,17 @@ declare interface ClientEntry extends BaseSubscriberEntry {
3944
4074
  * service-token connections that have no principal.
3945
4075
  */
3946
4076
  actorPrincipalId?: string;
4077
+ /**
4078
+ * Last desktop presence reported by this client, for clients that report it.
4079
+ * In-memory only, so consumers must fail open when it is absent.
4080
+ */
4081
+ presence?: ClientPresence;
4082
+ }
4083
+
4084
+ declare interface ClientPresence {
4085
+ state: DesktopPresenceState;
4086
+ /** When the daemon last heard from the client. Drives staleness. */
4087
+ reportedAt: Date;
3947
4088
  }
3948
4089
 
3949
4090
  declare interface CliOptionHelp {
@@ -4033,6 +4174,8 @@ export declare interface ConversationRow {
4033
4174
  originInterface: string | null;
4034
4175
  forkParentConversationId: string | null;
4035
4176
  forkParentMessageId: string | null;
4177
+ /** `"reference"` on referential forks; `"cloning"` or null on copied ones. */
4178
+ forkStrategy: string | null;
4036
4179
  isAutoTitle: number;
4037
4180
  scheduleJobId: string | null;
4038
4181
  lastMessageAt: number | null;
@@ -4102,6 +4245,14 @@ export declare class CredentialResolutionError extends Error {
4102
4245
  */
4103
4246
  export declare function deleteConversation(id: string): Promise<void>;
4104
4247
 
4248
+ /**
4249
+ * The presence states a desktop client may report. Single runtime source: the
4250
+ * stored type and the route's wire enum both derive from this tuple.
4251
+ */
4252
+ declare const DESKTOP_PRESENCE_STATES: readonly ["active", "idle", "away"];
4253
+
4254
+ declare type DesktopPresenceState = (typeof DESKTOP_PRESENCE_STATES)[number];
4255
+
4105
4256
  declare interface DiffInfo {
4106
4257
  filePath: string;
4107
4258
  oldContent: string;
@@ -4190,6 +4341,14 @@ export declare function getConversation(id: string): Promise<ConversationRow | n
4190
4341
  */
4191
4342
  export declare function getConversationDirPath(id: string, createdAtMs: number): Promise<string>;
4192
4343
 
4344
+ /**
4345
+ * The persisted `processing_started_at` stamp for a conversation, or null
4346
+ * when the conversation is idle (or the row does not exist). Lets background
4347
+ * consumers age-gate the processing flag: a stamp far in the past is a
4348
+ * stranded flag (a swallowed turn-end clear), not a live turn.
4349
+ */
4350
+ export declare function getConversationProcessingStartedAt(id: string): Promise<number | null>;
4351
+
4193
4352
  /** Fetch one document from the calling plugin's index, or null. */
4194
4353
  export declare function getDocument(documentId: string): Promise<IndexedDocument | null>;
4195
4354
 
@@ -4512,7 +4671,13 @@ export declare function lastToolResultUserMessageIndex(history: Message[]): numb
4512
4671
  */
4513
4672
  export declare function listCatalogSkills(): Promise<ResolvedSkillEntry[]>;
4514
4673
 
4515
- /** List conversation rows, newest first. */
4674
+ /**
4675
+ * List conversation rows, newest first.
4676
+ *
4677
+ * The positional signature is part of the plugin API surface and stays
4678
+ * stable; the underlying query takes a named filter, which this maps onto.
4679
+ * Omitted arguments stay omitted so the query's own defaults apply.
4680
+ */
4516
4681
  export declare function listConversations(limit?: number, conversationType?: ConversationType, offset?: number, archiveStatus?: ArchiveStatusFilter, originChannel?: string): Promise<ConversationRow[]>;
4517
4682
 
4518
4683
  /**
@@ -4607,6 +4772,19 @@ declare interface LiveVoiceErrorServerFrame extends LiveVoiceServerFrameBase {
4607
4772
  readonly type: "error";
4608
4773
  readonly code: LiveVoiceProtocolErrorCode;
4609
4774
  readonly message: string;
4775
+ /**
4776
+ * The client frame this error is about, when the failure was a parse or
4777
+ * validation failure of a specific frame. Absent otherwise, and absent from
4778
+ * daemons predating the field.
4779
+ *
4780
+ * It exists so an `unknown_type` is attributable. A client that sends more
4781
+ * than one optional frame (today: `update_config` and `attach_image`) gets
4782
+ * the same code for either, and without this has to assume which one was
4783
+ * refused. The wrong assumption is silent in both directions: settings stop
4784
+ * applying for a session, or a photo the user watched themselves take is
4785
+ * dropped with nothing said.
4786
+ */
4787
+ readonly frameType?: string;
4610
4788
  /**
4611
4789
  * True when the session continues past the error (e.g. a transient
4612
4790
  * transcriber blip or one failed TTS segment). Absent (including on frames
@@ -4883,6 +5061,7 @@ declare const messageMetadataSchema: z.ZodObject<{
4883
5061
  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>>>;
4884
5062
  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>>>;
4885
5063
  client: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
5064
+ clientOsFromRequest: z.ZodOptional<z.ZodBoolean>;
4886
5065
  subagentNotification: z.ZodOptional<z.ZodObject<{
4887
5066
  subagentId: z.ZodString;
4888
5067
  label: z.ZodString;
@@ -4933,8 +5112,8 @@ declare const messageMetadataSchema: z.ZodObject<{
4933
5112
  command: z.ZodString;
4934
5113
  startedAt: z.ZodNumber;
4935
5114
  status: z.ZodEnum<{
4936
- cancelled: "cancelled";
4937
5115
  completed: "completed";
5116
+ cancelled: "cancelled";
4938
5117
  failed: "failed";
4939
5118
  }>;
4940
5119
  exitCode: z.ZodNullable<z.ZodNumber>;
@@ -5624,7 +5803,7 @@ declare type ResolutionFallbackReason = "missing" | "disabled" | "incomplete";
5624
5803
  * 3. `llm.callSites[callSite].profile` (the call site's named profile)
5625
5804
  * 4. `CALL_SITE_DEFAULTS[callSite].profile` intent resolved through
5626
5805
  * `llm.defaultProvider`
5627
- * 5. balanced intent through `llm.defaultProvider` the code-owned anchor
5806
+ * 5. balanced intent through `llm.defaultProvider`: the code-owned anchor
5628
5807
  * for profileless call sites, or when nothing above is usable
5629
5808
  *
5630
5809
  * A winner must carry its own `provider` AND `model`: the base layer's schema
@@ -5767,12 +5946,31 @@ export declare function resolveMediaSourceData(source: MediaSource_2): {
5767
5946
  } | null;
5768
5947
 
5769
5948
  /**
5770
- * Read the guardian's display name from `users/default.md`. We look for the
5771
- * markdown-bold "Name" label (matching the IDENTITY.md convention) and fall
5772
- * back to `null` on any miss; callers substitute a generic label.
5949
+ * Read the user's display name from the guardian's persona file
5950
+ * (`users/<slug>.md`, resolved via the guardian-delivery binding), falling
5951
+ * back to `users/default.md`. Returns `null` on any miss; callers substitute
5952
+ * a generic label.
5953
+ *
5954
+ * The guardian resolution reads the sync in-process guardian-delivery cache;
5955
+ * callers in processes that do not otherwise warm it (memory worker) await
5956
+ * `getGuardianDelivery` first.
5773
5957
  */
5774
5958
  export declare function resolveUserName(workspaceDir: string): string | null;
5775
5959
 
5960
+ /**
5961
+ * Resolve the public URL a third party should deliver to for `path`.
5962
+ *
5963
+ * On the managed branches this registers a callback route with the platform,
5964
+ * which is idempotent and matches what `assistant webhooks register` does.
5965
+ *
5966
+ * @throws when the plugin cannot be determined, when `path` is not one the
5967
+ * gateway would serve, or when no ingress is configured and the assistant is
5968
+ * not connected to the platform. That last case has no URL that would work,
5969
+ * and a plausible one would produce a vendor registration that silently
5970
+ * receives nothing.
5971
+ */
5972
+ export declare function resolveWebhookUrl(options: WebhookUrlOptions): Promise<string>;
5973
+
5776
5974
  export declare enum RiskLevel {
5777
5975
  Low = "low",
5778
5976
  Medium = "medium",
@@ -5992,12 +6190,32 @@ export declare interface SendMessageConfig {
5992
6190
  */
5993
6191
  logit_bias?: Record<string, number>;
5994
6192
  /**
5995
- * When true, the most recent user message's content varies across
5996
- * otherwise-identical turns (e.g. a per-turn memory block was injected into
5997
- * it). The provider places the primary long-TTL cache breakpoint on the most
5998
- * recent *stable* user message instead of the volatile latest one, so the
5999
- * cached prefix stays reusable across turns. Default false — existing
6000
- * behavior.
6193
+ * When true, the TURN-STARTING user message carries content that will not
6194
+ * recur byte-identically on the next turn, so a long-TTL breakpoint placed
6195
+ * on it could never be read back across turns. The agent loop is the only
6196
+ * producer: it sets the flag from the history it is about to send, when the
6197
+ * turn-starting message carries a memory-v3 `<memory_spotlight>` block (the
6198
+ * one injected block strip-and-replaced from every user message each turn).
6199
+ *
6200
+ * The flag describes the turn, not the request, so it holds for every
6201
+ * request the turn makes, including tool-loop iterations, whose trailing
6202
+ * tool-result message is user-role but carries no injected blocks.
6203
+ *
6204
+ * Consumed by the Anthropic client only, where it selects the TTL of the
6205
+ * turn-start breakpoint: short instead of long. The block is still marked,
6206
+ * so the turn's tool-loop iterations read the prefix back and each hit
6207
+ * refreshes the entry; nothing is spent on a long-TTL entry whose bytes
6208
+ * change before the next turn could reach it. Holding the flag steady across
6209
+ * the turn is what keeps that one boundary on a single TTL; marking it at
6210
+ * two would bill two writes for one reusable prefix.
6211
+ *
6212
+ * The OpenAI Responses transport ignores the flag and marks every markable
6213
+ * user item: a volatile message is fixed within its own turn, so the write is
6214
+ * prepaid once and read back by each tool-loop iteration.
6215
+ *
6216
+ * Default false. Providers that place no message-level breakpoints, or that
6217
+ * key their cache on a request-level identifier rather than message bytes,
6218
+ * can ignore it.
6001
6219
  */
6002
6220
  mutableLatestUserMessage?: boolean;
6003
6221
  /**
@@ -6685,6 +6903,14 @@ export declare interface ToolContext {
6685
6903
  * @legacy
6686
6904
  */
6687
6905
  overrideProfile?: string;
6906
+ /**
6907
+ * The firing's `cron_runs.id` when a schedule triggered this turn, `null`
6908
+ * otherwise. Tools that spawn further LLM work (`subagent_spawn`,
6909
+ * `subagent_message`) forward it so the delegated usage rows carry the same
6910
+ * stamp and attribute to the firing rather than dropping out of schedule
6911
+ * cost reporting.
6912
+ */
6913
+ cronRunId?: string | null;
6688
6914
  /**
6689
6915
  * The LLM call site of the turn currently executing this tool (`mainAgent`,
6690
6916
  * `heartbeatAgent`, scheduled work, etc.). `subagent_spawn` reads it to
@@ -6696,10 +6922,12 @@ export declare interface ToolContext {
6696
6922
  invokingCallSite?: LLMCallSite;
6697
6923
  /**
6698
6924
  * Canonical principal ID of the actor on whose behalf this tool invocation
6699
- * is running. Sourced from `conversation.trustContext.guardianPrincipalId`.
6925
+ * is running the turn's actor principal, falling back to the trust
6926
+ * context's `guardianPrincipalId` (see `resolveTurnActorPrincipalId`).
6700
6927
  * Used by host proxies to bind cross-client targeted execution to the same
6701
- * authenticated user identity. May be undefined for legacy/internal flows
6702
- * with no resolved actor identity.
6928
+ * authenticated user identity, so it must resolve to the SAME principal a
6929
+ * desktop client registers with on its SSE stream. May be undefined for
6930
+ * legacy/internal flows with no resolved actor identity.
6703
6931
  * @legacy
6704
6932
  */
6705
6933
  sourceActorPrincipalId?: string;
@@ -6860,6 +7088,14 @@ export declare interface ToolExecutionResult {
6860
7088
  /** Structured activity metadata for client rendering (web search, web fetch, etc).
6861
7089
  * Populated by daemon-internal tools; plugins must not set this. */
6862
7090
  activityMetadata?: ToolActivityMetadata;
7091
+ /**
7092
+ * Typed side channel from the `ask_question` executor to the agent loop: the
7093
+ * questions asked and the answers the user gave. The loop forwards it on the
7094
+ * `tool_result` event and persists it on the tool_use block, so the answered
7095
+ * card renders live and survives a history reopen instead of the decision
7096
+ * disappearing with the interactive prompt. Set only by `ask_question`.
7097
+ */
7098
+ answeredQuestion?: AnsweredQuestion;
6863
7099
  }
6864
7100
 
6865
7101
  export declare interface ToolResultContent {
@@ -7104,6 +7340,38 @@ declare interface WebFetchMetadata {
7104
7340
  /** Provider that backed a `web_fetch` call. `default` is the built-in fetcher. */
7105
7341
  declare type WebFetchProviderId = "default" | "firecrawl";
7106
7342
 
7343
+ /**
7344
+ * Public URL resolution for a plugin's own ingress route.
7345
+ *
7346
+ * A plugin that receives third-party webhooks has to tell the vendor where to
7347
+ * deliver. Which URL is correct depends on how the assistant is reachable:
7348
+ * a platform pod and a platform-connected assistant are served through a
7349
+ * managed callback route, while a self-hosted deployment is served through its
7350
+ * configured public ingress. `ingress.publicBaseUrl` alone does not decide it,
7351
+ * because on a platform-connected assistant that value holds the Velay tunnel
7352
+ * address, which is not where plugin routes are served.
7353
+ *
7354
+ * `resolveCallbackUrl` owns that decision for every caller in the codebase
7355
+ * (`webhooks register`, the Telegram webhook manager). This exposes it to
7356
+ * plugins so there is one implementation rather than one per plugin.
7357
+ */
7358
+ export declare interface WebhookUrlOptions {
7359
+ /**
7360
+ * Route path within the plugin's namespace, such as `"events-photon"`.
7361
+ * Relative, with no leading slash.
7362
+ */
7363
+ path: string;
7364
+ /**
7365
+ * Plugin whose namespace the route belongs to.
7366
+ *
7367
+ * Defaults to the plugin in context, which covers hooks and tools. Supply it
7368
+ * explicitly from a plugin route handler, where no context is established.
7369
+ */
7370
+ plugin?: string;
7371
+ /** Human-readable label for the platform's admin display. */
7372
+ sourceIdentifier?: string;
7373
+ }
7374
+
7107
7375
  declare interface WebSearchMetadata {
7108
7376
  query: string;
7109
7377
  provider: WebSearchProviderId;
package/index.js CHANGED
@@ -21,6 +21,7 @@ export const getAssistantName = api.getAssistantName;
21
21
  export const getConfiguredProvider = api.getConfiguredProvider;
22
22
  export const getConversation = api.getConversation;
23
23
  export const getConversationDirPath = api.getConversationDirPath;
24
+ export const getConversationProcessingStartedAt = api.getConversationProcessingStartedAt;
24
25
  export const getDocument = api.getDocument;
25
26
  export const getMessages = api.getMessages;
26
27
  export const getModelProfiles = api.getModelProfiles;
@@ -44,6 +45,7 @@ export const removeDocument = api.removeDocument;
44
45
  export const resolveCredential = api.resolveCredential;
45
46
  export const resolveMediaSourceData = api.resolveMediaSourceData;
46
47
  export const resolveUserName = api.resolveUserName;
48
+ export const resolveWebhookUrl = api.resolveWebhookUrl;
47
49
  export const runConversationTurn = api.runConversationTurn;
48
50
  export const searchMessageIdsLexical = api.searchMessageIdsLexical;
49
51
  export const selectedBackendSupportsMultimodal = api.selectedBackendSupportsMultimodal;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@vellumai/plugin-api",
3
- "version": "0.11.2-staging.3",
3
+ "version": "0.11.3-staging.1",
4
4
  "description": "Public TypeScript authoring contract for Vellum assistant plugins.",
5
5
  "license": "MIT",
6
6
  "type": "module",