dex-agents-builtin-cli 0.6.0__py3-none-any.whl

dex_agents_builtin_cli/__init__.py

@@ -0,0 +1,61 @@
+# 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-builtin`` command: a Dex built-in loop agent in the terminal.
+
+It builds the agent session Flow with the Dex built-in agent loop on LiteLLM and
+runs it with the shared Dex Agents CLI core. See the package README.
+"""
+
+import dex_agents_cli_core  # noqa: F401  # first: it configures gRPC before anything imports it
+
+# isort: split
+
+import sys
+
+from dex_agents_builtin_cli.harness import (
+    BUILTIN_CLI_FLOW_TYPE,
+    DEFAULT_BUILTIN_MODEL,
+    DEFAULT_INSTRUCTIONS,
+    BuiltinHarness,
+    validate_builtin_section,
+)
+from dex_agents_cli_core import ConfigError, command_name, run_agent_cli
+
+__all__ = [
+    "BUILTIN_CLI_FLOW_TYPE",
+    "DEFAULT_BUILTIN_MODEL",
+    "DEFAULT_INSTRUCTIONS",
+    "BuiltinHarness",
+    "main",
+    "run",
+    "validate_builtin_section",
+]
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the command and return its exit code.
+
+    Args:
+        argv: The arguments without the program name; ``None`` reads ``sys.argv``.
+
+    Returns:
+        0 on success, 1 for a failure at run time, and 2 for a usage or
+        configuration error, such as a key in the ``builtin`` section.
+    """
+    harness = BuiltinHarness()
+    try:
+        return run_agent_cli(harness, argv)
+    except ConfigError as error:
+        print(f"{command_name(harness)}: {error}", file=sys.stderr)
+        return 2
+
+
+def run() -> None:
+    """Run the command from its console script and exit with its code."""
+    raise SystemExit(main())

dex_agents_builtin_cli/__main__.py

@@ -0,0 +1,14 @@
+# 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
+
+"""``python -m dex_agents_builtin_cli`` runs the ``dex-agents-builtin`` command."""
+
+from dex_agents_builtin_cli import run
+
+if __name__ == "__main__":
+    run()

dex_agents_builtin_cli/harness.py

@@ -0,0 +1,112 @@
+# 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 built-in harness: a Dex built-in loop agent on LiteLLM with the CLI core's tools."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import dex_agents_cli_core  # noqa: F401  # first: it configures gRPC before anything imports it
+
+# isort: split
+
+from dex_agents import AgentSessionFlow, BuiltInTool
+from dex_agents.builtin_loop import AgentDefinition, InstructionContext, builtin_agent_session_flow
+from dex_agents.litellm import LiteLLMModelClient
+from dex_agents_cli_core import ConfigError, HarnessContext, LocalToolGroup
+
+#: The Flow type of the command's sessions, before the CLI core namespaces it.
+BUILTIN_CLI_FLOW_TYPE = "DexAgentsBuiltinCliSession"
+
+#: The LiteLLM model the command uses when the configuration file sets none.
+DEFAULT_BUILTIN_MODEL = "openai/gpt-5.2"
+
+#: The instructions the agent gets when the configuration sets none.
+DEFAULT_INSTRUCTIONS = (
+    "You are a helpful assistant. Use your tools to work with the files and commands "
+    "in your workspace and with the connected services."
+)
+
+
+class BuiltinHarness:
+    """The ``dex-agents-builtin`` command: a Dex built-in loop agent in the terminal.
+
+    Every model call is one LiteLLM request with the turn's model, so any
+    LiteLLM provider works with its standard environment variables. The
+    CLI core's connector and local tools are the agent's tools, with two
+    built-in tools: ``ask_user`` asks the user a question, and ``write_todos``
+    keeps the session's plan. Plan mode is on, so a ``plan_mode`` message
+    drafts a plan with ``write_todos`` and ``execute_plan`` runs it. Both
+    built-in names are reserved: no connector or local tool may use them.
+
+    .. versionchanged:: 0.6.0
+       Plan mode is on, and the agent has the ``write_todos`` built-in tool.
+    """
+
+    name = "builtin"
+    config_section = "builtin"
+    flow_type = BUILTIN_CLI_FLOW_TYPE
+    default_model: str | None = DEFAULT_BUILTIN_MODEL
+    replaced_local_tools: frozenset[LocalToolGroup] = frozenset()
+
+    def create_session_flow(self, context: HarnessContext) -> AgentSessionFlow:
+        """Build the built-in loop agent session Flow from the effective configuration.
+
+        Args:
+            context: The configuration, workspace, and tool sources.
+
+        Returns:
+            The Flow, with ``context.flow_type`` as its type.
+
+        Raises:
+            ConfigError: If the ``builtin`` section has a key; it has no options yet.
+        """
+        validate_builtin_section(context.harness_options)
+        models: dict[str, LiteLLMModelClient] = {}
+
+        def resolve_model(session_settings: Mapping[str, Any]) -> LiteLLMModelClient:
+            model_name = context.resolve_turn(session_settings).model
+            if model_name not in models:
+                models[model_name] = LiteLLMModelClient(model_name)
+            return models[model_name]
+
+        def instructions(instruction_context: InstructionContext) -> str:
+            turn = context.resolve_turn(instruction_context.session_settings)
+            return turn.instructions or DEFAULT_INSTRUCTIONS
+
+        definition = AgentDefinition(
+            name="builtin",
+            instructions=instructions,
+            model=LiteLLMModelClient(context.config.model),
+            resolve_model=resolve_model,
+            tool_sources=list(context.tool_sources),
+            built_in_tools=frozenset({BuiltInTool.ASK_USER, BuiltInTool.WRITE_TODOS}),
+            plan_mode_enabled=True,
+        )
+        return builtin_agent_session_flow(
+            definition,
+            flow_type=context.flow_type,
+            media_store=context.media_store,
+            summary_attributes_indexed=context.is_session_summary_indexed,
+        )
+
+
+def validate_builtin_section(options: Mapping[str, Any]) -> None:
+    """Reject every key of the ``builtin`` section, which has no options yet.
+
+    Args:
+        options: The section, ``{}`` when the file omits it.
+
+    Raises:
+        ConfigError: ``schema`` with the first key's JSON Pointer.
+    """
+    for key in sorted(options):
+        escaped = key.replace("~", "~0").replace("/", "~1")
+        raise ConfigError("schema", f"/builtin/{escaped}", keyword="additionalProperties")

dex_agents_builtin_cli-0.6.0.dist-info/METADATA

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: dex-agents-builtin-cli
+Version: 0.6.0
+Summary: The dex-agents-builtin command: a durable Dex built-in loop agent in your terminal
+Author: Super Durable
+License-Expression: LicenseRef-Sustainable-Use-1.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Dist: dex-agents[litellm]==0.6.0
+Requires-Dist: dex-agents-cli-core==0.6.0
+Requires-Dist: dex-python-sdk==1.45.0
+Requires-Dist: litellm>=1.104,<1.106
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/superdurable/dex/tree/main/agents/cli/python/builtin
+Project-URL: Repository, https://github.com/superdurable/dex
+Project-URL: Changelog, https://github.com/superdurable/dex/blob/main/agents/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# dex-agents-builtin-cli
+
+`dex-agents-builtin-cli` provides the `dex-agents-builtin` command. It runs
+the Dex built-in agent loop as a durable Dex agent session
+and chats with it in your terminal. No agent framework is involved: the
+session's own `RunModel` Step makes one model call through
+[LiteLLM](https://docs.litellm.ai/), and every tool call runs in its own Dex
+tool Step. The shared CLI core, [`dex-agents-cli-core`](../core/README.md),
+starts or reuses `dexcli dev`, connects the connectors MCP server, and runs
+the Worker. This package only builds the built-in loop agent with the
+[core's LiteLLM model client](../../../python/core/README.md).
+
+## Running it
+
+The command needs Python 3.11 or later and a key for the model's provider:
+
+```bash
+export OPENAI_API_KEY=sk-...
+uvx --from dex-agents-builtin-cli dex-agents-builtin
+```
+
+The first run asks the `init` questions and writes
+`~/.dex/agents/builtin.yaml`. Then type a message at the `>` prompt. Approve
+or reject tool calls with `y` or `n`, answer the agent's questions, and press
+Ctrl-D to exit. The session stays in Dex, and the command prints the
+`--resume` line that continues it. See the
+[CLI core README](../core/README.md#running-a-command) for every subcommand
+and option, and [`agents/cli`](../../README.md) for the configuration file.
+
+LiteLLM reads each provider's standard environment variables, such as
+`OPENAI_API_KEY` and `OPENAI_BASE_URL` for `openai/` models and
+`ANTHROPIC_API_KEY` for `anthropic/` models. The command never prints or
+stores a key.
+
+## Configuration
+
+The model defaults to `openai/gpt-5.2`; set `model` in the file or pass
+`--model` to change it. It is a LiteLLM model name, `<provider>/<model>`, such
+as `anthropic/claude-opus-5-5`. A session's settings may change the model and
+the instructions; each model call uses the values of its turn.
+`system_prompt` replaces the default instructions. The `builtin` section has
+no options yet, and any key in it is a configuration error.
+
+## Tools
+
+The agent's tools are the CLI core's: its local tool source and the connector
+tools of the connectors MCP server. Every call runs in its own Dex tool Step,
+with the CLI core's policy. Reads run at once, file writes and shell commands
+wait for approval unless the shell allow list has the command, and the file
+tools stay in the workspace. See the
+[CLI core README](../core/README.md) for the local tools.
+
+The agent also has two built-in tools that the session runs itself:
+
+- `ask_user` asks you a question, and the turn waits for your answer.
+- `write_todos` replaces the session's plan, a short task list, with no
+  approval.
+
+Plan mode is on. Use it through the terminal UI (`dexcli agents-tui`) or the
+session API, not the plain chat, which sends `/plan` and `/run` as ordinary
+messages. In the terminal UI, `/plan <message>` starts a planning turn: the
+agent drafts a plan with `write_todos` and uses no other tool. `/run` approves
+the draft, and the agent runs it with every tool.
+
+The names `ask_user` and `write_todos` are reserved, so a connector or local
+tool with one of these names fails the turn. This is a breaking change for
+such a tool: rename the conflicting connector or local tool, or use another
+harness.
+
+## Development
+
+Develop with uv 0.12.2. The package resolves `dex-agents` and the CLI core
+from this repository by path. `uv.lock` pins `litellm` to the version the
+core's lock pins, and `ci.sh` checks that. `ci.sh` installs the locked
+dependencies, checks lint and types, and runs the tests against a private
+`dexcli dev`:
+
+```bash
+cd agents/cli/python/builtin
+DEXCLI=/path/to/dexcli ./ci.sh
+```
+
+The tests run the command in a pseudo-terminal with a private home and an
+allow-listed environment. LiteLLM sends `openai/` models to the scripted
+Responses API of [`../testing`](../testing); a refused proxy stops any other
+request. A fake connectors MCP server serves a connector read and write. The
+tests cover a chat turn and `--resume`, `read_file` without approval and
+`write_file` after approval, a connector read and an approved connector write
+that runs once, session settings that change the model, and a key in the
+`builtin` section.
+They also cover a `system_prompt` set in the session settings, which reaches
+the next model request, and a rejected file write and connector write, which
+never run.

dex_agents_builtin_cli-0.6.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+dex_agents_builtin_cli/__init__.py,sha256=h9jW9WUehJCUdNXpizlZ11d_ygSXGmNhd_wr10hFz_0,1744
+dex_agents_builtin_cli/__main__.py,sha256=m4GBP6qOCphOjsVEJyk8hfJCuHmexevCxj0zMHo0-Ms,430
+dex_agents_builtin_cli/harness.py,sha256=l_eAIbbFZA9ECzZYm9bPAStLieSghxgpVF2wJLjXseM,4496
+dex_agents_builtin_cli/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dex_agents_builtin_cli-0.6.0.dist-info/licenses/LICENSE,sha256=0AJCV4ky-vrSnT08IIdYpyiFPPoF2UrtKsBAvuvt1G4,4220
+dex_agents_builtin_cli-0.6.0.dist-info/WHEEL,sha256=q9Wah2_CgP24mRNSlTyb0F8Yrbz55SzVl8eHLkZ_wvE,80
+dex_agents_builtin_cli-0.6.0.dist-info/entry_points.txt,sha256=lEEqNep3vNpoyKo3qmXAh05p8etqh5rL6bbOLaXJSzk,67
+dex_agents_builtin_cli-0.6.0.dist-info/METADATA,sha256=35_CqdP_9Z02kclAYoTyggmJwMdl42d7jtdnGGnswEc,5225
+dex_agents_builtin_cli-0.6.0.dist-info/RECORD,,

dex_agents_builtin_cli-0.6.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.2
+Root-Is-Purelib: true
+Tag: py3-none-any

dex_agents_builtin_cli-0.6.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+dex-agents-builtin = dex_agents_builtin_cli:run
+

dex_agents_builtin_cli-0.6.0.dist-info/licenses/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.