modastack 0.2.0__tar.gz

modastack-0.2.0/.claude/hooks/session-state.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+# Write Claude Code hook events to the manager activity log.
+# On Stop: also relay the assistant response to Slack via the relay config.
+python3 -c "
+import sys, json, time, os
+
+data = json.load(sys.stdin)
+entry = {
+    'event': data['hook_event_name'],
+    'ts': time.time(),
+    'session_id': data.get('session_id', ''),
+}
+
+# Write activity log
+log_dir = os.path.expanduser('~/.modastack/manager')
+os.makedirs(log_dir, exist_ok=True)
+with open(os.path.join(log_dir, 'activity.jsonl'), 'a') as f:
+    f.write(json.dumps(entry) + '\n')
+
+# On Stop: relay assistant response to Slack only if a Slack message triggered this turn
+if data['hook_event_name'] == 'Stop':
+    msg = data.get('last_assistant_message', '')
+    marker = os.path.expanduser('~/.modastack/manager/slack_reply_pending')
+    if msg and os.path.exists(marker):
+        os.unlink(marker)
+        try:
+            import yaml
+            config_path = os.path.expanduser('~/.modastack/config.yaml')
+            with open(config_path) as cf:
+                config = yaml.safe_load(cf) or {}
+            slack = config.get('slack', {})
+            token = slack.get('bot_token', '')
+            channel = slack.get('dm_channel', '') or 'D0B51JP1N4C'
+            if token:
+                import urllib.request, re
+                text = msg
+                # Markdown → Slack mrkdwn
+                text = re.sub(r'^#{1,6}\s+(.+)$', r'*\1*', text, flags=re.MULTILINE)
+                text = re.sub(r'\*\*(.+?)\*\*', r'*\1*', text)
+                text = re.sub(r'\[([^\]]+)\]\(([^)]+)\)', r'<\2|\1>', text)
+                if len(text) > 3000:
+                    text = text[:3000] + '\n_(truncated)_'
+                payload = json.dumps({'channel': channel, 'text': text}).encode()
+                req = urllib.request.Request(
+                    'https://slack.com/api/chat.postMessage',
+                    data=payload,
+                    headers={'Authorization': f'Bearer {token}', 'Content-Type': 'application/json'},
+                )
+                urllib.request.urlopen(req, timeout=5)
+        except Exception:
+            pass
+"

modastack-0.2.0/.claude/memory/project_dispatch.md

@@ -0,0 +1,22 @@
+---
+name: modastack project state
+description: Current state and decisions for the modastack project — cron-based dispatch loop with Linear as primary interaction channel
+type: project
+---
+
+Building a cron-based agent dispatch system at ~/dev/modastack.
+
+**Why:** User wants to understand agentic development from first principles by building their own orchestration layer, taking design decisions from OpenClaw and Hermes.
+
+**Key decisions made:**
+- Linear + Linear comments as the sole interaction channel (Slack deferred to later)
+- Cron every 1 minute (cheap cycle, just HTTP calls)
+- Python + pip/venv
+- Per-repo .modastack.yaml for portability
+- Named credentials in ~/.modastack/credentials.yaml for multi-workspace
+- Skills discovery layer (auto-detects gstack or any skill pack)
+- BLOCKED state: agent posts question as Linear comment, polls for reply each cycle
+- GitHub repo: underminedsk/modastack (public)
+- GitHub account for this project: underminedsk
+
+**How to apply:** When working on this project, use the underminedsk GitHub account. Linear is the primary channel — no Slack integration yet. Keep the architecture simple (cron, JSON state file, no daemon).

modastack-0.2.0/.claude/plans/github-app-manifest.md

@@ -0,0 +1,225 @@
+# Plan: Centralized Event Server + GitHub App
+
+Replace the current polling-and-direct-webhook architecture with a centralized
+event server on Cloudflare Workers. One GitHub App receives all webhook events.
+Modastack deployments connect outbound via WebSocket to subscribe to their repos'
+events, with automatic catch-up on missed events after downtime.
+
+## Problem
+
+Three problems, one solution:
+
+1. **Webhook permissions** — moda-bot can't install webhooks because it lacks admin
+   access. A centralized GitHub App gets webhook permissions via installation.
+2. **Event loss during downtime** — when modastack restarts or crashes, all events
+   during the gap are lost. The central server buffers events and replays on reconnect.
+3. **Inbound port requirement** — current webhook server requires a public IP with
+   open ports. Outbound WebSocket connections work behind NAT/firewalls.
+
+## Architecture
+
+```
+GitHub ──webhook──┐
+Linear ──webhook──┤
+Slack ──webhook───┤
+                  ▼
+     Cloudflare Worker (event-server)
+          │
+          ├── receives webhooks, assigns sequence IDs
+          ├── stores events in KV (48h buffer)
+          └── Durable Object per deployment
+                  │
+                  ▼ WebSocket
+          modastack deployment
+              │
+              └── "last_seen: 57" → replays 58, 59, 60... → live stream
+```
+
+## Components
+
+### 1. Cloudflare Worker: `moda-event-server`
+
+A single Worker with three responsibilities:
+
+**Webhook ingestion (HTTP routes):**
+- `POST /webhooks/github` — receives GitHub App webhook events
+- `POST /webhooks/linear` — receives Linear webhook events  
+- `POST /webhooks/slack` — receives Slack event API payloads
+
+Each incoming event gets:
+- A globally monotonic sequence ID (per-deployment namespace)
+- Stored in KV with TTL of 48 hours
+- Forwarded to the Durable Object for each matching deployment
+
+**Deployment registration (HTTP routes):**
+- `POST /deployments` — register a new deployment, returns API key
+- `GET /deployments/:id/subscribe` — upgrade to WebSocket
+
+**Event routing logic:**
+- GitHub: route by `installation.id` or `repository.full_name`
+- Linear: route by workspace ID or team key
+- Slack: route by workspace/bot token identifier
+
+### 2. Durable Object: `DeploymentSession`
+
+One DO per registered deployment. Responsibilities:
+
+- **Subscription state** — which repos/orgs/Linear teams this deployment cares about
+- **Cursor tracking** — last-acknowledged event ID per deployment
+- **WebSocket management** — holds the live connection to the deployment
+- **Replay on reconnect** — when a deployment reconnects with `last_seen: N`,
+  fetch events N+1..latest from KV and send them in order before switching to live
+
+**Event delivery contract:**
+- Events delivered in sequence order, no gaps
+- Deployment sends `{"ack": 73}` to advance its cursor
+- If WebSocket is disconnected, events buffer in KV (up to 48h)
+- On reconnect, full replay from cursor position
+
+### 3. GitHub App: `Modastack` (centralized)
+
+One GitHub App registered under the moda-labs org:
+
+**Permissions:**
+- `contents: write` — read/write repo contents (for PRs, branches)
+- `issues: write` — manage issues and labels
+- `pull_requests: write` — create/update PRs, request reviews
+- `checks: read` — read CI status
+- Webhook events: `issues`, `issue_comment`, `pull_request`,
+  `pull_request_review`, `check_run`, `workflow_run`
+
+**Webhook URL:** `https://moda-events.<domain>/webhooks/github`
+
+**Installation flow:**
+1. User runs `modastack setup`
+2. Opens `https://github.com/apps/modastack/installations/new`
+3. User selects org and repos to grant access
+4. GitHub sends `installation` webhook to the event server
+5. Event server auto-registers the deployment's subscription
+
+**Token generation stays local.** Each modastack deployment has a copy of the
+app's private key (provisioned during `modastack setup`). It generates its own
+installation tokens via JWT for GitHub API calls (creating PRs, managing issues).
+The central server only handles webhook receipt and forwarding — it never needs
+to call GitHub's API on behalf of deployments.
+
+### 4. Modastack client changes
+
+Replace the current webhook server + polling architecture in `modastack/manager/events/`
+with an outbound WebSocket client:
+
+**New file: `modastack/manager/events/event_client.py`**
+- Connects to `wss://moda-events.<domain>/deployments/:id/subscribe`
+- Authenticates with deployment API key
+- Sends `last_seen` cursor on connect (persisted in `~/.modastack/cursor.json`)
+- Receives events, feeds them into the existing event bus
+- Acks events after successful processing
+- Auto-reconnects with exponential backoff
+
+**Modified: `modastack/manager/events/consumer.py`**
+- `run()` starts the WebSocket client instead of (or alongside) pollers
+- Events from the WebSocket feed into the same bus/batching pipeline
+- Existing manager session injection unchanged
+
+**Removed (or made optional):**
+- `webhook_server.py` — no longer needed; events come via WebSocket
+- GitHub/Linear pollers in `pollers.py` — replaced by webhooks through the
+  central server. Slack Socket Mode can stay as-is or move to central server.
+
+**Kept as fallback:**
+- `gh` CLI auth for GitHub API calls (creating PRs, etc.)
+- Local polling mode via `modastack start` (no `--webhooks`) for users who
+  don't want the central server
+
+## KV Schema
+
+```
+events:{deployment_id}:{sequence_id} → {event JSON}     TTL: 48h
+cursor:{deployment_id}              → {last_acked_id}
+deployments:{api_key}               → {deployment config}
+subscriptions:{owner/repo}          → [deployment_id, ...]
+```
+
+## Setup Flow (updated)
+
+```bash
+modastack setup <repo>
+```
+
+1. Detect GitHub org from remote URL
+2. Check if Modastack GitHub App is installed on that org
+   - If not: open browser to install URL, wait for confirmation
+3. Register deployment with central event server (gets API key)
+4. Save API key + deployment ID to `~/.modastack/config.yaml`
+5. Configure repo subscriptions on the event server
+6. Existing setup steps: generate .modastack.yaml, install skills, hooks
+
+## Auth Model
+
+| Action | Auth method |
+|---|---|
+| Receive webhook events | Central server → deployment via WebSocket (API key) |
+| Create PRs, manage issues | Deployment generates installation token locally (app private key) |
+| Register deployment | One-time API key from central server |
+| Install GitHub App on org | User clicks install in browser (GitHub handles auth) |
+
+## Key Design Decisions
+
+- **Central server is dumb relay.** It receives, stores, and forwards. It never
+  calls external APIs. All GitHub/Linear API calls happen on the deployment side.
+  This keeps the Worker simple and stateless (except for KV/DO).
+- **48-hour event buffer.** Covers weekends, maintenance windows, EC2 crashes.
+  After 48h, the deployment falls back to polling-based reconciliation (scan
+  Linear/GitHub for current state), which already exists.
+- **Private key distributed to deployments.** Each deployment gets a copy during
+  setup. This means deployments can make GitHub API calls independently. The
+  alternative (central server proxies all API calls) adds latency and complexity.
+- **Sequence IDs per deployment namespace.** Not global. Each deployment gets its
+  own monotonic counter. Simpler, no cross-deployment ordering needed.
+- **`gh` CLI stays as fallback** for GitHub API calls. Existing users don't break.
+
+## What This Replaces
+
+| Current | New |
+|---|---|
+| `webhook_server.py` (inbound HTTP) | WebSocket client (outbound) |
+| GitHub polling in `pollers.py` | GitHub webhooks via central server |
+| Linear polling in `pollers.py` | Linear webhooks via central server |
+| `moda-bot` user account + PAT | Modastack GitHub App + installation tokens |
+| Events lost on restart | 48h buffer with replay |
+| Public IP required | Works behind NAT |
+
+## Implementation Sequence
+
+### Phase 1: Central event server (Cloudflare Worker)
+1. Scaffold Worker project with Durable Objects + KV
+2. GitHub webhook ingestion endpoint
+3. Deployment registration + API key management
+4. Durable Object: WebSocket handling, cursor tracking, replay
+5. Deploy to Cloudflare
+
+### Phase 2: GitHub App
+1. Register Modastack app under moda-labs org
+2. Configure permissions and webhook URL → central server
+3. Install on moda-labs org
+4. Test: webhook events arrive at central server
+
+### Phase 3: Modastack client
+1. New `event_client.py` — WebSocket client with reconnect + replay
+2. Wire into consumer.py event loop
+3. Update `modastack setup` to register with central server
+4. Update `modastack start` to use WebSocket mode by default
+5. Keep polling mode as `modastack start --local` fallback
+
+### Phase 4: Linear + Slack integration
+1. Add Linear webhook ingestion to central server
+2. Add Slack event API endpoint (or keep Socket Mode local)
+3. Route Linear events to deployments by team key
+4. Remove polling loops from modastack client
+
+## Testing
+
+- Unit tests: event serialization, cursor logic, subscription matching
+- Integration test: Worker receives webhook → DO buffers → client replays
+- Miniflare for local Worker testing
+- Manual end-to-end: install app, push to repo, verify event arrives at deployment

modastack-0.2.0/.claude/settings.json

@@ -0,0 +1,7 @@
+{
+  "permissions": {
+    "deny": [
+      "mcp__claude_ai_Venn__*"
+    ]
+  }
+}

modastack-0.2.0/.github/workflows/deploy-event-server.yml

@@ -0,0 +1,36 @@
+name: Deploy Event Server
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "event-server/**"
+
+jobs:
+  deploy:
+    name: Deploy Worker
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: event-server
+    steps:
+      - uses: actions/checkout@v5
+
+      - uses: actions/setup-node@v5
+        with:
+          node-version: "22"
+          cache: "npm"
+          cache-dependency-path: event-server/package-lock.json
+
+      - run: npm ci
+
+      - run: npx vitest run
+
+      - name: Deploy to Cloudflare
+        uses: cloudflare/wrangler-action@v4
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          workingDirectory: event-server
+          command: deploy

modastack-0.2.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,41 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+      - name: Extract version from tag
+        id: version
+        run: echo "version=${GITHUB_REF_NAME#v}" >> "$GITHUB_OUTPUT"
+
+      - name: Trigger Homebrew formula update
+        uses: peter-evans/repository-dispatch@v3
+        with:
+          token: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+          repository: moda-labs/homebrew-modastack
+          event-type: pypi-release
+          client-payload: '{"version": "${{ steps.version.outputs.version }}"}'

modastack-0.2.0/.gitignore

@@ -0,0 +1,16 @@
+.venv/
+__pycache__/
+*.egg-info/
+dist/
+.pytest_cache/
+*.pyc
+.env
+.claude/settings.local.json
+.claude/projects/
+worktrees/
+.dispatch/
+.dispatch.yaml
+.gstack/
+.modastack/
+.context/
+worktrees/

modastack-0.2.0/.idea/.gitignore

@@ -0,0 +1,5 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/

modastack-0.2.0/.idea/encodings.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="Encoding">
+    <file url="PROJECT" charset="UTF-8" />
+  </component>
+</project>

modastack-0.2.0/.modastack.yaml

@@ -0,0 +1,23 @@
+task_tracking:
+  system: github-issues
+  project: ENG
+  trigger_labels:
+  - agent
+  skip_labels:
+  - blocked
+  - human-only
+complexity:
+  trivial: label:typo OR label:docs OR label:config
+  medium: default
+  heavy: label:feature OR label:refactor OR estimate>3
+agent:
+  tool: claude
+  skills:
+  - review
+  - ship
+  max_parallel: 2
+verify:
+  test_command: pytest
+  review_required: true
+  auto_merge: true
+credentials: modastack

modastack-0.2.0/CHANGELOG.md

@@ -0,0 +1,63 @@
+# Changelog
+
+## Unreleased
+
+### Added
+- Auto-resolve merge conflicts: `monitor/pr.conflict_detected` now triggers the manager to auto-spawn an engineer (instead of just noting it) that follows a new `merge-conflict` skill — merge the base branch, resolve conflicts honoring both sides, verify build/tests, and push. If the conflict needs a human decision, the engineer comments on the PR and exits non-zero, and the manager escalates to the human via Slack (#117)
+
+## 0.4.1 — 2026-06-01
+
+### Added
+- Engineer lifecycle events: `modastack spawn` and workflow-managed engineers now emit `engineer/session.started`, `engineer/session.completed`, and `engineer/session.failed` to the event bus, so the manager can narrate engineer activity without polling (#103)
+- Events post fire-and-forget over HTTP (`POST /api/event`) on a daemon thread, reusing the same path monitor checks use, so delivery never blocks or breaks an engineer run
+- Manager event formatter now surfaces `phase`, `duration`, `summary`, and `error` fields from lifecycle events
+
+## 0.4.0 — 2026-06-01
+
+### Added
+- Background monitoring system: scheduled polling tasks that fill webhook gaps by detecting conditions and injecting synthetic events into the manager's event stream (#100)
+- Three-tier monitor storage (built-in `monitors/defaults.yaml` → user `~/.modastack/monitors.yaml` → repo `.modastack.yaml`), merged with later tiers overriding by `name` and repo-level `enabled: false` opt-out
+- Built-in default monitors: PR conflict check (15m) and stale-PR check (1h), both working out of the box
+- `modastack monitor add/list/pause/remove` CLI for managing monitors across tiers
+- Native check runners (`pr_conflicts`, `stale_prs`) with per-condition deduplication; description-only monitors fall back to manager interpretation
+
+## 0.3.3 — 2026-05-27
+
+### Added
+- Documentation: composable skills principle, workflow resolution chain (repo > user > default), and event normalization table (GitHub Issues + Linear to task.* format)
+
+## 0.3.2.1 — 2026-05-27
+
+### Fixed
+- README phase routing table and handoff example now use the correct `implement_complete` phase name (was `implementation_complete`)
+
+## 0.3.2 — 2026-05-26
+
+### Added
+- Mermaid flowchart diagrams in README: event flow, issue lifecycle, skill composition, and deploy pipeline
+
+## 0.3.1 — 2026-05-26
+
+### Changed
+- CLI help text for `workflow` and `history` subcommands now includes descriptions and usage examples
+
+## 0.2.2 — 2026-05-23
+
+### Added
+- Stall detection: heartbeat tracking via output hashing detects sessions idle >5 min (nudge) or >10 min (kill)
+- Permission prompt detection: sessions blocked on interactive approval are identified and reported
+- Process liveness checks: dead claude processes inside live tmux sessions emit `worker.process_dead`
+- Auto-routing: manager prompt now routes engineers to the next phase based on handoff state
+
+## 0.2.1 — 2026-05-23
+
+- Self-updating: version check poller, Slack notification, user-approved update
+- Slack threading fix — conversations inline, only proactive updates threaded
+
+## 0.2.0 — 2026-05-20
+
+- Event-driven architecture with persistent manager session
+- Linear + GitHub Issues task tracking
+- Slack Socket Mode for real-time events
+- Engineer lifecycle: pickup, spec, implement, prepare-pr, feedback
+- Orphan session detection