@opencxh/domain 1.219.0 → 1.222.0

package/dist/platform/communication.d.ts

@@ -510,6 +510,24 @@ export type ServerOp = {
     channelId: string;
     interactionId: string;
     body: NoteBody;
+}
+/**
+ * Put an emoji on a message at the provider, or take it off.
+ *
+ * Only dispatched to a provider that declares the `message_reactions` feature — everywhere
+ * else the reaction stays ours alone, which is the honest outcome for a channel whose
+ * protocol has no such thing (mail).
+ *
+ * `emoji` is the literal character. Providers that speak their own vocabulary translate at
+ * their own edge; a reaction means the same thing on every channel and should read the same.
+ */
+ | {
+    kind: "message.react";
+    channelId: string;
+    activityId: string;
+    emoji: string;
+    /** `true` sets it, `false` removes it. */
+    on: boolean;
 } | {
     kind: "message.forward";
     channelId: string;
@@ -640,6 +658,13 @@ export declare const FEATURE_FOLDER_MANAGEMENT = "folder_management";
  * channels in `GET /search/sources`; the client fans out via `POST /search/mailbox`.
  */
 export declare const FEATURE_REMOTE_SEARCH = "remote_search";
+/**
+ * Well-known `ProviderFeature.name` for per-message emoji reactions. A provider that can both
+ * report the reactions on a message and set one on the user's behalf declares it true; the
+ * comm-server then dispatches `message.react` there. Everywhere else the reaction is ours
+ * alone, which is the honest outcome for a protocol that has no such thing (mail).
+ */
+export declare const FEATURE_MESSAGE_REACTIONS = "message_reactions";
 /**
  * Result shape for `IProvider.dispatch` and the comm-server
  * `dispatchToProvider` helper, discriminated on `ok`. Deliberately not

package/dist/platform/document-operations.d.ts

@@ -0,0 +1,6 @@
+import { DocumentOperationDescriptor } from './documents';
+export declare const DOCUMENT_OPERATIONS: DocumentOperationDescriptor[];
+/** The descriptors valid on one kind. Used by an adapter to declare, and by the guard to refuse. */
+export declare function operationsForKind(kind: string): DocumentOperationDescriptor[];
+/** One descriptor by name, or `undefined` for an operation nobody declares. */
+export declare function operationDescriptor(op: string): DocumentOperationDescriptor | undefined;

package/dist/platform/documents.d.ts

@@ -0,0 +1,151 @@
+import { AiToolParameterSchema } from './ai-tools';
+/**
+ * Open editors, readable and drivable across app boundaries.
+ *
+ * An app that mounts an editor (Univer, pdf.js, a block editor) holds a live document model no
+ * other layer can reach. The assistant beside it could neither read it nor change it, so every
+ * "what does this say" and "fix that cell" ended at the app boundary.
+ *
+ * Three keys, all through `sdk.services.execute`, mirroring `resources.*`:
+ *
+ * | Key | Params | Answer |
+ * |---|---|---|
+ * | `documents.describe` | {@link DocumentTargetParams} | {@link DocumentCapability} \| `null` |
+ * | `documents.inspect` | {@link DocumentInspectParams} | {@link DocumentInspection} \| `null` |
+ * | `documents.apply` | {@link DocumentApplyParams} | {@link DocumentApplyResult} \| `null` |
+ *
+ * A service-bus contract rather than a provider role, for the same reason as `resources.*`: the
+ * document only exists in the browser of the user who has it open. There is nothing on the server
+ * to ask.
+ *
+ * **What a server-side AI tool can and cannot do with this.** The tool loop runs on the server and
+ * the transport is one-way (`Bridge.sse.push` → the app's SSE handler; handler return values are
+ * discarded in `packages/app-sdk/src/modules/api.ts`). So a tool can *deliver* operations and must
+ * say so honestly; it cannot read an answer back. Reading therefore travels the other way, as
+ * `context.collect` slices that ride the next turn — which doubles as the feedback channel for an
+ * operation delivered a turn earlier. {@link DocumentApplyResult} is already shaped as the answer
+ * a round trip would return, so adding one later is transport work and not a contract change.
+ */
+/** The service-bus keys, as constants so a typo does not silently yield an empty list. */
+export declare const DOCUMENT_DESCRIBE_SERVICE = "documents.describe";
+export declare const DOCUMENT_INSPECT_SERVICE = "documents.inspect";
+export declare const DOCUMENT_APPLY_SERVICE = "documents.apply";
+/**
+ * Which document, as `<kind>:<ref>` — `file:<fileId>` for a stored file.
+ *
+ * Deliberately the same shape as a scopeKey and not a second identifier: it is the key the
+ * assistant already groups its conversations on and the key `provider/scope/authorize` gates, so
+ * "the document the user is looking at" and "the scope this thread belongs to" stay one thing.
+ */
+export type DocumentKey = string;
+/** Params for `documents.describe` and the shared prefix of the other two. */
+export interface DocumentTargetParams {
+    docKey: DocumentKey;
+}
+/**
+ * One operation an editor accepts, as the editor itself declares it.
+ *
+ * Declared rather than derived: the same list feeds the AI tool's parameter schema and the
+ * adapter's own validation, so the model can never be offered an operation the editor does not
+ * implement. Adding a capability is one descriptor plus one handler — no new tool, no prompt
+ * change, no server change.
+ */
+export interface DocumentOperationDescriptor {
+    /** `<kind>.<verb>`, and the prefix *is* the kind: that makes the guard a prefix test. */
+    op: string;
+    /** The document kinds this operation is valid on. */
+    kinds: string[];
+    /** One line, model-facing. This is what the assistant reads to choose. */
+    summary: string;
+    parameters: AiToolParameterSchema;
+    /**
+     * Can the user undo it with ctrl-Z?
+     *
+     * Not cosmetic: a Univer facade call goes through the command service and lands in the undo
+     * stack, while a snapshot rewrite (slides has no facade at all) does not. The tool result says
+     * which, because "I changed it, undo if you disagree" is a promise that has to hold.
+     */
+    undoable: boolean;
+    /**
+     * Does the user see the change before saving?
+     *
+     * `false` means the operation is written on save but not drawn yet — pdf.js draws its editor
+     * layer from `AnnotationEditor` instances, so an annotation injected as a plain object into the
+     * annotation storage is real to `saveDocument()` and invisible on screen. An invisible change
+     * needs to be announced, not assumed.
+     */
+    visible: boolean;
+}
+/** Answer to `documents.describe`: what is open, and what may be done to it. */
+export interface DocumentCapability {
+    docKey: DocumentKey;
+    /** `pdf` · `sheet` · `word` · `slides`, or whatever a future editor calls itself. */
+    kind: string;
+    title: string;
+    /** Someone else holds the lock, or a write-back would drop content, or it is read-only. */
+    readOnly: boolean;
+    /**
+     * Is the document parsed and answerable, or still loading?
+     *
+     * A separate field because the page knows what the file *is* (name, kind, which operations
+     * apply) the moment it opens, while the engine needs a second or two to parse it. Without the
+     * distinction a consumer cannot tell "no content" from "not yet", and a model told the first
+     * reports an empty document.
+     */
+    ready: boolean;
+    /** What a write-back would lose, from the editor's own `unsupportedFeatures`. */
+    blocked: string[];
+    /** The subset of {@link DOCUMENT_OPERATIONS} this mounted editor actually implements. */
+    operations: DocumentOperationDescriptor[];
+}
+/** One operation to apply. The extra keys are the params its descriptor declares. */
+export interface DocumentOperation {
+    op: string;
+    [key: string]: unknown;
+}
+export interface DocumentApplyParams extends DocumentTargetParams {
+    operations: DocumentOperation[];
+}
+/**
+ * What applying did. Partial success is the normal case, not an edge: operations arrive as a batch
+ * from a model, and one bad range should not discard the other four.
+ */
+export interface DocumentApplyResult {
+    docKey: DocumentKey;
+    applied: number;
+    failed: {
+        op: string;
+        reason: string;
+    }[];
+    /** Is there unsaved work now? The user still owns the save. */
+    dirty: boolean;
+    /** How many applied operations are not drawn yet. See {@link DocumentOperationDescriptor.visible}. */
+    pending: number;
+}
+/**
+ * What to read. Absent `slices` = the cheap overview only.
+ *
+ * Deliberately not the typed per-kind query tree Univer's inspection API uses: the consumer here
+ * is a prompt with a character budget, and the useful question is always "the overview, plus this
+ * much content". Names are per kind and documented by the adapter's own descriptor.
+ */
+export interface DocumentInspectParams extends DocumentTargetParams {
+    slices?: string[];
+    /** Character ceiling per slice. The adapter truncates predictably rather than mid-row. */
+    budget?: number;
+}
+/** Answer to `documents.inspect`: read-only, kind-shaped, budgeted. */
+export interface DocumentInspection {
+    docKey: DocumentKey;
+    kind: string;
+    /** Per-slice content, already truncated. `truncated` names the slices that were cut. */
+    slices: Record<string, unknown>;
+    truncated?: string[];
+}
+/**
+ * The kind out of a {@link DocumentKey} or an operation name.
+ *
+ * One helper for both because the operation prefix *is* the kind — `pdf.goToPage` on a `sheet`
+ * is a routing mistake, and this is what catches it.
+ */
+export declare function documentKindOf(value: string): string;

package/dist/platform/permission.d.ts

@@ -18,7 +18,7 @@ export declare const APP_PERMISSIONS: {
     readonly "app-store": readonly ["app.publish", "app.read", "app.write", "setting.read", "setting.write"];
     readonly assist: readonly ["board.read"];
     readonly automations: readonly ["sync.read", "sync.write", "webhook.read", "webhook.write"];
-    readonly communication: readonly ["account.read", "account.write", "activity-type.read", "activity.read", "activity.write", "attachment.read", "attribute.read", "attribute.write", "calendar.read", "calendar.write", "channel.read", "channel.write", "custom-field.read", "custom-field.write", "folder.read", "folder.write", "inbox.read", "inbox.write", "interaction.read", "interaction.write", "reminder.read", "template.read", "template.write", "topic.read", "topic.write"];
+    readonly communication: readonly ["account.read", "account.write", "activity-type.read", "activity.read", "activity.write", "attachment.read", "attribute.read", "attribute.write", "calendar.read", "calendar.write", "channel.read", "channel.write", "custom-field.read", "custom-field.write", "folder.read", "folder.write", "inbox.read", "inbox.write", "interaction.read", "interaction.write", "reaction.read", "reaction.write", "reminder.read", "template.read", "template.write", "topic.read", "topic.write"];
     readonly context: readonly ["kind.read", "kind.write", "memory.read", "memory.write"];
     readonly crm: readonly ["company.read", "company.write", "contact.read", "contact.write"];
     readonly "eylo-voip": readonly ["account.read", "account.write", "callflow.read", "callflow.write", "channel.read", "channel.write", "contact.read", "contact.write", "device.read", "device.write", "group.read", "group.write", "interaction.read", "interaction.write", "media.read", "media.write", "menu.read", "menu.write", "phone-number.read", "phone-number.write", "recording.read", "recording.write", "sip.read", "temporal-rule.read", "temporal-rule.write", "user.read", "user.write", "vmbox.read", "vmbox.write", "webhook.read", "webhook.write"];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencxh/domain",
-  "version": "1.219.0",
+  "version": "1.222.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",