How kiss/agents/vscode talks to kiss/server, kiss/agents/sorcar, and kiss/core

1. The four layers in one sentence each

2. The one rule everything obeys: strict downward layering

The dependency direction is enforced by real tests (src/kiss/tests/test_layering_invariants.py walks the full AST of every file, and test_core_sorcar_layer_separation.py re-imports core in a fresh interpreter with kiss.agents deleted):

• core may import nothing outside kiss/core/ — it is a standalone foundation.
• sorcar may import only itself and core. It never imports kiss/server.
• server imports both sorcar and core freely.
• vscode is TypeScript — it imports no Python at all. Its only link to the rest of the system is a socket.

3. vscode ↔ server: a socket and a shared command catalog

3.1 The transport

src/AgentClient.ts opens a Unix-domain socket to ~/.kiss/sorcar.sock (overridable via $KISS_SORCAR_SOCK) and speaks newline-delimited JSON: one command object per line down, one event object per line up. It is deliberately defensive:

• Exponential reconnect backoff with jitter (500 ms → 15 s), so N open VS Code windows do not stampede a restarting daemon.
• A pending-command queue with a 10-second TTL and a 256-entry cap: a run queued during an outage must not be replayed into a different daemon that answers later — that would start an agent nobody asked for. Dropped commands are announced (commandDropped) so the UI can undo its optimistic “running” state.
• A per-connection StringDecoder and a 32 MB line buffer keep multi-byte UTF-8 and huge events intact.

3.2 The protocol

Both ends agree on a single catalog. On the Python side, kiss/server/sorcar.py is “the single source of truth for the wire API”: it defines the API catalog, validate_command(), and ServerApi.dispatch(), which routes each JSON object on its "type" field to a _cmd_* handler. On the TypeScript side, src/types.ts mirrors it as two discriminated unions, and src/SorcarApi.ts is a thin facade whose methods map 1:1 onto catalog names.

Every event carries an optional tabId. The daemon’s JsonPrinter is task-centric: events are recorded and persisted under the task’s database id, then fanned out to every subscribed tab (each copy stamped with that tab’s id) — which is how several VS Code windows, the sidebar, and a phone browser can all watch the same task live.

3.3 Who dials whom inside the extension

• extension.ts activates SorcarSidebarView (the webview provider), registers palette commands (runSelection, stopTask, focus toggles), and hijacks git.generateCommitMessage so the SCM sparkle button asks the daemon for a commit message (answered as a commitMessage event and written into the SCM input box).
• SorcarSidebarView.ts owns exactly one AgentClient + SorcarApi pair. Webview postMessage traffic (FromWebviewMessage) is validated and forwarded as AgentCommands; daemon events flow back with webview.postMessage().
• The same webview assets (media/main.js, media/api.js…) are served by the daemon to remote browsers over HTTPS/WSS, so the wire protocol is identical for both front ends — remote clients just add an auth handshake (password from ~/.kiss/config.json, optional Cloudflare tunnel).

3.4 The extension is also the daemon’s babysitter

The Python backend ships inside the extension: copy-kiss.sh snapshots the whole repository into vscode/kiss_project/ before packaging the .vsix (and syncs the extension version from kiss/core/_version.py). On activation, DependencyInstaller.ts:

1. Installs uv if missing and builds the venv inside the bundled kiss_project/.
2. Fingerprints the installed code; when the fingerprint changes (extension update), it restarts the daemon — but only after probing sorcar.sock for active tasks so an update never kills a running agent.
3. Launches .venv/bin/kiss-web (the pyproject.toml entry point kiss.server.web_server:main) as a macOS LaunchAgent, a systemd user service, or a detached direct spawn — guarded by a cross-process restart lock so multiple VS Code windows do not race.
4. daemonHealth.js probes the socket; extension.ts watches ~/.kiss/.extension-updated plus the socket, and reloads the window only when the new bundle is stable and the daemon is back up.

4. server ↔ sorcar: the daemon hires the agent

The extension never touches an agent directly — the server does it on its behalf. When a run command arrives, commands.py:_cmd_run hands it to the task-runner mixin, which starts a background thread. The heart of the interaction is one call in kiss/server/task_runner.py:

state.agent = WorktreeSorcarAgent("Sorcar VS Code")   # one agent per tab, reused across runs
...
agent_returned = agent.run(
    prompt_template=task_prompt,          # one <task> segment of the submitted prompt
    model_name=model,                     # from the tab's model picker
    work_dir=work_dir,
    printer=self.printer,                 # the JsonPrinter — the agent's only voice
    ask_user_question_callback=self._ask_user_question,   # becomes the askUser round-trip
    is_parallel=state.use_parallel,
    use_worktree=use_worktree,
    auto_commit=state.auto_commit_mode,
    max_budget=..., web_tools=..., model_config=...,      # from ~/.kiss/config.json
    tools=client_tools,                   # optional user tools file, imported by the daemon
)

The agent the server instantiates sits atop a four-deep inheritance chain that crosses into core:

kiss.core.base.Base
  └─ kiss.agents.sorcar.relentless_agent.RelentlessAgent   (drives kiss.core.kiss_agent.KISSAgent in rounds)
       └─ kiss.agents.sorcar.sorcar_agent.SorcarAgent      (tools, skills, web browsing, sub-agents, MCP)
            └─ chat_sorcar_agent.ChatSorcarAgent           (chat sessions, persistence, resume)
                 └─ worktree_sorcar_agent.WorktreeSorcarAgent   (git-worktree isolation)  ← the server uses this one

Beyond launching agents, the server leans on the sorcar package for four more services:

Live run bookkeeping lives in agent_state.py: a registry agent_states: dict[task_id → AgentState] guarded by one STATE_LOCK. Each AgentState holds the agent instance, its thread, a cooperative stop_event, and worktree/merge flags. A stop command sets the event; if the agent does not yield, the runner force-stops the thread by injecting KeyboardInterrupt with PyThreadState_SetAsyncExc — but only while an ownership guard proves the thread still belongs to that task.

5. Everyone ↔ core: the shared foundation

6. Life of a task, end to end

1. You type a prompt in the sidebar. media/main.js posts {type:'submit', prompt, model, tabId, useWorktree, …} to the extension host.
2. SorcarSidebarView.ts forwards it through SorcarApi.run(); AgentClient.ts writes one JSON line to ~/.kiss/sorcar.sock.
3. The kiss-web daemon (web_server.py) reads the line; ServerApi.dispatch() in sorcar.py validates it against the API catalog and calls VSCodeServer._cmd_run.
4. task_runner.py spins up a background thread, registers an AgentState, splits the prompt on <task> tags, loads budget/model settings from core.vscode_config, and calls WorktreeSorcarAgent.run(…, printer=JsonPrinter).
5. The agent (sorcar layer) creates a git worktree, assembles its tools, and drives the KISSAgent loop in kiss/core, which streams model output.
6. Every token and tool call flows into JsonPrinter, which stamps a timestamp, persists the event to sorcar.db (via persistence._queue_chat_event), and fans it out — down the Unix socket to every VS Code window and over WSS to any remote browser — each copy tagged with the receiving tab’s tabId.
7. If the agent calls its ask-user tool, the callback wired by the server emits an askUser event; your typed reply comes back as a userAnswer command and is handed to the waiting agent thread.
8. On completion the runner parses the result YAML (core.printer.parse_result_yaml), emits result + task_done, runs auto-commit / offers Merge / Discard (emitting worktree_done), and persists the task row with tokens, cost, and steps.
9. Clicking Merge sends worktreeAction; merge_flow.py drives GitWorktreeOps from the sorcar layer and streams progress events until your branch has the changes.

7. Takeaways

• One socket, one protocol. The entire vscode ↔ Python relationship is a newline-delimited JSON conversation on ~/.kiss/sorcar.sock, with kiss/server/sorcar.py as the authoritative command catalog and types.ts as its TypeScript mirror.
• The extension is a client and a supervisor, not a brain. All agent logic lives behind the daemon; the extension renders events, forwards clicks, and keeps kiss-web installed, healthy, and up to date.
• The daemon is shared state. Because tasks run in one long-lived process keyed by task id — not per window — every VS Code window, tab, and remote browser sees the same live streams, and closing a window never kills a run.
• The Printer abstraction is the hinge. Agents depend only on core; the server injects a core-typed JsonPrinter to pull agent output up into the UI world — a dependency inversion enforced by AST-walking layering tests.