@uns-kit/assistant-workflow 2.0.72

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Aljoša Vister
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# @uns-kit/assistant-workflow
+
+Provider-neutral TypeScript primitives for defining, evaluating, executing, and
+reviewing assistant workflows.
+
+The package defines workflow vocabulary and policy. Applications retain
+ownership of authentication, persistence, concrete tool handlers, provider SDKs,
+and user-facing responses.
+
+## Install
+
+```bash
+pnpm add @uns-kit/assistant-workflow
+```
+
+## Scope
+
+- typed workflow, intent, planning-step, memory, and clarification definitions;
+- tool capability and binding contracts for local functions, HTTP, hosted tools,
+  MCP, and controlled REPL integrations;
+- deterministic plan/run construction, execution queues, parity checks, and
+  safe trace/report serialization;
+- definition packages, catalog loading, replay, evaluation, and review helpers.
+
+The package deliberately does not contain provider credentials, database access,
+HTTP transport, UNS-specific tool implementations, or application-specific
+workflow definitions.
+
+## Development
+
+```bash
+pnpm --filter @uns-kit/assistant-workflow run verify
+pnpm --filter @uns-kit/assistant-workflow run build
+```
+
+The package is versioned with the rest of `@uns-kit/*`. Publishing is a manual
+maintainer action and is not performed by package verification commands.

package/dist/clarification-policy.d.ts

@@ -0,0 +1,64 @@
+import { type AssistantWorkflowClarificationCondition, type AssistantWorkflowClarificationQuestionStyle, type AssistantWorkflowClarificationRuleDefinition, type AssistantWorkflowDefinition, type AssistantWorkflowEntityKind } from "./definition.js";
+export type AssistantWorkflowClarificationPolicyInput = {
+    confidence?: number | null;
+    /** A host has already established one trusted, concrete scope. */
+    resolvedScope?: boolean;
+    /** A deterministic resolver returned multiple concrete candidates for one requested scope. */
+    resolverCandidatesAmbiguous?: boolean;
+    entities?: {
+        containers?: readonly string[] | null;
+        attributes?: readonly string[] | null;
+        fullTopicPaths?: readonly string[] | null;
+    } | null;
+    timeWindowHint?: string | null;
+};
+export type AssistantWorkflowClarificationRuleTrace = {
+    id: string;
+    condition: AssistantWorkflowClarificationCondition;
+    questionStyle: AssistantWorkflowClarificationQuestionStyle;
+    priority: number;
+    blocksExecution: boolean;
+    satisfiedByResolvedScope: boolean;
+    confidenceBelow: number | null;
+    requiredEntityKinds: AssistantWorkflowEntityKind[];
+    readsMemory: string[];
+    writesMemory: string[];
+};
+export type AssistantWorkflowResolvedClarificationPolicy = {
+    ruleIds: string[];
+    rules: AssistantWorkflowClarificationRuleTrace[];
+    blockingRuleIds: string[];
+    suggestedRuleIds: string[];
+    missingClarificationRules: string[];
+    needsClarification: boolean;
+    resolvedScope: boolean;
+    reasons: string[];
+};
+export type AssistantWorkflowObservedClarification = {
+    produced: boolean;
+    ruleId?: string | null;
+    source?: string | null;
+    layer?: string | null;
+    reason?: string | null;
+};
+export type AssistantWorkflowClarificationRuntimeComparisonOptions = {
+    equivalentRuleIds?: Record<string, readonly string[]>;
+};
+export type AssistantWorkflowClarificationRuntimeComparison = {
+    expectedRuleIds: string[];
+    expectedBlockingRuleIds: string[];
+    expectedSuggestedRuleIds: string[];
+    produced: boolean;
+    observedRuleId: string | null;
+    equivalentRuleIds: string[];
+    matched: boolean;
+    missingExpectedRuleIds: string[];
+    unexpectedObservedRuleId: string | null;
+    source: string | null;
+    layer: string | null;
+    reason: string | null;
+};
+export declare function findAssistantWorkflowClarificationRule(workflow: AssistantWorkflowDefinition<string, string, string, string>, ruleId: unknown): AssistantWorkflowClarificationRuleDefinition | null;
+export declare function buildAssistantWorkflowClarificationPolicy(workflow: AssistantWorkflowDefinition<string, string, string, string>, intentId: unknown, input?: AssistantWorkflowClarificationPolicyInput): AssistantWorkflowResolvedClarificationPolicy;
+export declare function buildAssistantWorkflowClarificationRuntimeComparison(policy: AssistantWorkflowResolvedClarificationPolicy, observed: AssistantWorkflowObservedClarification, options?: AssistantWorkflowClarificationRuntimeComparisonOptions): AssistantWorkflowClarificationRuntimeComparison;
+//# sourceMappingURL=clarification-policy.d.ts.map

package/dist/clarification-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clarification-policy.d.ts","sourceRoot":"","sources":["../src/clarification-policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,uCAAuC,EAC5C,KAAK,2CAA2C,EAChD,KAAK,4CAA4C,EACjD,KAAK,2BAA2B,EAChC,KAAK,2BAA2B,EACjC,MAAM,iBAAiB,CAAC;AAEzB,MAAM,MAAM,yCAAyC,GAAG;IACtD,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,kEAAkE;IAClE,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,8FAA8F;IAC9F,2BAA2B,CAAC,EAAE,OAAO,CAAC;IACtC,QAAQ,CAAC,EAAE;QACT,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;QACtC,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;QACtC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;KAC3C,GAAG,IAAI,CAAC;IACT,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,uCAAuC,GAAG;IACpD,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,uCAAuC,CAAC;IACnD,aAAa,EAAE,2CAA2C,CAAC;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,OAAO,CAAC;IACzB,wBAAwB,EAAE,OAAO,CAAC;IAClC,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,mBAAmB,EAAE,2BAA2B,EAAE,CAAC;IACnD,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,4CAA4C,GAAG;IACzD,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,KAAK,EAAE,uCAAuC,EAAE,CAAC;IACjD,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,yBAAyB,EAAE,MAAM,EAAE,CAAC;IACpC,kBAAkB,EAAE,OAAO,CAAC;IAC5B,aAAa,EAAE,OAAO,CAAC;IACvB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAEF,MAAM,MAAM,sCAAsC,GAAG;IACnD,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB,CAAC;AAEF,MAAM,MAAM,sDAAsD,GAAG;IACnE,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC;CACvD,CAAC;AAEF,MAAM,MAAM,+CAA+C,GAAG;IAC5D,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,uBAAuB,EAAE,MAAM,EAAE,CAAC;IAClC,wBAAwB,EAAE,MAAM,EAAE,CAAC;IACnC,QAAQ,EAAE,OAAO,CAAC;IAClB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB,sBAAsB,EAAE,MAAM,EAAE,CAAC;IACjC,wBAAwB,EAAE,MAAM,GAAG,IAAI,CAAC;IACxC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,CAAC;AAEF,wBAAgB,sCAAsC,CACpD,QAAQ,EAAE,2BAA2B,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EACrE,MAAM,EAAE,OAAO,GACd,4CAA4C,GAAG,IAAI,CAIrD;AAED,wBAAgB,yCAAyC,CACvD,QAAQ,EAAE,2BAA2B,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EACrE,QAAQ,EAAE,OAAO,EACjB,KAAK,GAAE,yCAA8C,GACpD,4CAA4C,CAuC9C;AAED,wBAAgB,oDAAoD,CAClE,MAAM,EAAE,4CAA4C,EACpD,QAAQ,EAAE,sCAAsC,EAChD,OAAO,GAAE,sDAA2D,GACnE,+CAA+C,CA4BjD"}

package/dist/clarification-policy.js

@@ -0,0 +1,174 @@
+import { findAssistantWorkflowIntent, normalizeAssistantWorkflowId, } from "./definition.js";
+export function findAssistantWorkflowClarificationRule(workflow, ruleId) {
+    const normalized = normalizeAssistantWorkflowId(ruleId);
+    if (!normalized)
+        return null;
+    return (workflow.clarificationRules ?? []).find((rule) => rule.id === normalized) ?? null;
+}
+export function buildAssistantWorkflowClarificationPolicy(workflow, intentId, input = {}) {
+    const intent = findAssistantWorkflowIntent(workflow, intentId);
+    const rulesById = new Map((workflow.clarificationRules ?? []).map((rule) => [rule.id, rule]));
+    const rules = [];
+    const missingClarificationRules = [];
+    const seen = new Set();
+    for (const rawRuleId of intent?.clarificationRules ?? []) {
+        const ruleId = normalizeAssistantWorkflowId(rawRuleId);
+        if (!ruleId || seen.has(ruleId))
+            continue;
+        seen.add(ruleId);
+        const rule = rulesById.get(ruleId);
+        if (rule) {
+            rules.push(rule);
+        }
+        else {
+            missingClarificationRules.push(ruleId);
+        }
+    }
+    const sortedRules = [...rules].sort((left, right) => getPriority(left) - getPriority(right));
+    const suggested = sortedRules
+        .map((rule) => evaluateRule(rule, intent?.id ?? null, input))
+        .filter((result) => result !== null);
+    const suggestedRuleIds = suggested.map((result) => result.ruleId);
+    const suggestedSet = new Set(suggestedRuleIds);
+    const blockingRuleIds = sortedRules
+        .filter((rule) => rule.blocksExecution === true && suggestedSet.has(rule.id))
+        .map((rule) => rule.id);
+    return {
+        ruleIds: sortedRules.map((rule) => rule.id),
+        rules: sortedRules.map(ruleToTrace),
+        blockingRuleIds,
+        suggestedRuleIds,
+        missingClarificationRules,
+        needsClarification: blockingRuleIds.length > 0,
+        resolvedScope: input.resolvedScope === true,
+        reasons: suggested.map((result) => result.reason),
+    };
+}
+export function buildAssistantWorkflowClarificationRuntimeComparison(policy, observed, options = {}) {
+    const observedRuleId = normalizeAssistantWorkflowId(observed.ruleId);
+    const equivalentRuleIds = observedRuleId
+        ? uniqueStrings([observedRuleId, ...(options.equivalentRuleIds?.[observedRuleId] ?? [])])
+        : [];
+    const expectedRuleIds = policy.blockingRuleIds.length ? policy.blockingRuleIds : policy.suggestedRuleIds;
+    const matched = observed.produced
+        ? equivalentRuleIds.some((ruleId) => expectedRuleIds.includes(ruleId))
+        : policy.blockingRuleIds.length === 0;
+    const missingExpectedRuleIds = observed.produced
+        ? expectedRuleIds.filter((ruleId) => !equivalentRuleIds.includes(ruleId))
+        : [...policy.blockingRuleIds];
+    const unexpectedObservedRuleId = observed.produced && observedRuleId && !matched ? observedRuleId : null;
+    return {
+        expectedRuleIds,
+        expectedBlockingRuleIds: [...policy.blockingRuleIds],
+        expectedSuggestedRuleIds: [...policy.suggestedRuleIds],
+        produced: observed.produced,
+        observedRuleId,
+        equivalentRuleIds,
+        matched,
+        missingExpectedRuleIds,
+        unexpectedObservedRuleId,
+        source: normalizeOptionalText(observed.source),
+        layer: normalizeOptionalText(observed.layer),
+        reason: normalizeOptionalText(observed.reason),
+    };
+}
+function evaluateRule(rule, intentId, input) {
+    if (input.resolvedScope === true && rule.satisfiedByResolvedScope === true) {
+        return null;
+    }
+    switch (rule.condition) {
+        case "low_confidence": {
+            const threshold = rule.confidenceBelow ?? 0.55;
+            const confidence = typeof input.confidence === "number" && Number.isFinite(input.confidence)
+                ? input.confidence
+                : null;
+            if (confidence !== null && confidence < threshold) {
+                return { ruleId: rule.id, reason: `confidence ${confidence} below ${threshold}` };
+            }
+            return null;
+        }
+        case "missing_required_entity": {
+            const requiredKinds = rule.requiredEntityKinds ?? [];
+            const missingKinds = requiredKinds.filter((kind) => !hasEntityKind(input, kind));
+            if (missingKinds.length === requiredKinds.length && requiredKinds.length > 0) {
+                return { ruleId: rule.id, reason: `missing required entity scope: ${missingKinds.join(", ")}` };
+            }
+            return null;
+        }
+        case "multiple_entity_candidates": {
+            const candidateKinds = rule.requiredEntityKinds?.length
+                ? rule.requiredEntityKinds
+                : ["container", "attribute", "full_topic_path"];
+            const ambiguousKinds = candidateKinds.filter((kind) => getEntityCount(input, kind) > 1);
+            if (ambiguousKinds.length > 0) {
+                return { ruleId: rule.id, reason: `multiple entity candidates: ${ambiguousKinds.join(", ")}` };
+            }
+            return null;
+        }
+        case "resolver_candidates_ambiguous":
+            return input.resolverCandidatesAmbiguous === true
+                ? { ruleId: rule.id, reason: "resolver returned multiple concrete scope candidates" }
+                : null;
+        case "fallback_intent":
+            return intentId === null || intentId === "other"
+                ? { ruleId: rule.id, reason: "fallback intent requires user clarification" }
+                : null;
+    }
+}
+function ruleToTrace(rule) {
+    return {
+        id: rule.id,
+        condition: rule.condition,
+        questionStyle: rule.questionStyle,
+        priority: getPriority(rule),
+        blocksExecution: rule.blocksExecution === true,
+        satisfiedByResolvedScope: rule.satisfiedByResolvedScope === true,
+        confidenceBelow: typeof rule.confidenceBelow === "number" ? rule.confidenceBelow : null,
+        requiredEntityKinds: [...(rule.requiredEntityKinds ?? [])],
+        readsMemory: uniqueStrings(rule.readsMemory ?? []),
+        writesMemory: uniqueStrings(rule.writesMemory ?? []),
+    };
+}
+function getPriority(rule) {
+    return typeof rule.priority === "number" && Number.isFinite(rule.priority) ? rule.priority : 100;
+}
+function hasEntityKind(input, kind) {
+    if (kind === "time_window") {
+        return typeof input.timeWindowHint === "string" && input.timeWindowHint.trim().length > 0;
+    }
+    return getEntityCount(input, kind) > 0;
+}
+function getEntityCount(input, kind) {
+    const entities = input.entities;
+    if (!entities)
+        return 0;
+    if (kind === "container")
+        return countStrings(entities.containers);
+    if (kind === "attribute")
+        return countStrings(entities.attributes);
+    if (kind === "full_topic_path")
+        return countStrings(entities.fullTopicPaths);
+    return 0;
+}
+function countStrings(values) {
+    if (!Array.isArray(values))
+        return 0;
+    return values.filter((value) => typeof value === "string" && value.trim().length > 0).length;
+}
+function uniqueStrings(values) {
+    const out = [];
+    const seen = new Set();
+    for (const value of values) {
+        const normalized = normalizeAssistantWorkflowId(value);
+        if (!normalized || seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        out.push(normalized);
+    }
+    return out;
+}
+function normalizeOptionalText(value) {
+    const normalized = value?.trim();
+    return normalized?.length ? normalized : null;
+}
+//# sourceMappingURL=clarification-policy.js.map

package/dist/clarification-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clarification-policy.js","sourceRoot":"","sources":["../src/clarification-policy.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,2BAA2B,EAC3B,4BAA4B,GAM7B,MAAM,iBAAiB,CAAC;AAmEzB,MAAM,UAAU,sCAAsC,CACpD,QAAqE,EACrE,MAAe;IAEf,MAAM,UAAU,GAAG,4BAA4B,CAAC,MAAM,CAAC,CAAC;IACxD,IAAI,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC;IAC7B,OAAO,CAAC,QAAQ,CAAC,kBAAkB,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,KAAK,UAAU,CAAC,IAAI,IAAI,CAAC;AAC5F,CAAC;AAED,MAAM,UAAU,yCAAyC,CACvD,QAAqE,EACrE,QAAiB,EACjB,QAAmD,EAAE;IAErD,MAAM,MAAM,GAAG,2BAA2B,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC/D,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,CAAC,kBAAkB,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,IAAI,CAAU,CAAC,CAAC,CAAC;IACvG,MAAM,KAAK,GAAmD,EAAE,CAAC;IACjE,MAAM,yBAAyB,GAAa,EAAE,CAAC;IAC/C,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAE/B,KAAK,MAAM,SAAS,IAAI,MAAM,EAAE,kBAAkB,IAAI,EAAE,EAAE,CAAC;QACzD,MAAM,MAAM,GAAG,4BAA4B,CAAC,SAAS,CAAC,CAAC;QACvD,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;YAAE,SAAS;QAC1C,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACjB,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACnC,IAAI,IAAI,EAAE,CAAC;YACT,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnB,CAAC;aAAM,CAAC;YACN,yBAAyB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IAED,MAAM,WAAW,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;IAC7F,MAAM,SAAS,GAAG,WAAW;SAC1B,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,IAAI,EAAE,KAAK,CAAC,CAAC;SAC5D,MAAM,CAAC,CAAC,MAAM,EAAgD,EAAE,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC;IACrF,MAAM,gBAAgB,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAClE,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAC/C,MAAM,eAAe,GAAG,WAAW;SAChC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,eAAe,KAAK,IAAI,IAAI,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;SAC5E,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAE1B,OAAO;QACL,OAAO,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC;QAC3C,KAAK,EAAE,WAAW,CAAC,GAAG,CAAC,WAAW,CAAC;QACnC,eAAe;QACf,gBAAgB;QAChB,yBAAyB;QACzB,kBAAkB,EAAE,eAAe,CAAC,MAAM,GAAG,CAAC;QAC9C,aAAa,EAAE,KAAK,CAAC,aAAa,KAAK,IAAI;QAC3C,OAAO,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC;KAClD,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,oDAAoD,CAClE,MAAoD,EACpD,QAAgD,EAChD,UAAkE,EAAE;IAEpE,MAAM,cAAc,GAAG,4BAA4B,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IACrE,MAAM,iBAAiB,GAAG,cAAc;QACtC,CAAC,CAAC,aAAa,CAAC,CAAC,cAAc,EAAE,GAAG,CAAC,OAAO,CAAC,iBAAiB,EAAE,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QACzF,CAAC,CAAC,EAAE,CAAC;IACP,MAAM,eAAe,GAAG,MAAM,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC,MAAM,CAAC,gBAAgB,CAAC;IACzG,MAAM,OAAO,GAAG,QAAQ,CAAC,QAAQ;QAC/B,CAAC,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,eAAe,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACtE,CAAC,CAAC,MAAM,CAAC,eAAe,CAAC,MAAM,KAAK,CAAC,CAAC;IACxC,MAAM,sBAAsB,GAAG,QAAQ,CAAC,QAAQ;QAC9C,CAAC,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,iBAAiB,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QACzE,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC;IAChC,MAAM,wBAAwB,GAAG,QAAQ,CAAC,QAAQ,IAAI,cAAc,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,IAAI,CAAC;IAEzG,OAAO;QACL,eAAe;QACf,uBAAuB,EAAE,CAAC,GAAG,MAAM,CAAC,eAAe,CAAC;QACpD,wBAAwB,EAAE,CAAC,GAAG,MAAM,CAAC,gBAAgB,CAAC;QACtD,QAAQ,EAAE,QAAQ,CAAC,QAAQ;QAC3B,cAAc;QACd,iBAAiB;QACjB,OAAO;QACP,sBAAsB;QACtB,wBAAwB;QACxB,MAAM,EAAE,qBAAqB,CAAC,QAAQ,CAAC,MAAM,CAAC;QAC9C,KAAK,EAAE,qBAAqB,CAAC,QAAQ,CAAC,KAAK,CAAC;QAC5C,MAAM,EAAE,qBAAqB,CAAC,QAAQ,CAAC,MAAM,CAAC;KAC/C,CAAC;AACJ,CAAC;AAED,SAAS,YAAY,CACnB,IAAkD,EAClD,QAAuB,EACvB,KAAgD;IAEhD,IAAI,KAAK,CAAC,aAAa,KAAK,IAAI,IAAI,IAAI,CAAC,wBAAwB,KAAK,IAAI,EAAE,CAAC;QAC3E,OAAO,IAAI,CAAC;IACd,CAAC;IACD,QAAQ,IAAI,CAAC,SAAS,EAAE,CAAC;QACvB,KAAK,gBAAgB,CAAC,CAAC,CAAC;YACtB,MAAM,SAAS,GAAG,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC;YAC/C,MAAM,UAAU,GAAG,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,UAAU,CAAC;gBAC1F,CAAC,CAAC,KAAK,CAAC,UAAU;gBAClB,CAAC,CAAC,IAAI,CAAC;YACT,IAAI,UAAU,KAAK,IAAI,IAAI,UAAU,GAAG,SAAS,EAAE,CAAC;gBAClD,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,cAAc,UAAU,UAAU,SAAS,EAAE,EAAE,CAAC;YACpF,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,KAAK,yBAAyB,CAAC,CAAC,CAAC;YAC/B,MAAM,aAAa,GAAG,IAAI,CAAC,mBAAmB,IAAI,EAAE,CAAC;YACrD,MAAM,YAAY,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;YACjF,IAAI,YAAY,CAAC,MAAM,KAAK,aAAa,CAAC,MAAM,IAAI,aAAa,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC7E,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,kCAAkC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;YAClG,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,KAAK,4BAA4B,CAAC,CAAC,CAAC;YAClC,MAAM,cAAc,GAAG,IAAI,CAAC,mBAAmB,EAAE,MAAM;gBACrD,CAAC,CAAC,IAAI,CAAC,mBAAmB;gBAC1B,CAAC,CAAC,CAAC,WAAW,EAAE,WAAW,EAAE,iBAAiB,CAAU,CAAC;YAC3D,MAAM,cAAc,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,cAAc,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;YACxF,IAAI,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC9B,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,+BAA+B,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC;YACjG,CAAC;YACD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,KAAK,+BAA+B;YAClC,OAAO,KAAK,CAAC,2BAA2B,KAAK,IAAI;gBAC/C,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,sDAAsD,EAAE;gBACrF,CAAC,CAAC,IAAI,CAAC;QACX,KAAK,iBAAiB;YACpB,OAAO,QAAQ,KAAK,IAAI,IAAI,QAAQ,KAAK,OAAO;gBAC9C,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,6CAA6C,EAAE;gBAC5E,CAAC,CAAC,IAAI,CAAC;IACb,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,IAAkD;IACrE,OAAO;QACL,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,QAAQ,EAAE,WAAW,CAAC,IAAI,CAAC;QAC3B,eAAe,EAAE,IAAI,CAAC,eAAe,KAAK,IAAI;QAC9C,wBAAwB,EAAE,IAAI,CAAC,wBAAwB,KAAK,IAAI;QAChE,eAAe,EAAE,OAAO,IAAI,CAAC,eAAe,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,eAAe,CAAC,CAAC,CAAC,IAAI;QACvF,mBAAmB,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,mBAAmB,IAAI,EAAE,CAAC,CAAC;QAC1D,WAAW,EAAE,aAAa,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC;QAClD,YAAY,EAAE,aAAa,CAAC,IAAI,CAAC,YAAY,IAAI,EAAE,CAAC;KACrD,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,IAAkD;IACrE,OAAO,OAAO,IAAI,CAAC,QAAQ,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC;AACnG,CAAC;AAED,SAAS,aAAa,CAAC,KAAgD,EAAE,IAAiC;IACxG,IAAI,IAAI,KAAK,aAAa,EAAE,CAAC;QAC3B,OAAO,OAAO,KAAK,CAAC,cAAc,KAAK,QAAQ,IAAI,KAAK,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;IAC5F,CAAC;IACD,OAAO,cAAc,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;AACzC,CAAC;AAED,SAAS,cAAc,CAAC,KAAgD,EAAE,IAAiC;IACzG,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,CAAC;IAChC,IAAI,CAAC,QAAQ;QAAE,OAAO,CAAC,CAAC;IACxB,IAAI,IAAI,KAAK,WAAW;QAAE,OAAO,YAAY,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IACnE,IAAI,IAAI,KAAK,WAAW;QAAE,OAAO,YAAY,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IACnE,IAAI,IAAI,KAAK,iBAAiB;QAAE,OAAO,YAAY,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;IAC7E,OAAO,CAAC,CAAC;AACX,CAAC;AAED,SAAS,YAAY,CAAC,MAA4C;IAChE,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,CAAC,CAAC;IACrC,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;AAC/F,CAAC;AAED,SAAS,aAAa,CAAC,MAAyB;IAC9C,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,UAAU,GAAG,4BAA4B,CAAC,KAAK,CAAC,CAAC;QACvD,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC;YAAE,SAAS;QAClD,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACrB,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACvB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,qBAAqB,CAAC,KAAgC;IAC7D,MAAM,UAAU,GAAG,KAAK,EAAE,IAAI,EAAE,CAAC;IACjC,OAAO,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC;AAChD,CAAC","sourcesContent":["import {\n  findAssistantWorkflowIntent,\n  normalizeAssistantWorkflowId,\n  type AssistantWorkflowClarificationCondition,\n  type AssistantWorkflowClarificationQuestionStyle,\n  type AssistantWorkflowClarificationRuleDefinition,\n  type AssistantWorkflowDefinition,\n  type AssistantWorkflowEntityKind,\n} from \"./definition.js\";\n\nexport type AssistantWorkflowClarificationPolicyInput = {\n  confidence?: number | null;\n  /** A host has already established one trusted, concrete scope. */\n  resolvedScope?: boolean;\n  /** A deterministic resolver returned multiple concrete candidates for one requested scope. */\n  resolverCandidatesAmbiguous?: boolean;\n  entities?: {\n    containers?: readonly string[] | null;\n    attributes?: readonly string[] | null;\n    fullTopicPaths?: readonly string[] | null;\n  } | null;\n  timeWindowHint?: string | null;\n};\n\nexport type AssistantWorkflowClarificationRuleTrace = {\n  id: string;\n  condition: AssistantWorkflowClarificationCondition;\n  questionStyle: AssistantWorkflowClarificationQuestionStyle;\n  priority: number;\n  blocksExecution: boolean;\n  satisfiedByResolvedScope: boolean;\n  confidenceBelow: number | null;\n  requiredEntityKinds: AssistantWorkflowEntityKind[];\n  readsMemory: string[];\n  writesMemory: string[];\n};\n\nexport type AssistantWorkflowResolvedClarificationPolicy = {\n  ruleIds: string[];\n  rules: AssistantWorkflowClarificationRuleTrace[];\n  blockingRuleIds: string[];\n  suggestedRuleIds: string[];\n  missingClarificationRules: string[];\n  needsClarification: boolean;\n  resolvedScope: boolean;\n  reasons: string[];\n};\n\nexport type AssistantWorkflowObservedClarification = {\n  produced: boolean;\n  ruleId?: string | null;\n  source?: string | null;\n  layer?: string | null;\n  reason?: string | null;\n};\n\nexport type AssistantWorkflowClarificationRuntimeComparisonOptions = {\n  equivalentRuleIds?: Record<string, readonly string[]>;\n};\n\nexport type AssistantWorkflowClarificationRuntimeComparison = {\n  expectedRuleIds: string[];\n  expectedBlockingRuleIds: string[];\n  expectedSuggestedRuleIds: string[];\n  produced: boolean;\n  observedRuleId: string | null;\n  equivalentRuleIds: string[];\n  matched: boolean;\n  missingExpectedRuleIds: string[];\n  unexpectedObservedRuleId: string | null;\n  source: string | null;\n  layer: string | null;\n  reason: string | null;\n};\n\nexport function findAssistantWorkflowClarificationRule(\n  workflow: AssistantWorkflowDefinition<string, string, string, string>,\n  ruleId: unknown,\n): AssistantWorkflowClarificationRuleDefinition | null {\n  const normalized = normalizeAssistantWorkflowId(ruleId);\n  if (!normalized) return null;\n  return (workflow.clarificationRules ?? []).find((rule) => rule.id === normalized) ?? null;\n}\n\nexport function buildAssistantWorkflowClarificationPolicy(\n  workflow: AssistantWorkflowDefinition<string, string, string, string>,\n  intentId: unknown,\n  input: AssistantWorkflowClarificationPolicyInput = {},\n): AssistantWorkflowResolvedClarificationPolicy {\n  const intent = findAssistantWorkflowIntent(workflow, intentId);\n  const rulesById = new Map((workflow.clarificationRules ?? []).map((rule) => [rule.id, rule] as const));\n  const rules: AssistantWorkflowClarificationRuleDefinition[] = [];\n  const missingClarificationRules: string[] = [];\n  const seen = new Set<string>();\n\n  for (const rawRuleId of intent?.clarificationRules ?? []) {\n    const ruleId = normalizeAssistantWorkflowId(rawRuleId);\n    if (!ruleId || seen.has(ruleId)) continue;\n    seen.add(ruleId);\n    const rule = rulesById.get(ruleId);\n    if (rule) {\n      rules.push(rule);\n    } else {\n      missingClarificationRules.push(ruleId);\n    }\n  }\n\n  const sortedRules = [...rules].sort((left, right) => getPriority(left) - getPriority(right));\n  const suggested = sortedRules\n    .map((rule) => evaluateRule(rule, intent?.id ?? null, input))\n    .filter((result): result is { ruleId: string; reason: string } => result !== null);\n  const suggestedRuleIds = suggested.map((result) => result.ruleId);\n  const suggestedSet = new Set(suggestedRuleIds);\n  const blockingRuleIds = sortedRules\n    .filter((rule) => rule.blocksExecution === true && suggestedSet.has(rule.id))\n    .map((rule) => rule.id);\n\n  return {\n    ruleIds: sortedRules.map((rule) => rule.id),\n    rules: sortedRules.map(ruleToTrace),\n    blockingRuleIds,\n    suggestedRuleIds,\n    missingClarificationRules,\n    needsClarification: blockingRuleIds.length > 0,\n    resolvedScope: input.resolvedScope === true,\n    reasons: suggested.map((result) => result.reason),\n  };\n}\n\nexport function buildAssistantWorkflowClarificationRuntimeComparison(\n  policy: AssistantWorkflowResolvedClarificationPolicy,\n  observed: AssistantWorkflowObservedClarification,\n  options: AssistantWorkflowClarificationRuntimeComparisonOptions = {},\n): AssistantWorkflowClarificationRuntimeComparison {\n  const observedRuleId = normalizeAssistantWorkflowId(observed.ruleId);\n  const equivalentRuleIds = observedRuleId\n    ? uniqueStrings([observedRuleId, ...(options.equivalentRuleIds?.[observedRuleId] ?? [])])\n    : [];\n  const expectedRuleIds = policy.blockingRuleIds.length ? policy.blockingRuleIds : policy.suggestedRuleIds;\n  const matched = observed.produced\n    ? equivalentRuleIds.some((ruleId) => expectedRuleIds.includes(ruleId))\n    : policy.blockingRuleIds.length === 0;\n  const missingExpectedRuleIds = observed.produced\n    ? expectedRuleIds.filter((ruleId) => !equivalentRuleIds.includes(ruleId))\n    : [...policy.blockingRuleIds];\n  const unexpectedObservedRuleId = observed.produced && observedRuleId && !matched ? observedRuleId : null;\n\n  return {\n    expectedRuleIds,\n    expectedBlockingRuleIds: [...policy.blockingRuleIds],\n    expectedSuggestedRuleIds: [...policy.suggestedRuleIds],\n    produced: observed.produced,\n    observedRuleId,\n    equivalentRuleIds,\n    matched,\n    missingExpectedRuleIds,\n    unexpectedObservedRuleId,\n    source: normalizeOptionalText(observed.source),\n    layer: normalizeOptionalText(observed.layer),\n    reason: normalizeOptionalText(observed.reason),\n  };\n}\n\nfunction evaluateRule(\n  rule: AssistantWorkflowClarificationRuleDefinition,\n  intentId: string | null,\n  input: AssistantWorkflowClarificationPolicyInput,\n): { ruleId: string; reason: string } | null {\n  if (input.resolvedScope === true && rule.satisfiedByResolvedScope === true) {\n    return null;\n  }\n  switch (rule.condition) {\n    case \"low_confidence\": {\n      const threshold = rule.confidenceBelow ?? 0.55;\n      const confidence = typeof input.confidence === \"number\" && Number.isFinite(input.confidence)\n        ? input.confidence\n        : null;\n      if (confidence !== null && confidence < threshold) {\n        return { ruleId: rule.id, reason: `confidence ${confidence} below ${threshold}` };\n      }\n      return null;\n    }\n    case \"missing_required_entity\": {\n      const requiredKinds = rule.requiredEntityKinds ?? [];\n      const missingKinds = requiredKinds.filter((kind) => !hasEntityKind(input, kind));\n      if (missingKinds.length === requiredKinds.length && requiredKinds.length > 0) {\n        return { ruleId: rule.id, reason: `missing required entity scope: ${missingKinds.join(\", \")}` };\n      }\n      return null;\n    }\n    case \"multiple_entity_candidates\": {\n      const candidateKinds = rule.requiredEntityKinds?.length\n        ? rule.requiredEntityKinds\n        : [\"container\", \"attribute\", \"full_topic_path\"] as const;\n      const ambiguousKinds = candidateKinds.filter((kind) => getEntityCount(input, kind) > 1);\n      if (ambiguousKinds.length > 0) {\n        return { ruleId: rule.id, reason: `multiple entity candidates: ${ambiguousKinds.join(\", \")}` };\n      }\n      return null;\n    }\n    case \"resolver_candidates_ambiguous\":\n      return input.resolverCandidatesAmbiguous === true\n        ? { ruleId: rule.id, reason: \"resolver returned multiple concrete scope candidates\" }\n        : null;\n    case \"fallback_intent\":\n      return intentId === null || intentId === \"other\"\n        ? { ruleId: rule.id, reason: \"fallback intent requires user clarification\" }\n        : null;\n  }\n}\n\nfunction ruleToTrace(rule: AssistantWorkflowClarificationRuleDefinition): AssistantWorkflowClarificationRuleTrace {\n  return {\n    id: rule.id,\n    condition: rule.condition,\n    questionStyle: rule.questionStyle,\n    priority: getPriority(rule),\n    blocksExecution: rule.blocksExecution === true,\n    satisfiedByResolvedScope: rule.satisfiedByResolvedScope === true,\n    confidenceBelow: typeof rule.confidenceBelow === \"number\" ? rule.confidenceBelow : null,\n    requiredEntityKinds: [...(rule.requiredEntityKinds ?? [])],\n    readsMemory: uniqueStrings(rule.readsMemory ?? []),\n    writesMemory: uniqueStrings(rule.writesMemory ?? []),\n  };\n}\n\nfunction getPriority(rule: AssistantWorkflowClarificationRuleDefinition): number {\n  return typeof rule.priority === \"number\" && Number.isFinite(rule.priority) ? rule.priority : 100;\n}\n\nfunction hasEntityKind(input: AssistantWorkflowClarificationPolicyInput, kind: AssistantWorkflowEntityKind): boolean {\n  if (kind === \"time_window\") {\n    return typeof input.timeWindowHint === \"string\" && input.timeWindowHint.trim().length > 0;\n  }\n  return getEntityCount(input, kind) > 0;\n}\n\nfunction getEntityCount(input: AssistantWorkflowClarificationPolicyInput, kind: AssistantWorkflowEntityKind): number {\n  const entities = input.entities;\n  if (!entities) return 0;\n  if (kind === \"container\") return countStrings(entities.containers);\n  if (kind === \"attribute\") return countStrings(entities.attributes);\n  if (kind === \"full_topic_path\") return countStrings(entities.fullTopicPaths);\n  return 0;\n}\n\nfunction countStrings(values: readonly string[] | null | undefined): number {\n  if (!Array.isArray(values)) return 0;\n  return values.filter((value) => typeof value === \"string\" && value.trim().length > 0).length;\n}\n\nfunction uniqueStrings(values: readonly string[]): string[] {\n  const out: string[] = [];\n  const seen = new Set<string>();\n  for (const value of values) {\n    const normalized = normalizeAssistantWorkflowId(value);\n    if (!normalized || seen.has(normalized)) continue;\n    seen.add(normalized);\n    out.push(normalized);\n  }\n  return out;\n}\n\nfunction normalizeOptionalText(value: string | null | undefined): string | null {\n  const normalized = value?.trim();\n  return normalized?.length ? normalized : null;\n}\n"]}

package/dist/decision.d.ts

@@ -0,0 +1,37 @@
+import { type AssistantWorkflowResolvedClarificationPolicy, type AssistantWorkflowClarificationPolicyInput } from "./clarification-policy.js";
+import { type AssistantWorkflowDefinition, type AssistantWorkflowExecutionBias, type AssistantWorkflowFirstHopToolPolicy, type AssistantWorkflowMemoryUse } from "./definition.js";
+import { type AssistantWorkflowResolvedMemoryPolicy } from "./memory-policy.js";
+import { type AssistantWorkflowPlan } from "./planning.js";
+export type AssistantWorkflowDecisionInput = {
+    intent?: string | null;
+    subintent?: string | null;
+    presentation?: string | null;
+    toolsToExpose?: readonly string[] | null;
+    confidence?: number | null;
+    resolvedScope?: boolean;
+    entities?: AssistantWorkflowClarificationPolicyInput["entities"];
+    timeWindowHint?: string | null;
+};
+export type AssistantWorkflowDecision = {
+    intent: string | null;
+    matchedIntent: boolean;
+    defaultPresentation: string | null;
+    effectivePresentation: string | null;
+    executionBias: AssistantWorkflowExecutionBias | null;
+    firstHopToolPolicy: AssistantWorkflowFirstHopToolPolicy | null;
+    memoryUse: AssistantWorkflowMemoryUse[];
+    memoryPolicy: AssistantWorkflowResolvedMemoryPolicy;
+    clarificationPolicy: AssistantWorkflowResolvedClarificationPolicy;
+    plan: AssistantWorkflowPlan;
+    requiredToolHints: string[];
+    missingRequiredToolHints: string[];
+    toolHints: string[];
+    missingToolHints: string[];
+    classifierTools: string[];
+    workflowSuggestedTools: string[];
+    extraClassifierTools: string[];
+};
+export declare function buildAssistantWorkflowDecision(workflow: AssistantWorkflowDefinition<string, string, string, string>, classification: AssistantWorkflowDecisionInput | null | undefined, availableToolNames?: readonly string[]): AssistantWorkflowDecision;
+export declare function buildAssistantWorkflowDecisionTracePayload(decision: AssistantWorkflowDecision): Record<string, unknown>;
+export declare function shouldRequireAssistantWorkflowFirstHopTool(workflow: AssistantWorkflowDefinition<string, string, string, string>, intentId: unknown): boolean;
+//# sourceMappingURL=decision.d.ts.map

package/dist/decision.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision.d.ts","sourceRoot":"","sources":["../src/decision.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,4CAA4C,EACjD,KAAK,yCAAyC,EAC/C,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAEL,KAAK,2BAA2B,EAChC,KAAK,8BAA8B,EACnC,KAAK,mCAAmC,EACxC,KAAK,0BAA0B,EAChC,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAEL,KAAK,qCAAqC,EAC3C,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,eAAe,CAAC;AAEvB,MAAM,MAAM,8BAA8B,GAAG;IAC3C,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;IACzC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,EAAE,yCAAyC,CAAC,UAAU,CAAC,CAAC;IACjE,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,aAAa,EAAE,OAAO,CAAC;IACvB,mBAAmB,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,qBAAqB,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,aAAa,EAAE,8BAA8B,GAAG,IAAI,CAAC;IACrD,kBAAkB,EAAE,mCAAmC,GAAG,IAAI,CAAC;IAC/D,SAAS,EAAE,0BAA0B,EAAE,CAAC;IACxC,YAAY,EAAE,qCAAqC,CAAC;IACpD,mBAAmB,EAAE,4CAA4C,CAAC;IAClE,IAAI,EAAE,qBAAqB,CAAC;IAC5B,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,wBAAwB,EAAE,MAAM,EAAE,CAAC;IACnC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,sBAAsB,EAAE,MAAM,EAAE,CAAC;IACjC,oBAAoB,EAAE,MAAM,EAAE,CAAC;CAChC,CAAC;AAEF,wBAAgB,8BAA8B,CAC5C,QAAQ,EAAE,2BAA2B,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EACrE,cAAc,EAAE,8BAA8B,GAAG,IAAI,GAAG,SAAS,EACjE,kBAAkB,GAAE,SAAS,MAAM,EAAO,GACzC,yBAAyB,CAqD3B;AAED,wBAAgB,0CAA0C,CACxD,QAAQ,EAAE,yBAAyB,GAClC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAoBzB;AAED,wBAAgB,0CAA0C,CACxD,QAAQ,EAAE,2BAA2B,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EACrE,QAAQ,EAAE,OAAO,GAChB,OAAO,CAET"}

package/dist/decision.js

@@ -0,0 +1,100 @@
+import { buildAssistantWorkflowClarificationPolicy, } from "./clarification-policy.js";
+import { findAssistantWorkflowIntent, } from "./definition.js";
+import { buildAssistantWorkflowMemoryPolicy, } from "./memory-policy.js";
+import { buildAssistantWorkflowPlan, } from "./planning.js";
+export function buildAssistantWorkflowDecision(workflow, classification, availableToolNames = []) {
+    const intent = typeof classification?.intent === "string" && classification.intent.trim().length
+        ? classification.intent.trim().toLowerCase()
+        : null;
+    const intentDefinition = intent ? findAssistantWorkflowIntent(workflow, intent) : null;
+    const availableSet = new Set(availableToolNames);
+    const classifierTools = uniqueNonEmptyStrings(classification?.toolsToExpose ?? [])
+        .filter((tool) => availableSet.size === 0 || availableSet.has(tool));
+    const toolHintsRaw = uniqueNonEmptyStrings(intentDefinition?.toolHints ?? []);
+    const requiredToolHintsRaw = uniqueNonEmptyStrings(intentDefinition?.requiredToolHints ?? []);
+    const toolHints = toolHintsRaw.filter((tool) => availableSet.size === 0 || availableSet.has(tool));
+    const requiredToolHints = requiredToolHintsRaw.filter((tool) => availableSet.size === 0 || availableSet.has(tool));
+    const missingToolHints = availableSet.size === 0 ? [] : toolHintsRaw.filter((tool) => !availableSet.has(tool));
+    const missingRequiredToolHints = availableSet.size === 0 ? [] : requiredToolHintsRaw.filter((tool) => !availableSet.has(tool));
+    const workflowSuggestedTools = uniqueNonEmptyStrings([...classifierTools, ...requiredToolHints, ...toolHints]);
+    const workflowHintSet = new Set([...requiredToolHints, ...toolHints]);
+    const memoryPolicy = buildAssistantWorkflowMemoryPolicy(workflow, intent);
+    const clarificationPolicy = buildAssistantWorkflowClarificationPolicy(workflow, intent, buildClarificationPolicyInput(classification));
+    const plan = buildAssistantWorkflowPlan(workflow, intent, availableToolNames, {
+        ...(typeof classification?.subintent === "string" ? { subintent: classification.subintent } : {}),
+        ...(typeof classification?.presentation === "string" ? { presentation: classification.presentation } : {}),
+        ...(typeof classification?.timeWindowHint === "string" ? { timeWindowHint: classification.timeWindowHint } : {}),
+        ...(Array.isArray(classification?.toolsToExpose) ? { toolsToExpose: classification.toolsToExpose } : {}),
+        ...(typeof classification?.confidence === "number" ? { confidence: classification.confidence } : {}),
+    });
+    return {
+        intent,
+        matchedIntent: intentDefinition !== null,
+        defaultPresentation: intentDefinition?.defaultPresentation ?? null,
+        effectivePresentation: typeof classification?.presentation === "string" && classification.presentation.trim().length
+            ? classification.presentation.trim().toLowerCase()
+            : intentDefinition?.defaultPresentation ?? null,
+        executionBias: intentDefinition?.executionBias ?? null,
+        firstHopToolPolicy: intentDefinition ? intentDefinition.firstHopToolPolicy ?? "auto" : null,
+        memoryUse: uniqueNonEmptyStrings(intentDefinition?.memoryUse ?? []),
+        memoryPolicy,
+        clarificationPolicy,
+        plan,
+        requiredToolHints,
+        missingRequiredToolHints,
+        toolHints,
+        missingToolHints,
+        classifierTools,
+        workflowSuggestedTools,
+        extraClassifierTools: classifierTools.filter((tool) => !workflowHintSet.has(tool)),
+    };
+}
+export function buildAssistantWorkflowDecisionTracePayload(decision) {
+    return {
+        intent: decision.intent,
+        matchedIntent: decision.matchedIntent,
+        defaultPresentation: decision.defaultPresentation,
+        effectivePresentation: decision.effectivePresentation,
+        executionBias: decision.executionBias,
+        firstHopToolPolicy: decision.firstHopToolPolicy,
+        memoryUse: decision.memoryUse,
+        memoryPolicy: decision.memoryPolicy,
+        clarificationPolicy: decision.clarificationPolicy,
+        plan: decision.plan,
+        classifierTools: decision.classifierTools,
+        requiredToolHints: decision.requiredToolHints,
+        missingRequiredToolHints: decision.missingRequiredToolHints,
+        toolHints: decision.toolHints,
+        missingToolHints: decision.missingToolHints,
+        workflowSuggestedTools: decision.workflowSuggestedTools,
+        extraClassifierTools: decision.extraClassifierTools,
+    };
+}
+export function shouldRequireAssistantWorkflowFirstHopTool(workflow, intentId) {
+    return findAssistantWorkflowIntent(workflow, intentId)?.firstHopToolPolicy === "require-tool";
+}
+function uniqueNonEmptyStrings(values) {
+    const out = [];
+    const seen = new Set();
+    for (const value of values) {
+        if (typeof value !== "string")
+            continue;
+        const trimmed = value.trim();
+        if (!trimmed.length || seen.has(trimmed))
+            continue;
+        seen.add(trimmed);
+        out.push(trimmed);
+    }
+    return out;
+}
+function buildClarificationPolicyInput(classification) {
+    if (!classification)
+        return {};
+    return {
+        ...(typeof classification.confidence === "number" ? { confidence: classification.confidence } : {}),
+        ...(classification.resolvedScope === true ? { resolvedScope: true } : {}),
+        ...(classification.entities !== undefined ? { entities: classification.entities } : {}),
+        ...(classification.timeWindowHint !== undefined ? { timeWindowHint: classification.timeWindowHint } : {}),
+    };
+}
+//# sourceMappingURL=decision.js.map

package/dist/decision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision.js","sourceRoot":"","sources":["../src/decision.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  buildAssistantWorkflowClarificationPolicy,\n  type AssistantWorkflowResolvedClarificationPolicy,\n  type AssistantWorkflowClarificationPolicyInput,\n} from \"./clarification-policy.js\";\nimport {\n  findAssistantWorkflowIntent,\n  type AssistantWorkflowDefinition,\n  type AssistantWorkflowExecutionBias,\n  type AssistantWorkflowFirstHopToolPolicy,\n  type AssistantWorkflowMemoryUse,\n} from \"./definition.js\";\nimport {\n  buildAssistantWorkflowMemoryPolicy,\n  type AssistantWorkflowResolvedMemoryPolicy,\n} from \"./memory-policy.js\";\nimport {\n  buildAssistantWorkflowPlan,\n  type AssistantWorkflowPlan,\n} from \"./planning.js\";\n\nexport type AssistantWorkflowDecisionInput = {\n  intent?: string | null;\n  subintent?: string | null;\n  presentation?: string | null;\n  toolsToExpose?: readonly string[] | null;\n  confidence?: number | null;\n  resolvedScope?: boolean;\n  entities?: AssistantWorkflowClarificationPolicyInput[\"entities\"];\n  timeWindowHint?: string | null;\n};\n\nexport type AssistantWorkflowDecision = {\n  intent: string | null;\n  matchedIntent: boolean;\n  defaultPresentation: string | null;\n  effectivePresentation: string | null;\n  executionBias: AssistantWorkflowExecutionBias | null;\n  firstHopToolPolicy: AssistantWorkflowFirstHopToolPolicy | null;\n  memoryUse: AssistantWorkflowMemoryUse[];\n  memoryPolicy: AssistantWorkflowResolvedMemoryPolicy;\n  clarificationPolicy: AssistantWorkflowResolvedClarificationPolicy;\n  plan: AssistantWorkflowPlan;\n  requiredToolHints: string[];\n  missingRequiredToolHints: string[];\n  toolHints: string[];\n  missingToolHints: string[];\n  classifierTools: string[];\n  workflowSuggestedTools: string[];\n  extraClassifierTools: string[];\n};\n\nexport function buildAssistantWorkflowDecision(\n  workflow: AssistantWorkflowDefinition<string, string, string, string>,\n  classification: AssistantWorkflowDecisionInput | null | undefined,\n  availableToolNames: readonly string[] = [],\n): AssistantWorkflowDecision {\n  const intent = typeof classification?.intent === \"string\" && classification.intent.trim().length\n    ? classification.intent.trim().toLowerCase()\n    : null;\n  const intentDefinition = intent ? findAssistantWorkflowIntent(workflow, intent) : null;\n  const availableSet = new Set(availableToolNames);\n  const classifierTools = uniqueNonEmptyStrings(classification?.toolsToExpose ?? [])\n    .filter((tool) => availableSet.size === 0 || availableSet.has(tool));\n  const toolHintsRaw = uniqueNonEmptyStrings(intentDefinition?.toolHints ?? []);\n  const requiredToolHintsRaw = uniqueNonEmptyStrings(intentDefinition?.requiredToolHints ?? []);\n  const toolHints = toolHintsRaw.filter((tool) => availableSet.size === 0 || availableSet.has(tool));\n  const requiredToolHints = requiredToolHintsRaw.filter((tool) => availableSet.size === 0 || availableSet.has(tool));\n  const missingToolHints = availableSet.size === 0 ? [] : toolHintsRaw.filter((tool) => !availableSet.has(tool));\n  const missingRequiredToolHints =\n    availableSet.size === 0 ? [] : requiredToolHintsRaw.filter((tool) => !availableSet.has(tool));\n  const workflowSuggestedTools = uniqueNonEmptyStrings([...classifierTools, ...requiredToolHints, ...toolHints]);\n  const workflowHintSet = new Set([...requiredToolHints, ...toolHints]);\n  const memoryPolicy = buildAssistantWorkflowMemoryPolicy(workflow, intent);\n  const clarificationPolicy = buildAssistantWorkflowClarificationPolicy(\n    workflow,\n    intent,\n    buildClarificationPolicyInput(classification),\n  );\n  const plan = buildAssistantWorkflowPlan(workflow, intent, availableToolNames, {\n    ...(typeof classification?.subintent === \"string\" ? { subintent: classification.subintent } : {}),\n    ...(typeof classification?.presentation === \"string\" ? { presentation: classification.presentation } : {}),\n    ...(typeof classification?.timeWindowHint === \"string\" ? { timeWindowHint: classification.timeWindowHint } : {}),\n    ...(Array.isArray(classification?.toolsToExpose) ? { toolsToExpose: classification.toolsToExpose } : {}),\n    ...(typeof classification?.confidence === \"number\" ? { confidence: classification.confidence } : {}),\n  });\n\n  return {\n    intent,\n    matchedIntent: intentDefinition !== null,\n    defaultPresentation: intentDefinition?.defaultPresentation ?? null,\n    effectivePresentation:\n      typeof classification?.presentation === \"string\" && classification.presentation.trim().length\n        ? classification.presentation.trim().toLowerCase()\n        : intentDefinition?.defaultPresentation ?? null,\n    executionBias: intentDefinition?.executionBias ?? null,\n    firstHopToolPolicy: intentDefinition ? intentDefinition.firstHopToolPolicy ?? \"auto\" : null,\n    memoryUse: uniqueNonEmptyStrings(intentDefinition?.memoryUse ?? []) as AssistantWorkflowMemoryUse[],\n    memoryPolicy,\n    clarificationPolicy,\n    plan,\n    requiredToolHints,\n    missingRequiredToolHints,\n    toolHints,\n    missingToolHints,\n    classifierTools,\n    workflowSuggestedTools,\n    extraClassifierTools: classifierTools.filter((tool) => !workflowHintSet.has(tool)),\n  };\n}\n\nexport function buildAssistantWorkflowDecisionTracePayload(\n  decision: AssistantWorkflowDecision,\n): Record<string, unknown> {\n  return {\n    intent: decision.intent,\n    matchedIntent: decision.matchedIntent,\n    defaultPresentation: decision.defaultPresentation,\n    effectivePresentation: decision.effectivePresentation,\n    executionBias: decision.executionBias,\n    firstHopToolPolicy: decision.firstHopToolPolicy,\n    memoryUse: decision.memoryUse,\n    memoryPolicy: decision.memoryPolicy,\n    clarificationPolicy: decision.clarificationPolicy,\n    plan: decision.plan,\n    classifierTools: decision.classifierTools,\n    requiredToolHints: decision.requiredToolHints,\n    missingRequiredToolHints: decision.missingRequiredToolHints,\n    toolHints: decision.toolHints,\n    missingToolHints: decision.missingToolHints,\n    workflowSuggestedTools: decision.workflowSuggestedTools,\n    extraClassifierTools: decision.extraClassifierTools,\n  };\n}\n\nexport function shouldRequireAssistantWorkflowFirstHopTool(\n  workflow: AssistantWorkflowDefinition<string, string, string, string>,\n  intentId: unknown,\n): boolean {\n  return findAssistantWorkflowIntent(workflow, intentId)?.firstHopToolPolicy === \"require-tool\";\n}\n\nfunction uniqueNonEmptyStrings(values: readonly unknown[]): string[] {\n  const out: string[] = [];\n  const seen = new Set<string>();\n  for (const value of values) {\n    if (typeof value !== \"string\") continue;\n    const trimmed = value.trim();\n    if (!trimmed.length || seen.has(trimmed)) continue;\n    seen.add(trimmed);\n    out.push(trimmed);\n  }\n  return out;\n}\n\nfunction buildClarificationPolicyInput(\n  classification: AssistantWorkflowDecisionInput | null | undefined,\n): AssistantWorkflowClarificationPolicyInput {\n  if (!classification) return {};\n  return {\n    ...(typeof classification.confidence === \"number\" ? { confidence: classification.confidence } : {}),\n    ...(classification.resolvedScope === true ? { resolvedScope: true } : {}),\n    ...(classification.entities !== undefined ? { entities: classification.entities } : {}),\n    ...(classification.timeWindowHint !== undefined ? { timeWindowHint: classification.timeWindowHint } : {}),\n  };\n}\n"]}

package/dist/definition-catalog-replay.d.ts

@@ -0,0 +1,25 @@
+import { type AssistantWorkflowDefinitionCatalog } from "./definition-catalog.js";
+import { type AssistantWorkflowSerializedDefinitionLinesParseResult } from "./definition-json.js";
+import { type AssistantWorkflowDefinitionManifestLinesParseResult } from "./definition-manifest.js";
+import type { AssistantWorkflowJsonValue } from "./run-report-json.js";
+export type AssistantWorkflowDefinitionCatalogReplayLinesInput = {
+    definitionLines: string;
+};
+export type AssistantWorkflowDefinitionCatalogReplayLinesResult = {
+    definitionParse: AssistantWorkflowSerializedDefinitionLinesParseResult;
+    parseErrorCount: number;
+    catalog: AssistantWorkflowDefinitionCatalog;
+};
+export type AssistantWorkflowDefinitionManifestCatalogReplayLinesInput = {
+    manifestLines: string;
+};
+export type AssistantWorkflowDefinitionManifestCatalogReplayLinesResult = {
+    manifestParse: AssistantWorkflowDefinitionManifestLinesParseResult;
+    parseErrorCount: number;
+    catalog: AssistantWorkflowDefinitionCatalog;
+};
+export declare function runAssistantWorkflowDefinitionCatalogReplayLines(input: AssistantWorkflowDefinitionCatalogReplayLinesInput): AssistantWorkflowDefinitionCatalogReplayLinesResult;
+export declare function runAssistantWorkflowDefinitionManifestCatalogReplayLines(input: AssistantWorkflowDefinitionManifestCatalogReplayLinesInput): AssistantWorkflowDefinitionManifestCatalogReplayLinesResult;
+export declare function buildAssistantWorkflowDefinitionCatalogReplayLinesTracePayload(result: AssistantWorkflowDefinitionCatalogReplayLinesResult): Record<string, AssistantWorkflowJsonValue>;
+export declare function buildAssistantWorkflowDefinitionManifestCatalogReplayLinesTracePayload(result: AssistantWorkflowDefinitionManifestCatalogReplayLinesResult): Record<string, AssistantWorkflowJsonValue>;
+//# sourceMappingURL=definition-catalog-replay.d.ts.map

package/dist/definition-catalog-replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition-catalog-replay.d.ts","sourceRoot":"","sources":["../src/definition-catalog-replay.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,kCAAkC,EACxC,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAEL,KAAK,qDAAqD,EAC3D,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAEL,KAAK,mDAAmD,EACzD,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAEvE,MAAM,MAAM,kDAAkD,GAAG;IAC/D,eAAe,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,mDAAmD,GAAG;IAChE,eAAe,EAAE,qDAAqD,CAAC;IACvE,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,kCAAkC,CAAC;CAC7C,CAAC;AAEF,MAAM,MAAM,0DAA0D,GAAG;IACvE,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,2DAA2D,GAAG;IACxE,aAAa,EAAE,mDAAmD,CAAC;IACnE,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,kCAAkC,CAAC;CAC7C,CAAC;AAEF,wBAAgB,gDAAgD,CAC9D,KAAK,EAAE,kDAAkD,GACxD,mDAAmD,CAQrD;AAED,wBAAgB,wDAAwD,CACtE,KAAK,EAAE,0DAA0D,GAChE,2DAA2D,CAU7D;AAED,wBAAgB,8DAA8D,CAC5E,MAAM,EAAE,mDAAmD,GAC1D,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAe5C;AAED,wBAAgB,sEAAsE,CACpF,MAAM,EAAE,2DAA2D,GAClE,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAe5C"}

package/dist/definition-catalog-replay.js

@@ -0,0 +1,54 @@
+import { buildAssistantWorkflowDefinitionCatalogTracePayload, buildAssistantWorkflowSerializedDefinitionCatalog, } from "./definition-catalog.js";
+import { parseAssistantWorkflowSerializedDefinitionLines, } from "./definition-json.js";
+import { parseAssistantWorkflowDefinitionManifestLines, } from "./definition-manifest.js";
+export function runAssistantWorkflowDefinitionCatalogReplayLines(input) {
+    const definitionParse = parseAssistantWorkflowSerializedDefinitionLines(input.definitionLines);
+    const catalog = buildAssistantWorkflowSerializedDefinitionCatalog(definitionParse.definitions);
+    return {
+        definitionParse,
+        parseErrorCount: definitionParse.errorCount,
+        catalog,
+    };
+}
+export function runAssistantWorkflowDefinitionManifestCatalogReplayLines(input) {
+    const manifestParse = parseAssistantWorkflowDefinitionManifestLines(input.manifestLines);
+    const catalog = buildAssistantWorkflowSerializedDefinitionCatalog(manifestParse.manifests.map((manifest) => manifest.serializedDefinition));
+    return {
+        manifestParse,
+        parseErrorCount: manifestParse.errorCount,
+        catalog,
+    };
+}
+export function buildAssistantWorkflowDefinitionCatalogReplayLinesTracePayload(result) {
+    return {
+        definitionParse: {
+            lineCount: result.definitionParse.lineCount,
+            definitionCount: result.definitionParse.definitionCount,
+            errorCount: result.definitionParse.errorCount,
+            errors: result.definitionParse.errors.map((error) => ({
+                lineNumber: error.lineNumber,
+                reason: error.reason,
+                preview: error.preview,
+            })),
+        },
+        parseErrorCount: result.parseErrorCount,
+        catalog: buildAssistantWorkflowDefinitionCatalogTracePayload(result.catalog),
+    };
+}
+export function buildAssistantWorkflowDefinitionManifestCatalogReplayLinesTracePayload(result) {
+    return {
+        manifestParse: {
+            lineCount: result.manifestParse.lineCount,
+            manifestCount: result.manifestParse.manifestCount,
+            errorCount: result.manifestParse.errorCount,
+            errors: result.manifestParse.errors.map((error) => ({
+                lineNumber: error.lineNumber,
+                reason: error.reason,
+                preview: error.preview,
+            })),
+        },
+        parseErrorCount: result.parseErrorCount,
+        catalog: buildAssistantWorkflowDefinitionCatalogTracePayload(result.catalog),
+    };
+}
+//# sourceMappingURL=definition-catalog-replay.js.map

package/dist/definition-catalog-replay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition-catalog-replay.js","sourceRoot":"","sources":["../src/definition-catalog-replay.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mDAAmD,EACnD,iDAAiD,GAElD,MAAM,yBAAyB,CAAC;AACjC,OAAO,EACL,+CAA+C,GAEhD,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,6CAA6C,GAE9C,MAAM,0BAA0B,CAAC;AAuBlC,MAAM,UAAU,gDAAgD,CAC9D,KAAyD;IAEzD,MAAM,eAAe,GAAG,+CAA+C,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;IAC/F,MAAM,OAAO,GAAG,iDAAiD,CAAC,eAAe,CAAC,WAAW,CAAC,CAAC;IAC/F,OAAO;QACL,eAAe;QACf,eAAe,EAAE,eAAe,CAAC,UAAU;QAC3C,OAAO;KACR,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,wDAAwD,CACtE,KAAiE;IAEjE,MAAM,aAAa,GAAG,6CAA6C,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IACzF,MAAM,OAAO,GAAG,iDAAiD,CAC/D,aAAa,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,oBAAoB,CAAC,CACzE,CAAC;IACF,OAAO;QACL,aAAa;QACb,eAAe,EAAE,aAAa,CAAC,UAAU;QACzC,OAAO;KACR,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,8DAA8D,CAC5E,MAA2D;IAE3D,OAAO;QACL,eAAe,EAAE;YACf,SAAS,EAAE,MAAM,CAAC,eAAe,CAAC,SAAS;YAC3C,eAAe,EAAE,MAAM,CAAC,eAAe,CAAC,eAAe;YACvD,UAAU,EAAE,MAAM,CAAC,eAAe,CAAC,UAAU;YAC7C,MAAM,EAAE,MAAM,CAAC,eAAe,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;gBACpD,UAAU,EAAE,KAAK,CAAC,UAAU;gBAC5B,MAAM,EAAE,KAAK,CAAC,MAAM;gBACpB,OAAO,EAAE,KAAK,CAAC,OAAO;aACvB,CAAC,CAAC;SACJ;QACD,eAAe,EAAE,MAAM,CAAC,eAAe;QACvC,OAAO,EAAE,mDAAmD,CAAC,MAAM,CAAC,OAAO,CAAC;KAC7E,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,sEAAsE,CACpF,MAAmE;IAEnE,OAAO;QACL,aAAa,EAAE;YACb,SAAS,EAAE,MAAM,CAAC,aAAa,CAAC,SAAS;YACzC,aAAa,EAAE,MAAM,CAAC,aAAa,CAAC,aAAa;YACjD,UAAU,EAAE,MAAM,CAAC,aAAa,CAAC,UAAU;YAC3C,MAAM,EAAE,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;gBAClD,UAAU,EAAE,KAAK,CAAC,UAAU;gBAC5B,MAAM,EAAE,KAAK,CAAC,MAAM;gBACpB,OAAO,EAAE,KAAK,CAAC,OAAO;aACvB,CAAC,CAAC;SACJ;QACD,eAAe,EAAE,MAAM,CAAC,eAAe;QACvC,OAAO,EAAE,mDAAmD,CAAC,MAAM,CAAC,OAAO,CAAC;KAC7E,CAAC;AACJ,CAAC","sourcesContent":["import {\n  buildAssistantWorkflowDefinitionCatalogTracePayload,\n  buildAssistantWorkflowSerializedDefinitionCatalog,\n  type AssistantWorkflowDefinitionCatalog,\n} from \"./definition-catalog.js\";\nimport {\n  parseAssistantWorkflowSerializedDefinitionLines,\n  type AssistantWorkflowSerializedDefinitionLinesParseResult,\n} from \"./definition-json.js\";\nimport {\n  parseAssistantWorkflowDefinitionManifestLines,\n  type AssistantWorkflowDefinitionManifestLinesParseResult,\n} from \"./definition-manifest.js\";\nimport type { AssistantWorkflowJsonValue } from \"./run-report-json.js\";\n\nexport type AssistantWorkflowDefinitionCatalogReplayLinesInput = {\n  definitionLines: string;\n};\n\nexport type AssistantWorkflowDefinitionCatalogReplayLinesResult = {\n  definitionParse: AssistantWorkflowSerializedDefinitionLinesParseResult;\n  parseErrorCount: number;\n  catalog: AssistantWorkflowDefinitionCatalog;\n};\n\nexport type AssistantWorkflowDefinitionManifestCatalogReplayLinesInput = {\n  manifestLines: string;\n};\n\nexport type AssistantWorkflowDefinitionManifestCatalogReplayLinesResult = {\n  manifestParse: AssistantWorkflowDefinitionManifestLinesParseResult;\n  parseErrorCount: number;\n  catalog: AssistantWorkflowDefinitionCatalog;\n};\n\nexport function runAssistantWorkflowDefinitionCatalogReplayLines(\n  input: AssistantWorkflowDefinitionCatalogReplayLinesInput,\n): AssistantWorkflowDefinitionCatalogReplayLinesResult {\n  const definitionParse = parseAssistantWorkflowSerializedDefinitionLines(input.definitionLines);\n  const catalog = buildAssistantWorkflowSerializedDefinitionCatalog(definitionParse.definitions);\n  return {\n    definitionParse,\n    parseErrorCount: definitionParse.errorCount,\n    catalog,\n  };\n}\n\nexport function runAssistantWorkflowDefinitionManifestCatalogReplayLines(\n  input: AssistantWorkflowDefinitionManifestCatalogReplayLinesInput,\n): AssistantWorkflowDefinitionManifestCatalogReplayLinesResult {\n  const manifestParse = parseAssistantWorkflowDefinitionManifestLines(input.manifestLines);\n  const catalog = buildAssistantWorkflowSerializedDefinitionCatalog(\n    manifestParse.manifests.map((manifest) => manifest.serializedDefinition),\n  );\n  return {\n    manifestParse,\n    parseErrorCount: manifestParse.errorCount,\n    catalog,\n  };\n}\n\nexport function buildAssistantWorkflowDefinitionCatalogReplayLinesTracePayload(\n  result: AssistantWorkflowDefinitionCatalogReplayLinesResult,\n): Record<string, AssistantWorkflowJsonValue> {\n  return {\n    definitionParse: {\n      lineCount: result.definitionParse.lineCount,\n      definitionCount: result.definitionParse.definitionCount,\n      errorCount: result.definitionParse.errorCount,\n      errors: result.definitionParse.errors.map((error) => ({\n        lineNumber: error.lineNumber,\n        reason: error.reason,\n        preview: error.preview,\n      })),\n    },\n    parseErrorCount: result.parseErrorCount,\n    catalog: buildAssistantWorkflowDefinitionCatalogTracePayload(result.catalog),\n  };\n}\n\nexport function buildAssistantWorkflowDefinitionManifestCatalogReplayLinesTracePayload(\n  result: AssistantWorkflowDefinitionManifestCatalogReplayLinesResult,\n): Record<string, AssistantWorkflowJsonValue> {\n  return {\n    manifestParse: {\n      lineCount: result.manifestParse.lineCount,\n      manifestCount: result.manifestParse.manifestCount,\n      errorCount: result.manifestParse.errorCount,\n      errors: result.manifestParse.errors.map((error) => ({\n        lineNumber: error.lineNumber,\n        reason: error.reason,\n        preview: error.preview,\n      })),\n    },\n    parseErrorCount: result.parseErrorCount,\n    catalog: buildAssistantWorkflowDefinitionCatalogTracePayload(result.catalog),\n  };\n}\n"]}