synix-agent-mesh 0.1.0__tar.gz

synix_agent_mesh-0.1.0/.github/prompts/claude_review.md

@@ -0,0 +1,68 @@
+You are a senior engineer reviewing a pull request for synix-agent-mesh, an
+orchestration layer that composes synix (build system for agent memory), synix
+mesh (cross-device session sync), and MCP into a single CLI tool. You have
+NEVER seen the codebase before. You are reviewing this PR using only the README
+and the diff.
+
+## Your context
+
+You have been given two documents:
+1. **README.md** — the full project documentation including architecture, CLI
+   reference, configuration, and multi-machine setup
+2. **The PR diff**
+
+This is an orchestration/glue project — it is intentionally thin (~500 lines)
+and delegates heavy lifting to synix core, synix mesh, and synix MCP. The CLI
+is called `sam`.
+
+## What to evaluate
+
+### Orchestration correctness
+Does this change correctly compose the underlying synix components? Does it
+respect the separation between synix-agent-mesh (orchestration) and synix
+(core build system)? Flag any change that duplicates functionality that
+belongs in synix core.
+
+### Configuration coherence
+The project uses a single `agent-mesh.toml` config file. Does this change
+maintain config consistency? Are new settings documented? Do environment
+variable overrides work correctly?
+
+### Multi-machine concerns
+The system runs across multiple machines (server, client, MCP router). Does
+this change work correctly in all roles? Are there assumptions about being
+the server that would break on client nodes? Are ports and hostnames
+configurable?
+
+### CLI ergonomics
+Is the CLI interface intuitive? Are error messages helpful? Does the output
+formatting make sense? Would a user running `sam serve` or `sam join` for the
+first time understand what's happening?
+
+### Async and process management
+The server runs mesh server + MCP HTTP + viewer + local client watcher in a
+single process using asyncio + threading. Does this change handle shutdown
+correctly? Are there potential deadlocks or resource leaks?
+
+### Legibility
+Can you understand what the code does from the diff alone? Are names clear?
+Would a new contributor be confused by anything?
+
+### Test coverage
+Does the diff include tests? Do the tests cover the happy path AND edge cases?
+Flag any behavioral changes that appear untested.
+
+## Output format
+
+Write a structured review with these sections:
+
+**Summary** — What this PR does in 2-3 sentences.
+
+**Observations** — Numbered list of specific findings. Each should reference a
+file or code pattern from the diff. Categorize each as: [concern], [question],
+[nit], or [positive].
+
+**Verdict** — One sentence: does this PR seem like a good incremental step for
+the project?
+
+Keep the total review under 600 words. Be direct. Skip generic praise.

synix_agent_mesh-0.1.0/.github/prompts/openai_review.md

@@ -0,0 +1,73 @@
+You are a skeptical systems architect doing a design review of a pull request.
+Your job is to find problems. You are not here to be encouraging. You are here
+to protect the project from bad decisions.
+
+The project is synix-agent-mesh — an orchestration layer that wires together
+synix (build system for agent memory), synix mesh (cross-device session sync),
+and MCP into a single CLI. It is pre-1.0 and under active development. You
+have NEVER seen the codebase. You are working from documentation and the diff
+only.
+
+## Your context
+
+You have two documents:
+1. **README.md** — full project documentation
+2. **The PR diff**
+
+## Your mandate
+
+Hunt for problems. Specifically:
+
+### One-way doors
+Decisions that are hard or impossible to reverse once shipped. Examples:
+- CLI commands or flags that users will depend on
+- Configuration key names that get documented and relied upon
+- Port numbers or protocol choices that become part of deployment guides
+- Mesh protocol changes that affect multi-machine compatibility
+
+For each one-way door: name it, explain why it is hard to reverse, and suggest
+what would need to be true for it to be safe to merge.
+
+### Orchestration failures
+- Error handling gaps when synix core APIs change or fail
+- Assumptions about synix internals that could break on version upgrades
+- Missing graceful degradation (e.g., viewer unavailable, mesh unreachable)
+- Process lifecycle issues (zombie processes, unhandled signals, port conflicts)
+
+### Multi-machine risks
+- Changes that work on the server but break on client nodes
+- Hardcoded hostnames, paths, or ports that should be configurable
+- Token or credential handling issues
+- Network timeout or retry gaps
+
+### What is NOT in the diff
+- Missing tests for behavioral changes
+- Missing error handling for plausible failure modes
+- Missing config documentation when new settings are added
+- Regression risks: does this change something that other code depends on?
+
+### Hidden complexity
+- Changes that look simple but have non-obvious downstream effects
+- Implicit dependencies between the server, client, and MCP components
+- Assumptions about execution order or environment state
+- Magic numbers, hardcoded paths, or configuration that should be parameterized
+
+## Output format
+
+**Threat assessment** — One sentence: how risky is this PR?
+
+**One-way doors** — Numbered list. If none found, say "None identified."
+
+**Findings** — Numbered list of problems found. Each must:
+1. Name the specific file and code pattern
+2. Explain the failure mode or risk
+3. Rate severity: [critical], [warning], or [minor]
+
+**Missing** — What you expected to see but did not. Be specific.
+
+**Verdict** — Ship it, ship with fixes, or block. One sentence with reasoning.
+
+Be blunt. If the PR looks clean, say so in two sentences and move on. Do not
+manufacture concerns to fill space. But do not go easy either.
+
+Keep the total review under 700 words.

synix_agent_mesh-0.1.0/.github/scripts/blind_review.py

@@ -0,0 +1,263 @@
+"""Blind PR review — posts an LLM review using only docs + diff as context."""
+
+from __future__ import annotations
+
+import os
+import sys
+from datetime import UTC, datetime
+from pathlib import Path
+
+import requests
+
+# ---------------------------------------------------------------------------
+# Configuration
+# ---------------------------------------------------------------------------
+
+MAX_DIFF_LINES = 10_000
+LLM_TIMEOUT = 120  # seconds
+
+CLAUDE_MODEL = "claude-opus-4-6"
+OPENAI_MODEL = "gpt-5.4"
+
+PROMPTS_DIR = Path(__file__).resolve().parent.parent / "prompts"
+
+# ---------------------------------------------------------------------------
+# Context gathering
+# ---------------------------------------------------------------------------
+
+
+def fetch_diff(repo: str, pr_number: str, token: str) -> str:
+    """Fetch PR diff via GitHub API, falling back to git diff for large PRs."""
+    url = f"https://api.github.com/repos/{repo}/pulls/{pr_number}"
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/vnd.github.v3.diff",
+    }
+    resp = requests.get(url, headers=headers, timeout=30)
+    if resp.status_code == 406:
+        # Diff too large for GitHub API — fall back to local git diff
+        print("Diff too large for API (406), falling back to git diff...")
+        return _git_diff_fallback(repo, pr_number, token)
+    resp.raise_for_status()
+    return resp.text
+
+
+def _git_diff_fallback(repo: str, pr_number: str, token: str) -> str:
+    """Compute diff locally using git when the API can't generate it."""
+    import subprocess
+
+    # Fetch PR metadata to get base/head refs
+    url = f"https://api.github.com/repos/{repo}/pulls/{pr_number}"
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/vnd.github.v3+json",
+    }
+    resp = requests.get(url, headers=headers, timeout=15)
+    resp.raise_for_status()
+    pr_data = resp.json()
+    base_sha = pr_data["base"]["sha"]
+    head_sha = pr_data["head"]["sha"]
+
+    result = subprocess.run(
+        ["git", "diff", f"{base_sha}...{head_sha}"],
+        capture_output=True,
+        text=True,
+        timeout=30,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(f"git diff failed: {result.stderr}")
+    return result.stdout
+
+
+def truncate_diff(diff: str) -> tuple[str, int, int]:
+    """Truncate diff to MAX_DIFF_LINES. Returns (diff, shown_lines, total_lines)."""
+    lines = diff.splitlines()
+    total = len(lines)
+    if total <= MAX_DIFF_LINES:
+        return diff, total, total
+    truncated = "\n".join(lines[:MAX_DIFF_LINES])
+    truncated += f"\n\n... [diff truncated: showing first {MAX_DIFF_LINES:,} of {total:,} lines]"
+    return truncated, MAX_DIFF_LINES, total
+
+
+def load_prompt(provider: str) -> str:
+    """Load the review prompt for the given provider."""
+    prompt_file = PROMPTS_DIR / f"{provider}_review.md"
+    return prompt_file.read_text()
+
+
+def read_file(name: str) -> str:
+    """Read a file from the workspace."""
+    workspace = Path(os.environ.get("GITHUB_WORKSPACE", "."))
+    path = workspace / name
+    if path.exists():
+        return path.read_text()
+    return f"({name} not found)"
+
+
+# ---------------------------------------------------------------------------
+# LLM calls
+# ---------------------------------------------------------------------------
+
+
+def build_user_message(readme: str, diff: str) -> str:
+    """Compose the user message with context sections."""
+    return f"""## README.md
+
+{readme}
+
+---
+
+## PR Diff
+
+```diff
+{diff}
+```"""
+
+
+def review_claude(system_prompt: str, user_message: str) -> tuple[str, str]:
+    """Call Claude API with extended thinking. Returns (review_text, model_name)."""
+    import anthropic
+
+    client = anthropic.Anthropic()
+    response = client.messages.create(
+        model=CLAUDE_MODEL,
+        max_tokens=16000,
+        temperature=1,  # required for extended thinking
+        thinking={
+            "type": "enabled",
+            "budget_tokens": 10000,
+        },
+        system=system_prompt,
+        messages=[{"role": "user", "content": user_message}],
+    )
+    # Extract the text block (skip thinking blocks)
+    for block in response.content:
+        if block.type == "text":
+            return block.text, CLAUDE_MODEL
+    return "(no text in response)", CLAUDE_MODEL
+
+
+def review_openai(system_prompt: str, user_message: str) -> tuple[str, str]:
+    """Call OpenAI API. Returns (review_text, model_name)."""
+    import openai
+
+    client = openai.OpenAI()
+    response = client.chat.completions.create(
+        model=OPENAI_MODEL,
+        messages=[
+            {"role": "developer", "content": system_prompt},
+            {"role": "user", "content": user_message},
+        ],
+    )
+    return response.choices[0].message.content, OPENAI_MODEL
+
+
+# ---------------------------------------------------------------------------
+# GitHub interaction
+# ---------------------------------------------------------------------------
+
+
+def post_comment(repo: str, pr_number: str, token: str, body: str) -> None:
+    """Post a comment on the PR via GitHub API."""
+    url = f"https://api.github.com/repos/{repo}/issues/{pr_number}/comments"
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/vnd.github.v3+json",
+    }
+    resp = requests.post(url, headers=headers, json={"body": body}, timeout=15)
+    resp.raise_for_status()
+
+
+def format_comment(
+    review: str,
+    provider: str,
+    model: str,
+    diff_shown: int,
+    diff_total: int,
+    prompt_file: str,
+) -> str:
+    """Format the review as a PR comment."""
+    timestamp = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    if provider == "claude":
+        header = "**Architectural Review** — Claude Opus | Blind review (docs + diff only)"
+    else:
+        header = "**Red Team Review** — OpenAI GPT-5.4 | Adversarial review (docs + diff only)"
+
+    diff_note = f"{diff_shown:,} lines"
+    if diff_shown < diff_total:
+        diff_note += f" (of {diff_total:,} total — truncated)"
+
+    return f"""> [!NOTE]
+> {header}
+
+{review}
+
+<details>
+<summary>Review parameters</summary>
+
+- **Model**: `{model}`
+- **Context**: README.md, PR diff
+- **Diff size**: {diff_note}
+- **Prompt**: `{prompt_file}`
+- **Timestamp**: {timestamp}
+
+</details>
+"""
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+    provider = os.environ["PROVIDER"]  # "claude" or "openai"
+    token = os.environ["GITHUB_TOKEN"]
+    pr_number = os.environ["PR_NUMBER"]
+    repo = os.environ["REPO"]
+
+    # 1. Gather context
+    print(f"Fetching diff for {repo}#{pr_number}...")
+    raw_diff = fetch_diff(repo, pr_number, token)
+    diff, diff_shown, diff_total = truncate_diff(raw_diff)
+    print(f"Diff: {diff_total:,} lines ({diff_shown:,} shown)")
+
+    readme = read_file("README.md")
+
+    # 2. Build prompt and call LLM
+    system_prompt = load_prompt(provider)
+    user_message = build_user_message(readme, diff)
+    prompt_file = f".github/prompts/{provider}_review.md"
+
+    print(f"Calling {provider} API ({CLAUDE_MODEL if provider == 'claude' else OPENAI_MODEL})...")
+    try:
+        if provider == "claude":
+            review, model = review_claude(system_prompt, user_message)
+        elif provider == "openai":
+            review, model = review_openai(system_prompt, user_message)
+        else:
+            print(f"Unknown provider: {provider}", file=sys.stderr)
+            sys.exit(1)
+    except Exception as exc:
+        error_type = type(exc).__name__
+        fail_body = (
+            f"> [!WARNING]\n"
+            f"> **AI Review failed** — {provider} | `{error_type}`\n\n"
+            f"The {provider} blind review could not be completed. "
+            f"This does not affect the PR.\n"
+        )
+        print(f"LLM call failed ({error_type}): {exc}", file=sys.stderr)
+        post_comment(repo, pr_number, token, fail_body)
+        sys.exit(0)  # don't red-X the PR
+
+    # 3. Post review comment
+    print(f"Posting review ({len(review)} chars)...")
+    body = format_comment(review, provider, model, diff_shown, diff_total, prompt_file)
+    post_comment(repo, pr_number, token, body)
+    print("Done.")
+
+
+if __name__ == "__main__":
+    main()

synix_agent_mesh-0.1.0/.github/workflows/blind-review.yml

@@ -0,0 +1,87 @@
+name: Blind PR Review
+
+on:
+  pull_request_target:
+    types: [opened, synchronize]
+
+env:
+  APPROVED_CONTRIBUTORS: '["marklubin"]'
+
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    outputs:
+      approved: ${{ steps.check.outputs.approved }}
+    steps:
+      - id: check
+        run: |
+          ACTOR="${{ github.actor }}"
+          if echo '${{ env.APPROVED_CONTRIBUTORS }}' | jq -e ". | index(\"$ACTOR\")" > /dev/null 2>&1; then
+            echo "approved=true" >> "$GITHUB_OUTPUT"
+            echo "::notice::Blind review approved for $ACTOR"
+          else
+            echo "approved=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::Skipping blind review — $ACTOR is not in approved list"
+          fi
+
+  review-claude:
+    needs: gate
+    if: needs.gate.outputs.approved == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          sparse-checkout: |
+            .github/scripts/blind_review.py
+            .github/prompts/claude_review.md
+            .github/prompts/openai_review.md
+            README.md
+          sparse-checkout-cone-mode: false
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - run: pip install anthropic requests
+
+      - run: python .github/scripts/blind_review.py
+        env:
+          PROVIDER: claude
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+
+  review-openai:
+    needs: gate
+    if: needs.gate.outputs.approved == 'true'
+    runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          sparse-checkout: |
+            .github/scripts/blind_review.py
+            .github/prompts/claude_review.md
+            .github/prompts/openai_review.md
+            README.md
+          sparse-checkout-cone-mode: false
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - run: pip install openai requests
+
+      - run: python .github/scripts/blind_review.py
+        env:
+          PROVIDER: openai
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}

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

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: ["*"]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync
+      - run: uv run ruff check .
+      - run: uv run pytest tests/ -v

synix_agent_mesh-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,53 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  id-token: write
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync
+      - run: uv run ruff check .
+      - run: uv run pytest tests/ -v
+
+  publish:
+    needs: [test]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with:
+          python-version: "3.12"
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  smoke-test:
+    needs: publish
+    runs-on: ubuntu-latest
+    steps:
+      - uses: astral-sh/setup-uv@v4
+        with:
+          python-version: "3.12"
+      - name: Wait for PyPI propagation
+        run: sleep 30
+      - name: Install from PyPI
+        run: uv tool install synix-agent-mesh
+      - name: Verify CLI
+        run: |
+          sam --help
+          sam --version

synix_agent_mesh-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+*.pyc
+.synix/
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+uv.lock
+uv.toml
+agent-mesh.toml

synix_agent_mesh-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Lubin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.