diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..3af7f8e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,127 @@ +# Agents.KT + +_Source: [sdlc/agents/parts/project/project.md](sdlc/agents/parts/project/project.md)._ + +## Project + +Agents.KT is the JVM runtime for an AI factory. A factory is a line of `Agent` stations: one input type, one output type, one job. The same line builds a software agent or an embodied agent. Software tools are compilers, repos, HTTP, and MCP. Body tools are sensors and actuators, attached the same way. The handoff for a partner agent is [docs/ai-factories.md](docs/ai-factories.md). The product site is [agents-kt.dev](https://agents-kt.dev/). The Maven coordinate is `ai.deep-code:agents-kt`. The license is MIT, held by Deep-Code.AI. The repository is [Deep-CodeAI/Agents.KT](https://github.com/Deep-CodeAI/Agents.KT). + +The published version, the provider count, and the protocol status live in [release-metadata.yaml](release-metadata.yaml). [README.md](README.md) tracks that file. `ReleaseMetadataConsistencyTest` fails when a surface drifts. The [wiki](https://github.com/Deep-CodeAI/Agents.KT/wiki) is the learning path. When the wiki names an older published version, `release-metadata.yaml` and the README win. + +| Path | Holds | +| --- | --- | +| `AGENTS.md` | This law, assembled from `sdlc/agents/parts/project/`. Edit the part, then copy the same text into the matching import block. | +| [docs/ai-factories.md](docs/ai-factories.md) | Partner handoff: one factory, software lines and embodied lines. | +| `README.md` | Product contract: security model, shipped surface, limitations, documentation index. | +| `docs/` | In-repo guides. Start with [docs/testing.md](docs/testing.md), [docs/source-layout.md](docs/source-layout.md), [docs/composition.md](docs/composition.md), [docs/threat-model.md](docs/threat-model.md). The README Documentation list names the rest. | +| [Wiki Home](https://github.com/Deep-CodeAI/Agents.KT/wiki) | Learning path, from Installation through Best Practices. | +| `release-metadata.yaml` | `currentRelease`, `developmentVersion`, `providers`, and `protocols`. | +| `src/main/kotlin/agents_engine/` | Core runtime. | +| `agents-kt-*` | Feature modules named in `settings.gradle.kts`. | + +JDK 21 or newer. Kotlin version and the dependency line are the ones the README Current Release section states. The Gradle wrapper is the build. `./gradlew build` is the environment check in [Building From Source](https://github.com/Deep-CodeAI/Agents.KT/wiki/Building-From-Source). + + + + + +_Source: [sdlc/agents/parts/project/legacy.md](sdlc/agents/parts/project/legacy.md)._ + +## Authority + +Read these, in this order, before changing a claim or a boundary: + +1. [release-metadata.yaml](release-metadata.yaml) for a version, a provider count, or a protocol status (`shipped`, `partial`, `experimental`, `spiked`). +2. [README.md](README.md) for the security model, the shipped list, and the known limitations. +3. [docs/threat-model.md](docs/threat-model.md) for which boundary the runtime enforces and which boundary the deployer owns. +4. The matching page under `docs/`. +5. The wiki page for the same topic, as the long-form narrative. [Best Practices](https://github.com/Deep-CodeAI/Agents.KT/wiki/Best-Practices) holds the DO and DON'T list. + +### What the runtime owns + +- Typed `Agent` contracts and the composition operators. +- Per-skill tool authorization and typed tool handles. +- MCP client and server surfaces on the same tool and skill shape. +- Permission manifests, declarative tool policies, and runtime audit correlation. +- JSONL audit export and the OTel, LangSmith, and Langfuse adapters through `ObservabilityBridge`. +- Local-first JVM execution. Ollama is the default local provider. Cloud providers are opt-in. + +The README section "What Agents.KT Owns" is the full statement. [docs/permission-manifest.md](docs/permission-manifest.md) and [docs/cli.md](docs/cli.md) cover the manifest and the `agents-kt` CLI (`generate`, `inspect`, `verify`). + +### What the deployer owns + +The README section "What Agents.KT Does Not Own" is the full statement. The durable split: + +| Boundary | Owner | +| --- | --- | +| Legal classification of a use case | Counsel and the compliance team. The runtime emits evidence. | +| Side effects inside a Kotlin tool lambda | The deployer. Layer 1 gates declared filesystem-path arguments. `processTool` adds the Layer 2 OS sandbox for subprocess tools. | +| Public MCP request rate | The gateway, plus `McpServer` auth and policy. | +| Prompt-injection classification | The deployer, through `onBeforeTurn`. | +| Vector storage, an eval product, hosted orchestration | The surrounding system. The runtime is the typed JVM boundary under those integrations. | + +A change that widens one of these claims updates the README, the threat model, and `release-metadata.yaml` in the same edit. + + + + + +_Source: [sdlc/agents/parts/project/new_wave.md](sdlc/agents/parts/project/new_wave.md)._ + +## Working on the runtime + +### Modules + +`settings.gradle.kts` is the module list. The root project `agents-kt` holds `src/main/kotlin/agents_engine/`. Feature modules stay out of the core classpath: + +| Module | Role | +| --- | --- | +| `agents-kt-ksp` | `@Generable` metadata. `kotlin-reflect` stays optional. | +| `agents-kt-no-reflect-test` | Consumer classpath that excludes `kotlin-reflect`. | +| `agents-kt-manifest` | Deterministic permission manifests. | +| `agents-kt-cli` | `generate`, `inspect`, `verify` outside Gradle. | +| `agents-kt-observability`, `agents-kt-otel`, `agents-kt-langsmith`, `agents-kt-langfuse` | Audit export and bridges. | +| `agents-kt-rag`, `agents-kt-rag-langchain4j`, `agents-kt-rag-spring-ai` | RAG seam. | +| `agents-kt-identity`, `agents-kt-dir` | AGNTCY Identity and DIR. | +| `agents-kt-detekt` | `ToolBodyForbiddenApis` and `ToolCapabilityExtractor`. | +| `agents-kt-whisper-jni` | Optional native Whisper backend. | + +### Packages + +The wiki [Architecture Overview](https://github.com/Deep-CodeAI/Agents.KT/wiki/Architecture-Overview) describes the original four packages: `core`, `composition`, `model`, `generation`. The tree also has `a2a`, `agui`, `agntcy`, `content`, `mcp`, `nlweb`, `runtime`, `sandbox`, `testing`, `x402`, and `internal`. Match the package that already owns the behavior. + +[docs/source-layout.md](docs/source-layout.md) is the file rule. One top-level type per file. The file name is the type name. A sealed type stays with its direct subtypes. `./gradlew checkOneTypePerFile` enforces it. A real sealed-ADT exception goes in `config/one-type-per-file-allowlist.txt` with a `# sealed-ADT: keep` reason. The allowlist only shrinks. + +### Agent shape + +Follow the wiki [Best Practices](https://github.com/Deep-CodeAI/Agents.KT/wiki/Best-Practices) and [Agent and Type Contract](https://github.com/Deep-CodeAI/Agents.KT/wiki/Agent-and-Type-Contract). + +- One agent, one job. A second job is a second agent composed with `then`, `/`, `forum`, `.loop`, `.branch`, or `handoff`. +- Skill and knowledge descriptions say when the model should pick them. Ambiguous skill routing throws `SkillRoutingException`. Predicate `skillSelection { }` stays the path when the input already decides. +- Tool allowlists take typed handles from `tool(...)`. String names stay for built-ins and MCP names discovered at runtime. +- An agentic agent sets `budget { maxTurns = N }`. A loop has an exit. `maxAgentDepth` bounds nested re-entry. +- Each agent instance is placed once. A second placement throws at construction. Reuse goes through a factory. [Single-Placement Rule](https://github.com/Deep-CodeAI/Agents.KT/wiki/Single-Placement-Rule). +- Agents pass data through typed input and output, or through `MemoryBank`. A public signature stays a concrete `IN` and `OUT`. +- Structured model output uses `@Generable` and `@Guide`. A long prompt lives in a classpath resource and loads with `loadResource`. +- Knowledge entries hold no secrets. +- Public API on the 0.x line stays additive. A behavior change is named in the CHANGELOG. + +### Verification + +[docs/testing.md](docs/testing.md) is the in-repo test guide. The wiki [Building From Source](https://github.com/Deep-CodeAI/Agents.KT/wiki/Building-From-Source) is the environment guide. + +| Command | When | +| --- | --- | +| `./gradlew test` | Before a commit. Excludes `live-llm`, `live-mcp`, and `interactive`. | +| `./gradlew :test --tests "pkg.Class"` | One class. Scope the module. A root-wide `test --tests` also hits modules that lack that class. | +| `./gradlew detekt` | With the change. `detekt.yml` holds new code to the rules. The baseline only shrinks. | +| `./gradlew check` | Includes `checkOneTypePerFile`, `checkReadmeVersion`, and `checkDetektBaseline`. | +| `./gradlew integrationTest` | LLM client or agentic-loop work. Needs Ollama. | +| `./gradlew mcpIntegrationTest` | MCP client or server work. Needs `MCP_REDMINE_URL`. | +| `./gradlew pitest` | After a new behavior, to see mutants the tests leave alive. | + +Unit tests inject a `ModelClient`. Live tests stay tagged. Linux sandbox tests (`bwrap`, `firejail`) need a Linux kernel and skip on macOS. CI runs them on Ubuntu. + +A reported defect gets a regression test that fails on the current code before the fix. An existing assertion stays. When a contract change forces an edit, the test name and the contract that replaced it go in the task note. + + diff --git a/docs/ai-factories.md b/docs/ai-factories.md new file mode 100644 index 0000000..1bd0e4e --- /dev/null +++ b/docs/ai-factories.md @@ -0,0 +1,68 @@ +# AI factories on Agents.KT + +Handoff for a partner agent. This file is the project picture. Shipped behavior lives in [README.md](../README.md) and [release-metadata.yaml](../release-metadata.yaml). When this file and those two disagree about a version, a provider, or a protocol, those two win. + +## Aim + +Agents.KT is the runtime for building an AI factory. A factory is a repeatable line: a typed job goes in, bounded stations do one job each, and a typed result comes out. The same line shape builds two kinds of agent. + +| Factory | The job | The tools | The result | +| --- | --- | --- | --- | +| Software | A spec, a ticket, a file, or a user turn | Compilers, repos, HTTP, MCP servers, other agents | A patch, a document, a decision, or a tool result | +| Embodied | A mission, a pose, or a sensor frame | Cameras, drivers, grippers, navigation, motion primitives | A command a controller can run, or a stop | + +One runtime serves both. The body is a set of tools and typed messages. It is a second product of the same factory, and it is a second framework. + +## What a station is + +A station is `Agent`: one input type, one output type, one job. A skill on that station allowlists the tools that station may call. The compiler checks that one station's output is the next station's input. + +A line is composition: + +| Line | Code | Use | +| --- | --- | --- | +| Sequence | `a then b` | Software: parse, then generate, then review. Embodied: perceive, then plan, then act. | +| Same input, concurrent stations | `a / b` | Two reviewers, or two sensors, on one workpiece. | +| Council | `forum { }` | Several stations, one captain, one verdict. | +| Repeat until done | `.loop { }` | Refine a patch, or replan while the goal is open. The loop has an exit. | +| Route on type | `.branch { }` | Send a sealed result to the station that owns that case, including a stop. | +| Hand off | `triage handoff { }` | Pass the typed input to a specialist. The specialist does not receive the source history. | + +Each station instance sits on one line. A second use is a new instance from a factory function. Stations pass work through typed input and output, or through `MemoryBank`. + +## What the factory freezes before a shift + +Before a line runs, the factory can show the boundary: + +- The permission manifest lists agents, skills, tools, policies, providers, and budgets, and hashes that graph. +- A budget caps turns, tool calls, time, and tokens. `maxAgentDepth` caps nested calls. +- A tool policy records filesystem, network, and environment scope. Declared filesystem paths are gated in the JVM. Subprocess tools can run in an OS sandbox. +- Runtime events carry the manifest hash. A JSONL log and a tamper-evident tool ledger record what the line did. +- A human gate is an interceptor or a HITL interrupt. For an embodied line, a stop is a station outcome, not a sentence in a prompt. + +The deployer still owns legal classification, rate limits on public MCP, prompt-injection detection, and any safety controller under the actuators. The runtime emits evidence and enforces the boundaries declared in code. [docs/threat-model.md](threat-model.md) is the table of which layer enforces which boundary. + +## Software factory, as it stands + +This repository is that factory's runtime. Kotlin on JDK 21+. Maven coordinate `ai.deep-code:agents-kt`. License MIT, Deep-Code.AI. Product site [agents-kt.dev](https://agents-kt.dev/). Source [github.com/Deep-CodeAI/Agents.KT](https://github.com/Deep-CodeAI/Agents.KT). + +A software line is a library inside a JVM service, an MCP server, an A2A peer, or a same-JVM swarm. Local models start with Ollama. Cloud providers are opt-in. The provider count and the protocol status (`mcp`, `a2a`, `agui`, `nlweb`, `x402`, `agntcy`) are the fields in `release-metadata.yaml`. + +Core code is `src/main/kotlin/agents_engine/`. Feature modules are the `agents-kt-*` projects in `settings.gradle.kts`. Factory work goes in `src/` and those modules. + +## Embodied factory, as a target + +The embodied line uses the same station, the same allowlist, and the same manifest. A camera frame is an input type. A motion primitive is a tool. A pose is an output type. The partner agent designs that line in types and tools. + +This repository has no robot, ROS, or actuator package. Do not treat a body driver as shipped code. Attach a body by giving the act station tools whose arguments are commands the existing controller already accepts, with a budget, a policy, and a branch whose stop case runs before motion. + +## What the partner agent does with this + +1. Read [README.md](../README.md) for the security model and the shipped list. +2. Read `currentRelease`, `providers`, and `protocols` in [release-metadata.yaml](../release-metadata.yaml) before stating a version. +3. Design a line as `Agent` stations. One station, one job. +4. Choose software tools or body tools. Keep both behind the skill allowlist. +5. Put a stop, a human gate, and a budget on any line that can move code into production or move a body. +6. Verify runtime changes with `./gradlew test`. The in-repo guide is [docs/testing.md](testing.md). The learning path is the [wiki](https://github.com/Deep-CodeAI/Agents.KT/wiki). + +Contributor rules for editing this repository are in [AGENTS.md](../AGENTS.md). diff --git a/sdlc/agents/parts/project/legacy.md b/sdlc/agents/parts/project/legacy.md new file mode 100644 index 0000000..4c77756 --- /dev/null +++ b/sdlc/agents/parts/project/legacy.md @@ -0,0 +1,34 @@ +## Authority + +Read these, in this order, before changing a claim or a boundary: + +1. [release-metadata.yaml](release-metadata.yaml) for a version, a provider count, or a protocol status (`shipped`, `partial`, `experimental`, `spiked`). +2. [README.md](README.md) for the security model, the shipped list, and the known limitations. +3. [docs/threat-model.md](docs/threat-model.md) for which boundary the runtime enforces and which boundary the deployer owns. +4. The matching page under `docs/`. +5. The wiki page for the same topic, as the long-form narrative. [Best Practices](https://github.com/Deep-CodeAI/Agents.KT/wiki/Best-Practices) holds the DO and DON'T list. + +### What the runtime owns + +- Typed `Agent` contracts and the composition operators. +- Per-skill tool authorization and typed tool handles. +- MCP client and server surfaces on the same tool and skill shape. +- Permission manifests, declarative tool policies, and runtime audit correlation. +- JSONL audit export and the OTel, LangSmith, and Langfuse adapters through `ObservabilityBridge`. +- Local-first JVM execution. Ollama is the default local provider. Cloud providers are opt-in. + +The README section "What Agents.KT Owns" is the full statement. [docs/permission-manifest.md](docs/permission-manifest.md) and [docs/cli.md](docs/cli.md) cover the manifest and the `agents-kt` CLI (`generate`, `inspect`, `verify`). + +### What the deployer owns + +The README section "What Agents.KT Does Not Own" is the full statement. The durable split: + +| Boundary | Owner | +| --- | --- | +| Legal classification of a use case | Counsel and the compliance team. The runtime emits evidence. | +| Side effects inside a Kotlin tool lambda | The deployer. Layer 1 gates declared filesystem-path arguments. `processTool` adds the Layer 2 OS sandbox for subprocess tools. | +| Public MCP request rate | The gateway, plus `McpServer` auth and policy. | +| Prompt-injection classification | The deployer, through `onBeforeTurn`. | +| Vector storage, an eval product, hosted orchestration | The surrounding system. The runtime is the typed JVM boundary under those integrations. | + +A change that widens one of these claims updates the README, the threat model, and `release-metadata.yaml` in the same edit. diff --git a/sdlc/agents/parts/project/new_wave.md b/sdlc/agents/parts/project/new_wave.md new file mode 100644 index 0000000..53df8b1 --- /dev/null +++ b/sdlc/agents/parts/project/new_wave.md @@ -0,0 +1,55 @@ +## Working on the runtime + +### Modules + +`settings.gradle.kts` is the module list. The root project `agents-kt` holds `src/main/kotlin/agents_engine/`. Feature modules stay out of the core classpath: + +| Module | Role | +| --- | --- | +| `agents-kt-ksp` | `@Generable` metadata. `kotlin-reflect` stays optional. | +| `agents-kt-no-reflect-test` | Consumer classpath that excludes `kotlin-reflect`. | +| `agents-kt-manifest` | Deterministic permission manifests. | +| `agents-kt-cli` | `generate`, `inspect`, `verify` outside Gradle. | +| `agents-kt-observability`, `agents-kt-otel`, `agents-kt-langsmith`, `agents-kt-langfuse` | Audit export and bridges. | +| `agents-kt-rag`, `agents-kt-rag-langchain4j`, `agents-kt-rag-spring-ai` | RAG seam. | +| `agents-kt-identity`, `agents-kt-dir` | AGNTCY Identity and DIR. | +| `agents-kt-detekt` | `ToolBodyForbiddenApis` and `ToolCapabilityExtractor`. | +| `agents-kt-whisper-jni` | Optional native Whisper backend. | + +### Packages + +The wiki [Architecture Overview](https://github.com/Deep-CodeAI/Agents.KT/wiki/Architecture-Overview) describes the original four packages: `core`, `composition`, `model`, `generation`. The tree also has `a2a`, `agui`, `agntcy`, `content`, `mcp`, `nlweb`, `runtime`, `sandbox`, `testing`, `x402`, and `internal`. Match the package that already owns the behavior. + +[docs/source-layout.md](docs/source-layout.md) is the file rule. One top-level type per file. The file name is the type name. A sealed type stays with its direct subtypes. `./gradlew checkOneTypePerFile` enforces it. A real sealed-ADT exception goes in `config/one-type-per-file-allowlist.txt` with a `# sealed-ADT: keep` reason. The allowlist only shrinks. + +### Agent shape + +Follow the wiki [Best Practices](https://github.com/Deep-CodeAI/Agents.KT/wiki/Best-Practices) and [Agent and Type Contract](https://github.com/Deep-CodeAI/Agents.KT/wiki/Agent-and-Type-Contract). + +- One agent, one job. A second job is a second agent composed with `then`, `/`, `forum`, `.loop`, `.branch`, or `handoff`. +- Skill and knowledge descriptions say when the model should pick them. Ambiguous skill routing throws `SkillRoutingException`. Predicate `skillSelection { }` stays the path when the input already decides. +- Tool allowlists take typed handles from `tool(...)`. String names stay for built-ins and MCP names discovered at runtime. +- An agentic agent sets `budget { maxTurns = N }`. A loop has an exit. `maxAgentDepth` bounds nested re-entry. +- Each agent instance is placed once. A second placement throws at construction. Reuse goes through a factory. [Single-Placement Rule](https://github.com/Deep-CodeAI/Agents.KT/wiki/Single-Placement-Rule). +- Agents pass data through typed input and output, or through `MemoryBank`. A public signature stays a concrete `IN` and `OUT`. +- Structured model output uses `@Generable` and `@Guide`. A long prompt lives in a classpath resource and loads with `loadResource`. +- Knowledge entries hold no secrets. +- Public API on the 0.x line stays additive. A behavior change is named in the CHANGELOG. + +### Verification + +[docs/testing.md](docs/testing.md) is the in-repo test guide. The wiki [Building From Source](https://github.com/Deep-CodeAI/Agents.KT/wiki/Building-From-Source) is the environment guide. + +| Command | When | +| --- | --- | +| `./gradlew test` | Before a commit. Excludes `live-llm`, `live-mcp`, and `interactive`. | +| `./gradlew :test --tests "pkg.Class"` | One class. Scope the module. A root-wide `test --tests` also hits modules that lack that class. | +| `./gradlew detekt` | With the change. `detekt.yml` holds new code to the rules. The baseline only shrinks. | +| `./gradlew check` | Includes `checkOneTypePerFile`, `checkReadmeVersion`, and `checkDetektBaseline`. | +| `./gradlew integrationTest` | LLM client or agentic-loop work. Needs Ollama. | +| `./gradlew mcpIntegrationTest` | MCP client or server work. Needs `MCP_REDMINE_URL`. | +| `./gradlew pitest` | After a new behavior, to see mutants the tests leave alive. | + +Unit tests inject a `ModelClient`. Live tests stay tagged. Linux sandbox tests (`bwrap`, `firejail`) need a Linux kernel and skip on macOS. CI runs them on Ubuntu. + +A reported defect gets a regression test that fails on the current code before the fix. An existing assertion stays. When a contract change forces an edit, the test name and the contract that replaced it go in the task note. diff --git a/sdlc/agents/parts/project/project.md b/sdlc/agents/parts/project/project.md new file mode 100644 index 0000000..e180773 --- /dev/null +++ b/sdlc/agents/parts/project/project.md @@ -0,0 +1,18 @@ +## Project + +Agents.KT is the JVM runtime for an AI factory. A factory is a line of `Agent` stations: one input type, one output type, one job. The same line builds a software agent or an embodied agent. Software tools are compilers, repos, HTTP, and MCP. Body tools are sensors and actuators, attached the same way. The handoff for a partner agent is [docs/ai-factories.md](docs/ai-factories.md). The product site is [agents-kt.dev](https://agents-kt.dev/). The Maven coordinate is `ai.deep-code:agents-kt`. The license is MIT, held by Deep-Code.AI. The repository is [Deep-CodeAI/Agents.KT](https://github.com/Deep-CodeAI/Agents.KT). + +The published version, the provider count, and the protocol status live in [release-metadata.yaml](release-metadata.yaml). [README.md](README.md) tracks that file. `ReleaseMetadataConsistencyTest` fails when a surface drifts. The [wiki](https://github.com/Deep-CodeAI/Agents.KT/wiki) is the learning path. When the wiki names an older published version, `release-metadata.yaml` and the README win. + +| Path | Holds | +| --- | --- | +| `AGENTS.md` | This law, assembled from `sdlc/agents/parts/project/`. Edit the part, then copy the same text into the matching import block. | +| [docs/ai-factories.md](docs/ai-factories.md) | Partner handoff: one factory, software lines and embodied lines. | +| `README.md` | Product contract: security model, shipped surface, limitations, documentation index. | +| `docs/` | In-repo guides. Start with [docs/testing.md](docs/testing.md), [docs/source-layout.md](docs/source-layout.md), [docs/composition.md](docs/composition.md), [docs/threat-model.md](docs/threat-model.md). The README Documentation list names the rest. | +| [Wiki Home](https://github.com/Deep-CodeAI/Agents.KT/wiki) | Learning path, from Installation through Best Practices. | +| `release-metadata.yaml` | `currentRelease`, `developmentVersion`, `providers`, and `protocols`. | +| `src/main/kotlin/agents_engine/` | Core runtime. | +| `agents-kt-*` | Feature modules named in `settings.gradle.kts`. | + +JDK 21 or newer. Kotlin version and the dependency line are the ones the README Current Release section states. The Gradle wrapper is the build. `./gradlew build` is the environment check in [Building From Source](https://github.com/Deep-CodeAI/Agents.KT/wiki/Building-From-Source).