teams-api 1.4.0 → 1.6.0

package/README.md

@@ -192,15 +192,15 @@ Manual token usage, debug-session auth, and programmatic Node.js usage are cover
 
 ## Platform support
 
-| Feature                | macOS          | Windows / Linux |
-| ---------------------- | -------------- | --------------- |
-| **Interactive login**  | Full support   | Full support    |
-| **Auto-login (FIDO2)** | Full support   | Not supported   |
-| **Debug session**      | Full support   | Full support    |
-| **Direct token**       | Full support   | Full support    |
+| Feature                | macOS          | Windows / Linux                   |
+| ---------------------- | -------------- | --------------------------------- |
+| **Interactive login**  | Full support   | Full support                      |
+| **Auto-login (FIDO2)** | Full support   | Not supported                     |
+| **Debug session**      | Full support   | Full support                      |
+| **Direct token**       | Full support   | Full support                      |
 | **Token caching**      | macOS Keychain | Windows DPAPI / Linux secret-tool |
-| **CLI & MCP server**   | Full support   | Full support    |
-| **Programmatic API**   | Full support   | Full support    |
+| **CLI & MCP server**   | Full support   | Full support                      |
+| **Programmatic API**   | Full support   | Full support                      |
 
 > [!NOTE]
 > **Windows Defender false positive:** Older versions of this package used inline PowerShell to call the Windows DPAPI — a pattern that Windows Defender flags as ransomware-like behavior. This has been replaced with native Windows Credential Manager storage via [keytar](https://github.com/atom/node-keytar). If you hit issues on an older version, upgrade and re-run `teams-api auth --login`. See [SECURITY.md](./SECURITY.md) for details.
@@ -305,8 +305,8 @@ The examples below use `teams-api` for readability. If you are not installing gl
 | `--substrate-token <token>` | Optional Substrate bearer token (advanced/manual)                                |
 | `--debug-port <port>`       | Chrome debug port (default: 9222)                                                |
 | `--region <region>`         | API region override. Auto-detected for login/debug auth; required with `--token` |
-| `--format <format>`         | Output format: concise, detailed                                             |
-| `--output <file>`           | Export output to file (default format: concise)                              |
+| `--format <format>`         | Output format: concise, detailed                                                 |
+| `--output <file>`           | Export output to file (default format: concise)                                  |
 
 ### Examples
 
@@ -381,16 +381,120 @@ Use this only if you already have tokens from another flow or need to avoid brow
 
 ### Environment variables
 
-| Variable                | Description                                                           |
-| ----------------------- | --------------------------------------------------------------------- |
-| `TEAMS_TOKEN`           | Pre-existing skype token                                              |
-| `TEAMS_BEARER_TOKEN`    | Optional middle-tier bearer token                                     |
-| `TEAMS_SUBSTRATE_TOKEN` | Optional Substrate bearer token                                       |
-| `TEAMS_REGION`          | API region override. Required with `TEAMS_TOKEN`; optional otherwise  |
-| `TEAMS_EMAIL`           | Corporate email. Optional — the server prompts the AI agent if needed |
-| `TEAMS_AUTO`            | Set to `true` to enable auto-login (macOS + FIDO2)                    |
-| `TEAMS_LOGIN`           | Set to `true` to enable interactive browser login                     |
-| `TEAMS_DEBUG_PORT`      | Chrome debug port (default: 9222)                                     |
+| Variable                        | Description                                                                            |
+| ------------------------------- | -------------------------------------------------------------------------------------- |
+| `TEAMS_TOKEN`                   | Pre-existing skype token                                                               |
+| `TEAMS_BEARER_TOKEN`            | Optional middle-tier bearer token                                                      |
+| `TEAMS_SUBSTRATE_TOKEN`         | Optional Substrate bearer token                                                        |
+| `TEAMS_REGION`                  | API region override. Required with `TEAMS_TOKEN`; optional otherwise                   |
+| `TEAMS_EMAIL`                   | Corporate email. Optional — the server prompts the AI agent if needed                  |
+| `TEAMS_AUTO`                    | Set to `true` to enable auto-login (macOS + FIDO2)                                     |
+| `TEAMS_LOGIN`                   | Set to `true` to enable interactive browser login                                      |
+| `TEAMS_DEBUG_PORT`              | Chrome debug port (default: 9222)                                                      |
+| `TEAMS_EDIT_REPLY_GUARD`        | Edit reply guard: `allow` (default), `warn`, or `block`. See below                     |
+| `TEAMS_AGENT_MARKER`            | Agent marker prefix for sent/edited messages (e.g. `Ⓜ`). See below                    |
+| `TEAMS_DELETE_MODE`             | Delete mode: `hard` (default), `soft`, or `block`. See below                           |
+| `TEAMS_DELETE_TOMBSTONE`        | Custom tombstone text for soft-delete mode. See below                                  |
+| `TEAMS_AUDIT_LOG`               | Audit logging: `off` (default), `stderr`, or `file:<path>`. See below                  |
+| `TEAMS_PROTECTED_CONVERSATIONS` | Comma-separated glob patterns of conversations where edit/delete is blocked. See below |
+
+#### Agent marker
+
+When an AI agent sends or edits messages on behalf of a user, it can be hard to tell which messages were composed by the agent and which by the human. The `TEAMS_AGENT_MARKER` environment variable (or `--agent-marker` CLI flag / `agentMarker` MCP parameter) automatically prepends a configurable string to message content:
+
+```jsonc
+{
+  "env": {
+    "TEAMS_AGENT_MARKER": "Ⓜ", // or "🤖", "[Bot]", etc.
+  },
+}
+```
+
+When set, every `send-message` and `edit-message` call prepends the marker followed by a space to the content. For example, with `TEAMS_AGENT_MARKER=Ⓜ`, sending "Hello world" produces "Ⓜ Hello world".
+
+The per-call parameter takes precedence over the environment variable. Pass an empty string to disable the marker for a specific call.
+
+#### Edit reply guard
+
+When editing a message that already has replies, the original context can be lost — replies may no longer make sense. The `TEAMS_EDIT_REPLY_GUARD` environment variable (or `--reply-guard` CLI flag / `replyGuard` MCP parameter) controls this:
+
+| Value   | Behavior                                                                           |
+| ------- | ---------------------------------------------------------------------------------- |
+| `allow` | Edit proceeds normally (default, backward-compatible)                              |
+| `warn`  | Edit proceeds but an annotation is appended: _"⚠️ This message was edited after…"_ |
+| `block` | Edit is refused with an error listing the reply count                              |
+
+The per-call parameter takes precedence over the environment variable.
+
+#### Delete mode (soft-delete)
+
+Hard-deleting messages removes content permanently, which can be problematic for auditability and conversation flow in group chats. The `TEAMS_DELETE_MODE` environment variable (or `--delete-mode` CLI flag / `deleteMode` MCP parameter) controls how message deletion is handled:
+
+| Value   | Behavior                                                            |
+| ------- | ------------------------------------------------------------------- |
+| `hard`  | Permanently delete the message (default, current behavior)          |
+| `soft`  | Replace message content with a tombstone marker instead of deleting |
+| `block` | Refuse deletion entirely with an error                              |
+
+When using `soft` mode, the message content is replaced with `~~This message was removed by an agent~~` by default. Customize the tombstone text with `TEAMS_DELETE_TOMBSTONE` (or `--delete-tombstone` / `deleteTombstone`):
+
+```jsonc
+{
+  "env": {
+    "TEAMS_DELETE_MODE": "soft",
+    "TEAMS_DELETE_TOMBSTONE": "🗑️ [removed by automation]",
+  },
+}
+```
+
+The per-call parameters take precedence over environment variables.
+
+#### Audit logging
+
+State-modifying actions (edit and delete) can emit structured audit events for compliance and traceability. The `TEAMS_AUDIT_LOG` environment variable controls where events are written:
+
+| Value         | Behavior                                                    |
+| ------------- | ----------------------------------------------------------- |
+| `off`         | No audit logging (default)                                  |
+| `stderr`      | Write JSON Lines to stderr                                  |
+| `file:<path>` | Append JSON Lines to the specified file (created on demand) |
+
+```jsonc
+{
+  "env": {
+    "TEAMS_AUDIT_LOG": "file:/var/log/teams-audit.jsonl",
+  },
+}
+```
+
+Each event is a single JSON line with the following fields:
+
+| Field               | Description                                                                   |
+| ------------------- | ----------------------------------------------------------------------------- |
+| `timestamp`         | ISO 8601 timestamp                                                            |
+| `action`            | `"edit"`, `"delete"`, or `"soft-delete"`                                      |
+| `conversationId`    | Conversation thread ID                                                        |
+| `conversationLabel` | Human-readable conversation label (topic or 1:1 partner name)                 |
+| `messageId`         | Target message ID                                                             |
+| `content`           | New content for edits, tombstone text for soft-delete, `null` for hard delete |
+
+Audit logging is designed to be silent — errors in the audit pipeline never affect tool execution.
+
+#### Protected conversations
+
+Some conversations contain sensitive or compliance-relevant information where accidental edits or deletions could be harmful. The `TEAMS_PROTECTED_CONVERSATIONS` environment variable (or `--protected-conversations` CLI flag / `protectedConversations` MCP parameter) blocks edit and delete actions in matching conversations:
+
+```jsonc
+{
+  "env": {
+    "TEAMS_PROTECTED_CONVERSATIONS": "Incident *,*compliance*,Architecture Decisions",
+  },
+}
+```
+
+Patterns are comma-separated and support `*` as a wildcard (matches any characters). Matching is case-insensitive. When a conversation's name matches any pattern, both `edit-message` and `delete-message` throw an error before making any changes — the message is left untouched.
+
+The per-call parameter takes precedence over the environment variable, so individual tool invocations can override the configured patterns when needed.
 
 ### Available tools
 
@@ -407,10 +511,23 @@ All MCP tools accept an optional `format` parameter (`concise` or `detailed`). D
 | `teams_send_message`       | Send a message to a conversation                      |
 | `teams_get_members`        | List members of a conversation                        |
 | `teams_get_transcript`     | Get a meeting transcript from a recorded conversation |
+| `teams_download_file`      | Download message files and inline images              |
+| `teams_describe_image`     | Describe an inline Teams image with a vision model    |
 | `teams_whoami`             | Get the authenticated user's display name             |
 
 Workflow guidance, tips, and important notes are served automatically via the MCP server's `instructions` field — no separate skill file needed. For the same content on the CLI, run `teams-api guide`.
 
+### Image descriptions
+
+`teams_describe_image` reuses the existing Teams AMS image download support and sends the image bytes to an OpenAI-compatible vision endpoint. Configure it with `TEAMS_IMAGE_DESCRIPTION_API_KEY` or `OPENAI_API_KEY`. Optional overrides: `TEAMS_IMAGE_DESCRIPTION_MODEL` and `TEAMS_IMAGE_DESCRIPTION_BASE_URL`.
+
+Examples:
+
+```bash
+teams-api describe-image --chat "Project Chat" --message-id 1773736076914 --image-index 0
+teams-api describe-image --ams-object-id 0-eaua-d2-877b82634f4e978692f2243d445a6650
+```
+
 ## API regions
 
 The Teams Chat Service URL varies by region. Login-based and debug-session auth detect it automatically. You only need to set `--region` or `TEAMS_REGION` when you are supplying tokens directly or want to force an override:
@@ -423,6 +540,7 @@ The Teams Chat Service URL varies by region. Login-based and debug-session auth
 
 ## Known limitations
 
+- **File attachments are not supported from remote AI hosts** (e.g. Claude.ai). The MCP server runs locally on your machine, so `--file` / `--image` paths must exist on your local filesystem. Cloud-hosted AI clients run in isolated containers and cannot access local paths. Use a local MCP client (Claude Desktop, Cursor, VS Code) or the CLI for file attachments.
 - Token lifetime is ~24 hours. After expiry, you must re-acquire.
 - The Teams Chat Service REST API is undocumented and may change without notice.
 - Auto-login requires macOS, system Chrome, a platform authenticator, and a FIDO2 passkey. On other platforms, use interactive login (`--login`) instead.

package/dist/actions/conversation-actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"conversation-actions.d.ts","sourceRoot":"","sources":["../../src/actions/conversation-actions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD,eAAO,MAAM,iBAAiB,EAAE,gBAoC/B,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,gBAkC9B,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,gBAgC1B,CAAC"}
+{"version":3,"file":"conversation-actions.d.ts","sourceRoot":"","sources":["../../src/actions/conversation-actions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAExD,eAAO,MAAM,iBAAiB,EAAE,gBAmC/B,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,gBAoC9B,CAAC;AAEF,eAAO,MAAM,YAAY,EAAE,gBAgC1B,CAAC"}

package/dist/actions/conversation-actions.js.map

@@ -1 +1 @@
-{"version":3,"file":"conversation-actions.js","sourceRoot":"","sources":["../../src/actions/conversation-actions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"conversation-actions.js","sourceRoot":"","sources":["../../src/actions/conversation-actions.ts"],"names":[],"mappings":"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"}

package/dist/actions/definitions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/actions/definitions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AA2CxD,6DAA6D;AAC7D,eAAO,MAAM,OAAO,EAAE,gBAAgB,EAAwC,CAAC"}
+{"version":3,"file":"definitions.d.ts","sourceRoot":"","sources":["../../src/actions/definitions.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AA6CxD,6DAA6D;AAC7D,eAAO,MAAM,OAAO,EAAE,gBAAgB,EAAwC,CAAC"}

package/dist/actions/definitions.js

@@ -13,6 +13,7 @@ const message_actions_js_1 = require("./message-actions.js");
 const search_actions_js_1 = require("./search-actions.js");
 const utility_actions_js_1 = require("./utility-actions.js");
 const file_actions_js_1 = require("./file-actions.js");
+const image_description_actions_js_1 = require("./image-description-actions.js");
 // ── Registry ─────────────────────────────────────────────────────────
 /**
  * Map-based action registry keyed by action name.
@@ -35,6 +36,7 @@ const actionRegistry = new Map([
     ["whoami", utility_actions_js_1.whoami],
     ["get-transcript", utility_actions_js_1.getTranscript],
     ["download-file", file_actions_js_1.downloadFileAction],
+    ["describe-image", image_description_actions_js_1.describeImageAction],
 ]);
 /** All registered actions, derived from the registry map. */
 exports.actions = Array.from(actionRegistry.values());

package/dist/actions/definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/actions/definitions.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAGH,uEAImC;AACnC,6DAO8B;AAC9B,2DAAwE;AACxE,6DAAyE;AACzE,uDAAuD;AAEvD,wEAAwE;AAExE;;;;GAIG;AACH,MAAM,cAAc,GAAG,IAAI,GAAG,CAA2B;IACvD,CAAC,oBAAoB,EAAE,2CAAiB,CAAC;IACzC,CAAC,mBAAmB,EAAE,0CAAgB,CAAC;IACvC,CAAC,iBAAiB,EAAE,sCAAY,CAAC;IACjC,CAAC,aAAa,EAAE,oCAAgB,CAAC;IACjC,CAAC,YAAY,EAAE,mCAAe,CAAC;IAC/B,CAAC,cAAc,EAAE,gCAAW,CAAC;IAC7B,CAAC,cAAc,EAAE,gCAAW,CAAC;IAC7B,CAAC,cAAc,EAAE,sCAAiB,CAAC;IACnC,CAAC,gBAAgB,EAAE,wCAAmB,CAAC;IACvC,CAAC,cAAc,EAAE,sCAAiB,CAAC;IACnC,CAAC,iBAAiB,EAAE,yCAAoB,CAAC;IACzC,CAAC,aAAa,EAAE,+BAAU,CAAC;IAC3B,CAAC,QAAQ,EAAE,2BAAM,CAAC;IAClB,CAAC,gBAAgB,EAAE,kCAAa,CAAC;IACjC,CAAC,eAAe,EAAE,oCAAkB,CAAC;CACtC,CAAC,CAAC;AAEH,6DAA6D;AAChD,QAAA,OAAO,GAAuB,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,CAAC,CAAC"}
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/actions/definitions.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAGH,uEAImC;AACnC,6DAO8B;AAC9B,2DAAwE;AACxE,6DAAyE;AACzE,uDAAuD;AACvD,iFAAqE;AAErE,wEAAwE;AAExE;;;;GAIG;AACH,MAAM,cAAc,GAAG,IAAI,GAAG,CAA2B;IACvD,CAAC,oBAAoB,EAAE,2CAAiB,CAAC;IACzC,CAAC,mBAAmB,EAAE,0CAAgB,CAAC;IACvC,CAAC,iBAAiB,EAAE,sCAAY,CAAC;IACjC,CAAC,aAAa,EAAE,oCAAgB,CAAC;IACjC,CAAC,YAAY,EAAE,mCAAe,CAAC;IAC/B,CAAC,cAAc,EAAE,gCAAW,CAAC;IAC7B,CAAC,cAAc,EAAE,gCAAW,CAAC;IAC7B,CAAC,cAAc,EAAE,sCAAiB,CAAC;IACnC,CAAC,gBAAgB,EAAE,wCAAmB,CAAC;IACvC,CAAC,cAAc,EAAE,sCAAiB,CAAC;IACnC,CAAC,iBAAiB,EAAE,yCAAoB,CAAC;IACzC,CAAC,aAAa,EAAE,+BAAU,CAAC;IAC3B,CAAC,QAAQ,EAAE,2BAAM,CAAC;IAClB,CAAC,gBAAgB,EAAE,kCAAa,CAAC;IACjC,CAAC,eAAe,EAAE,oCAAkB,CAAC;IACrC,CAAC,gBAAgB,EAAE,kDAAmB,CAAC;CACxC,CAAC,CAAC;AAEH,6DAA6D;AAChD,QAAA,OAAO,GAAuB,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,CAAC,CAAC"}

package/dist/actions/file-actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-actions.d.ts","sourceRoot":"","sources":["../../src/actions/file-actions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAMxD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,kBAAkB,EAAE,gBA2GhC,CAAC"}
+{"version":3,"file":"file-actions.d.ts","sourceRoot":"","sources":["../../src/actions/file-actions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAMxD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,eAAO,MAAM,kBAAkB,EAAE,gBA6GhC,CAAC"}

package/dist/actions/file-actions.js

@@ -21,7 +21,9 @@ exports.downloadFileAction = {
         "Specify the message containing the file(s) via --message-id. " +
         "Use --output-directory to save files to a specific directory. " +
         "Without --output-directory, files are saved to a temporary directory. " +
-        "File contents are returned inline in the response.",
+        "Text file contents and images are returned inline in the response. " +
+        "Other binary files (PDFs, videos, archives, etc.) are saved to disk only; " +
+        "the response reports the local save path.",
     parameters: [
         ...conversation_resolution_js_1.conversationParameters,
         {

package/dist/actions/file-actions.js.map

@@ -1 +1 @@
-{"version":3,"file":"file-actions.js","sourceRoot":"","sources":["../../src/actions/file-actions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"file-actions.js","sourceRoot":"","sources":["../../src/actions/file-actions.ts"],"names":[],"mappings":"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"}

package/dist/actions/image-description-actions.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Image description action definitions.
+ *
+ * Actions: describe-image.
+ */
+import { type ActionDefinition } from "./formatters.js";
+export declare const ImageDescriptionSourceType: {
+    readonly AmsObject: "ams-object";
+    readonly Message: "message";
+};
+export type ImageDescriptionSourceType = (typeof ImageDescriptionSourceType)[keyof typeof ImageDescriptionSourceType];
+export interface DescribeImageResult {
+    description: string;
+    provider: string;
+    model: string;
+    image: {
+        sourceType: ImageDescriptionSourceType;
+        amsObjectId: string;
+        contentType: string;
+        size: number;
+        messageId?: string;
+        imageIndex?: number;
+        width?: number | null;
+        height?: number | null;
+    };
+}
+export declare const describeImageAction: ActionDefinition;
+//# sourceMappingURL=image-description-actions.d.ts.map

package/dist/actions/image-description-actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-description-actions.d.ts","sourceRoot":"","sources":["../../src/actions/image-description-actions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,EAAE,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAMxD,eAAO,MAAM,0BAA0B;;;CAG7B,CAAC;AAEX,MAAM,MAAM,0BAA0B,GACpC,CAAC,OAAO,0BAA0B,CAAC,CAAC,MAAM,OAAO,0BAA0B,CAAC,CAAC;AAE/E,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE;QACL,UAAU,EAAE,0BAA0B,CAAC;QACvC,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KACxB,CAAC;CACH;AA6ED,eAAO,MAAM,mBAAmB,EAAE,gBAsGjC,CAAC"}

package/dist/actions/image-description-actions.js

@@ -0,0 +1,148 @@
+"use strict";
+/**
+ * Image description action definitions.
+ *
+ * Actions: describe-image.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.describeImageAction = exports.ImageDescriptionSourceType = void 0;
+const image_description_js_1 = require("../api/image-description.js");
+const conversation_resolution_js_1 = require("./conversation-resolution.js");
+exports.ImageDescriptionSourceType = {
+    AmsObject: "ams-object",
+    Message: "message",
+};
+function resolveImageIndex(value) {
+    const imageIndex = value ?? 0;
+    if (!Number.isInteger(imageIndex) || imageIndex < 0) {
+        throw new Error("imageIndex must be a non-negative integer.");
+    }
+    return imageIndex;
+}
+function resolveMessageImage(images, imageIndex) {
+    const image = images[imageIndex];
+    if (!image) {
+        throw new Error(`Message image index ${imageIndex} is out of range; the message has ${images.length} image(s).`);
+    }
+    return image;
+}
+async function resolveImageTarget(client, parameters) {
+    const amsObjectId = parameters.amsObjectId;
+    if (amsObjectId) {
+        return {
+            sourceType: exports.ImageDescriptionSourceType.AmsObject,
+            amsObjectId,
+        };
+    }
+    const messageId = parameters.messageId;
+    if (!messageId) {
+        throw new Error("Provide either amsObjectId, or messageId plus chat/to/conversationId.");
+    }
+    const { conversationId } = await (0, conversation_resolution_js_1.resolveConversationId)(client, parameters);
+    const messages = await client.getMessages(conversationId);
+    const message = messages.find((candidate) => candidate.id === messageId);
+    if (!message) {
+        throw new Error(`Message ${messageId} not found in conversation ${conversationId}`);
+    }
+    if (message.images.length === 0) {
+        throw new Error(`Message ${messageId} has no inline images.`);
+    }
+    const imageIndex = resolveImageIndex(parameters.imageIndex);
+    const image = resolveMessageImage(message.images, imageIndex);
+    return {
+        sourceType: exports.ImageDescriptionSourceType.Message,
+        amsObjectId: image.amsObjectId,
+        messageId,
+        imageIndex,
+        width: image.width,
+        height: image.height,
+    };
+}
+exports.describeImageAction = {
+    name: "describe-image",
+    title: "Describe Image",
+    description: "Describe an inline Teams image using a configured OpenAI-compatible vision model. " +
+        "Use amsObjectId directly, or identify a message by chat/to/conversationId plus messageId. " +
+        "Set TEAMS_IMAGE_DESCRIPTION_API_KEY or OPENAI_API_KEY before using this tool.",
+    parameters: [
+        ...conversation_resolution_js_1.conversationParameters,
+        {
+            name: "messageId",
+            type: "string",
+            description: "ID of the message containing the image. Required unless amsObjectId is provided.",
+            required: false,
+        },
+        {
+            name: "imageIndex",
+            type: "number",
+            description: "Zero-based index of the inline image within the message (default: 0).",
+            required: false,
+            default: 0,
+        },
+        {
+            name: "amsObjectId",
+            type: "string",
+            description: "Direct AMS object ID for an inline Teams image. When provided, conversation and message lookup are skipped.",
+            required: false,
+        },
+        {
+            name: "fullSize",
+            type: "boolean",
+            description: "Download the full-size AMS image before describing it (default: true).",
+            required: false,
+            default: true,
+        },
+        {
+            name: "prompt",
+            type: "string",
+            description: "Optional custom instruction for the vision model. Defaults to a concise Teams-context description prompt.",
+            required: false,
+        },
+    ],
+    execute: async (client, parameters) => {
+        const imageTarget = await resolveImageTarget(client, parameters);
+        const fullSize = parameters.fullSize ?? true;
+        const imageData = await client.downloadImage(imageTarget.amsObjectId, fullSize);
+        const descriptionResult = await (0, image_description_js_1.describeImageWithOpenAiCompatibleVision)({
+            imageData: imageData.data,
+            contentType: imageData.contentType,
+            prompt: parameters.prompt,
+        });
+        return {
+            description: descriptionResult.description,
+            provider: descriptionResult.provider,
+            model: descriptionResult.model,
+            image: {
+                ...imageTarget,
+                contentType: imageData.contentType,
+                size: imageData.size,
+            },
+        };
+    },
+    formatConcise: (result) => {
+        const descriptionResult = result;
+        const lines = [
+            "## Image description",
+            "",
+            descriptionResult.description,
+            "",
+            `- Provider: ${descriptionResult.provider}`,
+            `- Model: ${descriptionResult.model}`,
+            `- AMS object ID: ${descriptionResult.image.amsObjectId}`,
+            `- Content type: ${descriptionResult.image.contentType}`,
+            `- Size: ${descriptionResult.image.size} bytes`,
+        ];
+        if (descriptionResult.image.messageId) {
+            lines.push(`- Message ID: ${descriptionResult.image.messageId}`);
+        }
+        if (descriptionResult.image.imageIndex !== undefined) {
+            lines.push(`- Image index: ${descriptionResult.image.imageIndex}`);
+        }
+        if (descriptionResult.image.width !== undefined &&
+            descriptionResult.image.height !== undefined) {
+            lines.push(`- Dimensions: ${descriptionResult.image.width ?? "unknown"} x ${descriptionResult.image.height ?? "unknown"}`);
+        }
+        return lines.join("\n");
+    },
+};
+//# sourceMappingURL=image-description-actions.js.map

package/dist/actions/image-description-actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-description-actions.js","sourceRoot":"","sources":["../../src/actions/image-description-actions.ts"],"names":[],"mappings":"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"}

package/dist/actions/message-actions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"message-actions.d.ts","sourceRoot":"","sources":["../../src/actions/message-actions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAYH,OAAO,EACL,KAAK,gBAAgB,EAGtB,MAAM,iBAAiB,CAAC;AA0GzB,eAAO,MAAM,WAAW,EAAE,gBAiJzB,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,gBA4NzB,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,gBAgE/B,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,gBAuCjC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,gBAwD/B,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,gBAuDlC,CAAC"}
+{"version":3,"file":"message-actions.d.ts","sourceRoot":"","sources":["../../src/actions/message-actions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAcH,OAAO,EACL,KAAK,gBAAgB,EAGtB,MAAM,iBAAiB,CAAC;AA+GzB,eAAO,MAAM,WAAW,EAAE,gBAsJzB,CAAC;AAEF,eAAO,MAAM,WAAW,EAAE,gBAqPzB,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,gBA0J/B,CAAC;AAIF,eAAO,MAAM,mBAAmB,EAAE,gBAgJjC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,gBAwD/B,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,gBAuDlC,CAAC"}