Agents CLI: rename the shared package to the CLI core (dex-agents-cli-core) (#1634)

Author: longquanzheng

.github/workflows/agents-python-publish.yml

@@ -33,10 +33,10 @@ concurrency:
 env:
   DEXCLI_RELEASE_TAG: cli-v1.45.0
   DEXCLI_ARCHIVE: dexcli_v1.45.0_linux_amd64.tar.gz
-  # Upload order: the core, the adapters, the CLI runtime, then the CLI commands.
+  # Upload order: the core, the adapters, the CLI core, then the CLI commands.
   AGENTS_PYTHON_DISTRIBUTIONS: >-
     dex-agents dex-agents-openai-agents dex-agents-pydantic-ai dex-agents-langgraph dex-agents-google-adk
-    dex-agents-claude-agent-sdk dex-agents-cli dex-agents-claude-sdk-cli dex-agents-openai-sdk-cli
+    dex-agents-claude-agent-sdk dex-agents-cli-core dex-agents-claude-sdk-cli dex-agents-openai-sdk-cli
     dex-agents-pydantic-ai-cli dex-agents-deepagents-cli dex-agents-google-adk-cli dex-agents-builtin-cli
 
 jobs:

.github/workflows/agents-typescript-publish.yml

@@ -159,7 +159,7 @@ jobs:
           name: agents-typescript-tarballs
           path: dist
       # The core publishes first so every adapter's peer dependency on it resolves.
-      # The CLI runtime and commands follow the adapters.
+      # The CLI core and commands follow the adapters.
       - name: Publish tarballs with trusted publishing
         shell: bash
         env:
@@ -169,7 +169,7 @@ jobs:
           set -euo pipefail
           for package in dex-agents dex-agents-vercel-ai dex-agents-openai-agents \
             dex-agents-mastra dex-agents-claude-agent-sdk dex-agents-pi \
-            dex-agents-cli dex-agents-claude-sdk-cli dex-agents-openai-sdk-cli \
+            dex-agents-cli-core dex-agents-claude-sdk-cli dex-agents-openai-sdk-cli \
             dex-agents-vercel-ai-cli dex-agents-mastra-cli dex-agents-builtin-cli dex-agents-pi-cli; do
             tarball="./dist/superdurable-${package}-${RELEASE_VERSION}.tgz"
             [[ -f "${tarball}" ]] || { echo "Missing ${tarball}" >&2; exit 1; }

CONTRIBUTING.md

@@ -248,7 +248,7 @@ The dependency-aware paths are:
 | TypeScript SDK | `sdk-typescript/vX.Y.Z` | `sdk-typescript/v0.1.0` | npm [`@superdurable/dex`](https://www.npmjs.com/package/@superdurable/dex) via [`.github/workflows/sdk-typescript-publish.yml`](.github/workflows/sdk-typescript-publish.yml) (version from the tag) |
 | Rust SDK | `sdk-rust/vX.Y.Z` | `sdk-rust/v0.1.0` | crates.io `dex-sdk`, `dex-blob-cache`, and `dex-protocol` via [`.github/workflows/sdk-rust-publish.yml`](.github/workflows/sdk-rust-publish.yml) (version from the tag) |
 | Dex CLI | `cli-vX.Y.Z` | `cli-v0.1.0` | macOS/Linux archives and Homebrew formula input |
-| Agents packages | `agents/vX.Y.Z` | `agents/v0.1.0` | PyPI `dex-agents`, its five adapters, the CLI runtime `dex-agents-cli`, and six CLI commands via [`.github/workflows/agents-python-publish.yml`](.github/workflows/agents-python-publish.yml), and npm `@superdurable/dex-agents`, its five adapters, the CLI runtime `@superdurable/dex-agents-cli`, and six CLI commands via [`.github/workflows/agents-typescript-publish.yml`](.github/workflows/agents-typescript-publish.yml) (one version for all twenty-six; see [`agents/README.md`](agents/README.md#releases)) |
+| Agents packages | `agents/vX.Y.Z` | `agents/v0.1.0` | PyPI `dex-agents`, its five adapters, the CLI core `dex-agents-cli-core`, and six CLI commands via [`.github/workflows/agents-python-publish.yml`](.github/workflows/agents-python-publish.yml), and npm `@superdurable/dex-agents`, its five adapters, the CLI core `@superdurable/dex-agents-cli-core`, and six CLI commands via [`.github/workflows/agents-typescript-publish.yml`](.github/workflows/agents-typescript-publish.yml) (one version for all twenty-six; see [`agents/README.md`](agents/README.md#releases)) |
 
 Notes:
 

agents/CHANGELOG.md

@@ -24,7 +24,7 @@ for the Dex SDK and framework versions each release supports.
 - Dex SDK 1.45.0 still needs a Dex Server with protocol 4: server-zd v0.1.17
   or later.
 - Agents CI, the nightly long run, and the publish workflows test against
-  `dexcli` 1.45.0. The Python and TypeScript CLI runtimes download `dexcli`
+  `dexcli` 1.45.0. The Python and TypeScript CLI cores download `dexcli`
   1.45.0 when none is installed.
 
 ### Dex MCP conventions
@@ -78,32 +78,32 @@ for the Dex SDK and framework versions each release supports.
 
 ### Added
 
-- Python CLI runtime (`dex-agents-cli`, first published in 0.5.0): the shared runtime
+- Python CLI core (`dex-agents-cli-core`, first published in 0.5.0): the shared CLI core
   of the Python harness commands. It reads `~/.dex/agents/<harness>.yaml` and
   asks the init questions on first run, reuses or starts `dexcli dev`
   (downloading a checksum-verified `dexcli` when none is installed), offers the
   connectors MCP server's tools and local file, shell, web fetch, and browser
   tools as Dex tool Steps, narrows each turn by the session settings, and chats
   in the terminal with inline approvals and Ctrl-C to cancel a turn. Harness
   packages implement **AgentHarness**. See
-  [cli/python/runtime](cli/python/runtime/README.md).
+  [cli/python/core](cli/python/core/README.md).
 - The **dex-agents-claude-sdk** command, in Python (`dex-agents-claude-sdk-cli`)
   and TypeScript (`@superdurable/dex-agents-claude-sdk-cli`), first published
-  in 0.5.0: a Claude Agent SDK agent in the terminal on the shared CLI runtime.
+  in 0.5.0: a Claude Agent SDK agent in the terminal on the shared CLI core.
   Claude Code's own Read, Grep, Glob, Write, Edit, Bash, and WebFetch tools
-  replace the runtime's file, shell, and web fetch tools, with the same rules:
+  replace the CLI core's file, shell, and web fetch tools, with the same rules:
   each turn offers only the groups its session settings switch on, reads run at
   once, writes and shell commands wait for approval unless the shell allow list
   has the command, file tools stay in the workspace, and the tool Step checks an
   approved call again. `ANTHROPIC_API_KEY` reaches Claude Code unchanged. See
   [cli/python/claude-sdk](cli/python/claude-sdk/README.md).
 - The **dex-agents-pi** command (`@superdurable/dex-agents-pi-cli`, first
-  published in 0.5.0): a Pi coding agent in the terminal on the shared CLI runtime,
+  published in 0.5.0): a Pi coding agent in the terminal on the shared CLI core,
   where Dex runs the agent loop and pi-ai makes each model call. The model is
   `<provider>/<model>` from pi-ai's catalog, and the key comes only from the
   provider's API key variable. pi-coding-agent's `read`, `grep`, `find`, `ls`,
-  `write`, `edit`, and `bash` replace the runtime's file and shell tools, with
-  the same rules: their file access goes through the runtime's workspace file
+  `write`, `edit`, and `bash` replace the CLI core's file and shell tools, with
+  the same rules: their file access goes through the CLI core's workspace file
   layer. `bash` has the shell tool's 120-second default timeout
   (`pi.bash_timeout_seconds`) and its 600-second maximum, and a command that
   ran is a result with its exit status. `grep` and `find` walk the workspace
@@ -113,44 +113,44 @@ for the Dex SDK and framework versions each release supports.
   only directly in its own directory, and above the workspace the file, and a
   link to it, must belong to you or root. See
   [cli/typescript/pi](cli/typescript/pi/README.md).
-- TypeScript CLI runtime: **WorkspaceFiles**, the workspace file layer of the
+- TypeScript CLI core: **WorkspaceFiles**, the workspace file layer of the
   local file tools, is exported for harnesses that bring their own file tools,
   with new methods **readFileWithVersion** (with an optional smaller
   **maximumBytes**), **replaceFileIfUnchanged**, **statExisting**, and
   **readDirectoryEntries**. A refusal throws the new
   **WorkspaceFileRefusedError**, a `ToolExecutionError` thrown before anything
   changed. See
-  [cli/typescript/runtime](cli/typescript/runtime/README.md#the-harness-interface).
-- TypeScript CLI runtime: `read_file`, `edit_file`, and `search_files` open
+  [cli/typescript/core](cli/typescript/core/README.md#the-harness-interface).
+- TypeScript CLI core: `read_file`, `edit_file`, and `search_files` open
   files without blocking, so a FIFO in the workspace fails at once as not a
   regular file, or is skipped by a search, instead of hanging the call, as in
-  the Python runtime.
+  the Python CLI core.
 - Python commands for the other harnesses, first published in 0.5.0, on the
-  shared CLI runtime: **dex-agents-openai-sdk** (OpenAI Agents SDK),
+  shared CLI core: **dex-agents-openai-sdk** (OpenAI Agents SDK),
   **dex-agents-pydantic-ai** (Pydantic AI), **dex-agents-deepagents** (Deep
   Agents on the LangGraph adapter), **dex-agents-google-adk** (Google ADK), and
   **dex-agents-builtin** (the Dex built-in agent loop on LiteLLM). Each uses the
-  runtime's local and connector tools, so every tool call is its own Dex tool
-  Step with the runtime's policy, and each model call uses its turn's model and
+  CLI core's local and connector tools, so every tool call is its own Dex tool
+  Step with the CLI core's policy, and each model call uses its turn's model and
   instructions. Provider keys come only from each provider's standard
   environment variables. The configuration file's `langgraph` section is now
   `deepagents`. See [cli/python](cli/python).
 - The TypeScript **dex-agents-openai-sdk**, **dex-agents-vercel-ai**,
   **dex-agents-mastra**, and **dex-agents-builtin** commands
   (`@superdurable/dex-agents-<name>-cli`), first published in 0.5.0: an OpenAI Agents
   SDK, Vercel AI SDK, Mastra, or built-in loop agent in the terminal on the shared
-  CLI runtime, with its connector and local tools. Each turn uses the model and
+  CLI core, with its connector and local tools. Each turn uses the model and
   instructions its session settings resolve to. Provider keys come from each
   provider's standard environment variables, such as `OPENAI_API_KEY`. See
   [cli/typescript/openai-sdk](cli/typescript/openai-sdk/README.md),
   [vercel-ai](cli/typescript/vercel-ai/README.md),
   [mastra](cli/typescript/mastra/README.md), and
   [builtin](cli/typescript/builtin/README.md).
-- TypeScript CLI runtime: a harness whose runner fixes its tools when the Flow
-  is built sets **AgentHarness.isToolSetFixedAtBuild**. The runtime then lists
+- TypeScript CLI core: a harness whose runner fixes its tools when the Flow
+  is built sets **AgentHarness.isToolSetFixedAtBuild**. The CLI core then lists
   the file's connector tools before building the Flow and, when the connectors
   MCP server does not answer at startup, says that a restart brings them back.
-  See [cli/typescript/runtime](cli/typescript/runtime/README.md#connectors).
+  See [cli/typescript/core](cli/typescript/core/README.md#connectors).
 - Python and TypeScript Claude Agent SDK adapters: **claude_code_tool_permission**
   (`claudeCodeToolPermission`) decides each call of a tool that runs inside the
   Claude Code CLI from its input. It returns a **ToolPolicy** for that call,
@@ -176,7 +176,7 @@ for the Dex SDK and framework versions each release supports.
   values that say where the program that started the session ran. The session
   never reads it; it stays in the Flow's start input. Python
   `AgentSessionClient.start_session` and TypeScript `startAgentSession` take
-  it. Workers before 0.5.0 ignore it. The CLI runtimes record their host name,
+  it. Workers before 0.5.0 ignore it. The CLI cores record their host name,
   user ID and user name, configuration identity, and workspace there.
 - Python and TypeScript cores: new **ToolCallContext.effect**, the effect of a
   built-in agent loop function tool call after the tool policies are applied.
@@ -323,7 +323,7 @@ for the Dex SDK and framework versions each release supports.
     `EncodeStepwiseMessage` -> `EncodeBuiltinLoopMessage`;
     `DecodeStepwiseMessage` -> `DecodeBuiltinLoopMessage`. Package `stepwise`
     forwards to `builtinloop` and is marked `Deprecated:`.
-  - The framework adapters, the Pi adapter, and the agents CLI runtime import
+  - The framework adapters, the Pi adapter, and the agents CLI core import
     the new names.
 - The error text for a session message that the built-in agent loop cannot
   read now says "built-in agent loop item" (Python and Go cores) or "built-in
@@ -333,7 +333,7 @@ for the Dex SDK and framework versions each release supports.
   Python loggers are now named `dex_agents.builtin_loop.*`, and the Go core's
   panic messages for a nil model client or definition start with
   `builtinloop:` instead of `stepwise:`.
-- Breaking, Python and TypeScript CLI runtimes: the session Flow type suffix is
+- Breaking, Python and TypeScript CLI cores: the session Flow type suffix is
   now 6 lowercase base36 characters instead of 12 hex digits, from the same
   SHA-256 of the host name, user, configuration identity, and workspace: the
   digest's first 8 bytes as an unsigned big-endian integer, modulo 36^6, in
@@ -343,7 +343,7 @@ for the Dex SDK and framework versions each release supports.
   `current_session_environment_identity`, and `SessionEnvironmentIdentity`
   match the TypeScript `namespaceSessionFlowType`.
   `agents/conformance/cli_session_flow_types.json` fixes the suffix for every
-  CLI runtime.
+  CLI core.
 - Breaking, Python and TypeScript cores: a connector tool's default name now
   uses the Connector library's snake case (connectorctl `lowerCamelToSnake`),
   which also names the Python Step factories. An acronym run stays one word.

agents/README.md

@@ -21,7 +21,7 @@ adapter depends on the published core instead.
 | [`python/langgraph`](python/langgraph) | [`dex-agents-langgraph`](https://pypi.org/project/dex-agents-langgraph/) | LangChain `create_agent` and LangGraph |
 | [`python/google-adk`](python/google-adk) | [`dex-agents-google-adk`](https://pypi.org/project/dex-agents-google-adk/) | Google ADK |
 | [`python/claude-agent-sdk`](python/claude-agent-sdk) | [`dex-agents-claude-agent-sdk`](https://pypi.org/project/dex-agents-claude-agent-sdk/) | Claude Agent SDK |
-| [`cli/python/runtime`](cli/python/runtime) | `dex-agents-cli` (`dex_agents_cli`), not published yet | Shared runtime of the Python CLI commands: configuration, `dexcli dev`, connector and local tools, terminal chat |
+| [`cli/python/core`](cli/python/core) | `dex-agents-cli-core` (`dex_agents_cli_core`), not published yet | Shared core of the Python CLI commands: configuration, `dexcli dev`, connector and local tools, terminal chat |
 | [`cli/python/claude-sdk`](cli/python/claude-sdk) | `dex-agents-claude-sdk-cli`, not published yet | The `dex-agents-claude-sdk` command: a Claude Agent SDK agent in the terminal |
 | [`cli/python/openai-sdk`](cli/python/openai-sdk) | `dex-agents-openai-sdk-cli`, not published yet | The `dex-agents-openai-sdk` command: an OpenAI Agents SDK agent in the terminal |
 | [`cli/python/pydantic-ai`](cli/python/pydantic-ai) | `dex-agents-pydantic-ai-cli`, not published yet | The `dex-agents-pydantic-ai` command: a Pydantic AI agent in the terminal |
@@ -35,7 +35,7 @@ adapter depends on the published core instead.
 | [`typescript/openai-agents`](typescript/openai-agents) | [`@superdurable/dex-agents-openai-agents`](https://www.npmjs.com/package/@superdurable/dex-agents-openai-agents) | OpenAI Agents SDK |
 | [`typescript/mastra`](typescript/mastra) | [`@superdurable/dex-agents-mastra`](https://www.npmjs.com/package/@superdurable/dex-agents-mastra) | Mastra |
 | [`typescript/claude-agent-sdk`](typescript/claude-agent-sdk) | [`@superdurable/dex-agents-claude-agent-sdk`](https://www.npmjs.com/package/@superdurable/dex-agents-claude-agent-sdk) | Claude Agent SDK |
-| [`cli/typescript/runtime`](cli/typescript/runtime) | `@superdurable/dex-agents-cli`, not published yet | Shared runtime of the TypeScript CLI commands: configuration, `dexcli dev`, connector and local tools, terminal chat |
+| [`cli/typescript/core`](cli/typescript/core) | `@superdurable/dex-agents-cli-core`, not published yet | Shared core of the TypeScript CLI commands: configuration, `dexcli dev`, connector and local tools, terminal chat |
 | [`cli/typescript/claude-sdk`](cli/typescript/claude-sdk) | `@superdurable/dex-agents-claude-sdk-cli`, not published yet | The `dex-agents-claude-sdk` command: a Claude Agent SDK agent in the terminal |
 | [`cli/typescript/openai-sdk`](cli/typescript/openai-sdk) | `@superdurable/dex-agents-openai-sdk-cli`, not published yet | The `dex-agents-openai-sdk` command: an OpenAI Agents SDK agent in the terminal |
 | [`cli/typescript/vercel-ai`](cli/typescript/vercel-ai) | `@superdurable/dex-agents-vercel-ai-cli`, not published yet | The `dex-agents-vercel-ai` command: a Vercel AI SDK agent in the terminal |
@@ -168,7 +168,7 @@ or later.
 
 Publishing a GitHub Release with the tag `agents/v<version>` from a commit on
 `main` publishes all twenty-six packages in dependency order: the core, the
-adapters, the CLI runtime, then the CLI commands. `dex-agents-cli-testing`
+adapters, the CLI core, then the CLI commands. `dex-agents-cli-testing`
 is never published.
 [`agents-python-publish.yml`](../.github/workflows/agents-python-publish.yml)
 uploads to PyPI and
@@ -188,7 +188,7 @@ It sets one version in all fourteen `pyproject.toml` files (the thirteen
 published ones and `dex-agents-cli-testing`) and thirteen `package.json`
 files, their lockfiles, and every constraint between agents packages: the
 adapters' on their core, and the CLI packages' on the core, their adapter,
-and the CLI runtime. Python pins `==<version>`; npm peer-depends on
+and the CLI core. Python pins `==<version>`; npm peer-depends on
 `^<version>`. Run it locally to bump the committed version, and pass
 `--check` to verify it.
 
@@ -198,7 +198,7 @@ and installs them into fresh projects without path dependencies: the core
 first, then each adapter. It imports every TypeScript core subpath with and
 without the optional peer `ai`. It then runs one Pydantic AI session and one Vercel
 AI SDK session against `dexcli dev --engine zd` with a scripted model, using
-the adapters' own test fixtures. Last, it installs the CLI runtime and each
+the adapters' own test fixtures. Last, it installs the CLI core and each
 CLI command from the built artifacts alone and runs each command's `--help`
 and `init --yes` with a scratch `HOME`; neither needs a model key or a Dex
 server. Agents CI runs it on every change, so packaging regressions fail CI:
@@ -211,7 +211,7 @@ DEXCLI=/path/to/dexcli agents/script/smoke-test-built-packages.sh all
 
 PyPI accepts only about five new projects per day. A release that publishes
 more new PyPI names than that uploads in two runs. The first release of the
-CLI packages has seven new names: `dex-agents-cli` and six commands.
+CLI packages has seven new names: `dex-agents-cli-core` and six commands.
 
 The PyPI workflow's `skip_packages` input leaves CLI command distributions
 out of one upload. It accepts only command names, because nothing else in the