@superdurable/dex-agents-mastra-cli 0.0.0 → 0.5.0

package/LICENSE

@@ -0,0 +1,105 @@
+# License
+
+Copyright (c) 2026 Super Durable, Inc.
+
+Portions of this software are licensed as follows:
+
+- Legacy Materials remain under their original licenses as described in
+  `LEGACY_NOTICES.md`.
+- Third-Party Materials remain under the licenses provided by their owners.
+- The `docs/` and `examples/` directories are not licensed under the
+  Sustainable Use License and retain their existing licensing status.
+- All other material owned or licensable by Super Durable, Inc. is available
+  under the Sustainable Use License below.
+
+See `LEGACY_NOTICES.md` for the applicable legacy and third-party notices.
+
+## Sustainable Use License
+
+Version 1.0
+
+### Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+### Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations below.
+
+### Limitations
+
+You may use or modify the software only for your own internal business purposes
+or for non-commercial or personal use. You may distribute the software or
+provide it to others only if you do so free of charge for non-commercial
+purposes. You may not alter, remove, or obscure any licensing, copyright, or
+other notices of the licensor in the software. Any use of the licensor's
+trademarks is subject to applicable law.
+
+### Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software.
+
+If you or your company make any written claim that the software infringes or
+contributes to infringement of any patent, your patent license for the software
+granted under these terms ends immediately. If your company makes such a claim,
+your patent license ends immediately for work on behalf of your company.
+
+### Notices
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms. If you modify the software, you must
+include in any modified copies of the software a prominent notice stating that
+you have modified the software.
+
+### No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+### Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your license will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your license will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your license
+to terminate automatically and permanently.
+
+### No Liability
+
+As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.
+
+### Definitions
+
+The "licensor" is the entity offering these terms.
+
+The "software" is the software the licensor makes available under these terms,
+including any portion of it.
+
+"You" refers to the individual or entity agreeing to these terms.
+
+"Your company" is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+Control means ownership of substantially all the assets of an entity, or the
+power to direct its management and policies by vote, contract, or otherwise.
+Control can be direct or indirect.
+
+"Your license" is the license granted to you for the software under these
+terms.
+
+"Use" means anything you do with the software requiring your license.
+
+"Trademark" means trademarks, service marks, and similar rights.

package/README.md

@@ -1,6 +1,75 @@
 # @superdurable/dex-agents-mastra-cli
 
-This version is a placeholder that reserves the package name. It contains no code.
-The first real release of this Dex agents package will replace it.
+`@superdurable/dex-agents-mastra-cli` provides the `dex-agents-mastra`
+command. It runs a [Mastra](https://mastra.ai) agent as a durable Dex agent
+session and chats with it in your terminal. The shared CLI core,
+[`@superdurable/dex-agents-cli-core`](../core/README.md), starts or reuses
+`dexcli dev`, connects the connectors MCP server, offers the local tools, and
+runs the Worker. This package only builds the agent with the
+[Mastra adapter](../../../typescript/mastra/README.md).
 
-Source: https://github.com/superdurable/dex/tree/main/agents/cli/typescript/mastra
+## Running it
+
+The command needs Node.js 22 or 24 and a provider API key:
+
+```bash
+export OPENAI_API_KEY=sk-...
+npx -p @superdurable/dex-agents-mastra-cli dex-agents-mastra
+```
+
+The first run asks the `init` questions and writes
+`~/.dex/agents/mastra.yaml`. Then type a message. Approve or reject tool calls
+with `y` or `n`, and type `/exit` to leave. The session stays in Dex, and the
+command prints the `--resume` line that continues it. See the
+[CLI core README](../core/README.md) for every subcommand and option, and
+[`agents/cli`](../../README.md) for the configuration file.
+
+## Models and keys
+
+The model defaults to `openai/gpt-5.2`; set `model` in the file or pass
+`--model` to change it. The model ID goes to Mastra's model router unchanged,
+so any `<provider>/<model>` ID that Mastra knows works, such as
+`anthropic/claude-sonnet-4-5`. Mastra reads the provider's standard
+environment variable, such as `OPENAI_API_KEY` (with optional
+`OPENAI_BASE_URL`) or `ANTHROPIC_API_KEY`. The command never prints or stores
+a key.
+
+The package pins `@mastra/core` to the version the Mastra adapter's lockfile
+tests, and `ci.sh` fails when the two lockfiles differ. Mastra brings its own
+copies of `@ai-sdk/provider`, 3.x and 4.x, for its model router; the command
+does not call the AI SDK itself.
+
+## Configuration and tools
+
+The `mastra` section has no options yet, and any key in it is a configuration
+error.
+
+The agent offers the connectors MCP server's tools and the CLI core's
+[local tools](../core/README.md#local-tools), each call in its own tool Step
+with the CLI core's approval rules. The Mastra agent's model and instructions
+are functions that Mastra calls in every model call, so each turn uses the
+model and instructions its session settings resolve to.
+
+## Images
+
+`/image <path>` attaches an image file to the next message. The command gives
+the Mastra adapter the media store of `media.store`, so the model sees the
+image, and images that tools return go to the same store. See
+[Images](../../README.md#images).
+
+## Development
+
+`ci.sh` builds the core, the Mastra adapter, and the CLI core, which this
+package installs from the repository, then typechecks and runs the integration
+tests against a private `dexcli dev`:
+
+```bash
+cd agents/cli/typescript/mastra
+DEXCLI=/path/to/dexcli ./ci.sh
+```
+
+`dex-server-zd` must sit next to `dexcli`. The tests run the command as a child
+process with a private home and an explicit environment allow list. Mastra's
+OpenAI model calls `test/fixtures/mock-responses-api.ts`, a scripted Responses
+API on 127.0.0.1, through `OPENAI_BASE_URL`, and the connector tools come from
+`test/fixtures/fake-connectors-mcp-server.ts`.

package/dist/src/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/bin.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+// 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 { processAgentCliIo, runAgentCli } from "@superdurable/dex-agents-cli-core";
+import { mastraHarness } from "./mastra-harness.js";
+// Exit explicitly: open connections can keep Node running after the chat ends.
+process.exit(await runAgentCli(mastraHarness, processAgentCliIo()));
+//# sourceMappingURL=bin.js.map

package/dist/src/bin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin.js","sourceRoot":"","sources":["../../src/bin.ts"],"names":[],"mappings":";AACA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAE1D,OAAO,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAEnF,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,+EAA+E;AAC/E,OAAO,CAAC,IAAI,CAAC,MAAM,WAAW,CAAC,aAAa,EAAE,iBAAiB,EAAE,CAAC,CAAC,CAAC"}

package/dist/src/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The `dex-agents-mastra` command: a Mastra agent in the terminal. It builds the agent session Flow with the Mastra
+ * adapter and runs it with the shared Dex Agents CLI core.
+ *
+ * @packageDocumentation
+ */
+export { createMastraCliSessionFlow, defaultInstructions, defaultMastraModel, mastraCliFlowType, mastraHarness, validateMastraSection, } from "./mastra-harness.js";

package/dist/src/index.js

@@ -0,0 +1,15 @@
+// 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
+/**
+ * The `dex-agents-mastra` command: a Mastra agent in the terminal. It builds the agent session Flow with the Mastra
+ * adapter and runs it with the shared Dex Agents CLI core.
+ *
+ * @packageDocumentation
+ */
+export { createMastraCliSessionFlow, defaultInstructions, defaultMastraModel, mastraCliFlowType, mastraHarness, validateMastraSection, } from "./mastra-harness.js";
+//# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAE1D;;;;;GAKG;AAEH,OAAO,EACL,0BAA0B,EAC1B,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,aAAa,EACb,qBAAqB,GACtB,MAAM,qBAAqB,CAAC"}

package/dist/src/mastra-harness.d.ts

@@ -0,0 +1,58 @@
+import { type AgentHarness, type HarnessContext } from "@superdurable/dex-agents-cli-core";
+import { createMastraAgentSessionFlow } from "@superdurable/dex-agents-mastra";
+/**
+ * The base Flow type of the command's sessions, before the CLI core namespaces it.
+ *
+ * @since 0.5.0
+ */
+export declare const mastraCliFlowType = "DexAgentsMastraCliSession";
+/**
+ * The model the command uses when the configuration file sets none.
+ *
+ * @since 0.5.0
+ */
+export declare const defaultMastraModel = "openai/gpt-5.2";
+/**
+ * The instructions the agent gets when the configuration sets none.
+ *
+ * @since 0.5.0
+ */
+export declare const defaultInstructions: string;
+/**
+ * The `dex-agents-mastra` command: a Mastra agent in the terminal.
+ *
+ * The agent offers the CLI core's connector and local tools. The model ID is any Mastra model router ID, such as
+ * `openai/gpt-5.2` or `anthropic/claude-sonnet-4-5`, and Mastra reads the provider's standard API key variable.
+ * Each turn uses the model and instructions its session settings resolve to. The `mastra` section has no options
+ * yet; any key in it is a configuration error.
+ *
+ * @example
+ * ```ts
+ * import { processAgentCliIo, runAgentCli } from "@superdurable/dex-agents-cli-core";
+ * import { mastraHarness } from "@superdurable/dex-agents-mastra-cli";
+ *
+ * process.exit(await runAgentCli(mastraHarness, processAgentCliIo()));
+ * ```
+ * @since 0.5.0
+ */
+export declare const mastraHarness: AgentHarness;
+/**
+ * Builds the Mastra agent session Flow from the effective configuration.
+ *
+ * The agent's model and instructions are functions, which Mastra calls in every model call, so each turn gets its
+ * own.
+ *
+ * @param context - The configuration, workspace, and tool sources.
+ * @returns The Flow, with `context.flowType` as its type.
+ * @throws {ConfigError} When the `mastra` section has a key.
+ * @since 0.5.0
+ */
+export declare function createMastraCliSessionFlow(context: HarnessContext): ReturnType<typeof createMastraAgentSessionFlow>;
+/**
+ * Rejects every key of the `mastra` section, which has no options yet.
+ *
+ * @param options - The section, `{}` when the file omits it.
+ * @throws {ConfigError} A `schema` error with the first key's JSON Pointer.
+ * @since 0.5.0
+ */
+export declare function validateMastraSection(options: Readonly<Record<string, unknown>>): void;

package/dist/src/mastra-harness.js

@@ -0,0 +1,92 @@
+// 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 { Agent } from "@mastra/core/agent";
+import { ConfigError } from "@superdurable/dex-agents-cli-core";
+import { createMastraAgentSessionFlow } from "@superdurable/dex-agents-mastra";
+/**
+ * The base Flow type of the command's sessions, before the CLI core namespaces it.
+ *
+ * @since 0.5.0
+ */
+export const mastraCliFlowType = "DexAgentsMastraCliSession";
+/**
+ * The model the command uses when the configuration file sets none.
+ *
+ * @since 0.5.0
+ */
+export const defaultMastraModel = "openai/gpt-5.2";
+/**
+ * The instructions the agent gets when the configuration sets none.
+ *
+ * @since 0.5.0
+ */
+export const defaultInstructions = "You are a helpful assistant. Use your tools to work with the files and commands in your workspace and with " +
+    "the connected services.";
+/**
+ * The `dex-agents-mastra` command: a Mastra agent in the terminal.
+ *
+ * The agent offers the CLI core's connector and local tools. The model ID is any Mastra model router ID, such as
+ * `openai/gpt-5.2` or `anthropic/claude-sonnet-4-5`, and Mastra reads the provider's standard API key variable.
+ * Each turn uses the model and instructions its session settings resolve to. The `mastra` section has no options
+ * yet; any key in it is a configuration error.
+ *
+ * @example
+ * ```ts
+ * import { processAgentCliIo, runAgentCli } from "@superdurable/dex-agents-cli-core";
+ * import { mastraHarness } from "@superdurable/dex-agents-mastra-cli";
+ *
+ * process.exit(await runAgentCli(mastraHarness, processAgentCliIo()));
+ * ```
+ * @since 0.5.0
+ */
+export const mastraHarness = {
+    name: "mastra",
+    configSection: "mastra",
+    flowType: mastraCliFlowType,
+    defaultModel: defaultMastraModel,
+    createSessionFlow: (context) => createMastraCliSessionFlow(context),
+};
+/**
+ * Builds the Mastra agent session Flow from the effective configuration.
+ *
+ * The agent's model and instructions are functions, which Mastra calls in every model call, so each turn gets its
+ * own.
+ *
+ * @param context - The configuration, workspace, and tool sources.
+ * @returns The Flow, with `context.flowType` as its type.
+ * @throws {ConfigError} When the `mastra` section has a key.
+ * @since 0.5.0
+ */
+export function createMastraCliSessionFlow(context) {
+    validateMastraSection(context.harnessOptions);
+    const agent = new Agent({
+        id: "assistant",
+        name: "Assistant",
+        instructions: () => context.currentTurn().instructions ?? defaultInstructions,
+        model: () => context.currentTurn().model,
+    });
+    return createMastraAgentSessionFlow(agent, context.flowType, {
+        toolSources: context.toolSources,
+        ...(context.mediaStore === undefined ? {} : { mediaStore: context.mediaStore }),
+    });
+}
+/**
+ * Rejects every key of the `mastra` section, which has no options yet.
+ *
+ * @param options - The section, `{}` when the file omits it.
+ * @throws {ConfigError} A `schema` error with the first key's JSON Pointer.
+ * @since 0.5.0
+ */
+export function validateMastraSection(options) {
+    const [firstKey] = Object.keys(options).sort();
+    if (firstKey !== undefined) {
+        const escaped = firstKey.replaceAll("~", "~0").replaceAll("/", "~1");
+        throw new ConfigError("schema", `/mastra/${escaped}`, "additionalProperties");
+    }
+}
+//# sourceMappingURL=mastra-harness.js.map

package/dist/src/mastra-harness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mastra-harness.js","sourceRoot":"","sources":["../../src/mastra-harness.ts"],"names":[],"mappings":"AAAA,yCAAyC;AACzC,EAAE;AACF,kDAAkD;AAClD,mEAAmE;AACnE,+CAA+C;AAC/C,EAAE;AACF,0DAA0D;AAE1D,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,WAAW,EAA0C,MAAM,mCAAmC,CAAC;AACxG,OAAO,EAAE,4BAA4B,EAAE,MAAM,iCAAiC,CAAC;AAE/E;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,2BAA2B,CAAC;AAE7D;;;;GAIG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,gBAAgB,CAAC;AAEnD;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAC9B,6GAA6G;IAC7G,yBAAyB,CAAC;AAE5B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,aAAa,GAAiB;IACzC,IAAI,EAAE,QAAQ;IACd,aAAa,EAAE,QAAQ;IACvB,QAAQ,EAAE,iBAAiB;IAC3B,YAAY,EAAE,kBAAkB;IAChC,iBAAiB,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,0BAA0B,CAAC,OAAO,CAAC;CACpE,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,UAAU,0BAA0B,CAAC,OAAuB;IAChE,qBAAqB,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;IAC9C,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC;QACtB,EAAE,EAAE,WAAW;QACf,IAAI,EAAE,WAAW;QACjB,YAAY,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,YAAY,IAAI,mBAAmB;QAC7E,KAAK,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,KAAK;KACzC,CAAC,CAAC;IACH,OAAO,4BAA4B,CAAC,KAAK,EAAE,OAAO,CAAC,QAAQ,EAAE;QAC3D,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,GAAG,CAAC,OAAO,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC;KAChF,CAAC,CAAC;AACL,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAA0C;IAC9E,MAAM,CAAC,QAAQ,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;IAC/C,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,OAAO,GAAG,QAAQ,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QACrE,MAAM,IAAI,WAAW,CAAC,QAAQ,EAAE,WAAW,OAAO,EAAE,EAAE,sBAAsB,CAAC,CAAC;IAChF,CAAC;AACH,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@superdurable/dex-agents-mastra-cli",
-  "version": "0.0.0",
-  "description": "Placeholder that reserves the name for a Dex agents package. It contains no code; the first real release follows.",
+  "version": "0.5.0",
+  "description": "The dex-agents-mastra command: a durable Mastra agent in your terminal",
   "license": "LicenseRef-Sustainable-Use-1.0",
   "repository": {
     "type": "git",
@@ -9,10 +9,54 @@
     "directory": "agents/cli/typescript/mastra"
   },
   "homepage": "https://github.com/superdurable/dex/tree/main/agents/cli/typescript/mastra#readme",
+  "bugs": {
+    "url": "https://github.com/superdurable/dex/issues"
+  },
+  "type": "module",
+  "types": "./dist/src/index.d.ts",
+  "engines": {
+    "node": "^22.0.0 || ^24.0.0"
+  },
+  "bin": {
+    "dex-agents-mastra": "dist/src/bin.js"
+  },
   "files": [
-    "README.md"
+    "dist/src",
+    "README.md",
+    "LICENSE"
   ],
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test --test-concurrency=1 --test-timeout=300000 'dist/test/integ/*.integration.test.js'"
+  },
+  "dependencies": {
+    "@mastra/core": "1.81.0",
+    "zod": "^4.0.0"
+  },
+  "peerDependencies": {
+    "@superdurable/dex": "1.45.0",
+    "@superdurable/dex-agents": "^0.5.0",
+    "@superdurable/dex-agents-cli-core": "^0.5.0",
+    "@superdurable/dex-agents-mastra": "^0.5.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "1.32.2",
+    "@superdurable/dex": "1.45.0",
+    "@superdurable/dex-agents": "file:../../../typescript/core",
+    "@superdurable/dex-agents-cli-core": "file:../core",
+    "@superdurable/dex-agents-mastra": "file:../../../typescript/mastra",
+    "@types/node": "22.20.5",
+    "typescript": "5.9.3"
+  },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   }
-}
+}