synapse-cli-agent 0.1.28__tar.gz → 0.1.30__tar.gz

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

@@ -0,0 +1,163 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - 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 }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: windows
+            os: windows-latest
+            artifact: executable-windows
+          # 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
+          - name: linux
+            os: ubuntu-latest
+            artifact: executable-linux
+    steps:
+      - uses: actions/checkout@v4
+
+      - 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)
+        run: uv sync --frozen
+
+      - name: Install PyInstaller
+        run: uv pip install pyinstaller
+
+      - name: Package executable with PyInstaller
+        shell: pwsh
+        run: |
+          uv run pyinstaller --noconfirm --clean --onefile --name synapse `
+            --paths src `
+            --collect-all textual `
+            --collect-all textual_serve `
+            --collect-all textual_image `
+            --collect-all termaid `
+            --collect-all texicode `
+            src/synapse/entry.py
+
+      - name: Fix executable permission (Unix)
+        if: runner.os != 'Windows'
+        run: chmod +x dist/synapse
+
+      - name: Upload executable artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.artifact }}
+          path: dist/synapse*
+          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.30/AGENTS.md

@@ -0,0 +1,136 @@
+# Synapse Collaboration Guide
+
+## Repository layout
+
+| Path | Responsibility |
+| --- | --- |
+| `src/synapse/app/` | Agent assembly and `AGENTS.md` injection |
+| `src/synapse/commands/` | Slash command parsing, completion, and results |
+| `src/synapse/content/` | Prompts, skills, input history, multimodal content |
+| `src/synapse/goals/` | Goal accounting, steering, and persistence |
+| `src/synapse/integrations/` | MCP, model transport, Codex import, vision |
+| `src/synapse/memory/` | Long-term memory (SQLite + embeddings) |
+| `src/synapse/models/` | Model profiles, registry, config helpers |
+| `src/synapse/observability/` | Startup and runtime observability |
+| `src/synapse/planner/` | LLM-driven task decomposition |
+| `src/synapse/projects/` | User-layer project catalog |
+| `src/synapse/rag/` | Project document index and retrieval |
+| `src/synapse/runtime/` | Backends, middleware, compression, steer, safety, async runtime |
+| `src/synapse/sessions/` | Sessions, transcripts, recap, persistence |
+| `src/synapse/settings/` | Layered config paths, Settings schema, loading |
+| `src/synapse/tool_output/` | Reversible tool output detection, transforms, storage, metrics |
+| `src/synapse/tools/` | Custom tools injected into the agent |
+| `src/synapse/ui/` | Textual TUI, stream, timeline, dialogs, topbar/bottombar |
+| `tests/` | Python tests, usually mirroring domain modules |
+| `rust/synapse-core-tool/` | Native filesystem tools (read/edit/patch/search) and math rendering; published to PyPI as `synapse-core-tool` |
+| `rust/synapse-tool-compress-core/` | Optional native tool-output compression core |
+| `docs/`, `mkdocs.yml` | User docs and MkDocs config |
+| `.github/workflows/` | CI, docs, Python release, native wheel builds |
+
+## Architecture & compatibility
+
+- `src/synapse/app/agent.py` is the assembly layer; 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.
+- `src/synapse/config.py` is a compatibility re-export layer. Import from `synapse.settings` 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.
+
+## Coding standards
+
+- Ruff is the only automated Python baseline: line length 100, target Python 3.12, rules `E/F/I/B/UP`.
+- 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 → full checks.
+
+```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 |
+
+Full checks:
+
+```powershell
+uv run --no-sync ruff check .
+uv run --no-sync pytest -q
+```
+
+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.
+
+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
+
+Two optional crates; the Python app must work without their wheels and must keep `ImportError`/`OSError` fallbacks.
+
+- `rust/synapse-core-tool` (`synapse-core-tool` on PyPI): native filesystem tools (read/edit/patch/search) and math rendering. 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`: native tool-output compression core. Release with tag `synapse-tool-compress-core-v*`; `native-compression-wheels.yml` publishes wheels to GitHub Release.
+
+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, build or install the local extension and run the related Python tests.
+
+Keep the Apache-2.0 SPDX headers, attribution, `LICENSE`, and `NOTICE` under `rust/synapse-tool-compress-core/src/headroom_port/`; 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.
+
+## cdp_take_screenshot usage
+
+### Known limits
+- `filePath` cannot write into the workspace (browser sandbox); any attempt returns `Access denied`.
+- Without `filePath`, the screenshot is stored as text (with base64) under `/large_tool_results/call_xx_xxx`.
+
+### Standard flow: screenshot → decode → describe
+1. Ensure `/decode_screenshot.py` exists (it picks the latest `large_tool_results/call_*`, extracts the base64, and writes `.tmp/screenshot_*.png`).
+2. Run `python decode_screenshot.py`.
+3. Call `describe_image(image_path="/.tmp/screenshot_<timestamp>.png", ...)` with the printed filename.
+
+### Notes
+- Every screenshot creates a new file; the script always picks the latest.
+- Output goes to `/.tmp/`, which is gitignored.
+- Use the script instead of decoding manually.