Skip to content

Commit cc03dfe

Browse files
murilxaraujoclaude
murilxaraujo
and
claude
committed
Initial KernelHarnessKit implementation
Ships the MVP surface from the HLD — engine, tools, providers, harness, coordination, workspace, streaming, permissions, MCP, persistence, planning — plus a runnable CLI demo and DocC catalog with articles and a tutorial. - 3 targets: KernelHarnessKit (core), KernelHarnessPostgres (optional), kernel-harness-demo (CLI executable) - OpenAI-compatible provider reaches every major vendor via preset base URLs - HarnessEngine actor with 5 phase types (programmatic, llmSingle, llmAgent, llmBatchAgents, llmHumanInput) and per-phase timeouts - JSON-RPC 2.0 MCP client over HTTP + SSE transports, with auto-registration into the local ToolRegistry - 78 tests on Swift Testing, all offline via MockLLMProvider - CI workflow targeting macOS + Linux on Swift 6 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
0 parents  commit cc03dfe

94 files changed

Lines changed: 9726 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
concurrency:
10+
group: ${{ github.workflow }}-${{ github.ref }}
11+
cancel-in-progress: true
12+
13+
jobs:
14+
macos:
15+
name: macOS · Swift 6
16+
runs-on: macos-14
17+
steps:
18+
- uses: actions/checkout@v4
19+
- name: Select Xcode
20+
run: sudo xcode-select -s /Applications/Xcode_16.0.app
21+
- name: Show Swift version
22+
run: swift --version
23+
- name: Build
24+
run: swift build -c release
25+
- name: Test
26+
run: swift test --parallel
27+
28+
linux:
29+
name: Linux · Swift 6
30+
runs-on: ubuntu-latest
31+
container:
32+
image: swift:6.0-jammy
33+
steps:
34+
- uses: actions/checkout@v4
35+
- name: Show Swift version
36+
run: swift --version
37+
- name: Build
38+
run: swift build -c release
39+
- name: Test
40+
run: swift test --parallel
41+
42+
docs:
43+
name: DocC build
44+
runs-on: macos-14
45+
steps:
46+
- uses: actions/checkout@v4
47+
- name: Select Xcode
48+
run: sudo xcode-select -s /Applications/Xcode_16.0.app
49+
- name: Generate documentation
50+
run: swift package generate-documentation --target KernelHarnessKit

‎.gitignore‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
.DS_Store
2+
.build/
3+
.swiftpm/
4+
Package.resolved
5+
*.xcodeproj/
6+
xcuserdata/
7+
.netrc
8+
.env
9+
.env.*
10+
!.env.example
11+
12+
# DocC build artefacts
13+
*.doccarchive
14+
docs/
15+
16+
# macOS
17+
.Spotlight-V100
18+
.Trashes
19+
20+
# VS Code
21+
.vscode/
22+
23+
# JetBrains
24+
.idea/

‎Kernel Harness/KernelHarnessKit-HLD.md‎

Lines changed: 1343 additions & 0 deletions
Large diffs are not rendered by default.

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Murilo Araujo
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎Package.swift‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
// swift-tools-version: 6.0
2+
import PackageDescription
3+
4+
let package = Package(
5+
name: "KernelHarnessKit",
6+
platforms: [
7+
.macOS(.v14),
8+
.iOS(.v17),
9+
.tvOS(.v17),
10+
.watchOS(.v10),
11+
],
12+
products: [
13+
.library(name: "KernelHarnessKit", targets: ["KernelHarnessKit"]),
14+
.library(name: "KernelHarnessPostgres", targets: ["KernelHarnessPostgres"]),
15+
.executable(name: "kernel-harness-demo", targets: ["KernelHarnessDemo"]),
16+
],
17+
dependencies: [
18+
.package(url: "https://github.com/MacPaw/OpenAI.git", from: "0.4.0"),
19+
.package(url: "https://github.com/swift-server/async-http-client.git", from: "1.21.0"),
20+
.package(url: "https://github.com/apple/swift-nio.git", from: "2.65.0"),
21+
.package(url: "https://github.com/vapor/postgres-nio.git", from: "1.21.0"),
22+
.package(url: "https://github.com/apple/swift-log.git", from: "1.5.0"),
23+
.package(url: "https://github.com/apple/swift-docc-plugin.git", from: "1.3.0"),
24+
],
25+
targets: [
26+
.target(
27+
name: "KernelHarnessKit",
28+
dependencies: [
29+
.product(name: "OpenAI", package: "OpenAI"),
30+
.product(name: "AsyncHTTPClient", package: "async-http-client"),
31+
.product(name: "NIOCore", package: "swift-nio"),
32+
.product(name: "NIOHTTP1", package: "swift-nio"),
33+
.product(name: "NIOFoundationCompat", package: "swift-nio"),
34+
.product(name: "Logging", package: "swift-log"),
35+
],
36+
swiftSettings: [
37+
.enableExperimentalFeature("StrictConcurrency"),
38+
]
39+
),
40+
.target(
41+
name: "KernelHarnessPostgres",
42+
dependencies: [
43+
"KernelHarnessKit",
44+
.product(name: "PostgresNIO", package: "postgres-nio"),
45+
],
46+
swiftSettings: [
47+
.enableExperimentalFeature("StrictConcurrency"),
48+
]
49+
),
50+
.executableTarget(
51+
name: "KernelHarnessDemo",
52+
dependencies: [
53+
"KernelHarnessKit",
54+
],
55+
swiftSettings: [
56+
.enableExperimentalFeature("StrictConcurrency"),
57+
]
58+
),
59+
.testTarget(
60+
name: "KernelHarnessKitTests",
61+
dependencies: ["KernelHarnessKit"]
62+
),
63+
.testTarget(
64+
name: "KernelHarnessPostgresTests",
65+
dependencies: ["KernelHarnessPostgres"]
66+
),
67+
]
68+
)

‎README.md‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
# KernelHarnessKit
2+
3+
**Swift infrastructure for custom AI agent harnesses.**
4+
5+
Agent loop · Tool system · Multi-agent coordination · Deterministic workflow engine ·
6+
LLM provider abstraction · Workspace · Streaming — everything you need to ship a
7+
custom agent service, minus the domain details *you* supply.
8+
9+
[![Swift 6.0+](https://img.shields.io/badge/swift-6.0+-orange.svg)](https://swift.org)
10+
[![Platforms](https://img.shields.io/badge/platforms-macOS%2014%20%7C%20iOS%2017%20%7C%20Linux-blue)](#platforms)
11+
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
12+
13+
---
14+
15+
## Why this exists
16+
17+
> *"The model is commoditized. Structured enforcement of process is the moat."*
18+
19+
KernelHarnessKit gives you two complementary execution strategies, so you can pick
20+
per-task:
21+
22+
1. **Autonomous agents** (soft harness) — the model drives, you curate the tools.
23+
`runAgent(context:initialMessages:)` returns a streaming event source.
24+
2. **Deterministic phase machines** (hard harness) — the system drives, the model
25+
executes within each constrained phase. Five phase types cover the common
26+
shapes of domain work (programmatic, single LLM call, agent loop, batch
27+
sub-agents, human input).
28+
29+
The framework ports the subsystem decomposition of [OpenHarness](https://github.com/HKUDS/OpenHarness)
30+
(Python) to Swift 6, leveraging structured concurrency (`TaskGroup`,
31+
`AsyncThrowingStream`) for in-process sub-agents and batch phases. It adds an
32+
original contribution — the deterministic phase state machine — because domain
33+
workflows deserve predictable, auditable progression that the LLM cannot
34+
reorder or skip.
35+
36+
## Quick start
37+
38+
```swift
39+
import KernelHarnessKit
40+
41+
let registry = ToolRegistry()
42+
registry.registerBuiltIns()
43+
44+
let provider = OpenAICompatibleProvider.openai(apiKey: apiKey)
45+
46+
let context = QueryContext(
47+
provider: provider,
48+
toolRegistry: registry,
49+
permissionChecker: DefaultPermissionChecker(mode: .auto),
50+
workspace: InMemoryWorkspace(),
51+
model: "openai/gpt-4o-mini",
52+
systemPrompt: "You are a helpful assistant."
53+
)
54+
55+
let result = runAgent(
56+
context: context,
57+
initialMessages: [ConversationMessage(role: .user, text: "list workspace files")]
58+
)
59+
for try await event in result.events {
60+
if case .textChunk(let text) = event { print(text, terminator: "") }
61+
}
62+
```
63+
64+
See the [DocC catalog](Sources/KernelHarnessKit/Documentation.docc/) — generate it with
65+
`swift package generate-documentation --target KernelHarnessKit` — for articles,
66+
tutorials, and full API reference.
67+
68+
## Run the demo
69+
70+
The package ships with a small CLI you can run against any OpenAI-compatible
71+
endpoint:
72+
73+
```bash
74+
export OPENAI_API_KEY=sk-…
75+
swift run kernel-harness-demo chat "write a haiku about deterministic agents"
76+
swift run kernel-harness-demo harness
77+
```
78+
79+
`harness` mode walks through a three-phase workflow: programmatic topic
80+
collection → parallel per-topic analysis via sub-agents → single-call
81+
summarization. Great for seeing every subsystem exercise at once.
82+
83+
## One provider, many vendors
84+
85+
KernelHarnessKit speaks one wire protocol: OpenAI's. Vendor-specific endpoints
86+
(Anthropic, Google Gemini, DeepSeek, Groq, xAI, OpenRouter, Ollama, vLLM,
87+
LM Studio) are reached via their OpenAI-compatible mode. This means a **single
88+
provider implementation** covers the vast majority of production use cases:
89+
90+
```swift
91+
let registry = ProviderRegistry(providers: [
92+
"openai": .openai(apiKey: env("OPENAI_API_KEY")),
93+
"anthropic": .anthropic(apiKey: env("ANTHROPIC_API_KEY")),
94+
"google": .google(apiKey: env("GOOGLE_AI_API_KEY")),
95+
"groq": .groq(apiKey: env("GROQ_API_KEY")),
96+
])
97+
98+
let provider = registry.provider(for: "anthropic/claude-sonnet-4-5")!
99+
```
100+
101+
A swap-in custom `LLMProvider` conformance is the escape hatch when a vendor's
102+
OpenAI-compat surface is too limited.
103+
104+
## Feature matrix
105+
106+
| Subsystem | What it gives you |
107+
|---|---|
108+
| **Engine** | `AsyncThrowingStream` agent loop with parallel tool dispatch and turn budget. |
109+
| **Tools** | `Tool` protocol, type-erased `AnyTool`, lock-protected `ToolRegistry`, 8 built-in tools. |
110+
| **Providers** | One `OpenAICompatibleProvider` implementation + prefix-routed `ProviderRegistry`. |
111+
| **Coordination** | `SubAgentExecutor`, `BatchExecutor` with concurrency control, `AskUserHandler`. |
112+
| **Harness** | `HarnessEngine` actor running 5 phase types with per-phase timeouts. |
113+
| **Workspace** | `WorkspaceProvider` protocol + `InMemoryWorkspace` (Postgres impl in companion target). |
114+
| **Streaming** | `AgentEvent` enum covering 17 event types, `SSEEncoder` for HTTP transports. |
115+
| **Permissions** | `default` / `auto` / `readOnly` / custom policy with glob-based path rules. |
116+
| **MCP** | JSON-RPC 2.0 over HTTP + SSE, `MCPToolBridge` to register server tools into a local `ToolRegistry`. |
117+
| **Persistence** | Protocol-based repositories with `PostgresNIO` implementations in `KernelHarnessPostgres`. |
118+
119+
## Platforms
120+
121+
- macOS 14+
122+
- iOS 17+, tvOS 17+, watchOS 10+
123+
- Linux (tested via Swift 6.0 Docker images)
124+
125+
Tests run offline against a `MockLLMProvider`; no API keys required.
126+
127+
## Installation
128+
129+
Add to your `Package.swift`:
130+
131+
```swift
132+
dependencies: [
133+
.package(url: "https://github.com/murilxaraujo/KernelHarnessKit.git", from: "0.1.0"),
134+
],
135+
targets: [
136+
.target(
137+
name: "YourApp",
138+
dependencies: [
139+
.product(name: "KernelHarnessKit", package: "KernelHarnessKit"),
140+
// Optional: Postgres-backed repositories for server deployments
141+
.product(name: "KernelHarnessPostgres", package: "KernelHarnessKit"),
142+
]
143+
)
144+
]
145+
```
146+
147+
## Design
148+
149+
See [the high-level design document](Kernel%20Harness/KernelHarnessKit-HLD.md) for
150+
the subsystem-by-subsystem rationale, the comparison to OpenHarness, and
151+
the delivery plan.
152+
153+
## License
154+
155+
MIT. See [LICENSE](LICENSE).

0 commit comments

Comments
 (0)