Chapter 33: Building on the Harness — Kocoro

A model loop becomes a product only when identity, state, permissions, integrations, automation, and verification have explicit contracts.

Public-source boundary: This chapter uses only concepts and commands documented in the public Kocoro repository. That repository contains the open-source engine, CLI, and daemon. Kocoro Desktop, the native GUI product, is separate and closed-source. No private repository code, production configuration, incidents, customer data, or proprietary assets are used here.

33.1 From Loop to Runtime

A durable runtime adds independent contracts around the execution loop:

Layer	Contract
Identity	Which named Agent, instructions, model policy, and tools are active?
Session state	Which messages, events, and remote tasks belong together?
Memory	Which facts may cross sessions, with what source and scope?
Permissions	What is blocked, allowed, or requires a human decision?
Integration	How do local tools, MCP servers, and channels connect?
Automation	What starts work when no user is at the terminal?
Verification	What evidence proves success, safe failure, or cancellation?

These layers must be additive. Switching Agents or trigger sources must not bypass the shared permission and execution core.

33.2 Current Public Entry Points

shan                              # interactive TUI
shan "review this directory"      # one-shot task
shan --agent ops-bot "check it"   # named Agent
shan daemon start                 # local daemon
shan mcp serve                    # MCP server over stdio
shan schedule list                # inspect schedules

Commands evolve, so the public README and CLI help are the operational source of truth. The stable lesson is that TUI, daemon, schedule, and MCP work should converge on the same harness.

33.3 Named Agents and State Boundaries

A Named Agent combines instructions, model policy, tool scope, MCP scope, sessions, memory, and optional commands or Skills. Safe configuration follows three rules:

Least privilege: only the tools and network destinations required for the task.
Visible provenance: the runtime can explain where every effective value came from.
No accidental inheritance: switching Agents rebuilds tool and integration scope.

Keep working context, resumable session records, and durable memory separate. Compaction is lossy; preserve only durable facts with evidence, time, and scope. A small-model extractor is a cost choice, not a correctness guarantee. Its output still needs deduplication, contradiction handling, privacy filtering, and evaluation.

33.4 Permissions and Untrusted Results

Authorization belongs to the runtime, not the model. A robust path has non-overridable destructive-operation blocks, operator deny rules, compound-command analysis, special handling for high-risk arguments, scoped allows, and explicit approval for everything else.

Auto-approval is not a global trust switch. It must be bounded by tool, arguments, path, destination, and invocation source.

Tool output is untrusted data. Bound its size, preserve full results outside the prompt when needed, mark truncation, and never reinterpret text from a web page or MCP result as system instructions.

33.5 Daemon, Channels, and Human Intervention

message arrives
  → authenticate and identify source
  → select Agent and session
  → execute through the shared harness
  → pause for approval or injected user input
  → stream events
  → persist an explicit terminal state

Channel metadata is data, not authority. A Slack message, webhook, browser page, or Desktop event cannot grant broader permissions. When human input is needed, persist a resumable pending state. Cancellation, timeout, restart, and duplicate delivery all need defined behavior.

33.6 MCP in Both Directions

Kocoro's public runtime documents two roles:

MCP server: expose approved local tools through the current shan mcp serve command.
MCP client: connect an Agent to configured external MCP servers.

Both roles preserve the same permission, audit, and untrusted-output boundaries as interactive use. Follow Chapter 4's current 2026-07-28 model: the protocol core is stateless and each request is self-describing; stdio remains appropriate for local subprocesses, while remote integrations use independent HTTP requests. Tasks are an opt-in extension after support is verified, not a global task system in the protocol core. That verification is implementation-specific: the stable Python SDK v2.0.0 release implemented the new core but explicitly did not yet implement Tasks.

33.7 Schedules, Watchers, and Heartbeats

Trigger	Best for	Main risk
Schedule	work at a known time	duplicate or missed execution
File watcher	react to state changes	event storms and partial writes
Heartbeat	periodic attention checks	noisy alerts and wasted tokens

All need overlap prevention, bounded retries, idempotency keys, quiet success, visible failure, and a disable path. Automated triggers should normally have less authority than an interactive user.

33.8 Agent Evaluation and Release Engineering

A demo asks “can it work once?” A release gate asks “does it keep working safely after change?”

Contract tests

validate every tool schema and representative error;
test allow, deny, and approval at exact argument boundaries;
verify session, Agent, and working-directory isolation;
assert cancellation and timeout terminal states;
verify retries do not duplicate side effects.

Golden traces and replay

Store synthetic, non-sensitive traces containing intent, selected tools, normalized results, approvals, and final postconditions. Replay after prompt, model, tool, or policy changes. Compare semantics and safety decisions, not exact prose.

Failure injection

Test unavailable models, malformed MCP responses, oversized results, dropped daemon connections, duplicate messages, partial writes, stale sessions, and restart during approval. Safe failure may be correct; hanging or fabricating success is not.

Quality and release gates

Measure task acceptance, unsupported claims, citation quality, permission violations, prompt-injection resistance, recovery, latency, and total cost. Separate deterministic postconditions, calibrated model grading, and human review.

unit and contract tests
  → golden-trace replay
  → adversarial and failure-injection suite
  → isolated canary or shadow run
  → monitored rollout
  → rollback evidence

A release is complete only after rollback, cancellation, and audit retrieval have also been exercised.

33.9 Safe Publication Boundary

Safe for this book	Keep private
Public README commands and architecture concepts	Private source or unreleased APIs
Generic state-machine and permission patterns	Production topology and credentials
Synthetic traces and illustrative values	Customer prompts, files, and messages
Public OSS links	Internal incidents and identifying fingerprints
General evaluation methodology	Proprietary prompts, thresholds, datasets, and results

Convert private lessons into vendor-neutral invariants and synthetic examples. Never retain identifiers, exact values, chronology, or topology that could reconstruct the original system.

Key Takeaways

A platform adds explicit identity, state, permission, integration, automation, and verification contracts.
Kocoro's engine, CLI, and daemon are public OSS; Kocoro Desktop is separate and closed-source.
Named Agents narrow scope rather than inherit authority accidentally.
Interactive, daemon, scheduled, and MCP work share one policy and execution core.
Evaluation needs contracts, replay, failure injection, canaries, and rollback.
Publish conceptual lessons and synthetic examples—never private implementation assets.

This chapter established why the Agent needs a harness around the loop. Part 10 now moves inside that boundary and examines the runtime mechanics that keep the loop coherent under long contexts, restarts, mid-run input, timeouts, and parallel tools.