aichs 0.4.9__py3-none-win_amd64.whl

aichs-0.4.9.data/data/share/aichs/docs/agent-canvas.md

@@ -0,0 +1,38 @@
+# Agent Canvas Restriction Model
+
+The canvas graph is a planning and run contract, not a free-form diagram. Restrictions should make runs predictable without forcing the graph into artificial complexity.
+
+## Hard Constraints
+
+These should fail instead of autocorrecting:
+
+- Patch payloads must be valid and atomic.
+- Node kind, title, status, and component details must be valid.
+- Connections must match `connection_rules` exactly, including `source_port`.
+- Scoped graph-agent edits must stay inside the selected goal graph.
+- New nodes in a scoped edit must connect into that selected goal graph.
+- The source goal for the current generation cannot be deleted or given an incoming edge.
+- Directed cycles are blocked because graph runs require an acyclic branch.
+- Files nodes must contain repo-like paths only, one per line.
+
+## Soft Quality Checks
+
+These are graph-quality checks. Keep them simple, explain failures clearly, and autocorrect only when the fix is deterministic:
+
+- Generated context should feed an action or decision.
+- Generated multi-action plans should carry real graph value, not just a generic task list.
+- Generated multi-action plans with DoD should include expected evidence/proof.
+- Planning, design, research, or spec actions should feed implementation actions directly.
+
+## Current Autocorrections
+
+- Missing crew on generated operation nodes defaults from the title/detail:
+  - research/survey/investigate/compare -> Scout
+  - implement/build/wire/code/engine/state/integration/frontend/backend/parser/evaluator/persist -> Coder
+  - design/architecture/plan/spec/requirements/UX/UI/model/strategy -> Architect
+  - otherwise -> Coder
+- A patch with exactly one obvious planning/design/research/spec action and exactly one obvious implementation action gets an `operation.implement -> operation` connection when it is missing.
+
+## Do Not Autocorrect
+
+Do not autocorrect cycles, scope escapes, invalid connection kinds, protected-goal deletion, incoming edges to the source goal, fake file paths, or ambiguous multi-node handoffs. Those need either a clear tool failure or an `ask_user` question.

aichs-0.4.9.data/data/share/aichs/docs/compact.md

@@ -0,0 +1,43 @@
+# Compaction
+
+Compaction is only context management. When a conversation grows past the
+context budget, compaction cuts off an older prefix of the chat, asks the model
+for a concise continuation summary, and keeps that summary plus recent verbatim
+messages.
+
+The compacted summary is optimized for the next model call: current goal,
+important constraints, relevant files, decisions, tool results, blockers, and
+the next step. It is not a durable archive.
+
+## Raw History
+
+Compaction replaces the saved conversation messages with the compacted history.
+The old raw prefix is not kept in the active conversation JSON.
+
+Do not automatically save raw compaction archives by default. That would make
+compaction a hidden retention mechanism instead of a straightforward context
+cleanup operation.
+
+## Related State
+
+Durable project memory, handoff notes, and large-output retention live outside
+core compaction. Project memory is a separate built-in store with local, global,
+and disabled scopes; see [Project Memory](project-memory.md). Compaction itself
+stays focused on context reduction and resumability.
+
+Extensions can still provide their own context-resilience workflows. Extension
+tools, commands, context providers, and hooks receive `ctx.extension_id` and
+`ctx.storage`, so they can share project-scoped state without hand-rolled paths.
+
+For extension-owned workflows, use:
+
+- JSON state for compact handoff notes, decisions, blockers, and next steps.
+- Text artifacts for bulky tool output or reports via
+  `ctx.storage.save_artifact(name, content)`.
+- Context snippets to re-inject only the small current handoff.
+- Runtime compaction/resume directives when a continuation should happen at a
+  safe model-request boundary.
+
+Artifacts are references, not model context by default. A handoff state entry
+should point to a large artifact path and summarize why it matters instead of
+injecting the full output into every turn.

aichs-0.4.9.data/data/share/aichs/docs/configuration.md

@@ -0,0 +1,41 @@
+# Configuration
+
+By default, settings are stored in `~/.aichs/settings.json` (written by
+**Settings** in the app). Set `AICHS_HOME` before launch to move all app-owned
+user data, including settings, models, skills, conversations, extensions, MCP
+state, and recent workspaces, to another directory.
+
+| Key | Description |
+|---|---|
+| `anthropic_api_key` | Fallback if `ANTHROPIC_API_KEY` is unset |
+| `openai_api_key` | Fallback if `OPENAI_API_KEY` is unset |
+| `provider_api_keys` | Per-provider keys for built-in and custom providers |
+| `system_prompt` | Overrides the default system prompt |
+| `file_review_prompt_template` | Replaces the first line of **Ask File** drafts. Supports `{mention}` and `{path}` |
+| `diagnostic_fix_prompt_template` | Replaces only the first line of diagnostic fix drafts. Supports `{mention}`, `{path}`, and `{line}` |
+| `git_fix_prompt_template` | Replaces only the first line of git pull/push failure drafts. Supports `{action}`, `{label}`, `{repo}`, `{command}`, `{exit_code}`, and `{output}` |
+| `compact_resume_prompt` | Default resume message used after compact-and-resume when no extension prompt is supplied |
+| `auto_title_prompt_instructions` | Replaces the title-writing instructions; the first user message is attached automatically |
+| `compaction_summary_guidance` | Optional additive guidance appended to the fixed compaction summary prompt |
+| `project_memory_scope` | Project memory storage scope: `local` (default), `global`, or `disabled` |
+| `archivist_prompt` | Replaces instructions for the built-in `/archivist` slash command; command name and tools stay fixed |
+| `commit_message_prompt_addition` | Optional additive guidance appended to generated commit-message requests |
+| `default_models` | Default model per provider |
+| `theme` | `"dark"` or `"light"` |
+| `font_size` | Chat font size (pt) |
+| `trash_retention_days` | Days to keep deleted chats in Trash before permanent removal (default 14) |
+| `compaction.reserve_tokens` | Optional. Tokens held back for the next reply before auto-compaction (omit to scale from each model's context window) |
+| `compaction.keep_recent_tokens` | Optional. Recent message tokens to keep verbatim when compacting (omit to scale automatically) |
+
+API keys can also be set via environment variables or **Settings -> Models** before launch.
+
+Project memory defaults to local workspace storage at `.aichs/memory/project-memory.json`.
+Set `project_memory_scope` to `global` to use `AICHS_HOME/memory/global-memory.json`,
+or `disabled` to prevent project-memory reads and writes.
+
+MCP servers are configured separately in standard `mcp.json` files; see
+[MCP](mcp.md).
+
+Organization governance is configured separately through signed files under
+`AICHS_HOME/organization/`; see [Organization Governance](organization-governance.md)
+for policy format, trust keys, runtime lock behavior, and audit logging.

aichs-0.4.9.data/data/share/aichs/docs/custom-models.md

@@ -0,0 +1,299 @@
+# Custom models
+
+aichs ships with Claude and OpenAI models built in. You can add any provider that exposes an **OpenAI-compatible API** by creating `AICHS_HOME/models.json` (default `~/.aichs/models.json`).
+
+Custom providers appear automatically in the provider dropdown — no code changes needed.
+
+---
+
+## File format
+
+```json
+{
+  "providers": {
+    "<provider-id>": {
+      "api":      "openai-compatible",
+      "baseUrl":  "https://...",
+      "apiKey":   "ENV_VAR_NAME | !shell-command | literal-key",
+      "models": [
+        { "id": "model-id", "name": "Display Name" }
+      ]
+    }
+  }
+}
+```
+
+| Field | Required | Description |
+|---|---|---|
+| `api` | yes (new providers) | Always `"openai-compatible"` for now |
+| `baseUrl` | yes (new providers) | API base URL |
+| `apiKey` | yes | Key resolution — see below |
+| `models` | yes (new providers) | List of models to expose |
+| `contextWindow` | no | Context size in **tokens** for compaction and the usage ring (defaults: Claude 180k, OpenAI-compatible 100k) |
+| `temperature` | no | Top-level request temperature, `0.0` to `2.0` |
+| `topK` | no | OpenAI-compatible `extra_body.top_k`, integer `-1` or greater |
+| `minP` | no | OpenAI-compatible `extra_body.min_p`, `0.0` to `1.0` |
+
+Generation fields can be set on a provider as defaults or on an individual model as an override. `topK` and `minP` are only sent for OpenAI-compatible requests.
+
+### API key formats
+
+| Value | Resolved as |
+|---|---|
+| `"GEMINI_API_KEY"` | Read env var `$GEMINI_API_KEY` |
+| `"!op read op://vault/gemini/key"` | Run shell command, use stdout |
+| `"AIza..."` | Used literally (not recommended — use an env var) |
+
+### Overriding a built-in provider
+
+Omit `api` and `models` to only override `baseUrl` or `apiKey` on `claude` / `openai`:
+
+```json
+{
+  "providers": {
+    "openai": {
+      "baseUrl": "https://my-corporate-proxy.example.com/v1"
+    }
+  }
+}
+```
+
+---
+
+## Examples
+
+### Google Gemini
+
+Google exposes an OpenAI-compatible endpoint for all Gemini models. See [current model IDs](https://ai.google.dev/gemini-api/docs/models) — Gemini 2.0 is deprecated; prefer 3.x.
+
+Get an API key at [aistudio.google.com](https://aistudio.google.com).
+
+```json
+{
+  "providers": {
+    "google": {
+      "api":     "openai-compatible",
+      "baseUrl": "https://generativelanguage.googleapis.com/v1beta/openai/",
+      "apiKey":  "GEMINI_API_KEY",
+      "models": [
+        { "id": "gemini-3.5-flash",         "name": "Gemini 3.5 Flash" },
+        { "id": "gemini-3.1-pro-preview",   "name": "Gemini 3.1 Pro" },
+        { "id": "gemini-3-flash-preview",   "name": "Gemini 3 Flash" },
+        { "id": "gemini-3.1-flash-lite",    "name": "Gemini 3.1 Flash Lite" }
+      ]
+    }
+  }
+}
+```
+
+```bash
+export GEMINI_API_KEY=AIza...
+```
+
+---
+
+### Ollama (local models)
+
+[Ollama](https://ollama.com) runs models on your machine with no API key or internet connection required.
+
+**1. Install Ollama**
+
+```bash
+# macOS
+brew install ollama
+
+# Linux
+curl -fsSL https://ollama.com/install.sh | sh
+
+# Windows — download the installer from https://ollama.com/download
+```
+
+**2. Pull models**
+
+```bash
+ollama pull llama3.1:8b          # general purpose, fast
+ollama pull qwen2.5-coder:7b     # coding-focused, recommended
+ollama pull qwen2.5-coder:32b    # better quality, needs ~20 GB RAM
+ollama pull deepseek-coder-v2    # strong at code, ~8 GB RAM
+```
+
+Browse all available models at [ollama.com/library](https://ollama.com/library).
+
+**3. Start the server** (runs automatically on macOS after install; on Linux run manually)
+
+```bash
+ollama serve
+```
+
+Ollama listens on `http://localhost:11434` by default.
+
+**4. Add to `AICHS_HOME/models.json`**
+
+```json
+{
+  "providers": {
+    "ollama": {
+      "api":     "openai-compatible",
+      "baseUrl": "http://localhost:11434/v1",
+      "apiKey":  "ollama",
+      "contextWindow": 32768,
+      "models": [
+        { "id": "llama3.1:8b",        "name": "Llama 3.1 8B" },
+        { "id": "llama3.1:70b",       "name": "Llama 3.1 70B" },
+        { "id": "qwen2.5-coder:7b",   "name": "Qwen 2.5 Coder 7B" },
+        { "id": "qwen2.5-coder:32b",  "name": "Qwen 2.5 Coder 32B" },
+        { "id": "mistral:7b",         "name": "Mistral 7B" },
+        { "id": "deepseek-coder-v2",  "name": "DeepSeek Coder V2" }
+      ]
+    }
+  }
+}
+```
+
+No API key needed — `"ollama"` is a placeholder the server ignores.
+
+Set `contextWindow` to the size you configured in Ollama (or in **Settings → Models → Edit provider**). Without it, aichs assumes 100k like cloud OpenAI models.
+
+> **Tip:** Only list models you have already pulled. Selecting an unpulled model will return an error from the Ollama server.
+
+**Verify it works**
+
+```bash
+curl http://localhost:11434/v1/models
+```
+
+Should return a JSON list of your pulled models.
+
+---
+
+### DeepSeek
+
+```json
+{
+  "providers": {
+    "deepseek": {
+      "api":     "openai-compatible",
+      "baseUrl": "https://api.deepseek.com/v1",
+      "apiKey":  "DEEPSEEK_API_KEY",
+      "models": [
+        { "id": "deepseek-chat",     "name": "DeepSeek V3" },
+        { "id": "deepseek-reasoner", "name": "DeepSeek R1" }
+      ]
+    }
+  }
+}
+```
+
+```bash
+export DEEPSEEK_API_KEY=sk-...
+```
+
+---
+
+### OpenRouter
+
+[OpenRouter](https://openrouter.ai) proxies 100+ models under a single API key.
+
+```json
+{
+  "providers": {
+    "openrouter": {
+      "api":     "openai-compatible",
+      "baseUrl": "https://openrouter.ai/api/v1",
+      "apiKey":  "OPENROUTER_API_KEY",
+      "models": [
+        { "id": "meta-llama/llama-3.3-70b-instruct", "name": "Llama 3.3 70B" },
+        { "id": "mistralai/mistral-large",            "name": "Mistral Large" },
+        { "id": "qwen/qwen-2.5-coder-32b-instruct",  "name": "Qwen 2.5 Coder 32B" },
+        { "id": "google/gemini-3.1-pro-preview",      "name": "Gemini 3.1 Pro (OR)" }
+      ]
+    }
+  }
+}
+```
+
+```bash
+export OPENROUTER_API_KEY=sk-or-...
+```
+
+---
+
+### Proxy / corporate gateway
+
+Route a built-in provider through your own endpoint without changing models:
+
+```json
+{
+  "providers": {
+    "anthropic": {
+      "baseUrl": "https://gateway.corp.example.com/anthropic"
+    },
+    "openai": {
+      "baseUrl": "https://gateway.corp.example.com/openai"
+    }
+  }
+}
+```
+
+The existing model lists and API keys are preserved; only the base URL changes.
+
+---
+
+### API key from a password manager
+
+Use `!command` to fetch keys at runtime instead of storing them in env vars:
+
+```json
+{
+  "providers": {
+    "google": {
+      "api":     "openai-compatible",
+      "baseUrl": "https://generativelanguage.googleapis.com/v1beta/openai/",
+      "apiKey":  "!op read op://Personal/Gemini/credential",
+      "models": [
+        { "id": "gemini-3.5-flash", "name": "Gemini 3.5 Flash" }
+      ]
+    }
+  }
+}
+```
+
+Works with any CLI tool: `op` (1Password), `bw` (Bitwarden), `pass`, `security` (macOS Keychain), etc.
+
+---
+
+## Full example
+
+A `AICHS_HOME/models.json` combining multiple providers:
+
+```json
+{
+  "providers": {
+    "google": {
+      "api":     "openai-compatible",
+      "baseUrl": "https://generativelanguage.googleapis.com/v1beta/openai/",
+      "apiKey":  "GEMINI_API_KEY",
+      "models": [
+        { "id": "gemini-3.5-flash",       "name": "Gemini 3.5 Flash" },
+        { "id": "gemini-3.1-pro-preview", "name": "Gemini 3.1 Pro" }
+      ]
+    },
+    "ollama": {
+      "api":     "openai-compatible",
+      "baseUrl": "http://localhost:11434/v1",
+      "apiKey":  "ollama",
+      "models": [
+        { "id": "qwen2.5-coder:32b", "name": "Qwen 2.5 Coder 32B" }
+      ]
+    },
+    "deepseek": {
+      "api":     "openai-compatible",
+      "baseUrl": "https://api.deepseek.com/v1",
+      "apiKey":  "DEEPSEEK_API_KEY",
+      "models": [
+        { "id": "deepseek-chat", "name": "DeepSeek V3" }
+      ]
+    }
+  }
+}
+```