flowjet 2.0.0__tar.gz

flowjet-2.0.0/.gitignore

@@ -0,0 +1,257 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$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
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.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
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+# flowjet commits uv.lock for reproducible installs (CLI + server extras).
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Local editor / tool backups
+.backups/
+
+# 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/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+#--------------------------------------------------#
+# The following was generated with gitignore.nvim: #
+#--------------------------------------------------#
+# Gitignore for the following technologies: macOS
+
+# General
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Icon must end with two 
+Icon
+
+# Thumbnails
+._*
+
+# Files that might appear in the root of a volume
+.DocumentRevisions-V100
+.fseventsd
+.Spotlight-V100
+.TemporaryItems
+.Trashes
+.VolumeIcon.icns
+.com.apple.timemachine.donotpresent
+
+# Directories potentially created on remote AFP share
+.AppleDB
+.AppleDesktop
+Network Trash Folder
+Temporary Items
+.apdisk
+
+# iCloud generated files
+*.icloud
+.soothe/
+
+# Claude Code session-local
+.claude/
+.codebuddy/

flowjet-2.0.0/CHANGELOG.md

@@ -0,0 +1,111 @@
+# Changelog
+
+All notable changes to **flowjet** are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+> History from 0.1.0–0.2.0 below was released as the separate `flowjet-server`
+> distribution, now merged into `flowjet`. See [docs/upgrade.md](docs/upgrade.md).
+
+## [2.0.0] — 2026-09-17 — unified CLI + server
+
+**Breaking.** `flowjet-server` is merged into this repository and ships as one
+distribution, `flowjet`. See [RFC-004](docs/specs/RFC-004-unified-package.md).
+
+### Added
+
+- **One distribution, two surfaces.** `flowjet.core` (shared runtime),
+  `flowjet.cli` (was `fj_ai`) and `flowjet.server` (was `flowjet_server`).
+- **`fj serve`** — run the HTTP service from the CLI (alias of `flowjet-server`,
+  flags: `--host`, `-p/--port`, `--api-key`, `--nano-config`).
+- **Optional `[server]` extra.** `pip install flowjet` pulls one runtime
+  dependency (soothe-nano); FastAPI/uvicorn/ACP/pydantic-settings are opt-in
+  and lazily imported so `fj` never loads them.
+- **`DirectRuntimeBackend`** — the CLI now runs on the same `RuntimeBackend`
+  contract and `RuntimeEvent` stream as SSE and ACP.
+- **`Narration` event** — pre-tool-call text is available to the terminal for
+  live preview while remaining invisible to protocol clients.
+- **`SurfaceProfile`** (`flowjet.core.modes`) — the CLI's permissive workspace
+  and the server's workspace confinement are now explicit, per-surface
+  invariants; `bypass` mode is rejected on the server surface.
+- Auth now uses `hmac.compare_digest` instead of `!=`.
+
+### Changed
+
+- Distribution renamed `flowjet-agent` → `flowjet`; version single-sourced from
+  `flowjet.__version__` (the server no longer hard-codes `0.2.0`).
+- Builtin skills moved to `flowjet/builtin_skills` and are registered for both
+  surfaces.
+- `langchain-core` is now an explicit `server` dependency (it was imported but
+  undeclared).
+
+### Removed
+
+- The `fj_ai` and `flowjet_server` import namespaces. No compatibility shims —
+  see [docs/upgrade.md](docs/upgrade.md) for the migration table.
+
+## [0.2.0] — 2026-09-16
+
+### Added
+
+- **ACP (Agent Client Protocol) support.** flowjet-server now exposes an ACP
+  `Agent` over a WebSocket endpoint at `/acp`. Other ACP clients (Zed, custom
+  integrations) connect via `ws://host:port/acp` and drive the same
+  nano-backed `RuntimeBackend` used by the OpenAI-compatible Responses API.
+  The implementation bridges `RuntimeEvent` streams (RunStarted, Progress,
+  OutputTextDelta, ToolStarted/Completed, RunCompleted) to ACP
+  `session/update` notifications (agent_message_chunk, agent_thought_chunk,
+  tool_call/tool_call_update) and returns `PromptResponse` with
+  `stopReason=end_turn` + token usage. Initialize, session/new,
+  session/load, session/list, session/prompt, session/cancel, and
+  session/close are all supported.
+
+### Changed
+
+- **Bumped `soothe-nano` dependency** from `>=1.2.23,<2.0.0` to
+  `>=1.2.28,<2.0.0` (latest release).
+- **Added `agent-client-protocol[http]`** as a runtime dependency
+  (`>=0.12.1,<1.0.0`), providing the ACP SDK server + WebSocket transport.
+
+## [0.1.1] — 2026-09-05
+
+### Fixed
+
+- **litellm corrupted-install fix.** The previous image (v0.1.0) shipped a
+  broken `litellm` 1.99.0 wheel: `litellm/__init__.py` was listed in the
+  dist-info RECORD but missing from disk, so Python treated the package as an
+  empty namespace package and every `/v1/responses` call failed with
+  `module 'litellm' has no attribute 'acompletion'`. Reinstalling litellm with
+  `uv pip install --force-reinstall litellm==1.99.0` restores
+  `litellm/__init__.py` and `acompletion` becomes available again. The Docker
+  image now rebuilds the venv cleanly so the fix is baked into the published
+  image.
+
+### Verified
+
+Full E2E suite (`examples/e2e_http_api.py`) passes against the live server:
+
+| Endpoint | Method | Result |
+|---|---|---|
+| `/health` | GET | ✅ `{"status":"ok",...}` |
+| `/v1/models` | GET | ✅ returns `default` model |
+| `/v1/responses` (stream=false) | POST | ✅ status `completed`, real LLM text |
+| `/v1/responses/{id}` | GET | ✅ retrieve returns stored response |
+| `/v1/responses/{id}` | DELETE | ✅ `deleted:true`, subsequent GET → 404 |
+| `/v1/responses` (SSE, report) | POST | ✅ `response.created` → `output_text.delta` → `response.completed` |
+| `/v1/responses` (SSE, progress) | POST | ✅ includes `response.flowjet.progress` stages |
+| `/v1/responses` (SSE, developer) | POST | ✅ completes; no tool args leaked to wire |
+| unknown model | POST | ✅ HTTP 404 `model_not_found` |
+| missing id | GET | ✅ HTTP 404 `response_not_found` |
+
+## [0.1.0] — initial release
+
+OpenAI Responses–compatible HTTP service backed by soothe-nano (≥1.2.23).
+Includes ask/agent interaction modes, three SSE projection modes
+(report / progress / developer), thread-pool isolation (RFC-002), production
+isolation suite (RFC-003), and a self-contained Docker deploy stack
+(PostgreSQL + pgvector + flowjet-server).
+
+[0.1.1]: https://github.com/caesar0301/flowjet-server/releases/tag/v0.1.1
+[0.1.0]: https://github.com/caesar0301/flowjet-server/releases/tag/v0.1.0

flowjet-2.0.0/LICENSE

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

flowjet-2.0.0/PKG-INFO

@@ -0,0 +1,288 @@
+Metadata-Version: 2.5
+Name: flowjet
+Version: 2.0.0
+Summary: FlowJet — agent CLI (fj) and server (ACP + OpenAI-compatible HTTP) powered by soothe-nano
+Project-URL: Homepage, https://github.com/caesar0301/flowjet-agent
+Project-URL: Repository, https://github.com/caesar0301/flowjet-agent
+Project-URL: Issues, https://github.com/caesar0301/flowjet-agent/issues
+Author: Xiaming Chen
+License: MIT
+License-File: LICENSE
+Keywords: acp,agent,ai,cli,coding-agent,fj,flowjet,nano,openai,server,soothe
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: <3.15,>=3.11
+Requires-Dist: soothe-nano<1.3.0,>=1.2.28
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: openai>=2.51.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.12.0; extra == 'dev'
+Requires-Dist: twine>=5.0.0; extra == 'dev'
+Provides-Extra: server
+Requires-Dist: agent-client-protocol[http]<1.0.0,>=0.12.1; extra == 'server'
+Requires-Dist: fastapi>=0.115.0; extra == 'server'
+Requires-Dist: langchain-core>=0.3; extra == 'server'
+Requires-Dist: pydantic-settings>=2.0; extra == 'server'
+Requires-Dist: pydantic>=2.0; extra == 'server'
+Requires-Dist: uvicorn[standard]>=0.32.0; extra == 'server'
+Description-Content-Type: text/markdown
+
+# FlowJet
+
+[![PyPI version](https://img.shields.io/pypi/v/flowjet.svg)](https://pypi.org/p/flowjet)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/flowjet.svg)](https://pypi.org/p/flowjet)
+[![CI](https://github.com/caesar0301/flowjet-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/caesar0301/flowjet-agent/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+🎥 [Watch the demo on Vimeo](https://vimeo.com/1211730182)
+
+**FlowJet** is one agent runtime, two surfaces:
+
+| Surface | Entry point | What it gives you |
+|---------|-------------|-------------------|
+| **Terminal CLI** | `fj` | A friendly one-shot coding agent — ask in plain English, get an answer |
+| **HTTP service** | `flowjet-server` / `fj serve` | **ACP** over WebSocket + an **OpenAI-compatible API** (`/v1/responses`, `/v1/chat/completions`, `/v1/models`) |
+
+Both are the same distribution and the same `flowjet.core` runtime: one nano
+bootstrap, one stream mapper, one `RuntimeEvent` contract. The terminal renders
+those events as a progress line; the server renders them as SSE or ACP updates.
+
+```bash
+# CLI
+fj explain this repo
+fj -f what did we decide last time     # continue the latest conversation
+fjf what did we decide last time       # alias of fj -f
+
+# Server (OpenAI-compatible + ACP)
+flowjet-server                         # or: fj serve --port 8618
+```
+
+It runs on [soothe-nano](https://github.com/mirasoth/soothe-nano) — tools, skills, MCP, subagents, and progressive loading — with SQLite persistence so every conversation is resumable.
+
+> Package: **flowjet** · CLI aliases: `fj`, `fjf` (=`-f`) · Server: `flowjet-server` · Runtime: [soothe-nano](https://github.com/mirasoth/soothe-nano) · Naming details: [docs/naming.md](docs/naming.md)
+
+> **Upgrading from 1.x?** The distribution and all import paths were renamed. See [docs/upgrade.md](docs/upgrade.md).
+
+---
+
+## Install
+
+```bash
+pip install flowjet            # CLI only (one runtime dependency: soothe-nano)
+pip install 'flowjet[server]'  # + the HTTP service (fastapi, uvicorn, ACP)
+# or
+uv tool install 'flowjet[server]'
+```
+
+Requires Python 3.11+. The server half is an optional extra — `fj` never imports
+FastAPI or uvicorn.
+
+## Configure
+
+**Option A — Local model (guided setup):**
+
+```bash
+fj setup
+```
+
+This walks you through an OpenAI-compatible endpoint (Ollama, LM Studio, vLLM, …) and writes the basics to `~/.soothe/config/nano.yml`.
+
+**Option B — Cloud (no config file needed):**
+
+```bash
+export OPENAI_API_KEY=sk-...
+fj summarize README.md
+```
+
+Without a `nano.yml`, FlowJet falls back to `OPENAI_API_KEY` or `ANTHROPIC_API_KEY`.
+
+## Doctor
+
+Check whether your machine is ready to run `fj` (tool binaries, providers, observability):
+
+```bash
+fj doctor                 # quick check
+fj doctor --deep          # thorough check
+fj doctor --live-llm      # actually call the model
+fj doctor --format json   # machine-readable
+```
+
+---
+
+## Conversations
+
+Threads persist in SQLite, so you can pick up where you left off — continue the latest, jump to a specific one, or list them:
+
+```bash
+fj -f and now add tests          # continue this project's latest active thread
+fj -t abc123 continue from here  # continue a specific thread
+fj -l                            # list recent threads
+```
+
+`-f` is scoped to the project you are in — the git repo root, or the current directory when it is not a repo — so parallel work in other checkouts never hijacks your thread. `fj -l` still lists every thread; pick one up from anywhere with `-t ID`.
+
+## Flags
+
+```text
+fj [options] [--] <query...>
+```
+
+| Flag | Meaning |
+|------|---------|
+| `-f` / `--follow` | Continue the latest active thread in this project directory |
+| `-t ID` / `--thread` | Continue (or pin) a specific thread (overrides `-f`) |
+| `-l` / `--list` | List recent threads (newest first) |
+| `-n NUM` | How many threads `-l` shows (`0` = all) |
+| `-c PATH` / `--config` | Use an alternate `nano.yml` |
+| `-w DIR` / `--workspace` | Workspace root |
+| `--no-stream` | Wait for the full answer instead of streaming |
+| `-v` / `--verbose` | Mirror tool calls on stderr |
+
+> `-t` and `-f` can be combined; `-t` wins (explicit id overrides follow).
+
+Shell completion is AI-assisted — it predicts natural-language intents, not just flags:
+
+```bash
+eval "$(fj completion zsh)"     # or: fj completion bash
+```
+
+---
+
+## Extend
+
+### Skills
+
+FlowJet ships with AgentSkills (planning, TDD, debugging, document tools, MCP builder, and more). Add your own in `nano.yml`:
+
+```yaml
+skills:
+  - ~/.soothe/skills/my-reviewer
+  - ./skills/deploy
+```
+
+Each skill is a `SKILL.md` with frontmatter; progressive loading keeps the catalog compact and loads skills on demand.
+
+### MCP servers
+
+Connect any Model Context Protocol server:
+
+```yaml
+mcp_servers:
+  - name: filesystem
+    transport: stdio
+    command: npx
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+```
+
+With `defer: true` (the default), MCP tools activate on demand.
+
+---
+
+## Server
+
+Start the service and point any OpenAI-compatible client at it:
+
+```bash
+flowjet-server                       # defaults: host :: (dual-stack), port 8618
+fj serve --port 8618                 # same thing from the CLI
+```
+
+```python
+from openai import OpenAI
+
+client = OpenAI(api_key="local", base_url="http://127.0.0.1:8618/v1")
+print(client.responses.create(model="default", input="Hello"))
+```
+
+| HTTP | Purpose |
+|------|---------|
+| `GET /health` | Liveness + thread-pool metrics |
+| `GET /v1/models` | Logical model ids |
+| `POST /v1/responses` | Create a response (`stream=true` → SSE) |
+| `GET` / `DELETE /v1/responses/{id}` | Retrieve / cancel a response |
+| `POST /v1/chat/completions` | Chat Completions (non-stream + SSE) |
+| `WS /acp` | Agent Client Protocol (JSON-RPC) |
+
+FlowJet options travel in `extra_body.flowjet`:
+
+| Field | Values | Default | Meaning |
+|-------|--------|---------|---------|
+| `projection` | `report` \| `progress` \| `developer` | `report` | How much SSE detail to expose |
+| `session` | string | new `fj-<uuid>` | Isolates workspace + conversation thread |
+| `interaction_mode` | `agent` \| `ask` | `agent` | `ask` is hard read-only |
+| `metadata` | object | — | Opaque bag forwarded to the runtime |
+
+### Environment
+
+| Variable | Default | Meaning |
+|----------|---------|---------|
+| `FLOWJET_API_KEY` | unset | If set, require Bearer auth |
+| `FLOWJET_MODELS` | `default` | Comma-separated logical model ids |
+| `FLOWJET_HOST` | `::` | Bind host (dual-stack IPv4/IPv6) |
+| `FLOWJET_PORT` | `8618` | Bind port |
+| `FLOWJET_HOME` | `~/.flowjet` | Root for per-session workspaces |
+| `FLOWJET_NANO_CONFIG` | unset | Optional `nano.yml` (else `$SOOTHE_HOME/config/nano.yml`) |
+| `FLOWJET_THREAD_POOL_MIN` | `2` | Min isolation worker threads |
+| `FLOWJET_THREAD_POOL_MAX` | `8` | Max isolation worker threads |
+| `FLOWJET_THREAD_POOL_IDLE_TIMEOUT` | `300` | Scaled-worker idle exit seconds (`0` = never) |
+| `FLOWJET_MAX_REQUESTS_PER_WORKER` | `100` | Recycle worker after N turns (`0` = unlimited) |
+| `FLOWJET_REUSE_RUNNER` | `true` | Reuse agent adapter per worker |
+| `FLOWJET_REQUEST_TIMEOUT` | `0` | Per-run timeout seconds (`0` = none; set in production) |
+| `FLOWJET_READY_TIMEOUT` | `30` | Max wait for post-turn worker ready |
+| `FLOWJET_ALLOW_EXTERNAL_WORKSPACE` | `false` | Allow `metadata.workspace` outside `FLOWJET_HOME` |
+| `FLOWJET_CORS_ORIGINS` | `*` | Comma-separated browser origins allowed to call the API |
+
+### Security model
+
+The two surfaces have deliberately different invariants (enforced in
+`flowjet.core.modes`, not by whichever module loaded first):
+
+| | CLI | Server |
+|---|---|---|
+| `allow_paths_outside_workspace` | `True` (your machine) | **`False`** (per-request workspace, non-overridable) |
+| `bypass` interaction mode | available | **rejected** — tools must never escape the request workspace |
+| API key | — | optional `FLOWJET_API_KEY` (Bearer, constant-time compare) |
+
+`FLOWJET_CORS_ORIGINS` defaults to `*` with credentials enabled so browser
+clients work out of the box; set it to an explicit origin list in production.
+
+Full protocol reference and deployment guide: [deploy/README.md](deploy/README.md),
+[docs/specs/RFC-001-openai-compatible-api.md](docs/specs/RFC-001-openai-compatible-api.md).
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/caesar0301/flowjet-agent.git
+cd flowjet-agent
+make sync-dev          # dev + server extras
+make test              # unit + integration + server suites
+make test-server       # HTTP/ACP suites only
+make run               # start the server locally
+make lint
+```
+
+CI runs format, lint, and tests on Python 3.11–3.13; releases go GitHub Release → PyPI.
+
+## Powered by
+
+Built on [soothe-nano](https://github.com/mirasoth/soothe-nano). For a full TUI coding agent from the same stack, see [mirasoth/soothe](https://github.com/mirasoth/soothe).
+
+## License
+
+MIT