@superdoc-dev/sdk 1.19.2 → 1.20.1

package/dist/agent/index.js

@@ -0,0 +1,15 @@
+/**
+ * Clean DOCX agent runtime.
+ *
+ * This barrel exposes the four product-stable agent tool entry points
+ * (inspect, apply, verify, operation) plus the IR types and the
+ * contract-derived operation catalog. Consumers should depend on this
+ * barrel — never reach into the benchmark `workflow-poc` profile from
+ * product code.
+ */
+export { AGENT_TOOL_DEFINITIONS, AGENT_TOOL_NAMES, isAgentToolName, listAgentTools, } from './catalog.js';
+export { agentInspect, agentApply, agentVerify, agentOperation, } from './runtime.js';
+export { validatePlan, isApplyStep, isInspectStep, isSelectStep, isVerifyStep, } from './ir.js';
+export { OPERATION_CATALOG, getOperationCatalogEntry, getOperationCatalogSummary, listMutatingOperations, listOperationsByDomain, listOperationsMissingStructuralVerification, } from './operation-catalog.js';
+export { AmbiguousSelectorError, buildDocumentSnapshot, resolveSnapshotSelector, } from './doc-snapshot.js';
+export { superdocPerformAction, isActionName, ACTION_NAMES_LIST, } from './actions.js';

package/dist/agent/ir.cjs

@@ -0,0 +1,170 @@
+'use strict';
+
+var operationCatalog = require('./operation-catalog.cjs');
+
+/**
+ * Clean agent IR.
+ *
+ * The IR makes the four phases of an agent edit explicit:
+ *
+ *   inspect -> select -> apply -> verify
+ *
+ * Every mutation a stable agent runtime path produces must be expressible as
+ * an `AgentPlan` whose steps reference real entries in the generated
+ * operation catalog. There is no prompt-derived execution contract: the IR is
+ * the only contract.
+ *
+ * Selectors are deterministic — they resolve to concrete blocks/ranges by
+ * ordinal, ref, nodeId, or named entity. Ambiguity is returned as a
+ * structured error so the agent must clarify rather than silently picking.
+ *
+ * Apply steps reference a generated `doc.*` operation id and carry the
+ * arguments the operation expects. The validator enforces that the operation
+ * id exists in the catalog, that it is the right mode for the requested
+ * intent (read vs write), and that arguments do not include reserved
+ * runtime keys.
+ *
+ * Verify steps describe the post-conditions the runtime must prove before
+ * declaring success. For risky domains (sections, protection,
+ * permission-ranges) the runtime additionally captures save/reopen evidence.
+ */
+const RESERVED_ARG_KEYS = new Set(['sessionId', 'doc']);
+function isSelectorValid(selector) {
+    switch (selector.kind) {
+        case 'ref':
+            return typeof selector.ref === 'string' && selector.ref.length > 0;
+        case 'nodeId':
+            return typeof selector.nodeId === 'string' && selector.nodeId.length > 0;
+        case 'ordinal':
+            return Number.isInteger(selector.value) && selector.value >= 1;
+        case 'tableCell':
+            return (Number.isInteger(selector.tableOrdinal) &&
+                selector.tableOrdinal >= 1 &&
+                Number.isInteger(selector.rowIndex) &&
+                selector.rowIndex >= 0 &&
+                Number.isInteger(selector.columnIndex) &&
+                selector.columnIndex >= 0);
+        case 'textSearch':
+            return (Array.isArray(selector.terms) &&
+                selector.terms.length > 0 &&
+                selector.terms.every((term) => typeof term === 'string' && term.length > 0) &&
+                (selector.match == null || selector.match === 'all' || selector.match === 'any') &&
+                (selector.occurrence == null || (Number.isInteger(selector.occurrence) && selector.occurrence >= 1)));
+        case 'entity':
+            return typeof selector.entityId === 'string' && selector.entityId.length > 0;
+        case 'placement':
+            return selector.at === 'document_start' || selector.at === 'document_end';
+        case 'relative':
+            return (selector.position === 'before' || selector.position === 'after') && isSelectorValid(selector.target);
+        case 'document':
+            return true;
+    }
+}
+function validatePlan(plan) {
+    const errors = [];
+    const references = [];
+    if (!plan.steps || plan.steps.length === 0) {
+        errors.push({ code: 'EMPTY_PLAN', message: 'Plan must contain at least one step.' });
+        return { ok: false, errors, references };
+    }
+    let hasApply = false;
+    let hasVerify = false;
+    let hasMutatingApply = false;
+    plan.steps.forEach((step, index) => {
+        switch (step.kind) {
+            case 'inspect': {
+                const entry = operationCatalog.getOperationCatalogEntry(step.operationId);
+                if (!entry) {
+                    errors.push({
+                        code: 'UNKNOWN_OPERATION',
+                        message: `Inspect step references unknown operation: ${step.operationId}.`,
+                        stepIndex: index,
+                        operationId: step.operationId,
+                    });
+                    break;
+                }
+                if (entry.mode === 'write') {
+                    errors.push({
+                        code: 'WRONG_OPERATION_MODE',
+                        message: `Inspect step ${step.operationId} must use a read-mode operation.`,
+                        stepIndex: index,
+                        operationId: step.operationId,
+                    });
+                }
+                for (const key of Object.keys(step.args)) {
+                    if (RESERVED_ARG_KEYS.has(key)) {
+                        errors.push({
+                            code: 'RESERVED_ARG_KEY',
+                            message: `Reserved key "${key}" must not appear in IR args.`,
+                            stepIndex: index,
+                            operationId: step.operationId,
+                        });
+                    }
+                }
+                references.push(entry);
+                break;
+            }
+            case 'select': {
+                if (!isSelectorValid(step.selector)) {
+                    errors.push({
+                        code: 'INVALID_SELECTOR',
+                        message: `Select step has invalid selector at index ${index}.`,
+                        stepIndex: index,
+                    });
+                }
+                break;
+            }
+            case 'apply': {
+                hasApply = true;
+                const entry = operationCatalog.getOperationCatalogEntry(step.operationId);
+                if (!entry) {
+                    errors.push({
+                        code: 'UNKNOWN_OPERATION',
+                        message: `Apply step references unknown operation: ${step.operationId}.`,
+                        stepIndex: index,
+                        operationId: step.operationId,
+                    });
+                    break;
+                }
+                if (entry.mode === 'read') {
+                    errors.push({
+                        code: 'WRONG_OPERATION_MODE',
+                        message: `Apply step ${step.operationId} must use a write-mode operation.`,
+                        stepIndex: index,
+                        operationId: step.operationId,
+                    });
+                }
+                if (entry.isMutating)
+                    hasMutatingApply = true;
+                for (const key of Object.keys(step.args)) {
+                    if (RESERVED_ARG_KEYS.has(key)) {
+                        errors.push({
+                            code: 'RESERVED_ARG_KEY',
+                            message: `Reserved key "${key}" must not appear in IR args.`,
+                            stepIndex: index,
+                            operationId: step.operationId,
+                        });
+                    }
+                }
+                references.push(entry);
+                break;
+            }
+            case 'verify': {
+                hasVerify = true;
+                break;
+            }
+        }
+    });
+    if (!hasApply) {
+        errors.push({ code: 'MISSING_APPLY_STEP', message: 'Plan must contain at least one apply step.' });
+    }
+    if (hasMutatingApply && !hasVerify) {
+        errors.push({
+            code: 'MISSING_VERIFY_STEP',
+            message: 'Mutating plans must include a verify step with explicit checks.',
+        });
+    }
+    return { ok: errors.length === 0, errors, references };
+}
+
+exports.validatePlan = validatePlan;

package/dist/agent/ir.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Clean agent IR.
+ *
+ * The IR makes the four phases of an agent edit explicit:
+ *
+ *   inspect -> select -> apply -> verify
+ *
+ * Every mutation a stable agent runtime path produces must be expressible as
+ * an `AgentPlan` whose steps reference real entries in the generated
+ * operation catalog. There is no prompt-derived execution contract: the IR is
+ * the only contract.
+ *
+ * Selectors are deterministic — they resolve to concrete blocks/ranges by
+ * ordinal, ref, nodeId, or named entity. Ambiguity is returned as a
+ * structured error so the agent must clarify rather than silently picking.
+ *
+ * Apply steps reference a generated `doc.*` operation id and carry the
+ * arguments the operation expects. The validator enforces that the operation
+ * id exists in the catalog, that it is the right mode for the requested
+ * intent (read vs write), and that arguments do not include reserved
+ * runtime keys.
+ *
+ * Verify steps describe the post-conditions the runtime must prove before
+ * declaring success. For risky domains (sections, protection,
+ * permission-ranges) the runtime additionally captures save/reopen evidence.
+ */
+import { type OperationCatalogEntry } from './operation-catalog.js';
+export type AgentSelector = {
+    kind: 'ref';
+    ref: string;
+} | {
+    kind: 'nodeId';
+    nodeId: string;
+} | {
+    kind: 'ordinal';
+    ordinalKind: AgentOrdinalKind;
+    value: number;
+} | {
+    kind: 'tableCell';
+    tableOrdinal: number;
+    rowIndex: number;
+    columnIndex: number;
+} | {
+    kind: 'textSearch';
+    terms: readonly string[];
+    match?: 'all' | 'any';
+    occurrence?: number;
+    caseSensitive?: boolean;
+    nodeTypes?: readonly ('paragraph' | 'heading' | 'listItem')[];
+} | {
+    kind: 'entity';
+    entityType: AgentEntityKind;
+    entityId: string;
+} | {
+    kind: 'document';
+} | {
+    kind: 'placement';
+    at: 'document_start' | 'document_end';
+} | {
+    kind: 'relative';
+    position: 'before' | 'after';
+    target: AgentSelector;
+};
+export type AgentOrdinalKind = 'blockOrdinal' | 'paragraphOrdinal' | 'bodyParagraphOrdinal' | 'headingOrdinal' | 'listOrdinal' | 'tableOrdinal' | 'sectionOrdinal';
+export type AgentEntityKind = 'comment' | 'trackedChange' | 'bookmark' | 'image' | 'hyperlink' | 'field';
+export type AgentChangeMode = 'direct' | 'tracked';
+export type AgentVerificationCheck = {
+    kind: 'block-text-contains';
+    nodeId: string;
+    text: string;
+} | {
+    kind: 'block-text-equals';
+    nodeId: string;
+    text: string;
+} | {
+    kind: 'block-count-delta';
+    nodeType: string;
+    delta: number;
+} | {
+    kind: 'list-item-count';
+    listId?: string;
+    expected: number;
+} | {
+    kind: 'table-shape';
+    nodeId: string;
+    rows: number;
+    columns: number;
+} | {
+    kind: 'comment-count-delta';
+    delta: number;
+} | {
+    kind: 'tracked-change-count-delta';
+    delta: number;
+} | {
+    kind: 'image-anchor-present';
+    imageId?: string;
+} | {
+    kind: 'revision-changed';
+} | {
+    kind: 'revision-unchanged';
+} | {
+    kind: 'document-saves-cleanly';
+} | {
+    kind: 'save-reopen-text-contains';
+    text: string;
+} | {
+    kind: 'block-text-matches-expectation';
+} | {
+    kind: 'list-kind-equals';
+    expected: string;
+} | {
+    kind: 'range-converted';
+    expected: number;
+} | {
+    kind: 'paragraphs-form-one-list';
+    expected: number;
+} | {
+    kind: 'single-list-with-expected-items';
+    expected: number;
+} | {
+    kind: 'items-form-one-list';
+    expected: number;
+} | {
+    kind: 'placement-honored';
+    at: string;
+    anchorNodeId: string;
+} | {
+    kind: 'marker-restored';
+    marker: string;
+} | {
+    kind: 'steps-undone';
+} | {
+    kind: 'marker-rendered';
+} | {
+    kind: 'block-style-equals';
+    styleId: string;
+};
+export type AgentInspectStep = {
+    kind: 'inspect';
+    /**
+     * `read`-mode catalog operation used to gather inspection data. e.g.
+     * `doc.info`, `doc.blocks.list`, `doc.tables.get`.
+     */
+    operationId: string;
+    args: Record<string, unknown>;
+    /** Optional alias used by later steps to reference the inspection result. */
+    bind?: string;
+};
+export type AgentSelectStep = {
+    kind: 'select';
+    selector: AgentSelector;
+    /** Optional alias used by later steps to reference the resolved selector. */
+    bind?: string;
+    /**
+     * When true, the selector must resolve uniquely. Multiple matches are
+     * reported as a structured AMBIGUOUS_SELECTOR error and the plan halts.
+     */
+    requireUnique?: boolean;
+};
+export type AgentApplyStep = {
+    kind: 'apply';
+    operationId: string;
+    args: Record<string, unknown>;
+    /** Optional human-readable rationale included in receipts for auditability. */
+    rationale?: string;
+    changeMode?: AgentChangeMode;
+    /** True for plans that must run as a single atomic batch. */
+    atomic?: boolean;
+};
+export type AgentVerifyStep = {
+    kind: 'verify';
+    checks: readonly AgentVerificationCheck[];
+    /** When true, the runtime must save and re-open the document and re-run the checks. */
+    saveReopen?: boolean;
+};
+export type AgentPlanStep = AgentInspectStep | AgentSelectStep | AgentApplyStep | AgentVerifyStep;
+export type AgentPlan = {
+    intent: string;
+    steps: readonly AgentPlanStep[];
+    /** Optional plain-language preconditions evaluated before execution. */
+    preconditions?: readonly string[];
+    /** Optional plain-language postconditions used for evidence reporting. */
+    postconditions?: readonly string[];
+    /** When true, the entire plan must be applied atomically. */
+    atomic?: boolean;
+    /** Expected diff summary (informational; used in receipts). */
+    expectedDiff?: {
+        blocksAdded?: number;
+        blocksRemoved?: number;
+        textReplacements?: number;
+        commentsAdded?: number;
+        trackedChangesAdded?: number;
+    };
+};
+export type IrValidationError = {
+    code: 'UNKNOWN_OPERATION' | 'WRONG_OPERATION_MODE' | 'MISSING_VERIFY_STEP' | 'MISSING_APPLY_STEP' | 'RESERVED_ARG_KEY' | 'INVALID_SELECTOR' | 'EMPTY_PLAN';
+    message: string;
+    stepIndex?: number;
+    operationId?: string;
+};
+export type IrValidationResult = {
+    ok: boolean;
+    errors: readonly IrValidationError[];
+    /** Catalog entries referenced by the plan, in order. */
+    references: readonly OperationCatalogEntry[];
+};
+export declare function validatePlan(plan: AgentPlan): IrValidationResult;
+/**
+ * Tagged-union narrowing helper used by runtimes and tests. Keeps the IR types
+ * the single source of truth for step discrimination.
+ */
+export declare function isApplyStep(step: AgentPlanStep): step is AgentApplyStep;
+export declare function isVerifyStep(step: AgentPlanStep): step is AgentVerifyStep;
+export declare function isInspectStep(step: AgentPlanStep): step is AgentInspectStep;
+export declare function isSelectStep(step: AgentPlanStep): step is AgentSelectStep;
+//# sourceMappingURL=ir.d.ts.map

package/dist/agent/ir.d.ts.map

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

package/dist/agent/ir.js

@@ -0,0 +1,181 @@
+/**
+ * Clean agent IR.
+ *
+ * The IR makes the four phases of an agent edit explicit:
+ *
+ *   inspect -> select -> apply -> verify
+ *
+ * Every mutation a stable agent runtime path produces must be expressible as
+ * an `AgentPlan` whose steps reference real entries in the generated
+ * operation catalog. There is no prompt-derived execution contract: the IR is
+ * the only contract.
+ *
+ * Selectors are deterministic — they resolve to concrete blocks/ranges by
+ * ordinal, ref, nodeId, or named entity. Ambiguity is returned as a
+ * structured error so the agent must clarify rather than silently picking.
+ *
+ * Apply steps reference a generated `doc.*` operation id and carry the
+ * arguments the operation expects. The validator enforces that the operation
+ * id exists in the catalog, that it is the right mode for the requested
+ * intent (read vs write), and that arguments do not include reserved
+ * runtime keys.
+ *
+ * Verify steps describe the post-conditions the runtime must prove before
+ * declaring success. For risky domains (sections, protection,
+ * permission-ranges) the runtime additionally captures save/reopen evidence.
+ */
+import { getOperationCatalogEntry } from './operation-catalog.js';
+const RESERVED_ARG_KEYS = new Set(['sessionId', 'doc']);
+function isSelectorValid(selector) {
+    switch (selector.kind) {
+        case 'ref':
+            return typeof selector.ref === 'string' && selector.ref.length > 0;
+        case 'nodeId':
+            return typeof selector.nodeId === 'string' && selector.nodeId.length > 0;
+        case 'ordinal':
+            return Number.isInteger(selector.value) && selector.value >= 1;
+        case 'tableCell':
+            return (Number.isInteger(selector.tableOrdinal) &&
+                selector.tableOrdinal >= 1 &&
+                Number.isInteger(selector.rowIndex) &&
+                selector.rowIndex >= 0 &&
+                Number.isInteger(selector.columnIndex) &&
+                selector.columnIndex >= 0);
+        case 'textSearch':
+            return (Array.isArray(selector.terms) &&
+                selector.terms.length > 0 &&
+                selector.terms.every((term) => typeof term === 'string' && term.length > 0) &&
+                (selector.match == null || selector.match === 'all' || selector.match === 'any') &&
+                (selector.occurrence == null || (Number.isInteger(selector.occurrence) && selector.occurrence >= 1)));
+        case 'entity':
+            return typeof selector.entityId === 'string' && selector.entityId.length > 0;
+        case 'placement':
+            return selector.at === 'document_start' || selector.at === 'document_end';
+        case 'relative':
+            return (selector.position === 'before' || selector.position === 'after') && isSelectorValid(selector.target);
+        case 'document':
+            return true;
+    }
+}
+export function validatePlan(plan) {
+    const errors = [];
+    const references = [];
+    if (!plan.steps || plan.steps.length === 0) {
+        errors.push({ code: 'EMPTY_PLAN', message: 'Plan must contain at least one step.' });
+        return { ok: false, errors, references };
+    }
+    let hasApply = false;
+    let hasVerify = false;
+    let hasMutatingApply = false;
+    plan.steps.forEach((step, index) => {
+        switch (step.kind) {
+            case 'inspect': {
+                const entry = getOperationCatalogEntry(step.operationId);
+                if (!entry) {
+                    errors.push({
+                        code: 'UNKNOWN_OPERATION',
+                        message: `Inspect step references unknown operation: ${step.operationId}.`,
+                        stepIndex: index,
+                        operationId: step.operationId,
+                    });
+                    break;
+                }
+                if (entry.mode === 'write') {
+                    errors.push({
+                        code: 'WRONG_OPERATION_MODE',
+                        message: `Inspect step ${step.operationId} must use a read-mode operation.`,
+                        stepIndex: index,
+                        operationId: step.operationId,
+                    });
+                }
+                for (const key of Object.keys(step.args)) {
+                    if (RESERVED_ARG_KEYS.has(key)) {
+                        errors.push({
+                            code: 'RESERVED_ARG_KEY',
+                            message: `Reserved key "${key}" must not appear in IR args.`,
+                            stepIndex: index,
+                            operationId: step.operationId,
+                        });
+                    }
+                }
+                references.push(entry);
+                break;
+            }
+            case 'select': {
+                if (!isSelectorValid(step.selector)) {
+                    errors.push({
+                        code: 'INVALID_SELECTOR',
+                        message: `Select step has invalid selector at index ${index}.`,
+                        stepIndex: index,
+                    });
+                }
+                break;
+            }
+            case 'apply': {
+                hasApply = true;
+                const entry = getOperationCatalogEntry(step.operationId);
+                if (!entry) {
+                    errors.push({
+                        code: 'UNKNOWN_OPERATION',
+                        message: `Apply step references unknown operation: ${step.operationId}.`,
+                        stepIndex: index,
+                        operationId: step.operationId,
+                    });
+                    break;
+                }
+                if (entry.mode === 'read') {
+                    errors.push({
+                        code: 'WRONG_OPERATION_MODE',
+                        message: `Apply step ${step.operationId} must use a write-mode operation.`,
+                        stepIndex: index,
+                        operationId: step.operationId,
+                    });
+                }
+                if (entry.isMutating)
+                    hasMutatingApply = true;
+                for (const key of Object.keys(step.args)) {
+                    if (RESERVED_ARG_KEYS.has(key)) {
+                        errors.push({
+                            code: 'RESERVED_ARG_KEY',
+                            message: `Reserved key "${key}" must not appear in IR args.`,
+                            stepIndex: index,
+                            operationId: step.operationId,
+                        });
+                    }
+                }
+                references.push(entry);
+                break;
+            }
+            case 'verify': {
+                hasVerify = true;
+                break;
+            }
+        }
+    });
+    if (!hasApply) {
+        errors.push({ code: 'MISSING_APPLY_STEP', message: 'Plan must contain at least one apply step.' });
+    }
+    if (hasMutatingApply && !hasVerify) {
+        errors.push({
+            code: 'MISSING_VERIFY_STEP',
+            message: 'Mutating plans must include a verify step with explicit checks.',
+        });
+    }
+    return { ok: errors.length === 0, errors, references };
+}
+/**
+ * Tagged-union narrowing helper used by runtimes and tests. Keeps the IR types
+ * the single source of truth for step discrimination.
+ */
+export function isApplyStep(step) {
+    return step.kind === 'apply';
+}
+export function isVerifyStep(step) {
+    return step.kind === 'verify';
+}
+export function isInspectStep(step) {
+    return step.kind === 'inspect';
+}
+export function isSelectStep(step) {
+    return step.kind === 'select';
+}