@memberjunction/ai-agents 6.1.0-edge.6 → 6.1.0

package/dist/index.d.ts

@@ -73,4 +73,8 @@ export * from './realtime/agent-media-library.js';
 export * from './realtime/realtime-recording-capture.js';
 export * from './realtime/realtime-recording-store.js';
 export { RerankerService, RerankerConfiguration, parseRerankerConfiguration, RerankServiceResult, RerankObservabilityOptions, LLMReranker, } from '@memberjunction/ai-reranker';
+export * from './native-tools/action-tool-builder.js';
+export * from './native-tools/dual-channel.js';
+export * from './native-tools/control-tools.js';
+export * from './native-tools/tool-result-turns.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wCAAwC,CAAC;AACvD,cAAc,wCAAwC,CAAC;AACvD,cAAc,cAAc,CAAC;AAC7B,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,iCAAiC,CAAC;AAChD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wCAAwC,CAAC;AACvD,cAAc,YAAY,CAAC;AAC3B,cAAc,uBAAuB,CAAC;AACtC,cAAc,0CAA0C,CAAC;AACzD,cAAc,kCAAkC,CAAC;AACjD,cAAc,kCAAkC,CAAC;AACjD,cAAc,iCAAiC,CAAC;AAChD,cAAc,mCAAmC,CAAC;AAClD,cAAc,kCAAkC,CAAC;AACjD,cAAc,6CAA6C,CAAC;AAC5D,cAAc,iCAAiC,CAAC;AAChD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,kBAAkB,CAAC;AACjC,cAAc,mCAAmC,CAAC;AAClD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oCAAoC,CAAC;AACnD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,wCAAwC,CAAC;AACvD,cAAc,oCAAoC,CAAC;AAKnD,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AACrI,cAAc,4CAA4C,CAAC;AAC3D,cAAc,oCAAoC,CAAC;AACnD,cAAc,uCAAuC,CAAC;AACtD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,yCAAyC,CAAC;AACxD,cAAc,sCAAsC,CAAC;AACrD,cAAc,0CAA0C,CAAC;AACzD,cAAc,mCAAmC,CAAC;AAClD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,iCAAiC,CAAC;AAChD,cAAc,iDAAiD,CAAC;AAChE,cAAc,gCAAgC,CAAC;AAC/C,cAAc,uCAAuC,CAAC;AACtD,cAAc,qCAAqC,CAAC;AAGpD,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,0BAA0B,EAC1B,mBAAmB,EACnB,0BAA0B,EAC1B,WAAW,GACZ,MAAM,6BAA6B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wCAAwC,CAAC;AACvD,cAAc,wCAAwC,CAAC;AACvD,cAAc,cAAc,CAAC;AAC7B,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,iCAAiC,CAAC;AAChD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wCAAwC,CAAC;AACvD,cAAc,YAAY,CAAC;AAC3B,cAAc,uBAAuB,CAAC;AACtC,cAAc,0CAA0C,CAAC;AACzD,cAAc,kCAAkC,CAAC;AACjD,cAAc,kCAAkC,CAAC;AACjD,cAAc,iCAAiC,CAAC;AAChD,cAAc,mCAAmC,CAAC;AAClD,cAAc,kCAAkC,CAAC;AACjD,cAAc,6CAA6C,CAAC;AAC5D,cAAc,iCAAiC,CAAC;AAChD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,kBAAkB,CAAC;AACjC,cAAc,mCAAmC,CAAC;AAClD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oCAAoC,CAAC;AACnD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,wCAAwC,CAAC;AACvD,cAAc,oCAAoC,CAAC;AAKnD,OAAO,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AACrI,cAAc,4CAA4C,CAAC;AAC3D,cAAc,oCAAoC,CAAC;AACnD,cAAc,uCAAuC,CAAC;AACtD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,yCAAyC,CAAC;AACxD,cAAc,sCAAsC,CAAC;AACrD,cAAc,0CAA0C,CAAC;AACzD,cAAc,mCAAmC,CAAC;AAClD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,iCAAiC,CAAC;AAChD,cAAc,iDAAiD,CAAC;AAChE,cAAc,gCAAgC,CAAC;AAC/C,cAAc,uCAAuC,CAAC;AACtD,cAAc,qCAAqC,CAAC;AAGpD,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,0BAA0B,EAC1B,mBAAmB,EACnB,0BAA0B,EAC1B,WAAW,GACZ,MAAM,6BAA6B,CAAC;AACrC,cAAc,oCAAoC,CAAC;AACnD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kCAAkC,CAAC"}

package/dist/index.js

@@ -78,4 +78,8 @@ export * from './realtime/realtime-recording-capture.js';
 export * from './realtime/realtime-recording-store.js';
 // Re-export from ai-reranker for backward compatibility
 export { RerankerService, parseRerankerConfiguration, LLMReranker, } from '@memberjunction/ai-reranker';
+export * from './native-tools/action-tool-builder.js';
+export * from './native-tools/dual-channel.js';
+export * from './native-tools/control-tools.js';
+export * from './native-tools/tool-result-turns.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wCAAwC,CAAC;AACvD,cAAc,wCAAwC,CAAC;AACvD,cAAc,cAAc,CAAC;AAC7B,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,iCAAiC,CAAC;AAChD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wCAAwC,CAAC;AACvD,cAAc,YAAY,CAAC;AAC3B,cAAc,uBAAuB,CAAC;AACtC,cAAc,0CAA0C,CAAC;AACzD,cAAc,kCAAkC,CAAC;AACjD,cAAc,kCAAkC,CAAC;AACjD,cAAc,iCAAiC,CAAC;AAChD,cAAc,mCAAmC,CAAC;AAClD,cAAc,kCAAkC,CAAC;AACjD,cAAc,6CAA6C,CAAC;AAC5D,cAAc,iCAAiC,CAAC;AAChD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,kBAAkB,CAAC;AACjC,cAAc,mCAAmC,CAAC;AAClD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oCAAoC,CAAC;AACnD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,wCAAwC,CAAC;AACvD,cAAc,oCAAoC,CAAC;AACnD,4FAA4F;AAC5F,8FAA8F;AAC9F,2FAA2F;AAC3F,8BAA8B;AAC9B,OAAO,EAAE,kBAAkB,EAAkE,MAAM,iCAAiC,CAAC;AACrI,cAAc,4CAA4C,CAAC;AAC3D,cAAc,oCAAoC,CAAC;AACnD,cAAc,uCAAuC,CAAC;AACtD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,yCAAyC,CAAC;AACxD,cAAc,sCAAsC,CAAC;AACrD,cAAc,0CAA0C,CAAC;AACzD,cAAc,mCAAmC,CAAC;AAClD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,iCAAiC,CAAC;AAChD,cAAc,iDAAiD,CAAC;AAChE,cAAc,gCAAgC,CAAC;AAC/C,cAAc,uCAAuC,CAAC;AACtD,cAAc,qCAAqC,CAAC;AAEpD,wDAAwD;AACxD,OAAO,EACL,eAAe,EAEf,0BAA0B,EAG1B,WAAW,GACZ,MAAM,6BAA6B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wCAAwC,CAAC;AACvD,cAAc,wCAAwC,CAAC;AACvD,cAAc,cAAc,CAAC;AAC7B,cAAc,gCAAgC,CAAC;AAC/C,cAAc,sBAAsB,CAAC;AACrC,cAAc,6BAA6B,CAAC;AAC5C,cAAc,iCAAiC,CAAC;AAChD,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,eAAe,CAAC;AAC9B,cAAc,wBAAwB,CAAC;AACvC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,uBAAuB,CAAC;AACtC,cAAc,iCAAiC,CAAC;AAChD,cAAc,2BAA2B,CAAC;AAC1C,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,wCAAwC,CAAC;AACvD,cAAc,YAAY,CAAC;AAC3B,cAAc,uBAAuB,CAAC;AACtC,cAAc,0CAA0C,CAAC;AACzD,cAAc,kCAAkC,CAAC;AACjD,cAAc,kCAAkC,CAAC;AACjD,cAAc,iCAAiC,CAAC;AAChD,cAAc,mCAAmC,CAAC;AAClD,cAAc,kCAAkC,CAAC;AACjD,cAAc,6CAA6C,CAAC;AAC5D,cAAc,iCAAiC,CAAC;AAChD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,yBAAyB,CAAC;AACxC,cAAc,0BAA0B,CAAC;AACzC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,sBAAsB,CAAC;AACrC,cAAc,0BAA0B,CAAC;AACzC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,wBAAwB,CAAC;AACvC,cAAc,uBAAuB,CAAC;AACtC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,kBAAkB,CAAC;AACjC,cAAc,mCAAmC,CAAC;AAClD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,oCAAoC,CAAC;AACnD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,wCAAwC,CAAC;AACvD,cAAc,oCAAoC,CAAC;AACnD,4FAA4F;AAC5F,8FAA8F;AAC9F,2FAA2F;AAC3F,8BAA8B;AAC9B,OAAO,EAAE,kBAAkB,EAAkE,MAAM,iCAAiC,CAAC;AACrI,cAAc,4CAA4C,CAAC;AAC3D,cAAc,oCAAoC,CAAC;AACnD,cAAc,uCAAuC,CAAC;AACtD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,yCAAyC,CAAC;AACxD,cAAc,sCAAsC,CAAC;AACrD,cAAc,0CAA0C,CAAC;AACzD,cAAc,mCAAmC,CAAC;AAClD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,iCAAiC,CAAC;AAChD,cAAc,iDAAiD,CAAC;AAChE,cAAc,gCAAgC,CAAC;AAC/C,cAAc,uCAAuC,CAAC;AACtD,cAAc,qCAAqC,CAAC;AAEpD,wDAAwD;AACxD,OAAO,EACL,eAAe,EAEf,0BAA0B,EAG1B,WAAW,GACZ,MAAM,6BAA6B,CAAC;AACrC,cAAc,oCAAoC,CAAC;AACnD,cAAc,6BAA6B,CAAC;AAC5C,cAAc,8BAA8B,CAAC;AAC7C,cAAc,kCAAkC,CAAC"}

package/dist/native-tools/action-tool-builder.d.ts

@@ -0,0 +1,92 @@
+/**
+ * @fileoverview Maps MJ Actions onto native tool declarations (plan §8.2).
+ * @module @memberjunction/ai-agents
+ */
+import type { ChatTool } from '@memberjunction/ai';
+import type { MJActionParamEntity } from '@memberjunction/core-entities';
+import type { MJActionEntityExtended } from '@memberjunction/actions-base';
+/** One Action, and the provider-legal tool name it was declared under. */
+export interface ActionToolBinding {
+    /** Discriminant shared with the control-flow bindings in `control-tools.ts`. */
+    kind: 'action';
+    /** The sanitized name the model calls. */
+    toolName: string;
+    /** The Action the framework dispatches when that name comes back. */
+    action: MJActionEntityExtended;
+    tool: ChatTool;
+}
+/**
+ * A built tool set plus the reverse map from tool name back to Action.
+ *
+ * The reverse map is not a convenience — a tool call arrives as a sanitized string, and without it
+ * the framework cannot tell which Action to dispatch. It is built alongside the declarations so
+ * the two can never disagree.
+ */
+export interface ActionToolSet {
+    tools: ChatTool[];
+    /** Keyed by the sanitized tool name. */
+    byToolName: Map<string, ActionToolBinding>;
+}
+/**
+ * Ceiling on a tool's `description` — an OPERATING POINT, not a provider limit.
+ *
+ * No tool-capable vendor enforces a cap anywhere near here: OpenAI (gpt-5.6-luna), Cerebras
+ * (gpt-oss-120b) and Gemini (3.7 Flash) each accepted an 8,000-character description on a live
+ * call. The number is chosen from measurement instead. A comparison run used the
+ * same 1,026-observation corpus at 1,024 and at 4,096 (results doc §10–§11): at 1,024 — where a
+ * large Action degrades to output names and result codes with descriptions trimmed — native
+ * selection accuracy improved on two of three models (+6.3pp Gemini, +11.3pp GPT 5.6-luna). At
+ * 4,096, with every description in full, both gains disappeared, GPT-OSS-120B fell a further 5pp,
+ * its prompt grew by ~700 tokens per call, and it began returning no action at all on cases it
+ * had handled. Same-case comparison: −10 correct turns net.
+ *
+ * So the names and codes are what discriminates; the sentences around them are dilution the
+ * smallest model pays for most. One A/B at N=3 is directional rather than definitive (envelope-arm
+ * run-to-run noise is ±2–3pp), and a per-provider ceiling is the obvious follow-up — but until
+ * someone measures that, compact is the point the data favours. The detail-degradation below is
+ * therefore the NORMAL path for large Actions, not a safety net.
+ */
+export declare const MAX_TOOL_DESCRIPTION_LENGTH = 1024;
+/**
+ * Sanitizes an Action name into a provider-legal tool name (§8.2: `[a-zA-Z0-9_-]`, ≤64 chars).
+ *
+ * "Run Ad-hoc Query" → "run_ad_hoc_query". Deterministic, because a call has to resolve back to
+ * the Action that produced it; the collision check lives in {@link buildActionToolSet} rather than
+ * here, so this stays a pure function of the name.
+ */
+export declare function sanitizeToolName(actionName: string): string;
+/**
+ * Builds the `ChatTool` declaration for one Action.
+ *
+ * Only `Input` and `Both` params are declared: an `Output` param is something the Action returns,
+ * and declaring it would invite the model to supply it.
+ */
+export declare function buildToolFromAction(action: MJActionEntityExtended, params: readonly MJActionParamEntity[]): ChatTool;
+/**
+ * Builds the full tool set for an agent's available Actions, with the reverse map.
+ *
+ * **A post-sanitization collision is a hard error** (§8.2), not a silent disambiguation. Two
+ * Actions whose names differ only by punctuation would otherwise produce one tool name, and every
+ * call to it would dispatch whichever Action happened to be registered last — a routing bug that
+ * looks like a model error and would be found, if at all, by someone reading eval failures.
+ * Failing at build time turns it into a metadata problem with a name attached.
+ */
+export declare function buildActionToolSet(actions: readonly MJActionEntityExtended[], paramsByActionId: ReadonlyMap<string, readonly MJActionParamEntity[]>): ActionToolSet;
+/** The two fields of an `MJ: AI Agent Actions` row that declaration control reads. */
+export interface AgentActionDeclarationRow {
+    ActionID: string | null;
+    DeclareAsNativeTool: boolean;
+}
+/**
+ * Removes the Actions an agent has chosen not to declare as native tools.
+ *
+ * Only an explicit `DeclareAsNativeTool = false` on the agent-action row excludes an action. An
+ * action with no row — one granted through a skill at runtime — stays declarable, because the
+ * default is to declare. Pure so the rule is testable without the engine; `BaseAgent` supplies the
+ * rows from `AIEngine.Instance.AgentActions`.
+ *
+ * Note the consequence the design accepts: in native mode the prose catalog is not rendered, so an
+ * action removed here is unreachable on that turn, not merely de-emphasised.
+ */
+export declare function filterDeclarableActions(actions: readonly MJActionEntityExtended[], agentActionRows: ReadonlyArray<AgentActionDeclarationRow>): MJActionEntityExtended[];
+//# sourceMappingURL=action-tool-builder.d.ts.map

package/dist/native-tools/action-tool-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-tool-builder.d.ts","sourceRoot":"","sources":["../../src/native-tools/action-tool-builder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAE3E,0EAA0E;AAC1E,MAAM,WAAW,iBAAiB;IAC9B,gFAAgF;IAChF,IAAI,EAAE,QAAQ,CAAC;IACf,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,MAAM,EAAE,sBAAsB,CAAC;IAC/B,IAAI,EAAE,QAAQ,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC1B,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,wCAAwC;IACxC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC9C;AAKD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,2BAA2B,OAAO,CAAC;AAKhD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAO3D;AAwHD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,sBAAsB,EAAE,MAAM,EAAE,SAAS,mBAAmB,EAAE,GAAG,QAAQ,CA4BpH;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAC9B,OAAO,EAAE,SAAS,sBAAsB,EAAE,EAC1C,gBAAgB,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,mBAAmB,EAAE,CAAC,GACtE,aAAa,CAqBf;AAED,sFAAsF;AACtF,MAAM,WAAW,yBAAyB;IACtC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,mBAAmB,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACnC,OAAO,EAAE,SAAS,sBAAsB,EAAE,EAC1C,eAAe,EAAE,aAAa,CAAC,yBAAyB,CAAC,GAC1D,sBAAsB,EAAE,CAO1B"}

package/dist/native-tools/action-tool-builder.js

@@ -0,0 +1,226 @@
+/**
+ * @fileoverview Maps MJ Actions onto native tool declarations (plan §8.2).
+ * @module @memberjunction/ai-agents
+ */
+/** Providers cap tool names at 64 characters. */
+const MAX_TOOL_NAME_LENGTH = 64;
+/**
+ * Ceiling on a tool's `description` — an OPERATING POINT, not a provider limit.
+ *
+ * No tool-capable vendor enforces a cap anywhere near here: OpenAI (gpt-5.6-luna), Cerebras
+ * (gpt-oss-120b) and Gemini (3.7 Flash) each accepted an 8,000-character description on a live
+ * call. The number is chosen from measurement instead. A comparison run used the
+ * same 1,026-observation corpus at 1,024 and at 4,096 (results doc §10–§11): at 1,024 — where a
+ * large Action degrades to output names and result codes with descriptions trimmed — native
+ * selection accuracy improved on two of three models (+6.3pp Gemini, +11.3pp GPT 5.6-luna). At
+ * 4,096, with every description in full, both gains disappeared, GPT-OSS-120B fell a further 5pp,
+ * its prompt grew by ~700 tokens per call, and it began returning no action at all on cases it
+ * had handled. Same-case comparison: −10 correct turns net.
+ *
+ * So the names and codes are what discriminates; the sentences around them are dilution the
+ * smallest model pays for most. One A/B at N=3 is directional rather than definitive (envelope-arm
+ * run-to-run noise is ±2–3pp), and a per-provider ceiling is the obvious follow-up — but until
+ * someone measures that, compact is the point the data favours. The detail-degradation below is
+ * therefore the NORMAL path for large Actions, not a safety net.
+ */
+export const MAX_TOOL_DESCRIPTION_LENGTH = 1024;
+/** Per-item description lengths tried in order until the whole description fits the cap. */
+const DESCRIPTION_DETAIL_LEVELS = [160, 110, 70, 40, 0];
+/**
+ * Sanitizes an Action name into a provider-legal tool name (§8.2: `[a-zA-Z0-9_-]`, ≤64 chars).
+ *
+ * "Run Ad-hoc Query" → "run_ad_hoc_query". Deterministic, because a call has to resolve back to
+ * the Action that produced it; the collision check lives in {@link buildActionToolSet} rather than
+ * here, so this stays a pure function of the name.
+ */
+export function sanitizeToolName(actionName) {
+    return actionName
+        .trim()
+        .replace(/[^a-zA-Z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '')
+        .toLowerCase()
+        .slice(0, MAX_TOOL_NAME_LENGTH);
+}
+/**
+ * Maps one param's `ValueType` onto a JSON Schema fragment (§8.2 table).
+ *
+ * `ActionParam.ValueType` distinguishes only five coarse kinds, so this mapping is lossy by
+ * construction and the prose `Description` carries the real type — exactly as the rendered action
+ * catalog does today. Two choices here were settled by measurement rather than by reasoning
+ * Measured:
+ *
+ * - **`Scalar` emits a union type.** It appears to violate the cross-provider common subset —
+ *   OpenAPI 3.0, which Gemini's classic function declarations follow, has no union `type` — but it
+ *   measured clean on every provider tested, so the plan's literal mapping stands.
+ * - **Everything else emits `string`, not `object`.** §8.2 originally specified `object` for the
+ *   opaque kinds, reasoning it was "exact parity with the prose catalog". It is not:
+ *   `Run Ad-hoc Query.Query` is `ValueType: 'Other'` but holds SQL text, and typing it as an
+ *   object made models emit `Query: {}` on 40% of calls — well-formed, dispatchable and useless,
+ *   which no well-formedness check catches. Switching to `string` took usable arguments from
+ *   60% to 100% on the same prompts. The structural type beats the prose description whenever the
+ *   two disagree, so it must not disagree.
+ */
+function schemaForValueType(valueType) {
+    return valueType === 'Scalar'
+        ? { type: ['string', 'number', 'boolean'] }
+        : { type: 'string' };
+}
+/**
+ * Folds the metadata that has nowhere structural to go into the property description.
+ *
+ * Dropping `DefaultValue` would make the tool strictly less informative than the prose catalog it
+ * replaces, which is the one thing this mapping must never be.
+ */
+function describeParam(param) {
+    const parts = [];
+    if (param.Description) {
+        parts.push(param.Description.trim());
+    }
+    if (param.DefaultValue) {
+        parts.push(`Default: ${param.DefaultValue}.`);
+    }
+    return parts.join(' ');
+}
+/** A single clause of the description, trimmed to the current detail level. */
+function clip(text, max) {
+    const t = (text ?? '').replace(/\s+/g, ' ').trim();
+    if (max === 0 || t.length === 0) {
+        return '';
+    }
+    return t.length <= max ? t : `${t.slice(0, max - 1).trimEnd()}…`;
+}
+/**
+ * Composes the tool description at one level of detail. Sections with nothing to say are omitted
+ * rather than emitted empty, so an Action with no outputs or result codes reads exactly as before.
+ */
+function composeDescription(action, outputs, codes, detail) {
+    // §8.2: prescriptive about WHEN to call, not merely what the tool does — it measurably
+    // improves should-call rates, and an Action's Description is rarely phrased that way.
+    const lines = [`Call this when you need to: ${(action.Description ?? action.Name).trim()}`];
+    if (outputs.length > 0) {
+        lines.push(`Returns: ${outputs.map((p) => {
+            const d = clip(p.Description, detail);
+            return d ? `${p.Name} (${d})` : p.Name;
+        }).join(', ')}`);
+    }
+    if (codes.length > 0) {
+        lines.push(`Results: ${codes.map((rc) => {
+            const d = clip(rc.Description, detail);
+            // Mirror the prose catalog's convention, and skip a description that merely restates the code.
+            const restates = d.toLowerCase() === rc.ResultCode.toLowerCase();
+            return `${rc.ResultCode} ${rc.IsSuccess ? '✓' : '✗'}${d && !restates ? ` ${d}` : ''}`;
+        }).join(' · ')}`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Builds the tool's description — everything the prose action catalog says about an Action that
+ * has no structural home in the declaration.
+ *
+ * **Why outputs and result codes are here.** `formatActionDetails`, the prose catalog the envelope
+ * path renders, gives the model five things per action: name, description, inputs, outputs and
+ * result codes. The first version of this builder gave it three — and measurement showed the
+ * consequence. The confusion pairs were identical in both arms (`Run Ad-hoc Query` mistaken for
+ * `Search Query Catalog` on every model), but the native arm confused them MORE: P(right tool |
+ * acted) fell 82% → 70% on GPT-OSS-120B. For that pair the outputs and result codes are the
+ * discriminator — `Search Query Catalog` carries `NO_MATCHES ✓ … Proceed with ad-hoc SQL`, which
+ * states the relationship between the two actions in one line. A model reading prose saw it; a
+ * model reading the declaration did not. The rule this file already stated — never less
+ * informative than the prose catalog — was being broken by two sections out of five.
+ *
+ * **Why the detail degrades instead of the cap truncating.** Providers cap the description; some
+ * Actions have nine result codes with sentence-long explanations. A blind `slice` would keep the
+ * first few codes in full and drop the rest entirely, which is the worst trade — names and codes
+ * are the cheap, high-information part. So per-item descriptions shrink through
+ * {@link DESCRIPTION_DETAIL_LEVELS} until the whole thing fits, and only at detail 0 (names and
+ * codes alone) does a hard trim apply as a last resort.
+ */
+function describeTool(action, params) {
+    const outputs = params.filter((p) => p.Type === 'Output' || p.Type === 'Both');
+    // Harness stand-ins may build an Action literal without the related-record collection.
+    const codes = action.ResultCodes?.Items ?? [];
+    for (const detail of DESCRIPTION_DETAIL_LEVELS) {
+        const text = composeDescription(action, outputs, codes, detail);
+        if (text.length <= MAX_TOOL_DESCRIPTION_LENGTH) {
+            return text;
+        }
+    }
+    return `${composeDescription(action, outputs, codes, 0).slice(0, MAX_TOOL_DESCRIPTION_LENGTH - 1).trimEnd()}…`;
+}
+/**
+ * Builds the `ChatTool` declaration for one Action.
+ *
+ * Only `Input` and `Both` params are declared: an `Output` param is something the Action returns,
+ * and declaring it would invite the model to supply it.
+ */
+export function buildToolFromAction(action, params) {
+    const properties = {};
+    const required = [];
+    for (const param of params) {
+        if (param.Type !== 'Input' && param.Type !== 'Both') {
+            continue;
+        }
+        const element = schemaForValueType(param.ValueType);
+        // IsArray wraps the element schema rather than replacing it (§8.2).
+        const schema = param.IsArray ? { type: 'array', items: element } : element;
+        const description = describeParam(param);
+        properties[param.Name] = description ? { ...schema, description } : schema;
+        if (param.IsRequired) {
+            required.push(param.Name);
+        }
+    }
+    const inputSchema = { type: 'object', properties };
+    if (required.length > 0) {
+        inputSchema.required = required;
+    }
+    return {
+        name: sanitizeToolName(action.Name),
+        description: describeTool(action, params),
+        inputSchema
+    };
+}
+/**
+ * Builds the full tool set for an agent's available Actions, with the reverse map.
+ *
+ * **A post-sanitization collision is a hard error** (§8.2), not a silent disambiguation. Two
+ * Actions whose names differ only by punctuation would otherwise produce one tool name, and every
+ * call to it would dispatch whichever Action happened to be registered last — a routing bug that
+ * looks like a model error and would be found, if at all, by someone reading eval failures.
+ * Failing at build time turns it into a metadata problem with a name attached.
+ */
+export function buildActionToolSet(actions, paramsByActionId) {
+    const byToolName = new Map();
+    const tools = [];
+    for (const action of actions) {
+        const tool = buildToolFromAction(action, paramsByActionId.get(action.ID) ?? []);
+        const existing = byToolName.get(tool.name);
+        if (existing) {
+            throw new Error(`Action tool name collision: '${existing.action.Name}' and '${action.Name}' both sanitize to `
+                + `'${tool.name}'. Rename one of the Actions — a tool call cannot be resolved back to an Action otherwise.`);
+        }
+        if (tool.name.length === 0) {
+            throw new Error(`Action '${action.Name}' sanitizes to an empty tool name — it must contain at least one alphanumeric character.`);
+        }
+        byToolName.set(tool.name, { kind: 'action', toolName: tool.name, action, tool });
+        tools.push(tool);
+    }
+    return { tools, byToolName };
+}
+/**
+ * Removes the Actions an agent has chosen not to declare as native tools.
+ *
+ * Only an explicit `DeclareAsNativeTool = false` on the agent-action row excludes an action. An
+ * action with no row — one granted through a skill at runtime — stays declarable, because the
+ * default is to declare. Pure so the rule is testable without the engine; `BaseAgent` supplies the
+ * rows from `AIEngine.Instance.AgentActions`.
+ *
+ * Note the consequence the design accepts: in native mode the prose catalog is not rendered, so an
+ * action removed here is unreachable on that turn, not merely de-emphasised.
+ */
+export function filterDeclarableActions(actions, agentActionRows) {
+    const excluded = new Set(agentActionRows
+        .filter((row) => row.DeclareAsNativeTool === false && row.ActionID)
+        .map((row) => row.ActionID.toLowerCase()));
+    return actions.filter((action) => !excluded.has(action.ID.toLowerCase()));
+}
+//# sourceMappingURL=action-tool-builder.js.map

package/dist/native-tools/action-tool-builder.js.map

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

package/dist/native-tools/control-tools.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview Control-flow tools for the implicit protocol (spec §2.2, §4): one tool per
+ * sub-agent, `payload_change_request`, `ask_user`. Built beside the Action tools so the reverse map
+ * resolves every call the model can make.
+ *
+ * The agent declares these without knowing which model will answer. The prompt runner keeps them
+ * only when the selected model's `LLM.NativeControlFlow` resolves to `'implicit'` and strips them
+ * otherwise — see `AIPromptParams.controlFlowToolNames`.
+ * @module @memberjunction/ai-agents
+ */
+import type { ChatTool } from '@memberjunction/ai';
+import type { MJAIAgentEntityExtended } from '@memberjunction/ai-core-plus';
+import { type ActionToolBinding, type ActionToolSet } from './action-tool-builder.js';
+export declare const PAYLOAD_CHANGE_TOOL = "payload_change_request";
+export declare const ASK_USER_TOOL = "ask_user";
+export declare const SUB_AGENT_TOOL_PREFIX = "delegate_to_";
+/** The fixed control tools. Sub-agent tools are recognised by {@link SUB_AGENT_TOOL_PREFIX}. */
+export declare const NATIVE_CONTROL_TOOL_NAMES: readonly string[];
+/** Every tool the agent can declare, and what a call to it means. Discriminated on `kind`. */
+export type NativeToolBinding = ActionToolBinding | {
+    kind: 'subAgent';
+    toolName: string;
+    agent: MJAIAgentEntityExtended;
+    tool: ChatTool;
+} | {
+    kind: 'payloadChange';
+    toolName: string;
+    tool: ChatTool;
+} | {
+    kind: 'askUser';
+    toolName: string;
+    tool: ChatTool;
+};
+export interface NativeToolSet {
+    tools: ChatTool[];
+    /** Keyed by the declared tool name. */
+    byToolName: Map<string, NativeToolBinding>;
+    /** Every declared name that is NOT an Action — what the runner strips for hybrid models. */
+    controlToolNames: string[];
+}
+/** `payload_change_request` — a state write that continues the loop (spec §3). */
+export declare function buildPayloadChangeTool(): ChatTool;
+/** `ask_user` — the one explicit control tool: the run pauses as `Chat` / `AwaitingFeedback` (spec §1). */
+export declare function buildAskUserTool(): ChatTool;
+/** One tool per sub-agent: `delegate_to_<sanitized name>`, described by the agent's own description. */
+export declare function buildSubAgentTool(agent: MJAIAgentEntityExtended): ChatTool;
+/**
+ * Actions, then sub-agents, then the fixed control tools — one reverse map for all of them.
+ * Collisions and reserved-name clashes are hard errors, exactly as Action/Action collisions are.
+ */
+export declare function buildNativeToolSet(actionSet: ActionToolSet, subAgents: readonly MJAIAgentEntityExtended[]): NativeToolSet;
+//# sourceMappingURL=control-tools.d.ts.map

package/dist/native-tools/control-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"control-tools.d.ts","sourceRoot":"","sources":["../../src/native-tools/control-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAC5E,OAAO,EAAiD,KAAK,iBAAiB,EAAE,KAAK,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAElI,eAAO,MAAM,mBAAmB,2BAA2B,CAAC;AAC5D,eAAO,MAAM,aAAa,aAAa,CAAC;AACxC,eAAO,MAAM,qBAAqB,iBAAiB,CAAC;AACpD,gGAAgG;AAChG,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAAyC,CAAC;AAIjG,8FAA8F;AAC9F,MAAM,MAAM,iBAAiB,GACvB,iBAAiB,GACjB;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,uBAAuB,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GACtF;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC;AAE5D,MAAM,WAAW,aAAa;IAC1B,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,uCAAuC;IACvC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;IAC3C,4FAA4F;IAC5F,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC9B;AAID,kFAAkF;AAClF,wBAAgB,sBAAsB,IAAI,QAAQ,CAsBjD;AAED,2GAA2G;AAC3G,wBAAgB,gBAAgB,IAAI,QAAQ,CA8B3C;AAED,wGAAwG;AACxG,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,uBAAuB,GAAG,QAAQ,CAc1E;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,aAAa,EAAE,SAAS,EAAE,SAAS,uBAAuB,EAAE,GAAG,aAAa,CA6BzH"}

package/dist/native-tools/control-tools.js

@@ -0,0 +1,113 @@
+import { sanitizeToolName, MAX_TOOL_DESCRIPTION_LENGTH } from './action-tool-builder.js';
+export const PAYLOAD_CHANGE_TOOL = 'payload_change_request';
+export const ASK_USER_TOOL = 'ask_user';
+export const SUB_AGENT_TOOL_PREFIX = 'delegate_to_';
+/** The fixed control tools. Sub-agent tools are recognised by {@link SUB_AGENT_TOOL_PREFIX}. */
+export const NATIVE_CONTROL_TOOL_NAMES = [PAYLOAD_CHANGE_TOOL, ASK_USER_TOOL];
+/** Providers cap tool names at 64 characters. */
+const MAX_TOOL_NAME_LENGTH = 64;
+const clip = (text, max) => (text.length <= max ? text : `${text.slice(0, max - 1)}…`);
+/** `payload_change_request` — a state write that continues the loop (spec §3). */
+export function buildPayloadChangeTool() {
+    const section = (what) => ({ type: 'object', description: what });
+    return {
+        name: PAYLOAD_CHANGE_TOOL,
+        description: clip('Write to the shared payload. Call this when your work has produced results the payload contract says to store ' +
+            '(findings, code, results, drafts). Use newElements for keys that do not exist yet, updateElements for surgical ' +
+            'changes to keys that do (only the changing parts; arrays keep unchanged items as {}), replaceElements to swap a whole ' +
+            'object, removeElements to delete keys. The change is applied and the loop continues — when the task is then finished, ' +
+            'reply in plain text. Do not call this to report progress; only to store data.', MAX_TOOL_DESCRIPTION_LENGTH),
+        inputSchema: {
+            type: 'object',
+            properties: {
+                newElements: section('Keys and values to ADD that are not in the payload yet.'),
+                updateElements: section('Existing keys to UPDATE — only the parts that change.'),
+                replaceElements: section('Existing objects to REPLACE entirely.'),
+                removeElements: section('Keys to REMOVE (value ignored).'),
+                reasoning: { type: 'string', description: 'One sentence on why this change.' }
+            },
+            required: []
+        }
+    };
+}
+/** `ask_user` — the one explicit control tool: the run pauses as `Chat` / `AwaitingFeedback` (spec §1). */
+export function buildAskUserTool() {
+    return {
+        name: ASK_USER_TOOL,
+        description: clip('Stop and ask the user. Use only when you need something only the user can give you — a choice between ' +
+            'options only they can make, a value that exists nowhere in the payload, conversation or tools, permission. ' +
+            'If a declared sub-agent or an Action can supply what you need, use it instead of asking. The run pauses ' +
+            'until the user answers. Do NOT use this to report results or say you are done: for that, reply in plain ' +
+            'text with no tool call.', MAX_TOOL_DESCRIPTION_LENGTH),
+        inputSchema: {
+            type: 'object',
+            properties: {
+                message: { type: 'string', description: 'The question or request for the user, in plain language.' },
+                responseForm: {
+                    type: 'object',
+                    description: 'Optional. A structured form for the answer — the same shape as `responseForm` in the Response Forms ' +
+                        'section of your instructions: { title?, description?, submitLabel?, questions: [{ id, label, type, … }] }. ' +
+                        'Use it when the user should pick from options or fill in fields; omit it for a free-text question.',
+                    properties: {
+                        title: { type: 'string' },
+                        description: { type: 'string' },
+                        submitLabel: { type: 'string' },
+                        questions: { type: 'array', items: { type: 'object' } }
+                    }
+                }
+            },
+            required: ['message']
+        }
+    };
+}
+/** One tool per sub-agent: `delegate_to_<sanitized name>`, described by the agent's own description. */
+export function buildSubAgentTool(agent) {
+    const name = `${SUB_AGENT_TOOL_PREFIX}${sanitizeToolName(agent.Name)}`.slice(0, MAX_TOOL_NAME_LENGTH);
+    return {
+        name,
+        description: clip(`Delegate to the ${agent.Name} sub-agent. ${agent.Description ?? ''}`.trim(), MAX_TOOL_DESCRIPTION_LENGTH),
+        inputSchema: {
+            type: 'object',
+            properties: {
+                message: { type: 'string', description: 'Instructions for the sub-agent — what to do. Not the payload; it receives that separately.' },
+                terminateAfter: { type: 'boolean', description: 'true to end your own run when the sub-agent finishes; false (default) to continue with its result.' }
+            },
+            required: ['message']
+        }
+    };
+}
+/**
+ * Actions, then sub-agents, then the fixed control tools — one reverse map for all of them.
+ * Collisions and reserved-name clashes are hard errors, exactly as Action/Action collisions are.
+ */
+export function buildNativeToolSet(actionSet, subAgents) {
+    const byToolName = new Map(actionSet.byToolName);
+    const tools = [...actionSet.tools];
+    const controlToolNames = [];
+    for (const reserved of NATIVE_CONTROL_TOOL_NAMES) {
+        const clash = actionSet.byToolName.get(reserved);
+        if (clash) {
+            throw new Error(`Action '${clash.action.Name}' sanitizes to '${reserved}', which is a reserved control-tool name. Rename the Action.`);
+        }
+    }
+    for (const agent of subAgents) {
+        const tool = buildSubAgentTool(agent);
+        const existing = byToolName.get(tool.name);
+        if (existing) {
+            const other = existing.kind === 'action' ? `Action '${existing.action.Name}'`
+                : existing.kind === 'subAgent' ? `sub-agent '${existing.agent.Name}'` : `'${existing.toolName}'`;
+            throw new Error(`Tool name collision: sub-agent '${agent.Name}' and ${other} both declare '${tool.name}'. Rename one.`);
+        }
+        byToolName.set(tool.name, { kind: 'subAgent', toolName: tool.name, agent, tool });
+        tools.push(tool);
+        controlToolNames.push(tool.name);
+    }
+    const payload = buildPayloadChangeTool();
+    const ask = buildAskUserTool();
+    byToolName.set(payload.name, { kind: 'payloadChange', toolName: payload.name, tool: payload });
+    byToolName.set(ask.name, { kind: 'askUser', toolName: ask.name, tool: ask });
+    tools.push(payload, ask);
+    controlToolNames.push(payload.name, ask.name);
+    return { tools, byToolName, controlToolNames };
+}
+//# sourceMappingURL=control-tools.js.map

package/dist/native-tools/control-tools.js.map

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

package/dist/native-tools/dual-channel.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @fileoverview Detecting a turn that answered on BOTH channels.
+ * @module @memberjunction/ai-agents
+ */
+/**
+ * Whether assistant content is a Loop envelope — a JSON object carrying `taskComplete`,
+ * `nextStep` or `payloadChangeRequest` — allowing for a markdown fence.
+ *
+ * Used on native turns that made tool calls: if this is ALSO true, the model gave two answers and
+ * the loop's tool-call-wins rule discards one. The eval's normalizer applies the same test
+ * independently (it must stay framework-free), so keep the two in step if this changes.
+ *
+ * @param content The assistant message content — a string, or an array of content blocks
+ */
+export declare function looksLikeLoopEnvelope(content: unknown): boolean;
+//# sourceMappingURL=dual-channel.d.ts.map

package/dist/native-tools/dual-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dual-channel.d.ts","sourceRoot":"","sources":["../../src/native-tools/dual-channel.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CA0B/D"}

package/dist/native-tools/dual-channel.js

@@ -0,0 +1,44 @@
+/**
+ * @fileoverview Detecting a turn that answered on BOTH channels.
+ * @module @memberjunction/ai-agents
+ */
+/**
+ * Whether assistant content is a Loop envelope — a JSON object carrying `taskComplete`,
+ * `nextStep` or `payloadChangeRequest` — allowing for a markdown fence.
+ *
+ * Used on native turns that made tool calls: if this is ALSO true, the model gave two answers and
+ * the loop's tool-call-wins rule discards one. The eval's normalizer applies the same test
+ * independently (it must stay framework-free), so keep the two in step if this changes.
+ *
+ * @param content The assistant message content — a string, or an array of content blocks
+ */
+export function looksLikeLoopEnvelope(content) {
+    let text;
+    if (typeof content === 'string') {
+        text = content;
+    }
+    else if (Array.isArray(content)) {
+        text = content
+            .filter((block) => typeof block === 'object' && block !== null
+            && block.type === 'text'
+            && typeof block.content === 'string')
+            .map((block) => block.content)
+            .join('');
+    }
+    else {
+        return false;
+    }
+    const stripped = text.trim().replace(/^```[a-zA-Z]*\s*\n?/, '').replace(/\n?```\s*$/, '').trim();
+    if (!stripped.startsWith('{')) {
+        return false;
+    }
+    try {
+        const parsed = JSON.parse(stripped);
+        return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)
+            && ('taskComplete' in parsed || 'nextStep' in parsed || 'payloadChangeRequest' in parsed);
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=dual-channel.js.map

package/dist/native-tools/dual-channel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dual-channel.js","sourceRoot":"","sources":["../../src/native-tools/dual-channel.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAAgB;IAClD,IAAI,IAAY,CAAC;IACjB,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAC9B,IAAI,GAAG,OAAO,CAAC;IACnB,CAAC;SAAM,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QAChC,IAAI,GAAG,OAAO;aACT,MAAM,CAAC,CAAC,KAAK,EAA8C,EAAE,CAC1D,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI;eACvC,KAA4B,CAAC,IAAI,KAAK,MAAM;eAC7C,OAAQ,KAA+B,CAAC,OAAO,KAAK,QAAQ,CAAC;aACnE,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC;aAC7B,IAAI,CAAC,EAAE,CAAC,CAAC;IAClB,CAAC;SAAM,CAAC;QACJ,OAAO,KAAK,CAAC;IACjB,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,qBAAqB,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACjG,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5B,OAAO,KAAK,CAAC;IACjB,CAAC;IACD,IAAI,CAAC;QACD,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC7C,OAAO,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;eACvE,CAAC,cAAc,IAAI,MAAM,IAAI,UAAU,IAAI,MAAM,IAAI,sBAAsB,IAAI,MAAM,CAAC,CAAC;IAClG,CAAC;IAAC,MAAM,CAAC;QACL,OAAO,KAAK,CAAC;IACjB,CAAC;AACL,CAAC"}