KISS Sorcar: Complete Feature Inventory

Version 2026.9.18 · repository /home/ksen/kiss (4,496 commits) · task database ~/.kiss/sorcar.db · compiled 2026-09-20

This report enumerates everything KISS Sorcar can do. Every item was checked against the source tree, not only the README: the tool functions registered in src/kiss/agents/sorcar/sorcar_agent.py, the daemon command handlers in src/kiss/server/, the browser client in src/kiss/agents/vscode/media/, the 43 channel-agent modules, the CLI entry points in pyproject.toml, and the system prompt in src/kiss/SYSTEM.md. The last section turns to the recorded trajectories in sorcar.db to show which of these capabilities are actually used and how hard they have been pushed.

1. At a glance

2. Architecture

One local daemon, kiss-web, hosts every agent and serves every client. The agent is a five-layer class stack; each layer adds one concern. Lines of code below are from wc -l on 2026-09-20.

3. Interfaces and prompt surfaces

4. Agent runtime

KISSAgent (src/kiss/core/kiss_agent.py)

• Native function calling against every adapter; tool schemas are built once per tool set and rebuilt on model switch.
• Hard limits per run: max_budget (USD), max_steps, and context length (CONTEXT_LIMIT_FRACTION of the model's window); raises BudgetExceededError / ContextWindowExceededError.
• Retries with backoff; non-retryable errors (bad key, permission denied, low credit, model gated) trigger a one-shot fallback model registered in MODEL_INFO.json, copying the conversation so no context is lost.
• Tool-output compaction (context_compaction.py): once the context passes 100k tokens, old tool results longer than 2,000 chars are replaced by 200-char stubs, keeping the 20 newest; repeated every 50k of growth.
• Read dedupe and outlines: re-reading an unchanged range returns a one-line note; files over 2,000 lines return an outline (config flags read_dedupe, read_outline_lines).
• Implicit finish: a model that stops calling tools is wrapped into a finish result instead of erroring.
• Per-tool-call interrupt (tool_interrupt.py): the Stop button on one panel aborts that tool call while the task continues; the model sees USER_INTERRUPTED_MESSAGE.
• Streamed responses that go quiet are aborted and retried (stream_abort.py, stream_stall_timeout).
• Image and PDF attachments travel with the prompt (Attachment; HEIC/HEIF converted, oversized images re-encoded).
• Prompt caching on Anthropic (cache_control: ephemeral); usage/cost tracked per response from catalog prices.
• Non-agentic single-shot mode (used by the classifier, commit-message generation and TTS).

RelentlessAgent (relentless_agent.py)

• Auto-continuation: when a session exhausts its context the agent calls finish(is_continue=True) with a structured progress summary and a fresh sub-session resumes from it (up to max_sub_sessions, default 10,000). Prior-session summaries are capped and re-injected.
• Append-only usage ledger with epochs so spend from sub-agents, abandoned children, classifier calls and TTS is counted exactly once even across stop-interrupts.
• Optional docker_image: Bash/Read/Write/Edit execute inside a container (docker_manager.py, docker_tools.py) with streaming output, per-exec kill tokens and output caps.
• Host settings (IP, machine, OS, PID, user id, chat/task ids) are placed in the system prompt.

SorcarAgent (sorcar_agent.py)

• Builds the tool set (section 5), the Playwright browser, the memory tools, the classifier, run_parallel fan-out and run_agent dispatch.
• Tool profiles: full, review (Bash, Read, run_commands_parallel, memory reads, decide, summary) and shell (Bash, Read, run_commands_parallel); reviewer children get review automatically.
• Review quota (fanout_guard.py): at most 3 review rounds per task tree; "at most N% of the budget for reviewing" in the prompt clips reviewer budgets; sub-agent budgets are split from the parent's remainder with a $0.50 floor.
• Sub-agents open their own tabs, are persisted with parent_task_id, and their spend folds into the parent.
• Auto-commit with an LLM-generated commit message (commit_message.py) after non-worktree tasks.

ChatSorcarAgent and WorktreeSorcarAgent

• Chat continuation: earlier tasks of the same chat_id are replayed as context, with a digest for older entries (chat_history_digest).
• Every event (system prompt, prompt, thinking, text, tool call, tool result, usage, result) is persisted to sorcar.db for live mirroring, resume and replay.
• Worktree isolation per task (section 11).

5. Built-in tools

Tools the model can call in a standard run, grouped by concern. Names are the exact function names registered in SorcarAgent._get_tools.

6. Models and multi-model routing

• Catalog: 665 models in MODEL_INFO.json with prices, context lengths and capability flags (fc, gen, emb, dec): OpenAI 102, Anthropic 14, Gemini 24, Together AI 103, Z.AI 8, Moonshot AI 10, OpenRouter 382, Claude Code CLI cc/* 14, Codex CLI codex/* 8. Rolling aliases such as openrouter/~anthropic/claude-opus-latest.
• Adapters: Anthropic native, OpenAI-compatible (Chat Completions and Responses API), Gemini, Claude Code CLI, Codex CLI, Decisions. Reasoning-effort variants (-low/-medium/-high/-xhigh) are catalog entries.
• Mix vendors inside one task: set_model mid-run, run_parallel(model_name=…) for sub-agents, per-channel and per-cron model overrides, model picker per tab, live model switch from the UI while a task runs.
• Routing by prompt: bundled "tricks" pair a builder model with a read-only reviewer (e.g. claude-fable-5-1 + gpt-5.6-sol); a trick reads ./ROUTING.md and asks the agent to update the routing strategy after each task.
• Custom models: ~/.kiss/MY_MODELS.json entries (local vLLM/Ollama or any OpenAI-compatible endpoint) appear in the picker; custom endpoint, API key and HTTP headers per run via model_config or the Settings panel.
• Catalog maintenance: update_models.py fetches vendor pricing, tests generation/embedding/function-calling/decisions, and rewrites the catalog; update_responses_api_support.py live-verifies Responses API support; an "Update models" button in Settings.
• API keys live in $KISS_HOME/api_keys.env, settable from the Settings panel or environment.

7. Chat client features

Verified against element ids in media/chat.html and message types in media/main.js.

• Input: @ file/folder mentions with ranked completion; ghost-text autocomplete from input history and frequent tasks; attachments by picker, paste or drag-and-drop (images, PDFs); input history; clear; tricks panel (promptlets inserted into the input); tips panel; sample-task chips on the welcome screen; "Suggested next" follow-up after each task.
• Run controls: model picker with search, per-task budget cap, Stop, per-panel tool interrupt, live steering (send a message into a running task), <task>…</task> to queue a follow-up task, model switch during a run.
• Rendering: streamed text and thinking, collapsible tool panels, syntax-highlighted code (highlight.js, light/dark theme toggle), inline images produced by tools, clickable file paths that open in the editor (existence verified via checkPaths), copy buttons, nested sub-agent panels, collapsed groups after every summary.
• Tabs: server-canonical tab registry mirrored across every VS Code window and web client on the same workspace; sub-agents open their own tabs; adjacent-task navigation within a chat.
• History: search, filters (workspace, running/completed/errors, date range, favorites), resume a chat, open a task from history, frequent-tasks panel, delete frequent task, share a chat or selected tasks as a standalone HTML page (share.js, e.g. reports/chat-*.html).
• Workspace views (web app): Explorer tree with New File/Folder, Rename, Delete, Cut/Copy/Paste, Find in Folder, Compare; Source Control view with branch, changes, commit graph, git show; file open/save from the browser.
• Git actions: autocommit button and progress, worktree merge/discard/leave prompts, main-tree actions, generate commit message.
• Settings panel: work dir, default max budget, worktree on/off, auto-commit, classify tasks, classify with Jev, web tools on/off, memory on/off and memory directory, editor-tabs mode, voice sensitivity and auto-submit, remote password, remote URL, API keys, custom endpoint/headers/model, custom models list, Update button, Update models, Server reset.
• Status: bottom bar with steps, tokens, budget, machine; Task Info drawer with task id, chat id, parent, model, date, time, work dir, worktree and parallel flags; daemon status and update-available notices.

8. Voice

• Wake-word listener (voice_wake.py, Vosk model auto-downloaded) runs as a daemon child process; fuzzy match on "Sorcar" (Levenshtein), sensitivity levels, silence trimming, speaker identification, language detection.
• Speech-to-text of the captured utterance through a catalog model; transcripts arrive as Speaker #N says in the language xx that: … (114 such top-level tasks recorded).
• Spoken replies: the talk tool synthesizes MP3 server-side with gpt-audio-1.5 (emotion hint supported), broadcast to every client tab of the task, with a system-TTS fallback on the daemon (talk_player.py).
• Acknowledgement sound (working-on-it.mp3) and a listening overlay in the UI; voice auto-submit setting.

9. Persistent memory (memoryfield)

• Markdown pages with generated frontmatter under ~/.kiss/memories (or a custom directory), indexed in SQLite with vector embeddings: OpenAI embeddings when a key exists, otherwise an offline hashed embedder.
• Seven tools (search, pull, read, write, list, refresh, delete); memory_refresh re-indexes external edits and reports near-duplicates and stale pages.
• A memory protocol in the system prompt: recall before work, record durable knowledge, never store secrets, keep per-session notes in ./tmp/PROGRESS.md.
• Disabled for Docker runs, cc/*/codex/* models, runs without the built-in toolset, or runs with a caller-supplied system prompt; toggle with KISS_USE_MEMORY or the settings panel.
• memoryfield/evaluate.py measures Recall@k and MRR on real past tasks from sorcar.db.

10. Task classifier

• Runs once before each task to decide (a) whether the task edits files (worktree needed) and (b) whether it is simple (use SYSTEM_LITE.md, 4.1 KB, instead of SYSTEM.md, 20.7 KB).
• With an OpenRouter key it asks ~typesafe/jev-latest one typed question (about 0.2 s, $0.00003); otherwise one non-agentic structured-output call on the run's model with a plain-text retry; skipped for CLI models.
• Verdicts are cached on disk; classifier spend folds into the task's totals; benchmark of 415 prompts in benchmarkings/task_classifier/.

11. Git integration and worktrees

• Each development task runs in a fresh git worktree on a unique branch (.kiss-worktrees/); a spare worktree is pre-created in the background (worktree_pool.py) so tasks start in well under a second on large repos.
• On success: auto-commit and merge back, or an interactive merge/discard/leave-as-is prompt; conflicts are detected and reported; stash-pop and merge-conflict warnings are surfaced; ignored files can be rescued on discard.
• Failed or stopped tasks leave their work committed on the branch; retired worktrees are cleaned up when no abandoned sub-agent still writes to them.
• Bash and file tools rewrite parent-repo paths into the worktree and block edits that would escape it.
• Non-worktree tasks get post-task auto-commit with a generated message; the extension exposes Generate Commit Message and Git Commit commands.
• 22,023 of 24,063 recorded task rows ran with worktree isolation.

12. Scheduled automations

• Natural-language requests are dispatched to the cron agent (run_agent("cron", …); also kiss-cron from the shell). Its cron_job tool creates, lists, pauses, resumes, removes or immediately runs jobs stored in ~/.kiss/cron/jobs.json.
• Schedules: 5-field cron expressions and one-shot timestamps; a scheduler thread in kiss-web ticks about once a minute.
• Two job kinds: prompt jobs run an unattended Sorcar task (never asks questions, replies [SILENT] to suppress delivery) and command jobs run a shell command without a model (whole process tree killed on timeout).
• Delivery of results to authenticated channels (telegram:123456, email:user@example.com, …; 25 of 32 channels), with until_delivered retry semantics; outputs kept under ~/.kiss/cron/output.
• Recorded: 17 cron_job calls and 42 unattended cron-launched tasks; one job is currently configured on this machine.

13. Third-party agents and credential isolation

43 modules in src/kiss/agents/third_party_agents/, each a Sorcar Extension Agent whose tools() returns auth tools plus the backend's public methods once authenticated. Configuration lives under ~/.kiss/third_party_agents/<service>/; authentication happens by chatting.

• Dispatch: the top-level session names the service and calls run_agent; channel names match forgivingly; multi-account workspaces via KISS_CHANNEL_WORKSPACE; dispatched sessions cannot dispatch further.
• Gateway mode for channels with an inbound stream (section 3) and scheduled delivery (section 12).
• Muse auth (Linux): credentials for 24 connectors live in a vault owned by a local auth daemon; the agent holds only surrogate tokens swapped at the network edge; every request is host-allowlisted, classified read/write and checked against an allow/deny/ask policy with an audit log; OAuth device grants (GitHub, Twitch, Microsoft Teams), Nextcloud Login Flow v2, Matrix OAuth device grant, Signal QR linking; CLI python -m kiss.agents.third_party_agents.muse_auth with status, enroll, import, grant, revoke, audit, clear, daemon, stop, export; opt out with KISS_MUSE_AUTH=0.
• The agent never asks for a password or 2FA code; login walls are handed to the user's own browser.

14. Extension points: MCP, skills, SEAs

• MCP servers: discovered from ~/.kiss/mcp.json, <project>/.kiss/mcp.json, <project>/.mcp.json; stdio, HTTP and SSE transports; OAuth 2.1 with dynamic client registration and PKCE, tokens under ~/.kiss/mcp_auth/; tools exposed as <server>_<tool> and filtered by mcp_permissions wildcard rules; save/remove servers programmatically.
• Connector catalog (connectors/): 16 curated privacy-first MCP servers (fetch, time, memory, sequential-thinking, deepwiki, context7, github, google, slack, twilio-sms, whatsapp, brave-search, notion, postgres, firecrawl, playwright) with enable.py/verify.py CLIs; credentials read from the shell, never stored.
• Agent Skills: loaded from ~/.kiss/skills, <project>/.kiss/skills, Claude skill directories, .agents/skills and bundled skills; a single skill(name) tool loads SKILL.md and lists bundled resources; permission rules per skill.
• Sorcar Extension Agents: a Python file whose top-level getters (prompt(), model(), max_budget(), system_prompt(), tools(), use_worktree(), …) compute run parameters on the daemon, type-checked and applied atomically; llm_call_hook rewrites outgoing messages and tool_call_hook can veto tool calls. run_agent also runs any SEA file by path.
• Tools file: tools="/path/my_tools.py" whose get_tools() returns extra callables; append_basic_tools=False restricts the agent to finish plus those tools.
• Prompt customization without code: ~/.kiss/MY_TASK_TEMPLATES.md (sample-task chips), ~/.kiss/MY_INJECTION.md (tricks), ~/.kiss/MY_MODELS.json, per-repo SORCAR.md, optional ROUTING.md; 12 bundled sample tasks and 8 bundled tricks.

15. Persistence, accounting, observability

• ~/.kiss/sorcar.db (WAL SQLite): task_history (task, result, chat_id, model, work_dir, version, tokens, cost, steps, flags, start/end, favorite, parent_task_id, owner, max_budget), events (ordered JSON per task), model_usage, file_usage, frequent_tasks, replayed_journals. Journals protect against crashes; lost_and_found shows a past recovery.
• Live accounting: cost, tokens, steps and budget appear in every tool result, the status bar and the Task Info sidebar; sub-agent, classifier and TTS spend fold into the parent task.
• Cost KPIs: scripts/cost_report.py computes token-cost KPIs (peak context, hand-offs, compaction) over a database; cost_levers_experiment.py runs A/B experiments of the cost levers (read_dedupe, tool_output_compaction, tool_profiles, review_budget_fraction, chat_history_digest, dispatch_path_rewrite, context_limit_fraction in config.py).
• Trajectory viewer: kiss.viz_trajectory.server is a Flask app that renders saved trajectory YAML files under .kiss.artifacts; /api/jobs endpoints in the web server expose benchmark job trajectories.
• Shareable chats: any chat or task selection exports to a self-contained HTML page.
• Daemon health: GIL-independent stall watchdog, daemon health checks and restart verification in the extension, logs in ~/.kiss/kiss-web-*.log, active-task queries (scripts/check-kiss-web-active-tasks.py).
• Database tooling: sync_db.py (one-way merge of task and event rows), carry_over_tables.py, db_fingerprint.py, relocate_work_dir.py, running_tasks.py, scripts/sync-task-db.sh.

16. Installation, deployment, operations

• One-line install (install.sh, 63 KB): bootstraps Homebrew/Xcode CLT, git, node, uv, Python 3.13, Playwright, builds and installs the VSIX, launches VS Code; interactive or --non-interactive; immune to terminal signals; logs to ~/.kiss/install.log. Also pipx install kiss-agent-framework for the daemon and CLIs only.
• Remote deployment (rsorcar user@host): checks SSH, installs prerequisites, verifies no task is running and disk space suffices (with a bind-mount helper to move $HOME), copies SSH identity, syncs the checkout through origin, ships the task database, sets the remote password and work dir (remote_config.py), starts kiss-web and waits for the public cloudflared URL.
• Docker: sorcar-docker [PORT] [--rebuild] builds the image from Dockerfile, runs code-server with the extension in a container and opens the browser; per-task docker_image isolation for tools.
• Updates: Settings "Update" button re-runs the installer; the extension checks for new versions with a snooze shared between daemon and clients; scripts/release.sh packages releases.
• Auth helpers: install-api-keys.sh, install-github-auth.sh, collect-github-auth.sh, install-ssh-identity.sh.
• Platforms: macOS and Linux (x86_64, aarch64, arm64); Windows bash discovery exists in the tools; Muse auth is Linux-only.

17. Long-horizon research drivers and benchmarks

The system prompt contains procedures that turn one chat message into a multi-hour autonomous loop:

• AI discovery / auto research / optimization (SYSTEM.md §workflow): profile baseline, web-search state of the art, write ./tmp/ideas.md, judge ideas pairwise, implement and evaluate end to end, log to ./tmp/explored-ideas.md, compose winners, stop only when the metric goal holds on a held-out check.
• Adversarial testing: one sub-task tries to break the system with adversarial tests and workloads while another fixes it. Adversarial training: generate adversarial datasets until a model stops overfitting.
• GEPA prompt optimization and repository optimization as bundled sample prompts; recorded runs include xxHash (5,583 steps, $393), SQLite, LZ4 and the HydraKV and Bespoke OLAP case studies described in papers/kisssorcar/kiss_sorcar.tex.
• Paper writing and review: templates/write_paper_prompt.md and RECIPES.md give prompts for venue-conformant LaTeX papers with citation verification and AI-slop gates, and for deep conference reviews; the repo holds five paper directories (KISS Sorcar, SE KISS Sorcar, SorcarCCL, SweDefend, HydraKV) written this way.
• Deep work, planning, file-browsing rules: read-before-modify, concrete per-file plans for 3+ file changes, end-to-end tests with 100% branch coverage and no mocks, parallel test splitting by core count, single lint/typecheck at the end, three-item pre-finish check.
• Web research protocol: a confidence gate that mandates search whenever facts may be stale, a ten-site research procedure, and reports for answers over ~800 words.
• Benchmarks (benchmarkings/): Harbor agent for data-eng-bench (103 tasks, 309 trials, 69.58% accuracy, pass@3 0.728, $1,143 total); harnesstax runners for Terminal-Bench 2.0 (30 sampled tasks) and SWE-bench Lite with official graders; task-classifier benchmark; projects/swedefend (a prompt-injection defense pipeline with swedefend-eval).

18. Developer tooling and tests

• uv run check --full: syntax, ruff lint, pyright/mypy type check; JS side npm run check (tsc, eslint, stylelint, htmlhint, node tests).
• 1,228 Python test files with 8,669 test functions under src/kiss/tests/, mirroring every package (core, models, memoryfield, sorcar, server, third-party agents, vscode, viz, scripts, swedefend); JS tests for the extension in agents/vscode/test/.
• generate-api-docs builds API.md (82 KB) from the source by AST introspection; redundancy_analyzer.py finds redundant tests via branch coverage contexts.
• Type hints throughout (py.typed), pyproject-driven tooling, GitHub Actions workflow under .github/.

19. What the trajectories show

The task database records every task run on this machine and on machines whose databases were synced into it (71 distinct work directories; the main checkout accounts for 5,332 of the 5,648 top-level tasks). Rows before April 2026 are legacy imports; the six months from April to September 2026 hold the working history.

Models actually used

The split is the builder/reviewer pattern from the tricks: Anthropic models build, OpenAI gpt-5.6-sol reviews in read-only sub-agents. Thirteen further models appear in small numbers, including Gemini, Kimi, Sonnet, Haiku and the CLI-backed cc/* and codex/* namespaces.

Kinds of work recorded

Keyword counts over the 5,648 top-level task texts (a task can fall in several rows):

20. Caveats and gaps

• SYSTEM.md's "Desktop Apps" rule refers to screenshot, keyboard and mouse tools, but the only screenshot/click/press_key tools registered operate on the Playwright browser page, not the desktop. Desktop control is available only through channel agents such as Phone Control or through shell commands.
• Cron is not a built-in tool of a normal run: it works through run_agent("cron", …). The skill tool is registered only when a user or project skill directory exists; bundled skills alone do not add it.
• Memory, the classifier and prompt caching are unavailable for cc/* and codex/* runs, which hand the whole task to the external CLI.
• The summary-every-ten-steps rule is enforced by the prompt only; there is no mechanical check.
• Muse-auth isolation is a process boundary, not an OS boundary: an agent allowed to run arbitrary shell commands could read the vault unless tool permissions deny it (stated in muse_auth/__init__.py).
• The database contains artifacts: 64 task rows with an empty model, a minimum timestamp of 2009 (a clock artifact on an imported row), 1,524 calls to a retired code_graph tool, and a lost_and_found table from a past recovery.
• README counts (665 models, 43 agents, 24 Muse-covered connectors, 25 delivery-capable channels) were re-verified for the first two; the last two are taken from the README and third-party README.

Sources: README.md, src/kiss/SYSTEM.md, src/kiss/SYSTEM_LITE.md, src/kiss/TIPS.md, src/kiss/INJECTIONS.md, src/kiss/SAMPLE_TASKS.md, RECIPES.md, pyproject.toml, src/kiss/core/*, src/kiss/agents/sorcar/*, src/kiss/server/*, src/kiss/agents/third_party_agents/README.md, connectors/README.md, src/kiss/agents/vscode/{package.json,media/chat.html,media/main.js}, benchmarkings/, papers/kisssorcar/kiss_sorcar.tex, install.sh, rsorcar, sorcar-docker, and SQL queries against ~/.kiss/sorcar.db on 2026-09-20.