agentleFS
Omni-CraftOmni-Craft/OmniCraft/.claude/skills/harness-integration-guide/SKILL.md

harness-integration-guide

Skill1 starsChanged 4 months agoApache-2.0View on GitHub

Reference guide for building new OmniCraft harness integrations — covers SDK/subprocess harnesses and native harnesses as separate tracks, each with their own feature matrix, implementation patterns, and prioritized checklist.

1 other project uses a version of this, 1 of them edited.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    When a policy verdict is ASK, the harness must surface the pending tool call or tool result in the OmniCraft web UI as an approval card, …

    line 72
  2. Distinctive:

    All capabilities are required for a complete harness integration:

    line 99

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Harness integration guide

This skill describes the feature matrix every OmniCraft harness must consider. Use it when planning, reviewing, or implementing a new harness.

OmniCraft has two distinct harness tracks with different architectures and feature sets:

  • SDK/subprocess harnesses — run the vendor model directly (in-process SDK, CLI subprocess, or ACP subprocess). They own the model lifecycle.
  • Native harnesses — wrap a vendor's own TUI or server and mirror its output into OmniCraft. They observe and relay, rather than drive.

Part 1 — SDK / subprocess harnesses

These harnesses run the vendor model directly and bridge OmniCraft tools into the vendor's tool-calling interface.

Capability matrix

CapabilityWhat it means
Connects to OmniCraft MCPHarness exposes/consumes tools via the MCP protocol (in-proc SDK MCP server)
Model overrideUser can select a model via --model / config; some harnesses are vendor-locked (e.g. Claude-only, GPT-only, Gemini-only)
AuthHow credentials are obtained — API key, gateway token, vendor CLI login, OAuth, etc.
StreamingHarness forwards token-level or delta-level streaming to the OmniCraft forwarder
OmniCraft policiesHarness enforces OmniCraft-side tool policies — must support ALLOW, ASK, and DENY verdicts for both tool calls and tool results
Native elicitationWhen a policy verdict is ASK, the harness surfaces the approval request in the OmniCraft web UI so the user can approve or deny
InterruptUser can cancel a running turn mid-stream
Live queue (concurrent)Multiple turns can be queued and processed concurrently
Tool-boundary steerOmniCraft can inject steering text at tool-call boundaries
Resume/fork from OmniCraft transcriptRebuild a conversation from a stored OmniCraft transcript (replay history, seed prompt, or vendor session ID)
CompactionLong conversations are compacted; harness surfaces CompactionComplete events
ReasoningModel reasoning/thinking tokens are forwarded
ImagesImage content (screenshots, diagrams) is forwarded — full binary, path reference, or text-flattened
Cost trackingHarness reports token usage and cost data back to OmniCraft for each turn

MCP connectivity

The harness must bridge OmniCraft's builtin MCP tools so the model can call them. These tools provide session management, agent orchestration, policy control, and web access:

  • sys_session_get_info, sys_session_list, sys_session_get_history
  • sys_agent_get, sys_agent_list, sys_agent_download
  • sys_call_async, sys_cancel_async, sys_cancel_task
  • sys_read_inbox
  • sys_add_policy, sys_policy_registry
  • load_skill
  • list_comments, update_comment
  • web_fetch, web_search

OmniCraft policies

The harness must support the OmniCraft policy engine's three verdicts at two checkpoints:

CheckpointALLOWASKDENY
Tool call (before execution)Proceed silentlySurface approval request to user (via elicitation)Block the call and return a policy-denied error to the model
Tool result (after execution)Return result to modelSurface result for user review before returningSuppress the result and return a policy-denied error to the model

Native elicitation

When a policy verdict is ASK, the harness must surface the pending tool call or tool result in the OmniCraft web UI as an approval card, then relay the user's approve/deny decision back to the harness to continue or block execution.

Resume / fork strategies

StrategyHow it works
Full history replayReplays the entire message history into a fresh thread/session
History prefix replayReplays a prefix of the history into a fresh session
Text-prefix replayInjects a text summary/prefix of prior history
Prompt seedingSeeds prior history into the system prompt on rebuild
Vendor session IDRelies on the vendor's own session persistence (no OmniCraft-side rebuild)

Auth patterns

PatternDescription
API key / Databricks gatewayDirect API key or routed through a Databricks gateway
Vendor API key (direct)Vendor-specific API key (e.g. Cursor, Gemini)
Vendor CLI login / config fileCredentials stored in a vendor config file or managed via vendor CLI login
OAuth / GitHub tokenOAuth flow or platform token (e.g. GitHub PAT)
Gateway + fallbackPrimary gateway with fallback to vendor-native auth

Checklist for a new SDK/subprocess harness

All capabilities are required for a complete harness integration:

  • Connects to OmniCraft MCP (in-proc SDK MCP server or vendor-specific bridge)
  • Model override works (or document vendor lock-in)
  • Auth is configured and documented (setup flow in omni setup)
  • Streaming forwards to the OmniCraft forwarder
  • OmniCraft policies enforce tool-use rules
  • Native elicitation surfaces tool-approval requests to web UI
  • Interrupt cancels the running turn
  • Live queue supports concurrent turns
  • Tool-boundary steering injects correctly
  • Resume/fork rebuilds conversation from OmniCraft transcript
  • Compaction is surfaced (CompactionComplete events)
  • Reasoning tokens are forwarded
  • Images are forwarded (full binary preferred; path or text-flattened acceptable)
  • Cost tracking reports token usage and cost per turn
  • Unit tests cover tool bridging, auth, model routing
  • Mock LLM tests cover the happy path without real API calls

Part 2 — Native harnesses

Native harnesses wrap a vendor's own TUI or server and mirror output into OmniCraft. They relay the vendor's conversation into the OmniCraft session.

Capability matrix

CapabilityWhat it means
TransportHow the native harness communicates — tmux TUI, app server, HTTP/SSE, file-inject TUI
Connects to OmniCraft MCPWhether the native harness connects to the OmniCraft MCP server
Model overrideUser can select a model at launch or per-prompt
AuthVendor login / config / token
Streaming (forwarder)deltas (token-level) vs complete-only (full response after completion)
OmniCraft policiesWhether the native harness enforces OmniCraft-side tool policies — must support ALLOW, ASK, and DENY verdicts for both tool calls and tool results
Native elicitationWhen a policy verdict is ASK, the native harness surfaces the approval request in the OmniCraft web UI so the user can approve or deny
InterruptUser can abort a running turn
Bidirectional sync (TUI->Omni)TUI output mirrors into the OmniCraft conversation
In-harness session-cmd syncSupports clear, fork, resume, switch commands from OmniCraft
Resume/fork from OmniCraft transcriptCan rebuild conversation from OmniCraft transcript (native rebuild, or fresh launch)
CompactionVendor-internal compaction status
ReasoningModel reasoning/thinking tokens are forwarded
ImagesImage content is forwarded — path reference, full binary, or text-flattened
Cost trackingNative harness reports token usage and cost data back to OmniCraft for each turn
Tool-output streamingLive incremental command/tool output (outputDelta) vs final aggregated output only
Working-tree diffThe vendor's aggregated per-turn diff is surfaced (vs reconstructed from per-file edits)
Generated/viewed mediaModel-produced or model-viewed images are mirrored (distinct from user-supplied image input)
Vendor modesVendor-specific modes (review mode, plan mode, etc.) are mirrored as status

Checklist for a new native harness

Capabilities are tiered by how essential they are. P0 must work or the harness is non-functional. P1 is required for a complete, parity-level integration — the web surface should match what the vendor TUI shows. Stretch items depend on vendor-specific signals and improve fidelity; they are optional and may legitimately be closed as wontfix when the vendor provides no signal or the data is redundant.

P0 — core (non-functional without these)

  • Transport chosen and implemented (tmux TUI, app server, HTTP/SSE)
  • Connects to OmniCraft MCP
  • Auth configured (vendor login / config)
  • Streaming forwarder works (deltas preferred; complete-only acceptable)
  • OmniCraft policies enforce tool-use rules (ALLOW / ASK / DENY at both tool call and tool result)
  • Native elicitation surfaces tool-approval requests to web UI
  • Interrupt aborts the running turn
  • Bidirectional sync mirrors TUI output into OmniCraft conversation
  • Cost tracking reports token usage and cost per turn
  • Unit tests cover forwarder, auth, transport
  • Mock LLM tests cover the happy path without real API calls

P1 — parity (required for a complete integration)

  • Model override works at launch and per-prompt (or document vendor lock-in)
  • Session commands (clear, fork, resume) work from OmniCraft
  • Resume/fork rebuilds from OmniCraft transcript
  • Reasoning tokens are forwarded
  • Compaction status is surfaced
  • User-supplied images are forwarded (path preferred; binary or text-flattened acceptable)

Stretch — vendor-dependent fidelity

  • Live tool/command output is streamed (outputDelta), not just final aggregated output
  • The vendor's aggregated working-tree diff is surfaced (if provided)
  • Generated/viewed media (model-produced or model-viewed images) is mirrored
  • Vendor-specific modes (review mode, plan mode, etc.) are mirrored as status

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.