synapse-cli-agent 0.1.44__tar.gz → 0.1.45__tar.gz

synapse_cli_agent-0.1.45/.github/workflows/ci.yml

@@ -0,0 +1,123 @@
+name: CI
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: ruff check
+        run: uv run ruff check src tests
+
+  test:
+    needs: lint
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync
+
+  web-console:
+    name: Build Web Console
+    needs: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+
+      - name: Install web dependencies
+        working-directory: web
+        run: npm ci
+
+      - name: Build the web console
+        working-directory: web
+        run: npm run build
+
+      - name: Upload Web Console distribution
+        uses: actions/upload-artifact@v4
+        with:
+          name: web-console-dist
+          path: web/dist/
+          if-no-files-found: error
+
+  # The runtime contract gate runs once on ubuntu instead of in the
+  # Windows/Linux x 3.12/3.13 matrix: it is platform-neutral (a byte-for-byte
+  # artifact check plus static gates) and the Node half would otherwise repeat
+  # four times.  Only the targeted contract/architecture/compatibility tests run
+  # here; the full pytest suite stays out of CI on purpose.
+  contract:
+    needs: lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Verify generated contract artifacts
+        run: uv run --no-sync python scripts/export_contract_manifest.py --check
+
+      - name: Contract, architecture, and compatibility tests
+        run: >-
+          uv run --no-sync pytest
+          tests/test_runtime_contract_manifest.py
+          tests/test_runtime_architecture_boundaries.py
+          tests/test_runtime_service_import_purity.py
+          tests/test_runtime_transport_client_compatibility.py
+          -q
+
+      # Node >= 22.18 (or 24) strips TypeScript natively, so the node:test
+      # suites run the .ts sources directly with no transpiler step.
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+
+      - name: Install web dependencies
+        working-directory: web
+        run: npm ci
+
+      - name: Type-check the web console
+        working-directory: web
+        run: npx tsc -b
+
+      - name: Contract, boundary, and source guard tests
+        working-directory: web
+        run: >-
+          node --test
+          tests/runtimeContractFixture.test.ts
+          tests/runtimeClientBoundary.test.ts
+          tests/sourceGuard.test.ts

synapse_cli_agent-0.1.45/.github/workflows/release.yml

@@ -0,0 +1,230 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  web-console:
+    name: Build Web Console
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          cache: npm
+          cache-dependency-path: web/package-lock.json
+
+      - name: Install web dependencies
+        working-directory: web
+        run: npm ci
+
+      - name: Build the web console
+        working-directory: web
+        run: npm run build
+
+      - name: Upload Web Console distribution
+        uses: actions/upload-artifact@v4
+        with:
+          name: web-console-dist
+          path: web/dist/
+          if-no-files-found: error
+
+  build:
+    needs: web-console
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download Web Console distribution
+        uses: actions/download-artifact@v4
+        with:
+          name: web-console-dist
+          path: web/dist
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Extract changelog section
+        run: |
+          VERSION="${GITHUB_REF#refs/tags/}" python -c "
+          import os, re
+          ver = os.environ['VERSION']
+          with open('CHANGELOG.md', 'r', encoding='utf-8') as f:
+              content = f.read()
+          pattern = rf'(?ms)^## {re.escape(ver)}\n.*?(?=\n## |\Z)'
+          m = re.search(pattern, content)
+          if m:
+              out = m.group().strip()
+              with open('release_body.md', 'w', encoding='utf-8') as f:
+                  f.write(out)
+              print(f'Extracted {len(out)} chars for {ver}')
+          else:
+              raise SystemExit(f'ERROR: ## {ver} section not found in CHANGELOG.md')
+          "
+
+      - name: Build distributions
+        run: uv build
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Upload changelog body
+        uses: actions/upload-artifact@v4
+        with:
+          name: release-body
+          path: release_body.md
+          if-no-files-found: error
+
+  build-executables:
+    name: executable (${{ matrix.name }})
+    needs: web-console
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: windows
+            os: windows-latest
+            artifact: executable-windows
+            binname: synapse-windows-x64.exe
+          # macOS executables target Apple Silicon only; Intel macOS is unsupported
+          # (matches the native-core-tool wheels matrix).
+          - name: macos
+            os: macos-latest
+            artifact: executable-macos
+            binname: synapse-macos-arm64
+          - name: linux
+            os: ubuntu-latest
+            artifact: executable-linux
+            binname: synapse-linux-x64
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Download Web Console distribution
+        uses: actions/download-artifact@v4
+        with:
+          name: web-console-dist
+          path: web/dist
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Install dependencies (builds local synapse-core-tool and synapse-tool-compress-core)
+        run: uv sync --frozen
+
+      - name: Install PyInstaller
+        run: uv pip install pyinstaller
+
+      - name: Package executable with PyInstaller
+        shell: pwsh
+        run: |
+          $dataSep = if ($env:RUNNER_OS -eq 'Windows') { ';' } else { ':' }
+          uv run pyinstaller --noconfirm --clean --onefile --name synapse `
+            --paths src `
+            --add-data "web/dist${dataSep}synapse/web_console/static" `
+            --collect-all textual `
+            --collect-all textual_serve `
+            --collect-all textual_image `
+            --collect-all termaid `
+            --collect-all texicode `
+            --collect-all synapse_tool_compress_core `
+            --collect-data synapse `
+            src/synapse/entry.py
+
+      - name: Rename executable for artifact
+        shell: pwsh
+        run: |
+          $ext = if ($env:RUNNER_OS -eq 'Windows') { '.exe' } else { '' }
+          # Rename-Item refuses a destination that contains a path separator
+          # (pwsh treats it as a device path); Move-Item -LiteralPath is safe.
+          Move-Item -LiteralPath "dist/synapse$ext" -Destination "dist/${{ matrix.binname }}"
+          Write-Host "Renamed to ${{ matrix.binname }}"
+
+      - name: Fix executable permission (Unix)
+        if: runner.os != 'Windows'
+        run: chmod +x "dist/${{ matrix.binname }}"
+
+      - name: Generate SHA256 checksum
+        shell: pwsh
+        run: |
+          $hash = (Get-FileHash -Algorithm SHA256 -LiteralPath "dist/${{ matrix.binname }}").Hash.ToLower()
+          Set-Content -LiteralPath "dist/${{ matrix.binname }}.sha256" -Value $hash -NoNewline
+          Write-Host "sha256 for ${{ matrix.binname }}: $hash"
+
+      - name: Upload executable artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.artifact }}
+          path: |
+            dist/${{ matrix.binname }}
+            dist/${{ matrix.binname }}.sha256
+          if-no-files-found: error
+
+  release:
+    needs: [build, build-executables]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist
+
+      - name: Download executable artifacts
+        uses: actions/download-artifact@v4
+        with:
+          pattern: executable-*
+          merge-multiple: true
+          path: executables
+
+      - name: Download changelog body
+        uses: actions/download-artifact@v4
+        with:
+          name: release-body
+          path: .
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            dist/*
+            executables/*
+          body_path: release_body.md
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/synapse-cli-agent
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

synapse_cli_agent-0.1.45/.gitignore

@@ -0,0 +1,66 @@
+# Rust build artifacts
+**/target/
+
+# Python-generated files
+__pycache__/
+*.py[oc]
+*.pyd
+*.pdb
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Local env / agent state
+.env
+.coding-agent/
+.cmd-agent/
+.tmp/
+.tmp-pytest/
+.synapse/
+*.sqlite
+*.sqlite3
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Agent transient output
+large_tool_results/
+conversation_history/
+
+# Local misc files (unrelated to the repo)
+/ear-anatomy-exploded.html
+/ear-models/
+
+# Local scratch output (untracked scratch files)
+/article-translation/
+/article_ltt.html
+/twitter-replica/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# Runtime logs
+logs/
+site/
+
+# Benchmark evaluation artifacts (local, not part of the repo)
+benchmark21/
+jobs/
+tmp/
+harbor_eval/
+landing/
+
+# OS
+Thumbs.db
+.DS_Store.tmp/
+
+# Local release executables (build artifacts, not committed)
+synapse-*.exe

synapse_cli_agent-0.1.45/AGENTS.md

@@ -0,0 +1,102 @@
+# Synapse Collaboration Guide
+
+## Architecture
+
+- Domain packages live under `src/synapse/` (each `synapse.<package>`); their tests are flat files named after the domain under `tests/` (`tests/test_<area>*.py`, plus `tests/fixtures/`) — do not add per-package subdirectories there. Rust/PyO3 crates live under `rust/`; the MkDocs site lives under `docs/` + `mkdocs.yml`.
+- Repository Agent Skills live in `skills/<name>/SKILL.md` (YAML front matter: `name`, `description`, `license`, `compatibility`, `allowed_tools`). The default `skills_paths` is `["skills"]` relative to the project root (`src/synapse/settings/schema.py`); `src/synapse/content/skills_catalog.py` discovers them and feeds `/skills`, and `docs/skills.md` documents the feature. `skills/` is excluded from the sdist (`[tool.hatch.build.targets.sdist]`), so the skills travel with the checkout, not with the wheel. Keep the front matter accurate — it is what the catalog surfaces.
+- `src/synapse/app/agent.py` is the assembly composition root; the reusable assembly contracts (middleware build, typed resource wiring) live in `src/synapse/app/agent_assembly.py`. Keep domain algorithms in their own packages.
+- New features belong in the matching domain package; cross-domain wiring goes in `app/` or an explicit runtime middleware.
+- Console-script entry points live in `src/synapse/entry.py` (`synapse`), `src/synapse/web.py` (`synapse-web`, textual-serve TUI in the browser), `src/synapse/web_console/entry.py` (`synapse-web-console`, loopback React console host), `src/synapse/acp/server.py` (`synapse-acp`), and `src/synapse/runtime/daemon/entry.py` (`synapse-runtime`). Keep entry modules thin; delegate to a domain package. These scripts only exist after an install/sync step (`uv sync`); in a stale source checkout run the module form (`python -m synapse.web_console.entry`) instead, and start the console host/daemon detached with redirected stdout/stderr — see `README.md` section "Web 控制台".
+- `config.py`, `models_registry.py`, and `subagents.py` are compatibility re-export layers. Import from `synapse.settings`, `synapse.models.registry`, or `synapse.runtime.subagent_specs`/`synapse.runtime.subagents` in new code; keep legacy import paths working.
+- `__init__.py` exports are public API. Keep necessary re-exports when moving implementations.
+- Config merges user and project layers. When changing Settings, update `src/synapse/settings/schema.py`, `src/synapse/settings/config_paths.py`, `tests/test_config.py`, `tests/test_layered_config.py`, and the user docs (`README.md`, `docs/config.md`).
+- `AGENTS.md` is statically injected by the agent-md middleware (`src/synapse/app/agent_md.py`), independent of writable memory; never route it back into memory writes.
+- The browser console frontend lives in `web/` (React 19 + TypeScript + Vite, built to `web/dist/`); its conventions are in `web/AGENTS.md`. Read that file before changing anything under `web/` — this root file is the only one the agent-md middleware injects, so `web/AGENTS.md` is not loaded automatically.
+
+## Coding standards
+
+- Ruff is the only automated Python baseline: line length 100, target Python 3.12, rules `E/F/I/B/UP` with `B008` ignored (see `[tool.ruff]` in `pyproject.toml`).
+- Annotate new or modified public functions, complex state transitions, and compatibility branches.
+- Catch broad exceptions only at explicit degradation boundaries, and explain the fallback; never swallow core business errors silently.
+- Avoid unbounded reads, searches, and terminal output; cap logs, tool results, and external data.
+- Never leak API keys, tokens, `.env` contents, or private user config in code, tests, docs, or output.
+- Update README/docs when user-visible behavior changes; skip doc churn for internal-only changes.
+
+## Development & testing
+
+Run `uv sync` after the first install or dependency changes.
+
+Verification order: narrowest test → domain tests
+
+```powershell
+uv run --no-sync pytest tests/test_x.py -q
+uv run --no-sync pytest tests/test_x.py::test_case_name -q
+```
+
+| Change area | Preferred tests |
+| --- | --- |
+| settings/models | `tests/test_config.py`, `tests/test_layered_config.py`, model tests |
+| backend/safety/runtime | `tests/test_backends.py`, `tests/test_safety.py`, middleware tests |
+| tool output/compression | `tests/test_tool_output.py`, `tests/test_tool_output_*`, request compression tests |
+| sessions/Codex import | `tests/test_session_*`, `tests/test_transcript.py`, `tests/test_codex_*` |
+| CLI/slash commands | `tests/test_cli.py`, `tests/test_slash_*` |
+| TUI/widgets/dialogs | `tests/test_tui_*`, `tests/test_stream_*`, `tests/test_dialogs.py`, component tests |
+
+CI runs lint on ubuntu-latest and tests on Windows/Linux with Python 3.12/3.13. Platform-specific changes must at least pass on the current machine and be reviewed for the other platform.
+
+A separate ubuntu `contract` job is the only gate on the generated contract: it runs `uv run --no-sync python scripts/export_contract_manifest.py --check`, the targeted `tests/test_runtime_contract_manifest.py`, `tests/test_runtime_architecture_boundaries.py`, `tests/test_runtime_service_import_purity.py`, `tests/test_runtime_transport_client_compatibility.py` subset, and then `npx tsc -b` plus the web console's `runtimeContractFixture` / `runtimeClientBoundary` / `sourceGuard` tests. A wire-contract change has to keep all of those green.
+
+Docs and packaging:
+
+```powershell
+uv run --no-sync mkdocs build   # after touching docs/, README.md, or mkdocs.yml
+uv build                        # after packaging/entry-point changes
+```
+
+## Rust/PyO3 native crates
+
+The Python app must work without the optional wheels and must keep `ImportError`/`OSError` fallbacks.
+
+- `rust/synapse-core-tool` (`synapse-core-tool` on PyPI): native filesystem tools (read/edit/patch/search), math rendering, and the native OpenAI-compatible chat client (`RustOpenAIClient`, backed by `async-openai` byot). Release with tag `synapse-core-tool-v*`; `native-core-tool-wheels.yml` builds wheels and publishes to GitHub Release + PyPI. Keep the `pyproject.toml` version in sync with `Cargo.toml` — maturin names wheels from `pyproject.toml`.
+- `rust/synapse-tool-compress-core` (`synapse-tool-compress-core` on PyPI): native tool-output compression core. **Required dependency** of `synapse-cli-agent`. Release with tag `synapse-tool-compress-core-v*`; `native-compression-wheels.yml` builds wheels and publishes to GitHub Release + PyPI. Keep the `pyproject.toml` version in sync with `Cargo.toml`. Because the main package hard-depends on it, publish the compress-core wheels to PyPI before tagging the main `v*` release.
+
+### Building and installing a native crate locally
+
+`uv` builds the path dependencies declared in `[tool.uv.sources]` (`rust/synapse-core-tool` and `rust/synapse-tool-compress-core`). After changing Rust code, rebuild + reinstall the affected crate with:
+
+```powershell
+uv sync --reinstall-package synapse-core-tool
+```
+
+This runs maturin under the hood and installs the freshly built wheel into the venv. Do **not** rely on `maturin develop` — a plain `uv sync` afterwards re-copies the cached (stale) wheel over the develop install. To avoid that surprise, either always rebuild via `uv sync --reinstall-package ...`, or run every command with `uv run --no-sync` after a manual `maturin develop`.
+
+When changing either crate, at least run:
+
+```powershell
+cargo test --manifest-path rust/<crate>/Cargo.toml
+cargo fmt --manifest-path rust/<crate>/Cargo.toml --check
+```
+
+If Python bindings/APIs change, rebuild via `uv sync --reinstall-package <crate>` and run the related Python tests.
+
+Keep the Apache-2.0 SPDX headers in `rust/synapse-tool-compress-core/src/headroom_port/*.rs`, the crate's `LICENSE` and `NOTICE` at `rust/synapse-tool-compress-core/`, and the upstream attribution intact; do not introduce excluded network calls or model downloads.
+
+## Release process
+
+Before any `git push`, ask the user: "Do we need to tag a release this time?"
+
+If releasing:
+
+1. Read the current version from `pyproject.toml` and let the user confirm or override it.
+2. Review changes since the last `v*` tag with `git log`.
+3. Add a `## v{version}` section at the top of `CHANGELOG.md`; the heading must match the tag exactly, group entries by New Features / Bug Fixes / Engineering, and write entries in English (the section becomes the GitHub Release notes).
+4. Update `pyproject.toml` if the version changed; sync `uv.lock` when needed.
+5. Run relevant tests, Ruff, and `uv build`.
+6. Commit with `release: bump to v{version}`.
+7. Run:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts/release.ps1
+```
+
+8. The script creates and pushes the `v{version}` tag; `release.yml` extracts the matching CHANGELOG section, runs `uv build`, and creates the GitHub Release.