cyrenecode 0.1.0

package/LICENSE

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

package/README.md

@@ -0,0 +1,260 @@
+<p align="center">
+  <img src="assets/brand/cyrene-logo.svg" alt="Cyrene" width="420" />
+</p>
+
+# Cyrene
+
+Terminal-first coding assistant built with Bun, React Ink, and a reviewable query loop.
+
+## Install
+
+### Global CLI
+
+```bash
+npm install -g cyrenecode
+```
+
+Or run it without a global install:
+
+```bash
+npx cyrenecode
+```
+
+### From source
+
+```bash
+bun install
+```
+
+> The published npm package ships a prebuilt CLI bundle. If you are developing
+> from source, install Bun first.
+
+## Run from source
+
+```bash
+bun dev
+```
+
+By default, the CLI runs with a local in-memory core transport, so you can test
+the full query loop without any backend service.
+
+## Configure
+
+Cyrene now uses a **global user config home** by default:
+
+- Windows: `C:\Users\<you>\.cyrene`
+- macOS / Linux: `~/.cyrene`
+
+Project-local `.cyrene/` is still read for backward compatibility, but global
+user scope is the primary home for model/provider metadata and session state.
+
+### HTTP credentials
+
+You can still launch with explicit environment variables:
+
+```bash
+CYRENE_BASE_URL=https://your-openai-compatible-host
+CYRENE_API_KEY=your_api_key
+CYRENE_MODEL=gpt-4o-mini
+```
+
+When they are present, they remain the **highest-priority source** for that run.
+Cyrene will report them as `process_env` via `/auth` and will not overwrite them
+behind your back.
+
+### First-run login onboarding
+
+If usable HTTP credentials are missing, Cyrene auto-opens a skippable login
+wizard on the initial idle screen.
+
+Wizard flow:
+
+1. provider base URL
+2. API key
+3. optional initial model
+4. confirmation + persistence target preview
+
+Skip is always allowed. If you skip, Cyrene stays fully usable in `local-core`
+mode and you can reconnect later with `/login`.
+
+### What gets persisted where
+
+- **Secret only:** `CYRENE_API_KEY`
+  - Windows: user-level environment variable
+  - macOS/Linux zsh: managed block in `~/.zshrc`
+  - macOS/Linux bash: managed block in `~/.bashrc` or `~/.bash_profile`
+  - fish: managed file in `~/.config/fish/conf.d/`
+  - other POSIX shells: managed block in `~/.profile`
+- **Non-secret provider/model metadata:** global user `.cyrene/model.yaml`
+
+Successful `/login` persists the API key at user scope and also updates the
+current CLI process so the transport can switch immediately without restart.
+`/logout` removes only the Cyrene-managed persisted API key. It does **not**
+delete sessions, summaries, or model/provider catalog files.
+
+When credentials are missing or incomplete, Cyrene falls back to local-core
+instead of blocking the app.
+
+#### Shell-specific persistence behavior
+
+- **zsh**: updates one managed block in `~/.zshrc`
+- **bash**: uses `~/.bashrc`, otherwise `~/.bash_profile`, otherwise creates `~/.bashrc`
+- **fish**: writes `~/.config/fish/conf.d/cyrene-auth.fish`
+- **other POSIX shells**: updates one managed block in `~/.profile`
+
+Repeated `/login` updates replace the existing Cyrene-managed entry instead of
+duplicating it. `/logout` removes only the Cyrene-managed block or file and
+does not touch unrelated shell configuration.
+
+Current request shape:
+```json
+{
+  "model": "gpt-4o-mini",
+  "stream": true,
+  "messages": [{ "role": "user", "content": "..." }]
+}
+```
+
+Model switch:
+- `/model` opens model picker (Up/Down select, Left/Right page, Enter switch).
+- `/model refresh` pulls model list immediately and overwrites `.cyrene/model.yaml`.
+- `/model <name>` switches immediately only if model exists in `.cyrene/model.yaml`; otherwise it fails.
+- `/login` opens the auth wizard on demand.
+- `/logout` removes Cyrene-managed user-scoped API key persistence.
+- `/auth` shows the current mode, credential source, and persistence target.
+
+Model source priority:
+1. `.cyrene/model.yaml`
+2. If missing/invalid, fetch from `GET /v1/models`
+3. If fetch fails, model initialization fails (and refresh reports failure)
+
+Prompt priority and customization:
+- Priority is fixed as: `system prompt > .cyrene/.cyrene.md > pins`.
+- User-facing config is centralized in `.cyrene/config.yaml`.
+- `system_prompt` can be set in `.cyrene/config.yaml` (or env fallback: `CYRENE_SYSTEM_PROMPT=...`).
+- `auto_summary_refresh` can be set in `.cyrene/config.yaml` to enable/disable the rolling reducer that updates `summary` + `pendingDigest` inside normal user turns. Default: `true`.
+- `request_temperature` can be set in `.cyrene/config.yaml` to control the HTTP main-request sampling temperature. Default: `0.2`.
+- Runtime system prompt commands:
+  - `/system` show current system prompt
+  - `/system <text>` set current runtime system prompt
+  - `/system reset` reset to default
+- `.cyrene/.cyrene.md` is fully user-editable project policy.
+- `/pin <note>` and `/pins` manage human-selected focus.
+- `/unpin <index>` removes one pinned focus item (1-based index).
+
+Session and context:
+- Sessions are persisted under `.cyrene/session` as JSON files.
+- `/help` shows the command reference.
+- `/sessions` lists sessions by latest update time.
+- `/resume <session_id>` restores a previous session.
+- `/resume` opens keyboard picker (Left/Right page, Enter resume, Esc cancel).
+- `/new` starts a fresh session.
+- `/pin <note>` stores human-selected key context.
+- `/pins` shows pinned key context.
+- `/unpin <index>` removes a pinned key context item.
+- `/state` shows reducer/session state diagnostics for the current runtime.
+- `/auth` shows whether the runtime is using HTTP or local-core, plus where the
+  current credential came from.
+- Pin count comes from `.cyrene/config.yaml` via `pin_max_count`.
+- Older context is tracked through the rolling working-state pair: durable `summary` + lagging `pendingDigest`, while recent turns are kept for prompt context.
+
+## Rolling context architecture
+
+Cyrene keeps long-running coding context in three layers instead of stuffing the
+entire transcript back into every prompt:
+
+1. **`summary`** - a durable, compact working state used as the main context anchor
+2. **`pendingDigest`** - the most recent turn digest that has not been merged yet
+3. **memory index** - richer archived evidence that can be retrieved on demand
+
+This keeps prompts smaller while still preserving continuity. The durable summary
+is intentionally structured into sections such as:
+
+- `OBJECTIVE`
+- `CONFIRMED FACTS`
+- `CONSTRAINTS`
+- `COMPLETED`
+- `REMAINING`
+- `KNOWN PATHS`
+- `RECENT FAILURES`
+- `NEXT BEST ACTIONS`
+
+### High-level memory layout
+
+```mermaid
+flowchart TD
+    U["User turn"] --> P["Prompt builder"]
+    S["Durable summary"] --> P
+    D["Pending digest<br/>(last turn, not yet merged)"] --> P
+    M["Memory index<br/>(retrieved evidence)"] --> P
+    P --> Q["Main model request"]
+    Q --> A["Visible assistant answer"]
+    Q --> H["Hidden reducer block<br/>&lt;cyrene_state_update&gt;..."]
+    H --> R["Reducer parser"]
+    R --> S
+    R --> D
+    M -. "search / retrieval guided by summary + digest" .-> P
+```
+
+### One turn -> summary progression
+
+Cyrene does **not** make a second background summary request after the answer.
+Instead, state updates piggyback on the same main response.
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant C as Cyrene UI
+    participant P as Prompt Builder
+    participant L as LLM
+    participant R as Reducer Parser
+    participant S as Session Store
+
+    U->>C: Send current request
+    C->>S: Load summary + pendingDigest + retrieved memory
+    S-->>C: Current session context
+    C->>P: Build main prompt
+    P->>L: One normal model request
+
+    L-->>C: Visible answer + hidden state tail
+    Note over L,C: <cyrene_state_update>{...}</cyrene_state_update>
+
+    C->>R: Strip visible answer, parse reducer payload
+    R-->>C: Parsed update
+    C->>S: Persist visible assistant message
+
+    alt First reducer-enabled turn
+        C->>S: Keep summary as-is
+        C->>S: Store new pendingDigest
+    else Later turn with valid reducer payload
+        C->>S: Merge old pendingDigest into summary
+        C->>S: Replace pendingDigest with current-turn digest
+    else Missing/invalid reducer tail
+        C->>R: Build local fallback digest
+        alt Prior pendingDigest exists
+            C->>S: Locally advance summary from prior pendingDigest
+            C->>S: Store fallback pendingDigest for current turn
+        else No prior pendingDigest
+            C->>S: Store fallback pendingDigest only
+        end
+    end
+```
+
+### Why this design exists
+
+- avoids a hidden second model call after every answer
+- keeps prompt growth bounded
+- makes task progress explicit for the model
+- lets archive retrieval stay detailed while the working state stays small
+
+Use `/state` during a session to inspect reducer mode, `summary` length,
+`pendingDigest` length, and the latest state-update diagnostic.
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for repository security boundaries, disclosure
+guidelines, and hardening notes.
+
+## License
+
+[MIT](LICENSE)

package/SECURITY.md

@@ -0,0 +1,117 @@
+# Security Policy
+
+## Supported versions
+
+This repository is under active development. Security fixes are expected to land
+on the latest mainline code first.
+
+| Version | Supported |
+| --- | --- |
+| latest `main` / current working tree | Yes |
+| older snapshots / forks / local patches | Best effort only |
+
+## Reporting a vulnerability
+
+If you believe you found a security issue, please **avoid public disclosure
+first**.
+
+Recommended process:
+
+1. Share the issue privately with the project maintainers through an existing
+   trusted channel.
+2. Include:
+   - affected commit / branch
+   - reproduction steps
+   - impact assessment
+   - whether the issue requires local access, workspace access, or network access
+3. Wait for a fix or mitigation plan before publishing details.
+
+If this repository is hosted on a platform that supports private security
+reporting, prefer that channel.
+
+## Security model
+
+Cyrene is a local, terminal-first coding assistant. Its security posture relies
+on a few core boundaries:
+
+### 1. Workspace boundary
+
+- file tools are intended to stay inside the configured workspace root
+- path-escape checks should reject reads/writes outside the workspace
+- review-gated mutations should show the exact target path before approval
+
+### 2. Human review boundary
+
+- destructive or higher-risk filesystem actions should require review
+- shell and command execution should be reviewable unless explicitly classified
+  as low risk
+- persistent shell sessions should preserve clear status output so users know
+  what is running
+
+### 3. Prompt/context boundary
+
+- long-lived context is compacted into `summary` and `pendingDigest`
+- archive memory is indexed and retrieved selectively instead of replaying
+  entire transcripts
+- hidden reducer state should never be shown to users as visible transcript text
+
+### 4. Provider boundary
+
+- HTTP transport sends prompts to an OpenAI-compatible API when configured
+- `CYRENE_API_KEY` is intentionally excluded from transcript items, session
+  JSON, reducer state (`summary` / `pendingDigest`), and memory index storage
+- Cyrene may persist `CYRENE_API_KEY` in **user-scoped environment/profile
+  storage** through the login flow:
+  - Windows user environment
+  - managed shell-profile blocks for zsh / bash / POSIX shells
+  - managed fish config file under `~/.config/fish/conf.d/`
+- provider URL and model catalog metadata live in the global user `.cyrene`
+  directory and are treated as non-secret runtime metadata
+- model/provider switching should be explicit and visible in the UI
+
+## Current hardening expectations
+
+When changing code, please preserve or improve these properties:
+
+- prevent duplicate request submission and duplicate completion handling
+- avoid command/tool loops that cause accidental repeated execution
+- keep approval flows one-shot and idempotent where possible
+- do not allow hidden reducer metadata to leak into visible assistant output
+- keep large-file and large-output handling bounded to protect terminal stability
+- maintain test coverage for:
+  - workspace escape protection
+  - review-gated file mutations
+  - command/shell risk handling
+  - duplicate submit / duplicate finalize guards
+  - reducer fallback behavior
+
+## Out of scope / non-goals
+
+Unless explicitly documented otherwise, this project does **not** currently
+promise:
+
+- sandboxing against a malicious local user with full machine access
+- protection against a compromised upstream model or provider
+- protection against unsafe custom plugins, local patches, or user-modified
+  prompts/policies
+- backward security support for stale forks or heavily diverged branches
+
+## Secure deployment notes
+
+If you run Cyrene outside local experimentation:
+
+- keep API keys out of the repo and shell history
+- review `.cyrene/` config and session files before sharing them
+- remember that login persistence writes `CYRENE_API_KEY` to user-scoped shell
+  or environment storage, not to session JSON
+- treat session logs as potentially sensitive prompt/output data
+- prefer least-privilege execution contexts for shell access
+- verify Docker / CI mounts so the workspace root is exactly what you intend
+- rotate provider credentials if they were ever written to logs or transcripts
+
+## Disclosure philosophy
+
+Please report vulnerabilities responsibly and give maintainers time to patch
+before publishing exploit details. Public issues are welcome for general
+hardening ideas, but not for live secrets, escape techniques, or reproducible
+unpatched exploit chains.

package/assets/brand/cyrene-logo.svg

@@ -0,0 +1,11 @@
+<svg width="820" height="200" viewBox="0 0 820 200" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="cyreneLogoTitle cyreneLogoDesc">
+  <title id="cyreneLogoTitle">Cyrene Logo</title>
+  <desc id="cyreneLogoDesc">Cyrene wordmark paired with a geometric cyan C-shaped signal mark.</desc>
+  <g transform="translate(18 20)">
+    <path d="M108 44C95.8497 32.2032 77.5944 28.7658 61.9407 35.2795C46.287 41.7932 36 57.07 36 74.0252C36 90.9804 46.287 106.257 61.9407 112.771C77.5944 119.284 95.8497 115.847 108 104.05" stroke="#2FD7FF" stroke-width="18" stroke-linecap="round"/>
+    <path d="M77 63L98 80L77 97" stroke="#08131B" stroke-width="14" stroke-linecap="round" stroke-linejoin="round"/>
+    <path d="M77 63L98 80L77 97" stroke="#F3FCFF" stroke-width="7" stroke-linecap="round" stroke-linejoin="round"/>
+    <circle cx="108" cy="80" r="8" fill="#2FD7FF" stroke="#08131B" stroke-width="4"/>
+  </g>
+  <text x="178" y="118" fill="#F4FCFF" stroke="#08131B" stroke-width="8" paint-order="stroke fill" font-family="'Segoe UI', 'Helvetica Neue', Arial, sans-serif" font-size="88" font-weight="800" letter-spacing="11">CYRENE</text>
+</svg>

package/assets/brand/cyrene-mark.svg

@@ -0,0 +1,8 @@
+<svg width="160" height="160" viewBox="0 0 160 160" fill="none" xmlns="http://www.w3.org/2000/svg" role="img" aria-labelledby="cyreneMarkTitle cyreneMarkDesc">
+  <title id="cyreneMarkTitle">Cyrene Mark</title>
+  <desc id="cyreneMarkDesc">A geometric cyan C-shape with a forward signal arrow and locator dot.</desc>
+  <path d="M108 44C95.8497 32.2032 77.5944 28.7658 61.9407 35.2795C46.287 41.7932 36 57.07 36 74.0252C36 90.9804 46.287 106.257 61.9407 112.771C77.5944 119.284 95.8497 115.847 108 104.05" stroke="#2FD7FF" stroke-width="18" stroke-linecap="round"/>
+  <path d="M77 63L98 80L77 97" stroke="#08131B" stroke-width="14" stroke-linecap="round" stroke-linejoin="round"/>
+  <path d="M77 63L98 80L77 97" stroke="#F3FCFF" stroke-width="7" stroke-linecap="round" stroke-linejoin="round"/>
+  <circle cx="108" cy="80" r="8" fill="#2FD7FF" stroke="#08131B" stroke-width="4"/>
+</svg>

package/bin/cyrene.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/cli.js";