docs: migrate examples to typed Tool<*, *> refs (#1015-#1017)
Lead all skill-allowlist examples with the typed `tools(handle)` form.
String-name `tools("...")` remains documented for built-in tools and
runtime-discovered MCP tools, with inline comments calling out why.
New "Typed tool refs" section in Skills-and-Knowledge.md (or new page,
your call) cross-linked from Best-Practices.md and Cookbook.md.
Tracks: agents-kt-11 #1017
b4b4832
docs: Swarm — new wiki page covering multi-agent JAR composition
- New Swarm.md with the mechanism explained end-to-end:
ServiceLoader discovery, AgentProvider SPI, the three-step absorb
implementation (validation → wrap-as-tool → register + auto-enable),
runtime delegation diagram showing two-layer LLM dispatch, properties
preserved (personality, independence, two-layer observability,
no-type-erasure-trickery, single-JVM), multi-captain setups, and
documented constraints (String input only, single tool per sibling,
no cross-JAR static typing, no process isolation).
- _Sidebar.md adds the Swarm link under "LLM Integration".
- Agent-Deployment-Modes.md cross-references Swarm at the end of its
tradeoffs section as the natural multi-agent extension.
- API-Quick-Reference.md adds a Swarm section with the four
symbols (AgentProvider, Swarm.discover, Swarm.discover(loader),
Agent.absorb) in the same table format used elsewhere.
Refs: #984.
9be27f0
docs: loadResource(path) — canonical pattern for prompts from classpath
- Best-Practices.md: new "DO: Load Long Prompts from Resources" section
with the agent { prompt(loadResource("prompts/coder.md")) } pattern,
rationale (editor support, no string-escape gymnastics, fail-fast),
loadResourceOrNull for the optional case, leading-slash normalization,
cross-link to Skills-and-Knowledge.
- Skills-and-Knowledge.md: new "Loading prompts and knowledge from
classpath resources" subsection inside Knowledge Entries showing
the same pattern applied to knowledge() lambdas + the optional case.
- API-Quick-Reference.md: new "Resource Loading" entry between
MemoryBank and Error Recovery DSL — table of the two functions
with their fail-fast / null-return contracts.
Refs: #980 (PR #29 in repo).
7177959
Add Building From Source page; link from sidebar
Practical contributor guide covering prerequisites, common Gradle
tasks, mutation testing, dependency-verification workflow, IDE setup,
and troubleshooting. Cross-platform invocation (./gradlew vs
gradlew.bat) called out explicitly.
Sidebar gets a new 'Contributing' section.
6105b91
Document typed tool DSL, provider schemas, validation routing (PR 2)
Adds a "Typed Tools" section to Model-and-Tool-Calling that explains the
tool<Args, Result>(...) builder shipped in #634, the real JSON-Schema
provider envelopes from #635 (proper properties / required / @Guide
descriptions, replacing the empty-properties fallback), and the
invalidArgs routing from #636 (deserialization failures go through the
same handler as JSON-parse failures, not through executionError).
Includes a complete WriteFileArgs / WriteFileResult example.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
b51693f
Document tool authorization model (PR 1 security release)
Model-and-Tool-Calling: new "Tool Authorization Model" section
explaining the per-skill allowlist enforced at execution
(skill.toolNames ∪ autoToolNames ∪ memory tools ∪ knowledge),
the rejection error format, what's protected against (hallucination,
cross-skill access, prompt injection), and practical guidance on
declaring dangerous tools per-skill.
MCP-Integration: cross-link from the Scope section so MCP-only
readers see that MCP-discovered tools go through the same
authorization boundary as local tools.
References #630 (allowlist enforcement at execution), #631
(fail-fast on typos at agent construction), #632 (safer
maxTurns default).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
5fff24f
Add Agent Deployment Modes page
Same agent, three ways to ship it. Each mode is one line of glue away
from the next — a deliberate progression that lets agents earn their
way from embedded function to autonomous entity:
- Library — agent<IN, OUT>("...") { } in your JVM, in-process
- Hosted — + McpServer.from(agent).start() for an MCP endpoint
- Autonomous — fun main(args) = exitProcess(McpRunner.serve(...))
runs as its own process / JAR / Docker / native binary
The page covers all three with code, "best for" notes, an ASCII flow
diagram, and a 7-row tradeoff table (overhead, type safety, deploy
unit, scaling, isolation, language reach, ops cost). Closes with a
"progression" section explaining when to advance modes.
Sidebar and Home table updated.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
d33db24
Reflect shipped MCP work on Roadmap and Home
Roadmap was silent about the MCP arc that landed in Phase 2:
- Phase 2 Priority: mark MCP client / server / 2025-03-26 conformance /
McpRunner as done. Replace the abandoned `Tool<IN, OUT>` +
`McpTool<IN, OUT>` line with a note explaining we deliberately took
a different path (MCP tools mint as standard ToolDefs).
- Phase 2 Secondary: add the still-pending MCP follow-ups (incoming
auth on McpServer, OAuth client, Origin header, MCP-Protocol-Version
header, custom tool deserializers).
- "What You Can Build Today": add three rows for MCP client / server /
runner.
- "What is Coming Next": replace the now-shipped MCP entry with the
remaining Phase 2 items.
Home: tighten the MCP Integration row to name McpServer and McpRunner
explicitly, since those are the surfaces external clients actually
hit.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
4237c79
Add McpRunner subsection to MCP Integration
Picocli-style one-liner main for shipping agents as runnable JARs:
fun main(args: Array<String>) = exitProcess(McpRunner.serve(coder, args) {
port = 8080
expose("write-code")
})
Documents the four flags (--port, --expose, --help, --version), the
runner lifecycle (parse → validate → start → print URL → shutdown
hook → block until SIGTERM), and the rationale for hand-rolling the
CLI parser instead of pulling in picocli. Reference table updated.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
6c32d6b
Add MCP Integration page
Bidirectional MCP coverage — consuming external MCP servers via the
mcp { server() } agent DSL (HTTP/stdio/TCP transports, Bearer auth,
tool name namespacing) and exposing agent skills as MCP tools via
McpServer.from(agent). Includes how external clients (Claude Code,
Cursor, generic MCP libraries) connect to an agent's HTTP endpoint,
the lower-level McpClient factories, and the in-process mock servers
shipped for hermetic tests.
Sidebar and Home table updated to link the new page.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
0c8fda8
Bump version to 0.1.1
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
a5f524d
Expand escalation/throwing sections + Eckel exception philosophy
- Detailed escalate() vs throwException() with decision table
- EscalationError data class walkthrough
- Parent agent handling patterns (retry, reroute, partial result)
- Full escalation flow diagram with repair agent retries
- Auto-injected tools in repair agents
- Smart fixer agent example
- Bruce Eckel's "Thinking in Java" exception philosophy comparison
- Errors as values vs control flow
- Three-tier error model (handle/escalate/throw)
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
a643634
Merge existing wiki and replace with full 29-article wiki
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
32cec6f
Initial wiki: 29 educational articles
Getting Started, Core Concepts, Composition Operators,
LLM Integration, Guided Generation, Agent Memory,
and Reference articles with full code examples.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
ce838a0