jean-agent 0.1.0__tar.gz

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

@@ -0,0 +1,69 @@
+name: Release to PyPI
+
+# Triggers on either a `v*` tag push (typical release) or a manual
+# workflow_dispatch (re-publish without a new tag, e.g. recovering from
+# a build flake). The workflow validates that pyproject.toml's version
+# matches the tag name before publishing.
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build wheel + sdist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build tooling
+        run: pip install --upgrade build hatchling
+      - name: Verify version matches tag
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PROJ_VERSION=$(python -c "import tomllib, pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])")
+          if [ "$TAG_VERSION" != "$PROJ_VERSION" ]; then
+            echo "::error::Tag is v$TAG_VERSION but pyproject.toml says version=$PROJ_VERSION"
+            exit 1
+          fi
+          echo "Version $PROJ_VERSION matches tag $GITHUB_REF_NAME ✓"
+      - name: Build distributions
+        run: python -m build
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: build
+    environment:
+      # The `pypi` environment must exist in the GitHub repo's Settings →
+      # Environments. PyPI's Trusted Publisher config is bound to it.
+      name: pypi
+      url: https://pypi.org/project/jean-agent/
+    permissions:
+      # Required for PyPI Trusted Publishing (OIDC token issuance).
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI via Trusted Publishing
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # No api-token configured — Trusted Publishing uses the OIDC token
+        # signed by GitHub Actions and verified by PyPI against the
+        # pending-publisher config (project + owner + repo + workflow +
+        # environment).

jean_agent-0.1.0/.gitignore

@@ -0,0 +1,168 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# pdm
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582
+__pypackages__/
+
+# Celery
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.env.*
+!.env.example
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# Ruff
+.ruff_cache/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Jean runtime artifacts (when self-hosting jean against this repo).
+# The canonical templates live in jean/templates/; these are local copies
+# from `jean init` and the local data the running app produces.
+/jean.toml
+/jean.local.toml
+/fly.toml
+/Dockerfile
+/.dockerignore
+/jean_system_prompt.md
+/.jean/
+/.jean-vendor/
+/credentials.enc
+/.claude/skills

jean_agent-0.1.0/AGENTS.md

@@ -0,0 +1,333 @@
+# AGENTS.md
+
+Read this before working on jean. It captures the architectural invariants
+and the non-obvious gotchas we discovered the hard way.
+
+## What jean is
+
+A drop-in Slack-fronted Claude Code agent for any host repo. The host adds a
+`skills/` directory plus `jean init`-generated artifacts; jean handles the
+Slack bot, web UI for conversation history, Sign in with Slack auth,
+per-thread Claude sessions, owner-gated rollout (private mode + per-channel
+approvals + non-owner CC), user-created skills via DM, two-way file
+attachments, and Fly.io deploy.
+
+The same `jean` package self-tests against itself — `skills/haiku/SKILL.md`
+in this repo is the bundled smoke skill so `jean run` here gives you a
+working bot.
+
+## Project layout
+
+```
+jean/
+  cli.py                 typer CLI (init, doctor, run, configure-secrets,
+                         deploy, print-manifest, migrate, grant/revoke-admin)
+  config.py              Pydantic config model; jean.toml + env + encrypted-store merge
+  diagnostics.py         Phase 1 (offline) + Phase 2 (Slack API) checks
+  setup_guide.py         Walkthrough + Slack app manifest renderer
+  wizard.py              Interactive secrets wizard (browser-open, clipboard, live auth.test)
+  credentials.py         AES-256-GCM encrypted store; master key in OS keychain
+  app.py                 FastAPI factory + lifespan (starts SessionManager, Socket Mode)
+  db.py                  aiosqlite + WAL pragmas + migration runner
+  models.py              Dataclasses + DAO for users, conversations, messages,
+                         attachments, channel_approvals, pending_channel_messages,
+                         user_skills
+  auth/
+    siws.py              Sign in with Slack via authlib (OIDC)
+    deps.py              FastAPI deps: current_user, require_user/admin/owner
+  harness/
+    options.py           Build ClaudeAgentOptions from cfg; stitches MCP servers,
+                         pipes SDK stderr into jean's logger
+    sessions.py          SessionManager + LiveSession + idle reaper + debug dump
+                         + resume-failure fallback + context_was_lost flag
+    skills.py            Skill discovery + .claude/skills per-skill symlink materializer
+    skill_tools.py       MCP server `jean_skills` (DM-only): list/read/save/delete user skills
+    io_tools.py          MCP server `jean_io` (every session): send_file_to_user
+    user_skills.py       Filesystem layer + reconcile loop for user-created skills
+  slack/
+    bolt.py              AsyncApp + Socket Mode handler factories (pops CLIENT_ID/SECRET
+                         from env so bolt doesn't auto-enable OAuth)
+    identity.py          auth.test + owner resolution + UsersCache + mention resolver
+    handlers.py          app_mention + message.im → SessionManager; EventDedup;
+                         ThrottledPoster; ProgressReactionLoop; private mode +
+                         channel approval gates; owner-CC; rescue context
+    approvals.py         Block Kit approval UI + action handlers + replay-on-approve
+    attachments.py       Download Slack files → multimodal content blocks
+    thread_context.py    Fetch unseen replies for thread catch-up; full-thread mode
+                         (include_bot=True) for rescue context after session loss
+    formatting.py        mrkdwn conversion + chunking + skill-preamble fallback regex
+  web/
+    routes.py            /, /conversations, /admin/(users|skills|channels),
+                         /_diagnostics, /attachments
+    display.py           Slack ID → human handle resolver (DB-first, cache fallback)
+    templates/           Jinja2 (base, index, conversations_list,
+                         admin_users/skills/channels, etc.)
+    static/              Pico CSS + jean.css
+  migrations/            001_initial, 002_channel_approvals, 003_pending_channel_messages,
+                         004_user_skills, 005_owner_cc
+  templates/             Files copied by `jean init` (jean.toml, fly.toml, Dockerfile, …)
+  builtin_skills/        Skills shipped inside the jean package (skill-builder)
+skills/haiku/            Bundled self-test skill
+tests/                   pytest; 51 tests; uses pytest-asyncio auto mode
+```
+
+## Local development
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .[dev]
+```
+
+Run the package against itself (you need a real Slack app + Anthropic key —
+see `jean doctor --setup-guide` for the manifest + step-by-step):
+
+```bash
+jean doctor              # Phase 1, no network
+jean configure-secrets   # encrypted store wizard
+jean doctor --deep       # Phase 2 (auth.test + scope check + owner resolve)
+jean run                 # FastAPI :8080 + Socket Mode listener
+```
+
+## Tests
+
+```bash
+pytest                   # 51 tests; ~0.7s
+pytest tests/test_db.py  # focused
+```
+
+Fixtures in `tests/conftest.py` build a tmpdir config + SQLite DB, mock env
+vars where needed. There are NO tests that hit Slack or Anthropic APIs;
+`test_create_app_smoke_does_not_crash_in_force_mode` stubs identity to
+exercise the full `create_app(force=True)` path offline.
+
+## Architecture invariants — don't break these
+
+1. **Single uvicorn worker, single Fly machine.** SQLite + WAL needs one
+   writer; the in-memory `SessionManager` needs single-process state.
+2. **Socket Mode only.** No public webhook URL needed for events; only the
+   SIWS callback is inbound HTTP. Don't reintroduce HTTP Events Mode without
+   re-evaluating the ACK story (see the `process_before_response` gotcha).
+3. **One LiveSession per (channel, thread_ts)** while warm. Resume from
+   disk via `ClaudeAgentOptions(resume=session_id)` after idle reap. The SDK
+   writes transcripts to `~/.claude/...` (per `getpwuid()` lookup) — see the
+   non-root user gotcha below for the symlink trick that keeps them on the
+   Fly volume.
+4. **Env vars override the encrypted credentials file** at runtime. Never
+   reverse the precedence — `fly secrets set` must always win.
+5. **Skill discovery is filesystem-based** via `setting_sources=["project"]`
+   and `.claude/skills/`. We materialize per-skill symlinks from three
+   sources (repo / builtin / user) with precedence repo > builtin > user.
+6. **DM-only invariant for skill mutations.** Three gates: visibility in
+   the `skills_only` system prompt, MCP server registration, in-tool check.
+
+## Non-obvious gotchas (read before changing related code)
+
+These each cost real debugging time. Don't re-introduce them.
+
+### Bundled Claude CLI ignores `HOME`; needs `~/.claude` symlinked to the volume
+
+The Claude CLI binary that ships inside `claude-agent-sdk` resolves home via
+`getpwuid()` (not `$HOME`). The `jean` user's passwd home is `/home/jean`,
+so transcripts go to `/home/jean/.claude/...` regardless of `HOME=/data/home`.
+That's on the ephemeral container layer — gone on every redeploy → every
+existing thread breaks with "No conversation found with session ID …".
+
+The Dockerfile's entrypoint replaces `/home/jean/.claude` with a symlink
+to `/data/home/.claude` on the persistent volume. Don't reintroduce code
+that relies on `HOME=/data/home` working — verify with
+`ls -la /home/jean/.claude` after a deploy that it's a symlink.
+
+There's also a runtime fallback: when resume fails (`LiveSession._ensure_client`
+catches the exception), the session retries fresh AND sets `context_was_lost`.
+The handler reads that flag, fetches the full Slack thread (including the
+bot's own past replies via `include_bot=True`), and feeds it to Claude as
+"rescue context" so the user keeps continuity. See
+`jean/slack/thread_context.py:fetch_unseen_thread_messages`.
+
+### slack-bolt auto-enables OAuth when `SLACK_CLIENT_ID/SECRET` are in env
+
+If both are present in `os.environ` when constructing `AsyncApp`, bolt
+silently wires up a file-based `InstallationStore` + multi-team
+authorization → every event fails with "AuthorizeResult was not found"
+because the install store is empty. We use those env vars for our own
+SIWS code via authlib, not for bolt. `jean/slack/bolt.py:build_app` pops
+them from `os.environ` for the constructor's lifetime, then restores.
+
+### SDK skill scaffolding lives in UserMessage TextBlocks
+
+When a Claude Code skill activates, the SDK sends the SKILL.md content +
+`ARGUMENTS: <input>` as a TextBlock inside a **UserMessage** (not an
+AssistantMessage). It's input to the model, not the model's reply.
+
+`jean/harness/sessions.py:_interpret_message` only yields TextDeltas from
+**AssistantMessage** blocks for this reason. Don't add a fallback that
+yields UserMessage text — you'll get the SKILL.md echoed into Slack.
+
+A regex fallback exists in `jean/slack/formatting.py:filter_for_display`
+as defense-in-depth in case a future SDK version moves scaffolding to
+AssistantMessage.
+
+### `bot_user_id` must be the Uxxx, not the Bxxx
+
+`auth.test` returns both `bot_id` (`Bxxx`) and `user_id` (`Uxxx`). Slack
+mentions use `<@Uxxx>` — bot-mention stripping and "is this the bot?"
+checks need the user_id form. `jean/slack/identity.py:workspace_identity`
+prefers `user_id`. Don't switch the order.
+
+### `ThrottledPoster` needs `_post_lock`
+
+Two concurrent `_do_flush` calls (loop tick + `finalize()`) can both
+observe `posted_ts is None` and both call `chat.postMessage` → duplicate
+replies. The `_post_lock` serializes the post-or-update decision across
+the actual API call.
+
+### `process_before_response` defaults to False — keep it that way
+
+If `True`, bolt waits for the listener to finish before ACKing Slack.
+Claude turns take >3s, Slack re-delivers, the listener runs twice →
+duplicate replies. `EventDedup` catches it too, but the ACK timing is
+the right fix.
+
+### `client.query()` accepts `str` or `AsyncIterable[dict]`, never `list`
+
+`to_content_blocks(text, staged_files)` returns a `list[dict]` for
+multimodal messages. Pass it to `query()` directly and the SDK tries to
+`async for` over the list — crash with `__aiter__` error. The fix wraps
+in `_as_message_stream()` (single-item async generator) inside
+`LiveSession.submit`.
+
+### Don't run as root in Docker — Claude CLI refuses `bypassPermissions`
+
+`--dangerously-skip-permissions` (which `bypassPermissions` translates to)
+errors out with "cannot be used with root/sudo privileges". The Dockerfile
+creates a non-root `jean` user (uid 1000) and uses `gosu` in the entrypoint
+to drop privileges. Even with the current default `permission_mode = "auto"`,
+keep the non-root setup — it's good practice independent of the SDK
+check, and lets users flip to `bypassPermissions` cleanly.
+
+### Honor `X-Forwarded-Proto` in uvicorn behind the Fly edge proxy
+
+Fly terminates TLS at the edge and forwards plain HTTP to the container.
+Without `proxy_headers=True` + `forwarded_allow_ips="*"`, `request.url_for()`
+generates `http://...` callbacks → Slack rejects them with "redirect_uri
+did not match". See the uvicorn config in `jean/cli.py:run`.
+
+### `pip install jean` resolves to a different PyPI package
+
+The `jean` name on PyPI is taken by an unrelated "OOP Learning Example".
+The Dockerfile installs from the local repo (`pip install /app`). When we
+publish to PyPI as `shinkansen-jean`, switch the Dockerfile back to
+installing from PyPI by name.
+
+### Hatchling: don't list packages in both `packages` and `force-include`
+
+`packages = ["jean"]` already picks up every non-gitignored file under
+`jean/`. Listing the same subdirs in `force-include` makes hatchling crash
+with "second file at same path: …/__init__.py". The current `pyproject.toml`
+uses only `packages`.
+
+### Slack app's Messages Tab is off by default
+
+Without `features.app_home.messages_tab_enabled: true` in the manifest,
+users see "Se desactivó el envío de mensajes a esta aplicación" when they
+try to DM the bot. `jean/setup_guide.py:render_manifest` includes the
+toggle; existing apps need to flip it in App Home settings.
+
+### Session must close after `save_skill_file` / `delete_skill_file`
+
+The Claude SDK caches the skill list at client construction. New skills
+written mid-turn aren't visible to the same client. The handler tracks
+`SESSION_INVALIDATING_TOOLS` (in `jean/slack/handlers.py`) and calls
+`SessionManager.close_session` after the turn ends — the next message in
+the thread spins up a fresh client (via `resume=session_id`) that
+re-discovers skills. Context survives via the SDK's on-disk transcript.
+
+## How to add a skill (the host's job — but useful to know)
+
+In the host repo, create `skills/<name>/SKILL.md`:
+
+```markdown
+---
+name: <name>
+description: One-line; surfaces in `skills_only` system prompt + triggers the model.
+---
+
+Body — Claude reads this when the skill activates.
+```
+
+The `[claude] skills_only = true` default lists every discovered skill's
+name + description in the system prompt and tells Claude to politely
+decline anything that doesn't fit a skill. See
+`jean/harness/options.py:_skills_only_addendum`.
+
+Skills can call two MCP tools jean exposes:
+- `send_file_to_user(local_path, title?, comment?)` — upload an artifact to the current Slack thread (every session).
+- Skill-management tools (`save_skill_file`, etc.) — only available in DMs and only to users matching `[claude] user_skill_authors` policy.
+
+The bundled `skills/haiku/` is the simplest possible example.
+`jean/builtin_skills/skill-builder/SKILL.md` is the meta-skill that drives
+DM-based skill creation/editing.
+
+## Debugging
+
+- **Dump every SDK message** to inspect what's actually arriving:
+  `JEAN_DEBUG_SDK_MESSAGES=1 jean run` → writes JSON-lines to
+  `<db_dir>/sdk_debug.jsonl`. Used to discover the UserMessage gotcha.
+- **SDK subprocess stderr** is piped into `jean.sdk.stderr` logger at
+  WARNING level by default — visible in `flyctl logs`. Surfaces "unknown
+  flag", "model not found", "No conversation found", etc.
+- **SQLite shell**: `sqlite3 .jean/jean.db` (or `/data/jean.db` on Fly).
+- **Web UI diagnostics page**: `/_diagnostics` (owner-only) shows the
+  same Phase 1 + Phase 2 checks as `jean doctor --deep`.
+- **misconfig mode**: if startup checks fail, every route renders the
+  diagnostics page so the owner can fix things without dropping to CLI.
+- **`jean run --verbose`** promotes log level to DEBUG and unmutes
+  upstream loggers (`httpx`, `slack_sdk`).
+
+## When you change X, also do Y
+
+- **New `[<section>]` field in config.py** → add to
+  `jean/templates/jean.toml.tmpl` with explanatory comment.
+- **New DB column / table** → add a migration as
+  `jean/migrations/NNN_<name>.sql`; the runner picks it up automatically.
+  Update `tests/test_db.py:test_migrations_apply_to_clean_db` if a new
+  table needs explicit assertions.
+- **New required Slack bot scope** → add to
+  `slack/identity.py:REQUIRED_BOT_SCOPES` AND to the manifest in
+  `jean/setup_guide.py:render_manifest`. Users with existing apps need
+  to reinstall the app for new scopes.
+- **New jean CLI command** → register on the `typer` app in
+  `jean/cli.py`. Help text becomes visible in `jean --help`.
+- **New MCP tool** → decide DM-only (add to `jean_skills` server in
+  `skill_tools.py`) or every-session (add to `jean_io` server in
+  `io_tools.py`). Each is registered in `options.py:options_kwargs`.
+- **New OS package needed for a skill** (poppler, libreoffice, etc.) →
+  add to the `apt-get install` line in `jean/templates/Dockerfile.tmpl`
+  with a comment for why.
+
+## What's intentionally NOT built (future work)
+
+- Multi-machine / LiteFS — single machine is by design (see invariant 1).
+- HTTP Events Mode for Slack — Socket Mode covers our use cases.
+- Custom session store — the SDK's default disk transcripts + the symlink
+  to the Fly volume are enough; rescue-from-Slack covers the edge case.
+- Fast Mode (`speed: "fast"`) — the SDK doesn't expose it yet (`betas`
+  field only accepts `context-1m-2025-08-07`). When Anthropic ships it,
+  wire a `[claude] speed` config option to it.
+- PyPI publish as `shinkansen-jean` — until then, install from local
+  repo (jean-on-jean) or from a git tag.
+- Multi-tenant — one jean install talks to one Slack workspace.
+
+## Style notes
+
+- Async everywhere; if you need to mix sync/async, prefer async wrappers.
+- Pydantic v2 is the source of truth for config validation.
+- Defensive SDK probing via `getattr`/`type(x).__name__` — the SDK shape
+  drifts across versions; don't rely on exact class identity.
+- Tests use `pytest-asyncio` auto mode; no `@pytest.mark.asyncio`
+  decorators needed.
+- No `print()` — use `typer.echo`/`typer.secho` for CLI output and
+  `logging` for everything else.
+- Templates copied by `jean init` end in `.tmpl` but otherwise carry the
+  filename they'll be written as (so `Dockerfile.tmpl` → `Dockerfile`).

jean_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shinkansen Finance
+
+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.