@automagik/omni 2.260901.3 → 2.260902.2

package/dist/commands/send.d.ts

@@ -7,5 +7,10 @@
  * etc.
  */
 import { Command } from 'commander';
+import { z } from 'zod';
 export declare function createSendCommand(): Command;
+/** Test-only surface — not part of the CLI contract. */
+export declare const __testables: {
+    sentBySchema: z.ZodEnum<["agent", "user"]>;
+};
 //# sourceMappingURL=send.d.ts.map

package/dist/commands/send.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"send.d.ts","sourceRoot":"","sources":["../../src/commands/send.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgcpC,wBAAgB,iBAAiB,IAAI,OAAO,CAgG3C"}
+{"version":3,"file":"send.d.ts","sourceRoot":"","sources":["../../src/commands/send.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA6dxB,wBAAgB,iBAAiB,IAAI,OAAO,CAiG3C;AAED,wDAAwD;AACxD,eAAO,MAAM,WAAW;;CAAmB,CAAC"}

package/dist/commands/webhooks.d.ts

@@ -7,7 +7,44 @@
  * omni webhooks update <id> [--name <name>] [--enabled]
  * omni webhooks delete <id>
  * omni webhooks trigger --type <event-type> --payload <json> [--instance <id>]
+ *
+ * The signature secret can come from argv (`--signature-secret`, visible in
+ * shell history and `ps`), an environment variable (`--signature-secret-env`),
+ * or stdin (`--signature-secret-stdin`, for `pass show ... | omni webhooks ...`).
  */
+import type { WebhookSignatureConfigBody } from '@omni/sdk';
 import { Command } from 'commander';
+interface SignatureSecretOptions {
+    signatureSecret?: string;
+    signatureSecretEnv?: string;
+    signatureSecretStdin?: boolean;
+}
+/**
+ * Resolve the signature secret from exactly one of the three sources, or
+ * undefined when none is given. Throws (caught by the command's error path)
+ * on conflicting flags, a missing/empty env var, empty stdin, or a value
+ * outside the API's bounds — the CLI fails before any request is sent.
+ */
+declare function resolveSignatureSecret(options: SignatureSecretOptions, readStdin?: () => Promise<string>): Promise<string | undefined>;
+/** Assemble a signatureConfig from the --signature-* flags, or undefined when none given. */
+declare function buildSignatureConfig(options: {
+    signatureAlgorithm?: string;
+    signatureHeader?: string;
+    signaturePrefix?: string;
+}): WebhookSignatureConfigBody | undefined;
+/**
+ * Create-only pairing: the API rejects a `signatureConfig` without a secret
+ * and a secret without a config (CreateWebhookSourceSchema). Fail here, before
+ * the request, the same way the secret bounds do. Update is deliberately not
+ * covered — a secret-only update rotates the secret against the stored config.
+ */
+declare function assertPairedSignatureOnCreate(signatureConfig: WebhookSignatureConfigBody | undefined, signatureSecret: string | undefined): void;
 export declare function createWebhooksCommand(): Command;
+/** Test-only surface — not part of the CLI contract. */
+export declare const __testables: {
+    resolveSignatureSecret: typeof resolveSignatureSecret;
+    buildSignatureConfig: typeof buildSignatureConfig;
+    assertPairedSignatureOnCreate: typeof assertPairedSignatureOnCreate;
+};
+export {};
 //# sourceMappingURL=webhooks.d.ts.map

package/dist/commands/webhooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../../src/commands/webhooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AA4BpC,wBAAgB,qBAAqB,IAAI,OAAO,CA0O/C"}
+{"version":3,"file":"webhooks.d.ts","sourceRoot":"","sources":["../../src/commands/webhooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAC;AAC5D,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAapC,UAAU,sBAAsB;IAC9B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAcD;;;;;GAKG;AACH,iBAAe,sBAAsB,CACnC,OAAO,EAAE,sBAAsB,EAC/B,SAAS,GAAE,MAAM,OAAO,CAAC,MAAM,CAAuB,GACrD,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAqC7B;AAED,6FAA6F;AAC7F,iBAAS,oBAAoB,CAAC,OAAO,EAAE;IACrC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,GAAG,0BAA0B,GAAG,SAAS,CAczC;AAED;;;;;GAKG;AACH,iBAAS,6BAA6B,CACpC,eAAe,EAAE,0BAA0B,GAAG,SAAS,EACvD,eAAe,EAAE,MAAM,GAAG,SAAS,GAClC,IAAI,CAQN;AAED,wBAAgB,qBAAqB,IAAI,OAAO,CA2P/C;AAED,wDAAwD;AACxD,eAAO,MAAM,WAAW;;;;CAAkF,CAAC"}

package/dist/index.js

@@ -128289,7 +128289,7 @@ import { fileURLToPath } from "url";
 // package.json
 var package_default = {
   name: "@automagik/omni",
-  version: "2.260901.3",
+  version: "2.260902.2",
   description: "LLM-optimized CLI for Omni",
   type: "module",
   bin: {
@@ -140103,6 +140103,7 @@ function createSeeCommand() {
 import { existsSync as existsSync17, readFileSync as readFileSync14 } from "fs";
 import { basename as basename5, extname as extname5 } from "path";
 init_source();
+init_zod();
 init_config();
 init_output();
 init_output();
@@ -140127,6 +140128,16 @@ function parseLoadingMessages(value) {
   const messages3 = value?.split(",").map((item) => item.trim()).filter(Boolean);
   return messages3?.length ? messages3 : undefined;
 }
+var sentBySchema = exports_external.enum(["agent", "user"]);
+function resolveSentBy(value) {
+  if (value === undefined)
+    return;
+  const parsed = sentBySchema.safeParse(value);
+  if (!parsed.success) {
+    error(`Invalid --sent-by: ${value}`, { validValues: sentBySchema.options });
+  }
+  return parsed.data;
+}
 var messageSenders = {
   async text(client, instanceId, options3) {
     const { to, text: text3 } = options3;
@@ -140137,7 +140148,8 @@ var messageSenders = {
       to,
       text: text3,
       replyTo: options3.replyTo,
-      threadId: options3.threadId
+      threadId: options3.threadId,
+      sentBy: resolveSentBy(options3.sentBy)
     });
     success("Message sent", result);
   },
@@ -140160,7 +140172,8 @@ var messageSenders = {
       filename,
       caption: options3.caption,
       voiceNote: options3.voice,
-      threadId: options3.threadId
+      threadId: options3.threadId,
+      sentBy: resolveSentBy(options3.sentBy)
     });
     success("Media sent", result);
   },
@@ -140188,7 +140201,8 @@ var messageSenders = {
     const result = await client.messages.sendSticker({
       instanceId,
       to,
-      ...isBase64 ? { base64: sticker } : { url: sticker }
+      ...isBase64 ? { base64: sticker } : { url: sticker },
+      sentBy: resolveSentBy(options3.sentBy)
     });
     success("Sticker sent", result);
   },
@@ -140207,7 +140221,8 @@ var messageSenders = {
         name,
         phone: options3.phone,
         email: options3.email
-      }
+      },
+      sentBy: resolveSentBy(options3.sentBy)
     });
     success("Contact sent", result);
   },
@@ -140224,7 +140239,8 @@ var messageSenders = {
       to,
       latitude: lat,
       longitude: lng,
-      address: options3.address
+      address: options3.address,
+      sentBy: resolveSentBy(options3.sentBy)
     });
     success("Location sent", result);
   },
@@ -140243,7 +140259,8 @@ var messageSenders = {
       question: poll,
       answers,
       multiSelect: options3.multiSelect,
-      durationHours: options3.duration
+      durationHours: options3.duration,
+      sentBy: resolveSentBy(options3.sentBy)
     });
     success("Poll sent", result);
   },
@@ -140257,7 +140274,8 @@ var messageSenders = {
       title: options3.title,
       description: options3.description,
       color: options3.color,
-      url: options3.url
+      url: options3.url,
+      sentBy: resolveSentBy(options3.sentBy)
     });
     success("Embed sent", result);
   },
@@ -140289,7 +140307,8 @@ var messageSenders = {
       to,
       text: tts,
       voiceId: options3.voiceId,
-      presenceDelay: options3.presenceDelay
+      presenceDelay: options3.presenceDelay,
+      sentBy: resolveSentBy(options3.sentBy)
     });
     success("TTS voice note sent", result);
   },
@@ -140309,7 +140328,8 @@ var messageSenders = {
       instanceId,
       to,
       messageId: message2,
-      fromChatId: fromChat
+      fromChatId: fromChat,
+      sentBy: resolveSentBy(options3.sentBy)
     });
     success("Message forwarded", result);
   }
@@ -140383,6 +140403,10 @@ function buildGroupedSendHelp() {
     {
       flags: "--to <recipient>",
       description: "Recipient: WA JID (5511@s.whatsapp.net), phone (+5511...), or Omni chat/person UUID"
+    },
+    {
+      flags: "--sent-by <agent|user>",
+      description: "Authorship: 'agent' attributes the send to the instance's configured agent (not for --reaction/--presence)"
     }
   ];
   const textOptions = [
@@ -140481,7 +140505,7 @@ function createSendCommand() {
   send.configureHelp({
     formatHelp: () => buildGroupedSendHelp()
   });
-  send.description("Send a message to a recipient").argument("[file]", "File to send as media (shorthand for --media, uses context for instance/chat)").option("--instance <id>", "Instance ID (uses default if not specified)").option("--to <recipient>", "Recipient: WA JID, phone number, or Omni chat/person UUID").option("--text <text>", "Send text message").option("--reply-to <id>", "Reply to a message ID").option("--thread-id <id>", "Thread/topic ID (Telegram forum topic, etc.)").option("--media <path>", "Send media file (image, audio, video, document)").option("--caption <text>", "Caption for media").option("--voice", "Send audio as voice note").option("--reaction <emoji>", "Send reaction emoji").option("--message <id>", "Message ID to react to").option("--sticker <url>", "Send sticker (URL or base64)").option("--contact", "Send contact card").option("--name <name>", "Contact name").option("--phone <phone>", "Contact phone number").option("--email <email>", "Contact email").option("--location", "Send location").option("--lat <latitude>", "Latitude", Number.parseFloat).option("--lng <longitude>", "Longitude", Number.parseFloat).option("--address <address>", "Location address").option("--poll <question>", "Send poll with question").option("--options <answers>", "Poll options (comma-separated)").option("--multi-select", "Allow multiple selections").option("--duration <hours>", "Poll duration in hours", Number.parseInt).option("--embed", "Send embed message").option("--title <title>", "Embed title").option("--description <desc>", "Embed description").option("--color <color>", "Embed color (hex)", Number.parseInt).option("--url <url>", "Embed URL").option("--presence <type>", "Send presence indicator (typing, recording, paused)").option("--status <text>", "Custom status text for channels that support it").option("--loading-messages <items>", "Comma-separated rotating loading messages").option("--tts <text>", "Send TTS voice note (text-to-speech)").option("--voice-id <id>", "ElevenLabs voice ID for TTS").option("--presence-delay <ms>", "Recording presence duration in ms", Number.parseInt).option("--forward", "Forward a message to another chat").option("--from-chat <chatId>", "Source chat ID for forwarding").action(async (file, options3) => {
+  send.description("Send a message to a recipient").argument("[file]", "File to send as media (shorthand for --media, uses context for instance/chat)").option("--instance <id>", "Instance ID (uses default if not specified)").option("--to <recipient>", "Recipient: WA JID, phone number, or Omni chat/person UUID").option("--sent-by <agent|user>", "Authorship: 'agent' attributes the send to the instance's configured agent").option("--text <text>", "Send text message").option("--reply-to <id>", "Reply to a message ID").option("--thread-id <id>", "Thread/topic ID (Telegram forum topic, etc.)").option("--media <path>", "Send media file (image, audio, video, document)").option("--caption <text>", "Caption for media").option("--voice", "Send audio as voice note").option("--reaction <emoji>", "Send reaction emoji").option("--message <id>", "Message ID to react to").option("--sticker <url>", "Send sticker (URL or base64)").option("--contact", "Send contact card").option("--name <name>", "Contact name").option("--phone <phone>", "Contact phone number").option("--email <email>", "Contact email").option("--location", "Send location").option("--lat <latitude>", "Latitude", Number.parseFloat).option("--lng <longitude>", "Longitude", Number.parseFloat).option("--address <address>", "Location address").option("--poll <question>", "Send poll with question").option("--options <answers>", "Poll options (comma-separated)").option("--multi-select", "Allow multiple selections").option("--duration <hours>", "Poll duration in hours", Number.parseInt).option("--embed", "Send embed message").option("--title <title>", "Embed title").option("--description <desc>", "Embed description").option("--color <color>", "Embed color (hex)", Number.parseInt).option("--url <url>", "Embed URL").option("--presence <type>", "Send presence indicator (typing, recording, paused)").option("--status <text>", "Custom status text for channels that support it").option("--loading-messages <items>", "Comma-separated rotating loading messages").option("--tts <text>", "Send TTS voice note (text-to-speech)").option("--voice-id <id>", "ElevenLabs voice ID for TTS").option("--presence-delay <ms>", "Recording presence duration in ms", Number.parseInt).option("--forward", "Forward a message to another chat").option("--from-chat <chatId>", "Source chat ID for forwarding").action(async (file, options3) => {
     if (file && !options3.media) {
       options3.media = file;
       if (!options3.to) {
@@ -142578,8 +142602,59 @@ ${lines.join(`
 }
 
 // src/commands/webhooks.ts
+init_zod();
 init_output();
 var SIGNATURE_ALGORITHMS = ["hmac-sha256", "hmac-sha1", "token-match"];
+var signatureSecretSchema = exports_external.string().min(8, "at least 8 characters").max(512, "at most 512 characters");
+var SECRET_SOURCE_FLAGS = "--signature-secret, --signature-secret-env, --signature-secret-stdin";
+async function readSecretFromStdin() {
+  if (process.stdin.isTTY) {
+    throw new Error('--signature-secret-stdin requires piped stdin (e.g. `printf %s "$SECRET" | omni webhooks ...`)');
+  }
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf-8");
+}
+async function resolveSignatureSecret(options3, readStdin = readSecretFromStdin) {
+  const sources = [
+    options3.signatureSecret !== undefined,
+    options3.signatureSecretEnv !== undefined,
+    options3.signatureSecretStdin === true
+  ].filter(Boolean).length;
+  if (sources === 0)
+    return;
+  if (sources > 1) {
+    throw new Error(`Use only one of ${SECRET_SOURCE_FLAGS}`);
+  }
+  let raw2;
+  let origin;
+  if (options3.signatureSecretEnv !== undefined) {
+    const name = options3.signatureSecretEnv;
+    if (!name)
+      throw new Error("--signature-secret-env requires a variable name");
+    raw2 = process.env[name];
+    origin = `environment variable ${name}`;
+    if (raw2 === undefined || raw2 === "") {
+      throw new Error(`${origin} is not set or empty`);
+    }
+  } else if (options3.signatureSecretStdin) {
+    raw2 = (await readStdin()).replace(/\r?\n$/, "");
+    origin = "stdin";
+    if (!raw2)
+      throw new Error("no secret received on stdin");
+  } else {
+    raw2 = options3.signatureSecret;
+    origin = "--signature-secret";
+  }
+  const parsed = signatureSecretSchema.safeParse(raw2);
+  if (!parsed.success) {
+    const reason = parsed.error.issues.map((issue) => issue.message).join("; ");
+    throw new Error(`Invalid signature secret from ${origin}: ${reason}`);
+  }
+  return parsed.data;
+}
 function buildSignatureConfig(options3) {
   const { signatureAlgorithm, signatureHeader, signaturePrefix } = options3;
   if (!signatureAlgorithm && !signatureHeader && !signaturePrefix)
@@ -142596,6 +142671,14 @@ function buildSignatureConfig(options3) {
   }
   return { algorithm, header: signatureHeader, prefix: signaturePrefix };
 }
+function assertPairedSignatureOnCreate(signatureConfig, signatureSecret) {
+  if (signatureConfig === undefined === (signatureSecret === undefined))
+    return;
+  if (signatureConfig === undefined) {
+    throw new Error(`a signature secret (${SECRET_SOURCE_FLAGS}) requires --signature-algorithm and --signature-header`);
+  }
+  throw new Error(`--signature-algorithm and --signature-header require a signature secret (${SECRET_SOURCE_FLAGS})`);
+}
 function createWebhooksCommand() {
   const webhooks = new Command("webhooks").description("Manage webhook sources");
   webhooks.command("list").description("List webhook sources").option("--enabled", "Show only enabled sources").option("--disabled", "Show only disabled sources").action(async (options3) => {
@@ -142632,7 +142715,7 @@ function createWebhooksCommand() {
       error(`Failed to get webhook source: ${message2}`);
     }
   });
-  webhooks.command("create").description("Create a webhook source").requiredOption("--name <name>", "Webhook source name").option("--description <desc>", "Description").option("--disabled", "Create in disabled state").option("--headers <json>", `Expected headers as JSON (e.g., '{"X-Secret": true}')`).option("--signature-algorithm <alg>", "Signature verification: hmac-sha256, hmac-sha1, or token-match").option("--signature-header <name>", "Header carrying the signature/token (e.g., X-Hub-Signature-256)").option("--signature-prefix <prefix>", "Prefix before the hex digest (e.g., 'sha256=')").option("--signature-secret <secret>", "Shared secret for signature verification (write-only)").action(async (options3) => {
+  webhooks.command("create").description("Create a webhook source").requiredOption("--name <name>", "Webhook source name").option("--description <desc>", "Description").option("--disabled", "Create in disabled state").option("--headers <json>", `Expected headers as JSON (e.g., '{"X-Secret": true}')`).option("--signature-algorithm <alg>", "Signature verification: hmac-sha256, hmac-sha1, or token-match").option("--signature-header <name>", "Header carrying the signature/token (e.g., X-Hub-Signature-256)").option("--signature-prefix <prefix>", "Prefix before the hex digest (e.g., 'sha256=')").option("--signature-secret <secret>", "Shared secret for signature verification (write-only). Visible in shell history and process lists \u2014 prefer --signature-secret-env or --signature-secret-stdin").option("--signature-secret-env <VAR>", "Read the shared secret from environment variable VAR").option("--signature-secret-stdin", "Read the shared secret from stdin (trailing newline stripped)").action(async (options3) => {
     const client = getClient();
     try {
       let expectedHeaders;
@@ -142644,13 +142727,15 @@ function createWebhooksCommand() {
         }
       }
       const signatureConfig = buildSignatureConfig(options3);
+      const signatureSecret = await resolveSignatureSecret(options3);
+      assertPairedSignatureOnCreate(signatureConfig, signatureSecret);
       const source = await client.webhooks.createSource({
         name: options3.name,
         description: options3.description,
         enabled: !options3.disabled,
         expectedHeaders,
         signatureConfig,
-        signatureSecret: options3.signatureSecret
+        signatureSecret
       });
       const details = {
         id: source.id,
@@ -142666,7 +142751,7 @@ function createWebhooksCommand() {
       error(`Failed to create webhook source: ${message2}`);
     }
   });
-  webhooks.command("update <id>").description("Update a webhook source").option("--name <name>", "New name").option("--description <desc>", "New description").option("--enable", "Enable the webhook").option("--disable", "Disable the webhook").option("--signature-algorithm <alg>", "Signature verification: hmac-sha256, hmac-sha1, or token-match").option("--signature-header <name>", "Header carrying the signature/token (e.g., X-Hub-Signature-256)").option("--signature-prefix <prefix>", "Prefix before the hex digest (e.g., 'sha256=')").option("--signature-secret <secret>", "Shared secret for signature verification (write-only)").option("--clear-signature", "Remove the signature config and stored secret").action(async (id, options3) => {
+  webhooks.command("update <id>").description("Update a webhook source").option("--name <name>", "New name").option("--description <desc>", "New description").option("--enable", "Enable the webhook").option("--disable", "Disable the webhook").option("--signature-algorithm <alg>", "Signature verification: hmac-sha256, hmac-sha1, or token-match").option("--signature-header <name>", "Header carrying the signature/token (e.g., X-Hub-Signature-256)").option("--signature-prefix <prefix>", "Prefix before the hex digest (e.g., 'sha256=')").option("--signature-secret <secret>", "Shared secret for signature verification (write-only). Visible in shell history and process lists \u2014 prefer --signature-secret-env or --signature-secret-stdin").option("--signature-secret-env <VAR>", "Read the shared secret from environment variable VAR").option("--signature-secret-stdin", "Read the shared secret from stdin (trailing newline stripped)").option("--clear-signature", "Remove the signature config and stored secret").action(async (id, options3) => {
     const resolvedId = await resolveWebhookId(id);
     const client = getClient();
     try {
@@ -142685,8 +142770,9 @@ function createWebhooksCommand() {
         const signatureConfig = buildSignatureConfig(options3);
         if (signatureConfig)
           updates.signatureConfig = signatureConfig;
-        if (options3.signatureSecret)
-          updates.signatureSecret = options3.signatureSecret;
+        const signatureSecret = await resolveSignatureSecret(options3);
+        if (signatureSecret)
+          updates.signatureSecret = signatureSecret;
       }
       const source = await client.webhooks.updateSource(resolvedId, updates);
       success(`Webhook source updated: ${source.id}`, {

package/dist/sdk/client.d.ts

@@ -261,6 +261,12 @@ export interface CreateInstanceBody {
     twilioWebhookUrl?: string;
     twilioValidateSignature?: boolean;
 }
+/**
+ * Authorship marker accepted by the send routes (#912). 'agent' attributes the
+ * message to the instance's configured agent server-side — the agent id is
+ * never taken from the caller.
+ */
+export type SentBy = 'agent' | 'user';
 /**
  * Body for sending a message
  */
@@ -270,6 +276,12 @@ export interface SendMessageBody {
     text: string;
     replyTo?: string;
     threadId?: string;
+    /**
+     * Authorship of this send. 'agent' attributes the message to the instance's
+     * configured agent (the response echoes the resolved `senderAgentId`, null
+     * when the instance has no configured agent). Default: unattributed.
+     */
+    sentBy?: SentBy;
 }
 /**
  * Query parameters for listing events
@@ -622,26 +634,33 @@ export interface ListWebhookSourcesParams {
     enabled?: boolean;
 }
 /**
- * Signature verification contract for a webhook source (issue #928)
+ * Signature verification contract for a webhook source (issue #928).
+ * Derived from the generated OpenAPI component so it cannot drift from the API.
  */
-export interface WebhookSignatureConfigBody {
-    algorithm: 'hmac-sha256' | 'hmac-sha1' | 'token-match';
-    /** Header carrying the signature/token (e.g. 'X-Hub-Signature-256') */
-    header: string;
-    /** Prefix before the hex digest (e.g. 'sha256=') */
-    prefix?: string;
-}
+export type WebhookSignatureConfigBody = components['schemas']['WebhookSignatureConfig'];
 /**
- * Body for creating a webhook source
+ * Body for creating a webhook source.
+ *
+ * Hand-written on purpose: the generated `CreateWebhookSourceRequest` marks
+ * `enabled` as required because the API schema gives it a default, while for
+ * a caller it is optional. Field set and semantics mirror that component.
  */
 export interface CreateWebhookSourceBody {
     name: string;
     description?: string;
     expectedHeaders?: Record<string, boolean>;
-    /** Required for the source to be reachable on the public ingress route */
+    /**
+     * Required for the source to be reachable on the public ingress route.
+     * Always paired with `signatureSecret`: a config without a stored secret is
+     * rejected, and clearing the config (null) also clears the stored secret.
+     */
     signatureConfig?: WebhookSignatureConfigBody | null;
-    /** Shared secret used by signatureConfig (write-only, never returned) */
+    /**
+     * Shared secret used by signatureConfig (write-only, never returned; 8-512
+     * chars). Cannot be set without a signatureConfig; null clears it.
+     */
     signatureSecret?: string | null;
+    /** Defaults to true server-side */
     enabled?: boolean;
 }
 /**
@@ -696,9 +715,15 @@ export interface SendMediaBody {
     caption?: string;
     voiceNote?: boolean;
     threadId?: string;
+    /**
+     * Authorship of this send. 'agent' attributes the message to the instance's
+     * configured agent (the response echoes the resolved `senderAgentId`, null
+     * when the instance has no configured agent). Default: unattributed.
+     */
+    sentBy?: SentBy;
 }
 /**
- * Body for sending a reaction
+ * Body for sending a reaction (no `sentBy`: reactions are not attributable sends)
  */
 export interface SendReactionBody {
     instanceId: string;
@@ -721,6 +746,12 @@ export interface SendForwardBody {
     to: string;
     messageId: string;
     fromChatId: string;
+    /**
+     * Authorship of this send. 'agent' attributes the message to the instance's
+     * configured agent (the response echoes the resolved `senderAgentId`, null
+     * when the instance has no configured agent). Default: unattributed.
+     */
+    sentBy?: SentBy;
 }
 /**
  * Body for sending a sticker
@@ -730,6 +761,12 @@ export interface SendStickerBody {
     to: string;
     url?: string;
     base64?: string;
+    /**
+     * Authorship of this send. 'agent' attributes the message to the instance's
+     * configured agent (the response echoes the resolved `senderAgentId`, null
+     * when the instance has no configured agent). Default: unattributed.
+     */
+    sentBy?: SentBy;
 }
 /**
  * Body for sending a contact
@@ -743,6 +780,12 @@ export interface SendContactBody {
         email?: string;
         organization?: string;
     };
+    /**
+     * Authorship of this send. 'agent' attributes the message to the instance's
+     * configured agent (the response echoes the resolved `senderAgentId`, null
+     * when the instance has no configured agent). Default: unattributed.
+     */
+    sentBy?: SentBy;
 }
 /**
  * Body for sending a TTS voice note
@@ -756,6 +799,12 @@ export interface SendTtsBody {
     stability?: number;
     similarityBoost?: number;
     presenceDelay?: number;
+    /**
+     * Authorship of this send. 'agent' attributes the message to the instance's
+     * configured agent (the response echoes the resolved `senderAgentId`, null
+     * when the instance has no configured agent). Default: unattributed.
+     */
+    sentBy?: SentBy;
 }
 /**
  * TTS voice configuration
@@ -775,6 +824,8 @@ export interface TtsResponse {
     audioSizeKb: number;
     durationMs: number;
     timestamp: number;
+    /** Present when the request set `sentBy: 'agent'`; null when the instance has no configured agent */
+    senderAgentId?: string | null;
 }
 /**
  * Body for sending a location
@@ -786,6 +837,12 @@ export interface SendLocationBody {
     longitude: number;
     name?: string;
     address?: string;
+    /**
+     * Authorship of this send. 'agent' attributes the message to the instance's
+     * configured agent (the response echoes the resolved `senderAgentId`, null
+     * when the instance has no configured agent). Default: unattributed.
+     */
+    sentBy?: SentBy;
 }
 /**
  * Body for sending a poll (Discord)
@@ -798,6 +855,12 @@ export interface SendPollBody {
     durationHours?: number;
     multiSelect?: boolean;
     replyTo?: string;
+    /**
+     * Authorship of this send. 'agent' attributes the message to the instance's
+     * configured agent (the response echoes the resolved `senderAgentId`, null
+     * when the instance has no configured agent). Default: unattributed.
+     */
+    sentBy?: SentBy;
 }
 /**
  * Body for sending an embed (Discord)
@@ -827,6 +890,12 @@ export interface SendEmbedBody {
         inline?: boolean;
     }>;
     replyTo?: string;
+    /**
+     * Authorship of this send. 'agent' attributes the message to the instance's
+     * configured agent (the response echoes the resolved `senderAgentId`, null
+     * when the instance has no configured agent). Default: unattributed.
+     */
+    sentBy?: SentBy;
 }
 /**
  * Body for connecting an instance