switchplane 0.1.0__tar.gz

switchplane-0.1.0/.github/labeler.yml

@@ -0,0 +1,21 @@
+feature:
+  - head-branch: ['^feat/', '^feature/']
+
+bug:
+  - head-branch: ['^fix/', '^bug/']
+
+docs:
+  - changed-files:
+    - any-glob-to-any-file: ['docs/**', '*.md']
+
+tests:
+  - changed-files:
+    - any-glob-to-any-file: ['tests/**']
+
+ci:
+  - changed-files:
+    - any-glob-to-any-file: ['.github/**']
+
+examples:
+  - changed-files:
+    - any-glob-to-any-file: ['examples/**']

switchplane-0.1.0/.github/release.yml

@@ -0,0 +1,20 @@
+changelog:
+  exclude:
+    labels:
+      - skip-changelog
+  categories:
+    - title: Breaking Changes
+      labels:
+        - breaking
+    - title: Features
+      labels:
+        - feature
+    - title: Bug Fixes
+      labels:
+        - bug
+    - title: Documentation
+      labels:
+        - docs
+    - title: Other Changes
+      labels:
+        - "*"

switchplane-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,45 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Install dependencies
+        run: |
+          uv venv
+          make install-test
+      - name: Check formatting
+        run: make formatcheck
+      - name: Check linting
+        run: make static
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: |
+          uv venv --python ${{ matrix.python-version }}
+          make install-test
+
+      - name: Run tests
+        run: make test

switchplane-0.1.0/.github/workflows/labeler.yml

@@ -0,0 +1,16 @@
+name: Labeler
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  label:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/labeler@v5
+        with:
+          configuration-path: .github/labeler.yml

switchplane-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,66 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check version matches tag
+        run: |
+          TAG="${GITHUB_REF#refs/tags/v}"
+          PKG_VERSION=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
+          if [ "$TAG" != "$PKG_VERSION" ]; then
+            echo "::error::Tag v${TAG} does not match package version ${PKG_VERSION}"
+            exit 1
+          fi
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: true
+      matrix:
+        python-version: ["3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          uv venv --python ${{ matrix.python-version }}
+          make install-test
+      - name: Run tests
+        run: make test
+
+  build:
+    needs: [validate, test]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build package
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

switchplane-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+
+# Virtual environment
+.venv/
+
+# uv
+uv.lock
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+
+# Switchplane runtime
+*.db
+*.sock
+*.pid
+
+# testing
+.tmp/*
+.coverage

switchplane-0.1.0/CLAUDE.md

@@ -0,0 +1,150 @@
+# CLAUDE.md — Switchplane
+
+## What is this project?
+
+Switchplane is a Python runtime control plane for agent-based task execution. It is LangGraph-native — tasks are defined as LangGraph StateGraph graphs. Each app built with Switchplane becomes a standalone CLI with its own isolated daemon and runtime directory.
+
+## Architecture in one sentence
+
+Each app gets its own CLI that sends requests over a Unix socket to a per-app daemonized control plane, which spawns agent subprocesses that communicate bidirectionally over a per-agent Unix socketpair using length-prefixed JSON framing.
+
+## Project layout
+
+```
+src/switchplane/           # Main package (pip-installable)
+  __init__.py              # Public API re-exports: Application, Shell, Task, command, Field
+  app.py                   # Application container and McpServerConfig
+  shell.py                 # Sandboxed subprocess execution with path/command allowlists, LangChain tool factory
+  agent.py                 # AgentSpec and AgentRecord models
+  task.py                  # Task ABC, TaskRecord, TaskStatus, @command decorator, parameter introspection
+  protocol.py              # IPC message types: CliRequest/Response, AgentEvent/Command
+  transport.py             # Unix socket server (async) + client (sync), 4-byte length-prefixed framing
+  persistence.py           # SQLite Store (aiosqlite, WAL mode) — tasks, agents, events tables
+  checkpoint.py            # LangGraph BaseCheckpointSaver backed by SQLite
+  discovery.py             # Agent/task discovery via module import (no entry point discovery)
+  daemon.py                # Daemonization (double-fork), signal handling, idle timer, RuntimePaths
+  control_plane.py         # Central orchestrator — request dispatch, single app, idle shutdown
+  subprocess_manager.py    # Agent subprocess lifecycle — socketpair creation, event reading, command sending
+  agent_runtime.py         # Runs inside agent subprocess — AgentContext, bidirectional IPC over socketpair
+  cli.py                   # Click CLI factory — build_cli(app) generates run, runtime, agent, task command groups
+  tui.py                   # prompt_toolkit full-screen TUI — tab-based task viewer with system tab [0]
+  fmt.py                   # Shared formatting utilities (e.g. tree rendering for detail payloads)
+  config.py                # TOML config loading — cascading: app defaults + user overrides
+
+  mcp.py                   # MCP client lifecycle: McpSession, McpManager, LangChain tool wrapper
+
+examples/hello/        # Simple LangGraph graph (get_user → say_hello)
+examples/weather/      # Long-running polling task (Open-Meteo weather watch, @command for coordinates)
+examples/devops/       # Ops review: deterministic pandas analysis + LLM summary
+examples/chatbot/      # Interactive LLM chat with interrupts
+tests/                     # Test directory (pytest)
+```
+
+## Key design rules
+
+- **The control plane owns task/event persistence.** Agents write only checkpoint data via a separate WAL-mode connection.
+- **The control plane never runs domain logic.** All user code runs inside agent subprocesses.
+- **Tasks are first-class.** Agents are just execution hosts. Every task has an ID, status, events, and stored results.
+- **LangGraph-native.** Do not introduce generic workflow abstractions. Tasks use LangGraph StateGraph directly.
+- **One app per runtime.** Each Application gets its own daemon, database, and socket.
+
+## Application entry point
+
+`Application(name="myapp")` creates an app. `app.discover_agents("myapp.agents")` registers discovery roots. `app.run()` discovers agents, builds the CLI, and starts it. The `name` determines the runtime directory (`~/.myapp/`). The CLI entry point is registered via `[project.scripts]` in pyproject.toml.
+
+## Configuration
+
+Two-layer cascading TOML config. App-bundled defaults (specified via `Application(default_config=Path(...))`) are deep-merged with user-level overrides at `~/.{app_name}/config.toml`. User config wins on conflict. Apps ship base URLs, model defaults, and agent settings; users provide personal config like API keys. Pydantic model: `AppConfig` with `LLMConfig` and per-agent dicts. Config is passed to agent subprocesses via the `execute_task` command payload and available as `ctx.config` in the agent runtime.
+
+## How to run
+
+```bash
+# Setup
+uv venv .venv && source .venv/bin/activate
+uv pip install -e . -e examples/hello -e examples/weather -e examples/devops -e examples/chatbot
+
+# Run a task (streams events inline, Ctrl+C detaches)
+hello run example hello --name Alice
+
+# Run detached
+weather run weather watch -d
+
+# Bare app invocation opens the full-screen TUI (auto-discovers running tasks)
+hello
+
+# Operator commands
+hello runtime start|stop|status
+hello task list|show|cancel|follow|resume|clear
+hello agent list
+
+# Send command to running task
+weather task <task_id> <command> [--key value ...]
+```
+
+## CLI and TUI
+
+**CLI** is always plain-text. `run`, `follow`, and `resume` stream events inline and support interactive command input (stdin reader thread). The TUI is **only** launched on a bare `<app>` call with a TTY. Non-TTY invocations always get plain text.
+
+**TUI** (`tui.py`) is a full-screen prompt_toolkit app with tab-based navigation. Tab `[0] system` is always present and receives daemon command output. Task tabs start at `[1]`. The shared arg parser `_parse_kv_args` lives in `tui.py` and is imported by `cli.py`.
+
+**Input prefixes** use a three-tier scheme designed to reserve freeform text for future interactive LLM tasks:
+- `:` prefix → daemon commands: `:run`, `:task follow <id>`, `:runtime status`, `:agent list`, `:help`
+- `/` prefix → task commands on the focused task: `/set_location --lat 40.7`
+- Plain text → reserved for future freeform LLM interaction (currently shows a hint)
+
+In CLI attached mode (`run`/`follow`/`resume`), only `/` task commands are supported inline. Daemon commands are not available — detach with Ctrl+C and use CLI subcommands directly.
+
+**Event buffers** are capped at a configurable `max_buffer_lines` (default 10,000) per tab to bound memory in long-running sessions.
+
+## Build system
+
+- **uv** for package management
+- **hatchling** build backend
+- No global CLI entry point — each app defines its own via `[project.scripts]`
+- Virtual environment at `.venv/`
+
+## Dependencies
+
+click, pydantic v2, aiosqlite, langgraph, prompt_toolkit, structlog. Optional: `langchain-core` via `switchplane[llm]`; `mcp` + `langchain-core` via `switchplane[mcp]`. Example-specific: langchain-anthropic (devops, chatbot), httpx (weather), pandas + numpy (devops).
+
+## IPC protocols
+
+**CLI ↔ Control Plane:** Unix socket at `~/.{app_name}/runtime.sock`. Messages are 4-byte big-endian length prefix + JSON body. Types: `CliRequest` / `CliResponse`.
+
+**Agent ↔ Control Plane:** Bidirectional over a per-agent Unix socketpair (`socket.socketpair(AF_UNIX)`). The CP creates the pair, passes one fd to the child via `--ipc-fd` + `pass_fds`. Same 4-byte length-prefixed JSON framing as CLI protocol. CP sends `AgentCommand`, agent sends `AgentEvent`. This allows mid-execution cancel/shutdown — the agent runs a command listener concurrently with task execution. stdout/stderr are freed for normal logging.
+
+## Database
+
+SQLite at `~/.{app_name}/state.db` with WAL mode. Tables: `agents`, `tasks`, `events`, `checkpoints`, `checkpoint_writes`. Use Pydantic v2 `model_dump_json()` / `model_validate_json()` for JSON columns.
+
+## Adding a task
+
+1. Create a task module at `<app>/agents/<agent>/tasks/<task>.py`
+2. Subclass `Task` from `switchplane` — set `name`, `description`, and optionally `mode` (`"ephemeral"` or `"long_running"`) class attributes
+3. Declare parameters as class attributes using `Field()` from `switchplane` (re-exported from Pydantic). Parameters are validated before execution and set as instance attributes.
+4. Implement `async def run(self, ctx: AgentContext)` — access params via `self.<param>`, build a LangGraph `StateGraph`, compile, `ainvoke`, then `ctx.complete(result)`
+5. Optionally add `@command`-decorated methods for runtime commands on long-running tasks. Command parameters are typed and auto-coerced.
+6. Discovery auto-registers the task from the `tasks/` subpackage — no need to declare it in `AgentSpec`
+
+## MCP integration
+
+MCP servers are registered at the app level via `McpServerConfig` (provide `command` for stdio, `url` for HTTP — transport is inferred). Agents declare which servers they need via `AgentSpec.mcp_servers`. The agent runtime manages client lifecycle (spawning stdio processes or connecting to HTTP endpoints) and exposes tools via `ctx.mcp` (raw sessions) and `ctx.mcp_tools()` (LangChain `StructuredTool` wrappers). MCP is an optional dependency: `pip install switchplane[mcp]`.
+
+## Checkpoint and resume
+
+Tasks opt into checkpointing by passing `ctx.checkpointer` to `graph.compile(checkpointer=ctx.checkpointer)` and using `ctx.task_id` as the LangGraph thread ID. The checkpointer is a `SqliteCheckpointSaver` backed by the app's `state.db` — each agent subprocess opens its own connection in WAL mode. LangGraph saves state after each node; on resume, it finds the existing checkpoint by thread ID and continues from the last completed node.
+
+Resume flow: CLI sends `resume_task` request → control plane validates terminal status (failed/cancelled/completed) → resets to PENDING → re-launches with the same task ID. The `task resume <task_id>` CLI command handles this. Tasks that don't use `ctx.checkpointer` run without checkpointing and will re-execute from the beginning on resume.
+
+## Testing
+
+```bash
+make test
+```
+
+## Style
+
+- Python 3.12+ type annotations (use `X | None` not `Optional[X]`)
+- Pydantic v2 (`model_dump()` not `.dict()`, `model_validate()` not `parse_obj()`)
+- asyncio throughout the control plane; sync only in CLI client and daemon bootstrap
+- Minimal abstractions — prefer direct code over premature generalization

switchplane-0.1.0/CODEOWNERS

@@ -0,0 +1,3 @@
+# Comment line immediately above ownership line is reserved for related other information. Please be careful while editing.
+#ECCN:Open Source
+#GUSINFO:

switchplane-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,105 @@
+# Salesforce Open Source Community Code of Conduct
+
+## About the Code of Conduct
+
+Equality is a core value at Salesforce. We believe a diverse and inclusive
+community fosters innovation and creativity, and are committed to building a
+culture where everyone feels included.
+
+Salesforce open-source projects are committed to providing a friendly, safe, and
+welcoming environment for all, regardless of gender identity and expression,
+sexual orientation, disability, physical appearance, body size, ethnicity, nationality, 
+race, age, religion, level of experience, education, socioeconomic status, or 
+other similar personal characteristics.
+
+The goal of this code of conduct is to specify a baseline standard of behavior so
+that people with different social values and communication styles can work
+together effectively, productively, and respectfully in our open source community.
+It also establishes a mechanism for reporting issues and resolving conflicts.
+
+All questions and reports of abusive, harassing, or otherwise unacceptable behavior
+in a Salesforce open-source project may be reported by contacting the Salesforce
+Open Source Conduct Committee at ossconduct@salesforce.com.
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of gender 
+identity and expression, sexual orientation, disability, physical appearance, 
+body size, ethnicity, nationality, race, age, religion, level of experience, education, 
+socioeconomic status, or other similar personal characteristics.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy toward other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Personal attacks, insulting/derogatory comments, or trolling
+* Public or private harassment
+* Publishing, or threatening to publish, others' private information—such as
+a physical or electronic address—without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+professional setting
+* Advocating for or encouraging any of the above behaviors
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned with this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project email
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the Salesforce Open Source Conduct Committee 
+at ossconduct@salesforce.com. All complaints will be reviewed and investigated 
+and will result in a response that is deemed necessary and appropriate to the 
+circumstances. The committee is obligated to maintain confidentiality with 
+regard to the reporter of an incident. Further details of specific enforcement 
+policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership and the Salesforce Open Source Conduct 
+Committee.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][contributor-covenant-home],
+version 1.4, available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.html. 
+It includes adaptions and additions from [Go Community Code of Conduct][golang-coc], 
+[CNCF Code of Conduct][cncf-coc], and [Microsoft Open Source Code of Conduct][microsoft-coc].
+
+This Code of Conduct is licensed under the [Creative Commons Attribution 3.0 License][cc-by-3-us].
+
+[contributor-covenant-home]: https://www.contributor-covenant.org (https://www.contributor-covenant.org/)
+[golang-coc]: https://golang.org/conduct
+[cncf-coc]: https://github.com/cncf/foundation/blob/master/code-of-conduct.md
+[microsoft-coc]: https://opensource.microsoft.com/codeofconduct/
+[cc-by-3-us]: https://creativecommons.org/licenses/by/3.0/us/

switchplane-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,83 @@
+# Contributing Guide For switchplane
+
+This page lists the operational governance model of this project, as well as the recommendations and requirements for how to best contribute to {PROJECT}. We strive to obey these as best as possible. As always, thanks for contributing – we hope these guidelines make it easier and shed some light on our approach and processes.
+
+# Governance Model
+
+## Community Based
+
+The intent and goal of open sourcing this project is to increase the contributor and user base. The governance model is one where new project leads (`admins`) will be added to the project based on their contributions and efforts, a so-called "do-acracy" or "meritocracy" similar to that used by all Apache Software Foundation projects.
+
+# Issues, requests & ideas
+
+Use GitHub Issues page to submit issues, enhancement requests and discuss ideas.
+
+### Bug Reports and Fixes
+-  If you find a bug, please search for it in the [Issues](https://github.com/salesforce-misc/switchplane/issues), and if it isn't already tracked,
+   [create a new issue](https://github.com/salesforce-misc/switchplane/issues/new). Fill out the "Bug Report" section of the issue template. Even if an Issue is closed, feel free to comment and add details, it will still
+   be reviewed.
+-  Issues that have already been identified as a bug (note: able to reproduce) will be labelled `bug`.
+-  If you'd like to submit a fix for a bug, [send a Pull Request](#creating_a_pull_request) and mention the Issue number.
+  -  Include tests that isolate the bug and verifies that it was fixed.
+
+### New Features
+-  If you'd like to add new functionality to this project, describe the problem you want to solve in a [new Issue](https://github.com/salesforce-misc/switchplane/issues/new).
+-  Issues that have been identified as a feature request will be labelled `enhancement`.
+-  If you'd like to implement the new feature, please wait for feedback from the project
+   maintainers before spending too much time writing the code. In some cases, `enhancement`s may
+   not align well with the project objectives at the time.
+
+### Tests, Documentation, Miscellaneous
+-  If you'd like to improve the tests, you want to make the documentation clearer, you have an
+   alternative implementation of something that may have advantages over the way its currently
+   done, or you have any other change, we would be happy to hear about it!
+  -  If its a trivial change, go ahead and [send a Pull Request](#creating_a_pull_request) with the changes you have in mind.
+  -  If not, [open an Issue](https://github.com/salesforce-misc/switchplane/issues/new) to discuss the idea first.
+
+If you're new to our project and looking for some way to make your first contribution, look for
+Issues labelled `good first contribution`.
+
+# Contribution Checklist
+
+- [x] Clean, simple, well styled code
+- [x] Commits should be atomic and messages must be descriptive. Related issues should be mentioned by Issue number.
+- [x] Comments
+  - Module-level & function-level comments.
+  - Comments on complex blocks of code or algorithms (include references to sources).
+- [x] Tests
+  - The test suite, if provided, must be complete and pass
+  - Increase code coverage, not versa.
+  - Use any of our testkits that contains a bunch of testing facilities you would need. For example: `import com.salesforce.op.test._` and borrow inspiration from existing tests.
+- [x] Dependencies
+  - Minimize number of dependencies.
+  - Prefer Apache 2.0, BSD3, MIT, ISC and MPL licenses.
+- [x] Reviews
+  - Changes must be approved via peer code review
+
+# Creating a Pull Request
+
+1. **Ensure the bug/feature was not already reported** by searching on GitHub under Issues.  If none exists, create a new issue so that other contributors can keep track of what you are trying to add/fix and offer suggestions (or let you know if there is already an effort in progress).
+2. **Clone** the forked repo to your machine.
+3. **Create** a new branch to contain your work (e.g. `git br fix-issue-11`)
+4. **Commit** changes to your own branch.
+5. **Push** your work back up to your fork. (e.g. `git push fix-issue-11`)
+6. **Submit** a Pull Request against the `main` branch and refer to the issue(s) you are fixing. Try not to pollute your pull request with unintended changes. Keep it simple and small.
+7. **Sign** the Salesforce CLA (you will be prompted to do so when submitting the Pull Request)
+
+> **NOTE**: Be sure to [sync your fork](https://help.github.com/articles/syncing-a-fork/) before making a pull request.
+
+# Contributor License Agreement ("CLA")
+In order to accept your pull request, we need you to submit a CLA. You only need
+to do this once to work on any of Salesforce's open source projects.
+
+Complete your CLA here: <https://cla.salesforce.com/sign-cla>
+
+# Issues
+We use GitHub issues to track public bugs. Please ensure your description is
+clear and has sufficient instructions to be able to reproduce the issue.
+
+# Code of Conduct
+Please follow our [Code of Conduct](CODE_OF_CONDUCT.md).
+
+# License
+By contributing your code, you agree to license your contribution under the terms of our project [LICENSE](LICENSE.txt) and to sign the [Salesforce CLA](https://cla.salesforce.com/sign-cla)