@opencxh/domain 1.219.0 → 1.221.0

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,142 @@
+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;
+    /** 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/package.json

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