@superdurable/dex-agents 0.2.0 → 0.4.0

package/dist/src/agent-session-flow-graph.d.ts

@@ -0,0 +1,38 @@
+/** What an application chooses for the session Flow Definition Graph of one agent. */
+export interface SessionFlowGraphOptions {
+    /** The Flow type of the agent, as passed to `createAgentSessionFlow`. */
+    readonly flowType: string;
+    /** The permission every session Action requires, such as `support-agent.operate`. */
+    readonly actionPermission: string;
+}
+/**
+ * Renders the Flow Definition Graph 2.0 file of one agent's session Flow.
+ *
+ * `dexcli visualize` cannot read the session Flow: the Flow lives in this library, and the application chooses its
+ * Flow type. This function fills both choices into the graph that ships with the package. Write the text to a file in
+ * the directory that Dex Web reads with `--flow-rendering-dir`. Dex Web then draws the session Steps and offers the
+ * `resolve_interrupt`, `answer_question`, `steer_user_message`, and `cancel_turn` Actions. Those Actions have no
+ * condition, because each RPC checks current state itself.
+ *
+ * The Python core renders the same bytes, so a graph from either core serves a session on Workers of either language.
+ * Render the file again after you upgrade this package. The `dex-agents-session-graph` command does the same from a
+ * build or deployment script.
+ *
+ * @example
+ * ```ts
+ * import { writeFileSync } from "node:fs";
+ * import { renderSessionFlowGraph } from "@superdurable/dex-agents";
+ *
+ * writeFileSync(
+ *   "definitions/support-agent.json",
+ *   renderSessionFlowGraph({ flowType: "SupportAgent", actionPermission: "support-agent.operate" }),
+ * );
+ * ```
+ *
+ * @param options - The Flow type and the Action permission.
+ * @returns The graph as JSON text that ends with a newline.
+ * @throws {TypeError} When `flowType` is blank, or when `actionPermission` is not lowercase letters, digits, dots, and
+ *   hyphens that start with a letter.
+ * @since 0.3.0
+ */
+export declare function renderSessionFlowGraph(options: SessionFlowGraphOptions): string;

package/dist/src/agent-session-flow-graph.js

@@ -0,0 +1,54 @@
+// Copyright (c) 2026 Super Durable, Inc.
+//
+// Licensed under the Sustainable Use License 1.0.
+// You may not use this file except in compliance with the License.
+// See the LICENSE file in the repository root.
+//
+// SPDX-License-Identifier: LicenseRef-Sustainable-Use-1.0
+import sessionFlowGraphTemplate from "./agent-session-flow-graph.json" with { type: "json" };
+const actionPermissionPattern = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/;
+/**
+ * Renders the Flow Definition Graph 2.0 file of one agent's session Flow.
+ *
+ * `dexcli visualize` cannot read the session Flow: the Flow lives in this library, and the application chooses its
+ * Flow type. This function fills both choices into the graph that ships with the package. Write the text to a file in
+ * the directory that Dex Web reads with `--flow-rendering-dir`. Dex Web then draws the session Steps and offers the
+ * `resolve_interrupt`, `answer_question`, `steer_user_message`, and `cancel_turn` Actions. Those Actions have no
+ * condition, because each RPC checks current state itself.
+ *
+ * The Python core renders the same bytes, so a graph from either core serves a session on Workers of either language.
+ * Render the file again after you upgrade this package. The `dex-agents-session-graph` command does the same from a
+ * build or deployment script.
+ *
+ * @example
+ * ```ts
+ * import { writeFileSync } from "node:fs";
+ * import { renderSessionFlowGraph } from "@superdurable/dex-agents";
+ *
+ * writeFileSync(
+ *   "definitions/support-agent.json",
+ *   renderSessionFlowGraph({ flowType: "SupportAgent", actionPermission: "support-agent.operate" }),
+ * );
+ * ```
+ *
+ * @param options - The Flow type and the Action permission.
+ * @returns The graph as JSON text that ends with a newline.
+ * @throws {TypeError} When `flowType` is blank, or when `actionPermission` is not lowercase letters, digits, dots, and
+ *   hyphens that start with a letter.
+ * @since 0.3.0
+ */
+export function renderSessionFlowGraph(options) {
+    if (options.flowType.trim() === "") {
+        throw new TypeError("flowType must not be empty");
+    }
+    if (!actionPermissionPattern.test(options.actionPermission)) {
+        throw new TypeError(`actionPermission ${JSON.stringify(options.actionPermission)} is not a valid permission`);
+    }
+    const graph = structuredClone(sessionFlowGraphTemplate);
+    graph.flow.name = options.flowType;
+    for (const action of graph.v2.actions) {
+        action.requiredPermission = options.actionPermission;
+    }
+    return `${JSON.stringify(graph, null, 2)}\n`;
+}
+//# sourceMappingURL=agent-session-flow-graph.js.map

package/dist/src/agent-session-flow-graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-session-flow-graph.js","sourceRoot":"","sources":["../../src/agent-session-flow-graph.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAE1D,OAAO,wBAAwB,MAAM,iCAAiC,CAAC,OAAO,IAAI,EAAE,MAAM,EAAE,CAAC;AAE7F,MAAM,uBAAuB,GAAG,oCAAoC,CAAC;AAUrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAgC;IACrE,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACnC,MAAM,IAAI,SAAS,CAAC,4BAA4B,CAAC,CAAC;IACpD,CAAC;IACD,IAAI,CAAC,uBAAuB,CAAC,IAAI,CAAC,OAAO,CAAC,gBAAgB,CAAC,EAAE,CAAC;QAC5D,MAAM,IAAI,SAAS,CAAC,oBAAoB,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,gBAAgB,CAAC,4BAA4B,CAAC,CAAC;IAChH,CAAC;IACD,MAAM,KAAK,GAAG,eAAe,CAAC,wBAAwB,CAAC,CAAC;IACxD,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC;IACnC,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC;QACtC,MAAM,CAAC,kBAAkB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IACvD,CAAC;IACD,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC;AAC/C,CAAC"}