@kindgi/cli 0.1.4-rc.5 → 0.1.5-rc.0

package/dist/templates/java/README.md.tmpl

@@ -0,0 +1,69 @@
+# {{PACK_NAME}}
+
+A sample Kindgi pack in Java — scaffolded by `kindgi init --template=java`.
+
+Two tools (`echo`, `greet`), one guardrail (`response-not-empty`), one agent
+that uses both tools and the guardrail, and one flow that runs the echo tool.
+
+Java and Scala support is in preview: tested and supported, but the API may
+still change in 0.1.6 without the usual deprecation period.
+
+## Layout
+
+```
+{{PACK_NAME}}/
+├── kindgi.config.json                       # the pack's id and version ("language": "java")
+├── pom.xml                                  # com.kindgi:kindgi-pack, Java 17
+├── src/main/java/{{JAVA_PACKAGE_PATH}}/
+│   ├── tools/Echo.java                      # Tool.define — records in, records out
+│   ├── tools/Greet.java                     # Tool.define
+│   ├── guardrails/ResponseNotEmpty.java     # Guardrail.define — a zero-LLM check over the run
+│   ├── agents/EchoAgent.java                # Agent.define — data
+│   └── flows/EchoFlow.java                  # Flow.define — data
+└── src/test/java/{{JAVA_PACKAGE_PATH}}/ToolsTest.java   # the tools, called directly
+```
+
+## Run
+
+You need a JDK 17 or later (`JAVA_HOME`); Maven comes with the project
+(`./mvnw`).
+
+```sh
+./mvnw test
+kindgi dev       # boots Kindgi locally, compiles and runs this pack, recompiling on save
+```
+
+Then, from another terminal:
+
+```sh
+kindgi runs start --agent={{PACK_ID}}.echo-agent --input='{"userMessage":"hi"}'
+```
+
+`kindgi dev` uses `JAVA_HOME`'s JDK (or `dev.javaHome` in `kindgi.config.json`)
+and the project's Maven wrapper (or `dev.maven`, e.g. `["mvn", "-s", "settings.xml"]`).
+`MAVEN_ARGS` and `MAVEN_OPTS` in your shell reach Maven only, never the pack.
+
+## Use a real model
+
+`kindgi dev` gives a new pack `dev-echo`, a fallback provider that isn't a
+model: it calls the first tool and replies "Tool responded: …", after a
+warning line that says so. It answers only while no other provider fits. To
+use a real model, set one LLM provider's key and register its preset, with
+`kindgi dev` running, from another terminal. For Claude:
+
+```sh
+kindgi secrets set ANTHROPIC_API_KEY --env=local --scope=tenant   # no-echo prompt; writes .env.local
+kindgi providers register --preset=anthropic                      # Opus 5.5, Sonnet 5.5, Haiku 4.5
+```
+
+Claude takes over from dev-echo on the next turn; nothing to restart.
+OpenAI (`OPENAI_API_KEY`, `--preset=openai`), Gemini (`GEMINI_API_KEY`,
+`--preset=gemini-api`), Groq (`GROQ_API_KEY`, `--preset=groq`) and
+OpenRouter (`OPENROUTER_API_KEY`, `--preset=openrouter`) work the same way;
+`kindgi providers presets` lists the presets.
+
+## Build
+
+`kindgi build --env=<name>` makes the pack's image: Maven compiles it in a
+pinned Maven + JDK 17 image, the index is built in the image, and the pack
+service runs on a JRE 17 as its entrypoint.

package/dist/templates/java/gitignore

@@ -0,0 +1,9 @@
+target/
+.kindgi/
+.kindgirc.json
+.env
+.env.*
+!.env.example
+.idea/
+*.iml
+.vscode/

package/dist/templates/java/kindgi.config.json.tmpl

@@ -0,0 +1,8 @@
+{
+  "language": "java",
+  "cli": "{{KINDGI_CLI_VERSION}}",
+  "pack": {
+    "id": "{{PACK_ID}}",
+    "version": "{{PACK_VERSION}}"
+  }
+}

package/dist/templates/java/kindgiw

@@ -0,0 +1,33 @@
+#!/bin/sh
+# kindgiw: runs the Kindgi CLI this pack pins ("cli" in kindgi.config.json),
+# as mvnw runs the Maven it pins. Written by `kindgi init`; `kindgi upgrade`
+# moves the pin.
+#
+#   ./kindgiw dev
+#   ./kindgiw runs start --agent=<id> --input='{"userMessage":"hi"}'
+#
+# It runs the CLI from npm (npx) when Node is installed, else from PyPI
+# (uvx; kindgi-cli brings its own Node), else says how to get one of them.
+set -eu
+dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+config="$dir/kindgi.config.json"
+version=$(sed -n 's/^[[:space:]]*"cli"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' "$config" 2>/dev/null | head -n 1)
+if [ -z "$version" ]; then
+  echo "kindgiw: no \"cli\" version in $config (kindgi upgrade writes it)." >&2
+  exit 1
+fi
+if command -v node >/dev/null 2>&1 && command -v npx >/dev/null 2>&1; then
+  exec npx --yes "@kindgi/cli@$version" "$@"
+fi
+# PyPI spells pre-releases PEP 440's way: 0.1.6-rc.2 is 0.1.6rc2.
+pep440=$(printf '%s' "$version" | sed -e 's/-alpha\./a/' -e 's/-beta\./b/' -e 's/-rc\./rc/')
+if command -v uvx >/dev/null 2>&1; then
+  exec uvx --from "kindgi-cli==$pep440" kindgi "$@"
+fi
+if command -v uv >/dev/null 2>&1; then
+  exec uv tool run --from "kindgi-cli==$pep440" kindgi "$@"
+fi
+echo "kindgiw: the Kindgi CLI $version runs with Node 22.12 or later (https://nodejs.org)," >&2
+echo "  or with uv (https://docs.astral.sh/uv/getting-started/installation/), which needs no Node." >&2
+echo "  Install either one, then run ./kindgiw again." >&2
+exit 1

package/dist/templates/java/kindgiw.cmd

@@ -0,0 +1,28 @@
+@echo off
+rem kindgiw: runs the Kindgi CLI this pack pins ("cli" in kindgi.config.json),
+rem as mvnw runs the Maven it pins. Written by `kindgi init`; `kindgi upgrade`
+rem moves the pin. From npm (npx) with Node, else from PyPI (uvx).
+setlocal
+set "KINDGIW_DIR=%~dp0"
+set "KINDGIW_VERSION="
+for /f "usebackq delims=" %%v in (`powershell -NoProfile -Command "(Get-Content -Raw -LiteralPath '%KINDGIW_DIR%kindgi.config.json' | ConvertFrom-Json).cli"`) do set "KINDGIW_VERSION=%%v"
+if "%KINDGIW_VERSION%"=="" (
+  echo kindgiw: no "cli" version in %KINDGIW_DIR%kindgi.config.json ^(kindgi upgrade writes it^). 1>&2
+  exit /b 1
+)
+rem `call`: npx is a batch file, and a batch file run without it never returns.
+where node >nul 2>nul && where npx >nul 2>nul && (
+  call npx --yes "@kindgi/cli@%KINDGIW_VERSION%" %*
+  exit /b
+)
+set "KINDGIW_PEP440=%KINDGIW_VERSION:-alpha.=a%"
+set "KINDGIW_PEP440=%KINDGIW_PEP440:-beta.=b%"
+set "KINDGIW_PEP440=%KINDGIW_PEP440:-rc.=rc%"
+where uvx >nul 2>nul && (
+  call uvx --from "kindgi-cli==%KINDGIW_PEP440%" kindgi %*
+  exit /b
+)
+echo kindgiw: the Kindgi CLI %KINDGIW_VERSION% runs with Node 22.12 or later ^(https://nodejs.org^), 1>&2
+echo   or with uv ^(https://docs.astral.sh/uv/getting-started/installation/^), which needs no Node. 1>&2
+echo   Install either one, then run kindgiw again. 1>&2
+exit /b 1

package/dist/templates/java/mvnw

@@ -0,0 +1,295 @@
+#!/bin/sh
+# ----------------------------------------------------------------------------
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements.  See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership.  The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License.  You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied.  See the License for the
+# specific language governing permissions and limitations
+# under the License.
+# ----------------------------------------------------------------------------
+
+# ----------------------------------------------------------------------------
+# Apache Maven Wrapper startup batch script, version 3.3.4
+#
+# Optional ENV vars
+# -----------------
+#   JAVA_HOME - location of a JDK home dir, required when download maven via java source
+#   MVNW_REPOURL - repo url base for downloading maven distribution
+#   MVNW_USERNAME/MVNW_PASSWORD - user and password for downloading maven
+#   MVNW_VERBOSE - true: enable verbose log; debug: trace the mvnw script; others: silence the output
+# ----------------------------------------------------------------------------
+
+set -euf
+[ "${MVNW_VERBOSE-}" != debug ] || set -x
+
+# OS specific support.
+native_path() { printf %s\\n "$1"; }
+case "$(uname)" in
+CYGWIN* | MINGW*)
+  [ -z "${JAVA_HOME-}" ] || JAVA_HOME="$(cygpath --unix "$JAVA_HOME")"
+  native_path() { cygpath --path --windows "$1"; }
+  ;;
+esac
+
+# set JAVACMD and JAVACCMD
+set_java_home() {
+  # For Cygwin and MinGW, ensure paths are in Unix format before anything is touched
+  if [ -n "${JAVA_HOME-}" ]; then
+    if [ -x "$JAVA_HOME/jre/sh/java" ]; then
+      # IBM's JDK on AIX uses strange locations for the executables
+      JAVACMD="$JAVA_HOME/jre/sh/java"
+      JAVACCMD="$JAVA_HOME/jre/sh/javac"
+    else
+      JAVACMD="$JAVA_HOME/bin/java"
+      JAVACCMD="$JAVA_HOME/bin/javac"
+
+      if [ ! -x "$JAVACMD" ] || [ ! -x "$JAVACCMD" ]; then
+        echo "The JAVA_HOME environment variable is not defined correctly, so mvnw cannot run." >&2
+        echo "JAVA_HOME is set to \"$JAVA_HOME\", but \"\$JAVA_HOME/bin/java\" or \"\$JAVA_HOME/bin/javac\" does not exist." >&2
+        return 1
+      fi
+    fi
+  else
+    JAVACMD="$(
+      'set' +e
+      'unset' -f command 2>/dev/null
+      'command' -v java
+    )" || :
+    JAVACCMD="$(
+      'set' +e
+      'unset' -f command 2>/dev/null
+      'command' -v javac
+    )" || :
+
+    if [ ! -x "${JAVACMD-}" ] || [ ! -x "${JAVACCMD-}" ]; then
+      echo "The java/javac command does not exist in PATH nor is JAVA_HOME set, so mvnw cannot run." >&2
+      return 1
+    fi
+  fi
+}
+
+# hash string like Java String::hashCode
+hash_string() {
+  str="${1:-}" h=0
+  while [ -n "$str" ]; do
+    char="${str%"${str#?}"}"
+    h=$(((h * 31 + $(LC_CTYPE=C printf %d "'$char")) % 4294967296))
+    str="${str#?}"
+  done
+  printf %x\\n $h
+}
+
+verbose() { :; }
+[ "${MVNW_VERBOSE-}" != true ] || verbose() { printf %s\\n "${1-}"; }
+
+die() {
+  printf %s\\n "$1" >&2
+  exit 1
+}
+
+trim() {
+  # MWRAPPER-139:
+  #   Trims trailing and leading whitespace, carriage returns, tabs, and linefeeds.
+  #   Needed for removing poorly interpreted newline sequences when running in more
+  #   exotic environments such as mingw bash on Windows.
+  printf "%s" "${1}" | tr -d '[:space:]'
+}
+
+scriptDir="$(dirname "$0")"
+scriptName="$(basename "$0")"
+
+# parse distributionUrl and optional distributionSha256Sum, requires .mvn/wrapper/maven-wrapper.properties
+while IFS="=" read -r key value; do
+  case "${key-}" in
+  distributionUrl) distributionUrl=$(trim "${value-}") ;;
+  distributionSha256Sum) distributionSha256Sum=$(trim "${value-}") ;;
+  esac
+done <"$scriptDir/.mvn/wrapper/maven-wrapper.properties"
+[ -n "${distributionUrl-}" ] || die "cannot read distributionUrl property in $scriptDir/.mvn/wrapper/maven-wrapper.properties"
+
+case "${distributionUrl##*/}" in
+maven-mvnd-*bin.*)
+  MVN_CMD=mvnd.sh _MVNW_REPO_PATTERN=/maven/mvnd/
+  case "${PROCESSOR_ARCHITECTURE-}${PROCESSOR_ARCHITEW6432-}:$(uname -a)" in
+  *AMD64:CYGWIN* | *AMD64:MINGW*) distributionPlatform=windows-amd64 ;;
+  :Darwin*x86_64) distributionPlatform=darwin-amd64 ;;
+  :Darwin*arm64) distributionPlatform=darwin-aarch64 ;;
+  :Linux*x86_64*) distributionPlatform=linux-amd64 ;;
+  *)
+    echo "Cannot detect native platform for mvnd on $(uname)-$(uname -m), use pure java version" >&2
+    distributionPlatform=linux-amd64
+    ;;
+  esac
+  distributionUrl="${distributionUrl%-bin.*}-$distributionPlatform.zip"
+  ;;
+maven-mvnd-*) MVN_CMD=mvnd.sh _MVNW_REPO_PATTERN=/maven/mvnd/ ;;
+*) MVN_CMD="mvn${scriptName#mvnw}" _MVNW_REPO_PATTERN=/org/apache/maven/ ;;
+esac
+
+# apply MVNW_REPOURL and calculate MAVEN_HOME
+# maven home pattern: ~/.m2/wrapper/dists/{apache-maven-<version>,maven-mvnd-<version>-<platform>}/<hash>
+[ -z "${MVNW_REPOURL-}" ] || distributionUrl="$MVNW_REPOURL$_MVNW_REPO_PATTERN${distributionUrl#*"$_MVNW_REPO_PATTERN"}"
+distributionUrlName="${distributionUrl##*/}"
+distributionUrlNameMain="${distributionUrlName%.*}"
+distributionUrlNameMain="${distributionUrlNameMain%-bin}"
+MAVEN_USER_HOME="${MAVEN_USER_HOME:-${HOME}/.m2}"
+MAVEN_HOME="${MAVEN_USER_HOME}/wrapper/dists/${distributionUrlNameMain-}/$(hash_string "$distributionUrl")"
+
+exec_maven() {
+  unset MVNW_VERBOSE MVNW_USERNAME MVNW_PASSWORD MVNW_REPOURL || :
+  exec "$MAVEN_HOME/bin/$MVN_CMD" "$@" || die "cannot exec $MAVEN_HOME/bin/$MVN_CMD"
+}
+
+if [ -d "$MAVEN_HOME" ]; then
+  verbose "found existing MAVEN_HOME at $MAVEN_HOME"
+  exec_maven "$@"
+fi
+
+case "${distributionUrl-}" in
+*?-bin.zip | *?maven-mvnd-?*-?*.zip) ;;
+*) die "distributionUrl is not valid, must match *-bin.zip or maven-mvnd-*.zip, but found '${distributionUrl-}'" ;;
+esac
+
+# prepare tmp dir
+if TMP_DOWNLOAD_DIR="$(mktemp -d)" && [ -d "$TMP_DOWNLOAD_DIR" ]; then
+  clean() { rm -rf -- "$TMP_DOWNLOAD_DIR"; }
+  trap clean HUP INT TERM EXIT
+else
+  die "cannot create temp dir"
+fi
+
+mkdir -p -- "${MAVEN_HOME%/*}"
+
+# Download and Install Apache Maven
+verbose "Couldn't find MAVEN_HOME, downloading and installing it ..."
+verbose "Downloading from: $distributionUrl"
+verbose "Downloading to: $TMP_DOWNLOAD_DIR/$distributionUrlName"
+
+# select .zip or .tar.gz
+if ! command -v unzip >/dev/null; then
+  distributionUrl="${distributionUrl%.zip}.tar.gz"
+  distributionUrlName="${distributionUrl##*/}"
+fi
+
+# verbose opt
+__MVNW_QUIET_WGET=--quiet __MVNW_QUIET_CURL=--silent __MVNW_QUIET_UNZIP=-q __MVNW_QUIET_TAR=''
+[ "${MVNW_VERBOSE-}" != true ] || __MVNW_QUIET_WGET='' __MVNW_QUIET_CURL='' __MVNW_QUIET_UNZIP='' __MVNW_QUIET_TAR=v
+
+# normalize http auth
+case "${MVNW_PASSWORD:+has-password}" in
+'') MVNW_USERNAME='' MVNW_PASSWORD='' ;;
+has-password) [ -n "${MVNW_USERNAME-}" ] || MVNW_USERNAME='' MVNW_PASSWORD='' ;;
+esac
+
+if [ -z "${MVNW_USERNAME-}" ] && command -v wget >/dev/null; then
+  verbose "Found wget ... using wget"
+  wget ${__MVNW_QUIET_WGET:+"$__MVNW_QUIET_WGET"} "$distributionUrl" -O "$TMP_DOWNLOAD_DIR/$distributionUrlName" || die "wget: Failed to fetch $distributionUrl"
+elif [ -z "${MVNW_USERNAME-}" ] && command -v curl >/dev/null; then
+  verbose "Found curl ... using curl"
+  curl ${__MVNW_QUIET_CURL:+"$__MVNW_QUIET_CURL"} -f -L -o "$TMP_DOWNLOAD_DIR/$distributionUrlName" "$distributionUrl" || die "curl: Failed to fetch $distributionUrl"
+elif set_java_home; then
+  verbose "Falling back to use Java to download"
+  javaSource="$TMP_DOWNLOAD_DIR/Downloader.java"
+  targetZip="$TMP_DOWNLOAD_DIR/$distributionUrlName"
+  cat >"$javaSource" <<-END
+	public class Downloader extends java.net.Authenticator
+	{
+	  protected java.net.PasswordAuthentication getPasswordAuthentication()
+	  {
+	    return new java.net.PasswordAuthentication( System.getenv( "MVNW_USERNAME" ), System.getenv( "MVNW_PASSWORD" ).toCharArray() );
+	  }
+	  public static void main( String[] args ) throws Exception
+	  {
+	    setDefault( new Downloader() );
+	    java.nio.file.Files.copy( java.net.URI.create( args[0] ).toURL().openStream(), java.nio.file.Paths.get( args[1] ).toAbsolutePath().normalize() );
+	  }
+	}
+	END
+  # For Cygwin/MinGW, switch paths to Windows format before running javac and java
+  verbose " - Compiling Downloader.java ..."
+  "$(native_path "$JAVACCMD")" "$(native_path "$javaSource")" || die "Failed to compile Downloader.java"
+  verbose " - Running Downloader.java ..."
+  "$(native_path "$JAVACMD")" -cp "$(native_path "$TMP_DOWNLOAD_DIR")" Downloader "$distributionUrl" "$(native_path "$targetZip")"
+fi
+
+# If specified, validate the SHA-256 sum of the Maven distribution zip file
+if [ -n "${distributionSha256Sum-}" ]; then
+  distributionSha256Result=false
+  if [ "$MVN_CMD" = mvnd.sh ]; then
+    echo "Checksum validation is not supported for maven-mvnd." >&2
+    echo "Please disable validation by removing 'distributionSha256Sum' from your maven-wrapper.properties." >&2
+    exit 1
+  elif command -v sha256sum >/dev/null; then
+    if echo "$distributionSha256Sum  $TMP_DOWNLOAD_DIR/$distributionUrlName" | sha256sum -c - >/dev/null 2>&1; then
+      distributionSha256Result=true
+    fi
+  elif command -v shasum >/dev/null; then
+    if echo "$distributionSha256Sum  $TMP_DOWNLOAD_DIR/$distributionUrlName" | shasum -a 256 -c >/dev/null 2>&1; then
+      distributionSha256Result=true
+    fi
+  else
+    echo "Checksum validation was requested but neither 'sha256sum' or 'shasum' are available." >&2
+    echo "Please install either command, or disable validation by removing 'distributionSha256Sum' from your maven-wrapper.properties." >&2
+    exit 1
+  fi
+  if [ $distributionSha256Result = false ]; then
+    echo "Error: Failed to validate Maven distribution SHA-256, your Maven distribution might be compromised." >&2
+    echo "If you updated your Maven version, you need to update the specified distributionSha256Sum property." >&2
+    exit 1
+  fi
+fi
+
+# unzip and move
+if command -v unzip >/dev/null; then
+  unzip ${__MVNW_QUIET_UNZIP:+"$__MVNW_QUIET_UNZIP"} "$TMP_DOWNLOAD_DIR/$distributionUrlName" -d "$TMP_DOWNLOAD_DIR" || die "failed to unzip"
+else
+  tar xzf${__MVNW_QUIET_TAR:+"$__MVNW_QUIET_TAR"} "$TMP_DOWNLOAD_DIR/$distributionUrlName" -C "$TMP_DOWNLOAD_DIR" || die "failed to untar"
+fi
+
+# Find the actual extracted directory name (handles snapshots where filename != directory name)
+actualDistributionDir=""
+
+# First try the expected directory name (for regular distributions)
+if [ -d "$TMP_DOWNLOAD_DIR/$distributionUrlNameMain" ]; then
+  if [ -f "$TMP_DOWNLOAD_DIR/$distributionUrlNameMain/bin/$MVN_CMD" ]; then
+    actualDistributionDir="$distributionUrlNameMain"
+  fi
+fi
+
+# If not found, search for any directory with the Maven executable (for snapshots)
+if [ -z "$actualDistributionDir" ]; then
+  # enable globbing to iterate over items
+  set +f
+  for dir in "$TMP_DOWNLOAD_DIR"/*; do
+    if [ -d "$dir" ]; then
+      if [ -f "$dir/bin/$MVN_CMD" ]; then
+        actualDistributionDir="$(basename "$dir")"
+        break
+      fi
+    fi
+  done
+  set -f
+fi
+
+if [ -z "$actualDistributionDir" ]; then
+  verbose "Contents of $TMP_DOWNLOAD_DIR:"
+  verbose "$(ls -la "$TMP_DOWNLOAD_DIR")"
+  die "Could not find Maven distribution directory in extracted archive"
+fi
+
+verbose "Found extracted Maven distribution directory: $actualDistributionDir"
+printf %s\\n "$distributionUrl" >"$TMP_DOWNLOAD_DIR/$actualDistributionDir/mvnw.url"
+mv -- "$TMP_DOWNLOAD_DIR/$actualDistributionDir" "$MAVEN_HOME" || [ -d "$MAVEN_HOME" ] || die "fail to move MAVEN_HOME"
+
+clean || :
+exec_maven "$@"

package/dist/templates/java/pom.xml.tmpl

@@ -0,0 +1,65 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+
+  <groupId>{{JAVA_PACKAGE}}</groupId>
+  <artifactId>{{PACK_NAME}}</artifactId>
+  <version>{{PACK_VERSION}}</version>
+  <name>{{PACK_NAME}}</name>
+  <description>A Kindgi pack in Java: its tools, guardrail checks, agents and flows.</description>
+
+  <properties>
+    <maven.compiler.release>17</maven.compiler.release>
+    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+    <kindgi.version>{{KINDGI_JAVA_VERSION}}</kindgi.version>
+  </properties>
+
+  <dependencies>
+    <!-- Tools, guardrail checks, the indexer and the pack service. -->
+    <dependency>
+      <groupId>com.kindgi</groupId>
+      <artifactId>kindgi-pack</artifactId>
+      <version>${kindgi.version}</version>
+    </dependency>
+    <!-- Constraints on tool inputs (@Size, @Min, @Email, …) become their schemas' keywords. -->
+    <dependency>
+      <groupId>jakarta.validation</groupId>
+      <artifactId>jakarta.validation-api</artifactId>
+      <version>3.0.2</version>
+    </dependency>
+
+    <dependency>
+      <groupId>org.junit.jupiter</groupId>
+      <artifactId>junit-jupiter</artifactId>
+      <version>6.1.3</version>
+      <scope>test</scope>
+    </dependency>
+  </dependencies>
+
+  <build>
+    <plugins>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-resources-plugin</artifactId>
+        <version>3.5.0</version>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-compiler-plugin</artifactId>
+        <version>3.16.0</version>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-surefire-plugin</artifactId>
+        <version>3.6.0</version>
+      </plugin>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-dependency-plugin</artifactId>
+        <version>3.11.0</version>
+      </plugin>
+    </plugins>
+  </build>
+</project>

package/dist/templates/java/src/main/java/__PACKAGE__/agents/EchoAgent.java.tmpl

@@ -0,0 +1,27 @@
+package {{JAVA_PACKAGE}}.agents;
+
+import {{JAVA_PACKAGE}}.guardrails.ResponseNotEmpty;
+import {{JAVA_PACKAGE}}.tools.Echo;
+import {{JAVA_PACKAGE}}.tools.Greet;
+import com.kindgi.pack.Agent;
+import java.util.List;
+import java.util.Map;
+
+/** {{PACK_ID}}.echo-agent — uses both tools; the response-not-empty guardrail guards its answer. */
+public final class EchoAgent {
+  public static final Agent AGENT = Agent.define("{{PACK_ID}}.echo-agent")
+      .version("{{PACK_VERSION}}")
+      .name("Echo Agent")
+      .description("Uses the pack's echo and greet tools; the response-not-empty guardrail guards the output.")
+      .instructions("For each user message: if the user sends a name, greet them with the greet tool. "
+          + "Otherwise echo their message with the echo tool. Quote the tool result verbatim.")
+      .capability(Map.of("needs", List.of(Map.of("feature", "tool-use"))))
+      .tool(Echo.TOOL)
+      .tool(Greet.TOOL)
+      .guardrail(ResponseNotEmpty.GUARDRAIL)
+      .set("conversationPolicy", Map.of("historyLimit", 10))
+      .set("budget", Map.of("maxSteps", 4, "maxCostUsd", 0.1, "maxWallMs", 60_000))
+      .build();
+
+  private EchoAgent() {}
+}

package/dist/templates/java/src/main/java/__PACKAGE__/flows/EchoFlow.java.tmpl

@@ -0,0 +1,18 @@
+package {{JAVA_PACKAGE}}.flows;
+
+import {{JAVA_PACKAGE}}.tools.Echo;
+import com.kindgi.pack.Flow;
+
+/** {{PACK_ID}}.echo-flow — runs the pack's echo tool, then ends. */
+public final class EchoFlow {
+  public static final Flow FLOW = Flow.define("{{PACK_ID}}.echo-flow")
+      .version("{{PACK_VERSION}}")
+      .set("name", "Echo Flow")
+      .set("description", "Runs the pack's echo tool and terminates.")
+      .toolNode("echo", Echo.TOOL)
+      .edge("e-start", "$start", "echo")
+      .edge("e-end", "echo", "$end")
+      .build();
+
+  private EchoFlow() {}
+}

package/dist/templates/java/src/main/java/__PACKAGE__/guardrails/ResponseNotEmpty.java.tmpl

@@ -0,0 +1,28 @@
+package {{JAVA_PACKAGE}}.guardrails;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.kindgi.pack.CheckResult;
+import com.kindgi.pack.Guardrail;
+import jakarta.validation.constraints.Min;
+import java.util.Map;
+
+/** {{PACK_ID}}.response-not-empty — a zero-LLM guardrail: the run's answer has content. */
+public final class ResponseNotEmpty {
+  public record Config(@JsonProperty(defaultValue = "1") @Min(0) int minLength) {}
+
+  public static final Guardrail<Config> GUARDRAIL = Guardrail.define("{{PACK_ID}}.response-not-empty")
+      .name("Response is non-empty")
+      .checkId("{{PACK_ID}}.checks.response-not-empty")
+      .onViolation("halt")
+      .severity("error")
+      .set("scope", Map.of("when", "runtime-only"))
+      .config(Config.class)
+      .check((config, trace) -> {
+        String text = trace.output() == null ? "" : trace.output().strip();
+        return text.length() >= config.minLength()
+            ? CheckResult.pass()
+            : CheckResult.fail("Response too short: " + text.length() + " chars, expected >= " + config.minLength() + ".");
+      });
+
+  private ResponseNotEmpty() {}
+}

package/dist/templates/java/src/main/java/__PACKAGE__/tools/Echo.java.tmpl

@@ -0,0 +1,22 @@
+package {{JAVA_PACKAGE}}.tools;
+
+import com.kindgi.pack.Tool;
+import jakarta.validation.constraints.PositiveOrZero;
+import jakarta.validation.constraints.Size;
+import java.time.Instant;
+
+/** {{PACK_ID}}.echo — echoes the message back with a UTC timestamp and its length. */
+public final class Echo {
+  public record Input(@Size(min = 1, max = 500) String message) {}
+
+  public record Output(String echo, Instant echoedAt, @PositiveOrZero int characterCount) {}
+
+  public static final Tool<Input, Output> TOOL = Tool.define("{{PACK_ID}}.echo")
+      .description("Echoes the caller-provided message with a UTC timestamp and character count.")
+      .input(Input.class)
+      .output(Output.class)
+      .mutating(false)
+      .handler((input, ctx) -> new Output(input.message(), Instant.now(), input.message().length()));
+
+  private Echo() {}
+}

package/dist/templates/java/src/main/java/__PACKAGE__/tools/Greet.java.tmpl

@@ -0,0 +1,23 @@
+package {{JAVA_PACKAGE}}.tools;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.kindgi.pack.Tool;
+import jakarta.validation.constraints.Size;
+
+/** {{PACK_ID}}.greet — greets a named recipient. */
+public final class Greet {
+  public record Input(
+      @Size(min = 1, max = 100) String name,
+      @JsonProperty(defaultValue = "Hello") @Size(min = 1, max = 50) String greeting) {}
+
+  public record Output(String message) {}
+
+  public static final Tool<Input, Output> TOOL = Tool.define("{{PACK_ID}}.greet")
+      .description("Formats a greeting for the named recipient.")
+      .input(Input.class)
+      .output(Output.class)
+      .mutating(false)
+      .handler((input, ctx) -> new Output(input.greeting() + ", " + input.name() + "!"));
+
+  private Greet() {}
+}

package/dist/templates/java/src/test/java/__PACKAGE__/ToolsTest.java.tmpl

@@ -0,0 +1,30 @@
+package {{JAVA_PACKAGE}};
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertFalse;
+
+import {{JAVA_PACKAGE}}.tools.Echo;
+import {{JAVA_PACKAGE}}.tools.Greet;
+import com.kindgi.pack.ToolContext;
+import org.junit.jupiter.api.Test;
+
+/** The pack's tools, called directly — `./mvnw test`. */
+class ToolsTest {
+  @Test
+  void echoRoundTripsTheMessage() throws Exception {
+    Echo.Output out = Echo.TOOL.call(new Echo.Input("hello"), ToolContext.forTest());
+    assertEquals("hello", out.echo());
+    assertEquals(5, out.characterCount());
+  }
+
+  @Test
+  void greetUsesTheGreetingItIsGiven() throws Exception {
+    assertEquals("Hi, Ada!", Greet.TOOL.call(new Greet.Input("Ada", "Hi"), ToolContext.forTest()).message());
+  }
+
+  @Test
+  void theToolsSayTheyOnlyRead() {
+    assertFalse(Echo.TOOL.mutating());
+    assertFalse(Greet.TOOL.mutating());
+  }
+}