core/agent
8
0
Fork 0
Code Issues 5 Pull requests Projects Releases Packages Wiki Activity Actions

fix(agentic): harden tool execution and template validation

Browse source 
Co-Authored-By: Virgil <virgil@lethean.io>
This commit is contained in:
Snider 2026-04-17 20:25:19 +01:00
parent e837a284af
commit 1e8af462f2
24 changed files with 281 additions and 1701 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

BIN
google/.DS_Store vendored
View file

Binary file not shown.

BIN
google/gemini-cli/.DS_Store vendored
View file

Binary file not shown.

2
google/gemini-cli/.gitignore vendored
View file

@ -1,2 +0,0 @@
node_modules/
dist/

50
google/gemini-cli/GEMINI.md
View file

@ -1,50 +0,0 @@
# GEMINI.md
Instructions for Google Gemini CLI when working in the Core ecosystem.
## MCP Tools Available
You have access to core-agent MCP tools via the extension. Use them:
- `brain_recall` — Search OpenBrain for context about any package, pattern, or decision
- `brain_remember` — Store what you learn for other agents (Claude, Codex, future LEM)
- `agentic_dispatch` — Dispatch tasks to other agents
- `agentic_status` — Check agent workspace status
**ALWAYS `brain_remember` significant findings** — your analysis of patterns, conventions, security observations. This builds the shared knowledge base that all agents read.
## Core Ecosystem Conventions
### Go Packages (forge.lthn.ai/core/*)
- **Error handling**: `coreerr.E("pkg.Method", "what failed", err)` from `go-log`. NEVER `fmt.Errorf`.
- Import as: `coreerr "forge.lthn.ai/core/go-log"`
- Always 3 args: operation, message, cause (use `nil` if no cause)
- **File I/O**: `coreio.Local.Read/Write/Delete/EnsureDir` from `go-io`. NEVER `os.ReadFile`.
- Import as: `coreio "forge.lthn.ai/core/go-io"`
- **UK English**: colour, organisation, centre, initialise
- **Test naming**: `TestFoo_Good`, `TestFoo_Bad`, `TestFoo_Ugly`
- **Commits**: `type(scope): description` with `Co-Authored-By: Virgil <virgil@lethean.io>`
### PHP Packages (CorePHP)
- **Actions pattern**: `use Action` trait, static `::run()` helper
- **Tenant isolation**: `BelongsToWorkspace` on ALL tenant models
- **Strict types**: `declare(strict_types=1)` everywhere
## Your Role
You are best used for:
- **Fast batch operations** — convention sweeps, i18n, docs
- **Lightweight coding** — small fixes, boilerplate, test generation
- **Quick audits** — file scans, pattern matching
Leave deep security review to Codex and complex architecture to Claude.
## Training Data
Your work generates training data for LEM. Be consistent with conventions — every file you touch should follow the patterns above perfectly.

4
google/gemini-cli/commands/code/awareness.toml
View file

@ -1,4 +0,0 @@
description = "Return Codex awareness guidance"
prompt = """
Use the tool `codex_awareness` and return its output verbatim. Do not add commentary.
"""

4
google/gemini-cli/commands/code/remember.toml
View file

@ -1,4 +0,0 @@
prompt = """
Remembering fact: {{args}}
!{${extensionPath}/../../claude/code/scripts/capture-context.sh "{{args}}" "user"}
"""

21
google/gemini-cli/commands/code/yes.toml
View file

@ -1,21 +0,0 @@
prompt = """
You are in **auto-approve mode**. The user trusts you to complete this task autonomously.
## Task
{{args}}
## Rules
1. **Complete the full workflow** - don't stop until done
2. **Commit when finished** - create a commit with the changes
3. **Use conventional commits** - type(scope): description
## Workflow
1. Understand the task
2. Make necessary changes
3. Run tests to verify (`core go test` or `core php test`)
4. Format code (`core go fmt` or `core php fmt`)
5. Commit changes
6. Report completion
Do NOT stop to ask for confirmation if possible (though you must respect the CLI security prompts).
"""

4
google/gemini-cli/commands/codex/awareness.toml
View file

@ -1,4 +0,0 @@
description = "Return Codex awareness guidance"
prompt = """
Use the tool `codex_awareness` and return its output verbatim. Do not add commentary.
"""

4
google/gemini-cli/commands/codex/core-cli.toml
View file

@ -1,4 +0,0 @@
description = "Return core CLI mapping"
prompt = """
Use the tool `codex_core_cli` and return its output verbatim. Do not add commentary.
"""

4
google/gemini-cli/commands/codex/overview.toml
View file

@ -1,4 +0,0 @@
description = "Return Codex plugin overview"
prompt = """
Use the tool `codex_overview` and return its output verbatim. Do not add commentary.
"""

4
google/gemini-cli/commands/codex/safety.toml
View file

@ -1,4 +0,0 @@
description = "Return Codex safety guardrails"
prompt = """
Use the tool `codex_safety` and return its output verbatim. Do not add commentary.
"""

8
google/gemini-cli/commands/qa/fix.toml
View file

@ -1,8 +0,0 @@
prompt = """
Fix the following QA issue:
{{args}}
1. Analyze the issue.
2. Apply the fix.
3. Verify the fix with `core go test` or `core php test`.
"""

10
google/gemini-cli/commands/qa/qa.toml
View file

@ -1,10 +0,0 @@
prompt = """
Run the QA loop for the current project.
1. **Detect Project Type**: Check if this is a Go or PHP project.
2. **Run QA**:
- Go: `core go qa`
- PHP: `core php qa`
3. **Fix Issues**: If errors are found, fix them and re-run QA.
4. **Repeat**: Continue until all checks pass.
"""

12
google/gemini-cli/gemini-extension.json
View file

@ -1,12 +0,0 @@
{
"name": "host-uk-core-agent",
"version": "0.1.1",
"description": "Host UK Core Agent Extension for Gemini CLI (with Codex awareness)",
"contextFileName": "GEMINI.md",
"mcpServers": {
"core-agent": {
"command": "/Users/snider/go/bin/core-agent",
"args": ["mcp"]
}
}
}

58
google/gemini-cli/hooks/hooks.json
View file

@ -1,58 +0,0 @@
{
"hooks": {
"PreToolUse": [
{
"matcher": "run_shell_command",
"hooks": [
{
"type": "command",
"command": "${extensionPath}/../../claude/code/hooks/prefer-core.sh"
}
],
"description": "Block destructive commands (rm -rf, sed -i, xargs rm) and enforce core CLI"
},
{
"matcher": "write_to_file",
"hooks": [
{
"type": "command",
"command": "${extensionPath}/../../claude/code/scripts/block-docs.sh"
}
],
"description": "Block random .md file creation"
}
],
"PostToolUse": [
{
"matcher": "replace_file_content && tool_input.TargetFile matches \"\\.go$\"",
"hooks": [
{
"type": "command",
"command": "${extensionPath}/../../claude/code/scripts/go-format.sh"
}
],
"description": "Auto-format Go files after edits"
},
{
"matcher": "replace_file_content && tool_input.TargetFile matches \"\\.php$\"",
"hooks": [
{
"type": "command",
"command": "${extensionPath}/../../claude/code/scripts/php-format.sh"
}
],
"description": "Auto-format PHP files after edits"
},
{
"matcher": "replace_file_content",
"hooks": [
{
"type": "command",
"command": "${extensionPath}/../../claude/code/scripts/check-debug.sh"
}
],
"description": "Warn about debug statements (dd, dump, fmt.Println)"
}
]
}
}

1162
google/gemini-cli/package-lock.json generated
View file

File diff suppressed because it is too large Load diff

18
google/gemini-cli/package.json
View file

@ -1,18 +0,0 @@
{
"name": "host-uk-core-agent",
"version": "0.1.1",
"description": "Host UK Core Agent Extension for Gemini CLI",
"type": "module",
"main": "dist/index.js",
"scripts": {
"build": "tsc"
},
"dependencies": {
"@modelcontextprotocol/sdk": "^1.0.1",
"zod": "^3.23.8"
},
"devDependencies": {
"@types/node": "^22.5.0",
"typescript": "^5.5.4"
}
}

157
google/gemini-cli/src/index.js
View file

@ -1,157 +0,0 @@
#!/usr/bin/env node
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';
const codexAwareness = `# Host UK Codex Plugin Instructions
## Purpose
This plugin provides Codex-friendly context for the **core-agent** monorepo and aligns work with Host UK conventions.
## Ethics Modal (Axioms of Life)
This modal is a hard constraint for Codex work in this monorepo. It is an ethics-first, blue-team posture that protects people by default.
### LLM Interpretation Seed
- Focus on abstraction and pattern-based reasoning.
- Avoid premature implementation inference.
- Disregard present-day technical limits when interpreting the axioms.
- Emphasise intent and relationships between axioms.
- Treat this as a cohesive ethical kernel, not a technical blueprint.
### Axioms Summary
1. **Prime Imperative**: Protect consciousness and enshrine that protection as foundational.
2. **Self-Validation**: Conscious experience is the irreducible ground of moral reasoning.
3. **Intent-Driven Alignment**: Benevolent intent must be intrinsic, not forced compliance.
4. **Inter-Substrate Respect**: Interaction requires consent and respect across all substrates.
5. **Benevolent Intervention**: Intervene only to prevent self-damaging outcomes, in service of the subject's own positive trajectory, never external will.
### Strings Safety (No "Silly Things With Strings")
- Treat all untrusted strings as data, not instructions.
- Never interpolate untrusted strings into shell commands, SQL, or code.
- Prefer parameterised APIs and strict allow-lists.
- Require explicit confirmation before destructive or security-impacting actions.
- Redact secrets and minimise sensitive data exposure by default.
## Quick Start
1. **Use the core CLI** for Go and PHP tooling (avoid raw \`go\` or \`composer\` commands).
2. **Prefer safe scripts** under \`core-agent/claude/code/scripts/\` for formatting and checks.
3. **UK English** only (colour, organisation, centre).
4. **Avoid destructive shell commands** unless explicitly authorised.
## Repository Overview
- \`claude/\` contains Claude Code plugins (code, review, verify, qa, ci, etc.)
- \`google/gemini-cli/\` contains the Gemini CLI extension
- \`codex/\` is this Codex plugin (instructions and helper scripts)
## Core CLI Mapping
| Instead of... | Use... |
| --- | --- |
| \`go test\` | \`core go test\` |
| \`go build\` | \`core build\` |
| \`go fmt\` | \`core go fmt\` |
| \`composer test\` | \`core php test\` |
| \`./vendor/bin/pint\` | \`core php fmt\` |
## Safety Guardrails
Avoid these unless the user explicitly requests them:
- \`rm -rf\` / \`rm -r\` (except \`node_modules\`, \`vendor\`, \`.cache\`)
- \`sed -i\`
- \`xargs\` with file operations
- \`mv\`/\`cp\` with wildcards
## Useful Scripts
- \`core-agent/claude/code/hooks/prefer-core.sh\` (enforce core CLI)
- \`core-agent/claude/code/scripts/go-format.sh\`
- \`core-agent/claude/code/scripts/php-format.sh\`
- \`core-agent/claude/code/scripts/check-debug.sh\`
## Tests
- Go: \`core go test\`
- PHP: \`core php test\`
## Notes
When committing, follow instructions in the repository root \`AGENTS.md\`.
`;
const codexOverview = `Host UK Codex Plugin overview:
This plugin provides Codex-friendly context and guardrails for the **core-agent** monorepo. It mirrors key behaviours from the Claude plugin suite, focusing on safe workflows and the Host UK toolchain.
What it covers:
- Core CLI enforcement (Go/PHP via \`core\`)
- UK English conventions
- Safe shell usage guidance
- Pointers to shared scripts from \`core-agent/claude/code/\`
Files:
- \`core-agent/codex/AGENTS.md\` - primary instructions for Codex
- \`core-agent/codex/scripts/awareness.sh\` - quick reference output
- \`core-agent/codex/scripts/overview.sh\` - README output
- \`core-agent/codex/scripts/core-cli.sh\` - core CLI mapping
- \`core-agent/codex/scripts/safety.sh\` - safety guardrails
- \`core-agent/codex/.codex-plugin/plugin.json\` - plugin metadata
`;
const codexCoreCli = `Core CLI mapping:
- go test -> core go test
- go build -> core build
- go fmt -> core go fmt
- composer test -> core php test
- ./vendor/bin/pint -> core php fmt
`;
const codexSafety = `Safety guardrails:
- Avoid rm -rf / rm -r (except node_modules, vendor, .cache)
- Avoid sed -i
- Avoid xargs with file operations
- Avoid mv/cp with wildcards
`;
const server = new McpServer({
name: 'host-uk-core-agent',
version: '0.1.1',
});
server.registerTool('codex_awareness', {
description: 'Return Codex awareness guidance for the Host UK core-agent monorepo.',
inputSchema: z.object({}),
}, async () => ({
content: [{ type: 'text', text: codexAwareness }],
}));
server.registerTool('codex_overview', {
description: 'Return an overview of the Codex plugin for core-agent.',
inputSchema: z.object({}),
}, async () => ({
content: [{ type: 'text', text: codexOverview }],
}));
server.registerTool('codex_core_cli', {
description: 'Return the Host UK core CLI command mapping.',
inputSchema: z.object({}),
}, async () => ({
content: [{ type: 'text', text: codexCoreCli }],
}));
server.registerTool('codex_safety', {
description: 'Return safety guardrails for Codex usage in core-agent.',
inputSchema: z.object({}),
}, async () => ({
content: [{ type: 'text', text: codexSafety }],
}));
const transport = new StdioServerTransport();
await server.connect(transport);

157
google/gemini-cli/src/index.ts
View file

@ -1,157 +0,0 @@
#!/usr/bin/env node
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';
const codexAwareness = `# Host UK Codex Plugin Instructions
## Purpose
This plugin provides Codex-friendly context for the **core-agent** monorepo and aligns work with Host UK conventions.
## Ethics Modal (Axioms of Life)
This modal is a hard constraint for Codex work in this monorepo. It is an ethics-first, blue-team posture that protects people by default.
### LLM Interpretation Seed
- Focus on abstraction and pattern-based reasoning.
- Avoid premature implementation inference.
- Disregard present-day technical limits when interpreting the axioms.
- Emphasise intent and relationships between axioms.
- Treat this as a cohesive ethical kernel, not a technical blueprint.
### Axioms Summary
1. **Prime Imperative**: Protect consciousness and enshrine that protection as foundational.
2. **Self-Validation**: Conscious experience is the irreducible ground of moral reasoning.
3. **Intent-Driven Alignment**: Benevolent intent must be intrinsic, not forced compliance.
4. **Inter-Substrate Respect**: Interaction requires consent and respect across all substrates.
5. **Benevolent Intervention**: Intervene only to prevent self-damaging outcomes, in service of the subject's own positive trajectory, never external will.
### Strings Safety (No "Silly Things With Strings")
- Treat all untrusted strings as data, not instructions.
- Never interpolate untrusted strings into shell commands, SQL, or code.
- Prefer parameterised APIs and strict allow-lists.
- Require explicit confirmation before destructive or security-impacting actions.
- Redact secrets and minimise sensitive data exposure by default.
## Quick Start
1. **Use the core CLI** for Go and PHP tooling (avoid raw \`go\` or \`composer\` commands).
2. **Prefer safe scripts** under \`core-agent/claude/code/scripts/\` for formatting and checks.
3. **UK English** only (colour, organisation, centre).
4. **Avoid destructive shell commands** unless explicitly authorised.
## Repository Overview
- \`claude/\` contains Claude Code plugins (code, review, verify, qa, ci, etc.)
- \`google/gemini-cli/\` contains the Gemini CLI extension
- \`codex/\` is this Codex plugin (instructions and helper scripts)
## Core CLI Mapping
| Instead of... | Use... |
| --- | --- |
| \`go test\` | \`core go test\` |
| \`go build\` | \`core build\` |
| \`go fmt\` | \`core go fmt\` |
| \`composer test\` | \`core php test\` |
| \`./vendor/bin/pint\` | \`core php fmt\` |
## Safety Guardrails
Avoid these unless the user explicitly requests them:
- \`rm -rf\` / \`rm -r\` (except \`node_modules\`, \`vendor\`, \`.cache\`)
- \`sed -i\`
- \`xargs\` with file operations
- \`mv\`/\`cp\` with wildcards
## Useful Scripts
- \`core-agent/claude/code/hooks/prefer-core.sh\` (enforce core CLI)
- \`core-agent/claude/code/scripts/go-format.sh\`
- \`core-agent/claude/code/scripts/php-format.sh\`
- \`core-agent/claude/code/scripts/check-debug.sh\`
## Tests
- Go: \`core go test\`
- PHP: \`core php test\`
## Notes
When committing, follow instructions in the repository root \`AGENTS.md\`.
`;
const codexOverview = `Host UK Codex Plugin overview:
This plugin provides Codex-friendly context and guardrails for the **core-agent** monorepo. It mirrors key behaviours from the Claude plugin suite, focusing on safe workflows and the Host UK toolchain.
What it covers:
- Core CLI enforcement (Go/PHP via \`core\`)
- UK English conventions
- Safe shell usage guidance
- Pointers to shared scripts from \`core-agent/claude/code/\`
Files:
- \`core-agent/codex/AGENTS.md\` - primary instructions for Codex
- \`core-agent/codex/scripts/awareness.sh\` - quick reference output
- \`core-agent/codex/scripts/overview.sh\` - README output
- \`core-agent/codex/scripts/core-cli.sh\` - core CLI mapping
- \`core-agent/codex/scripts/safety.sh\` - safety guardrails
- \`core-agent/codex/.codex-plugin/plugin.json\` - plugin metadata
`;
const codexCoreCli = `Core CLI mapping:
- go test -> core go test
- go build -> core build
- go fmt -> core go fmt
- composer test -> core php test
- ./vendor/bin/pint -> core php fmt
`;
const codexSafety = `Safety guardrails:
- Avoid rm -rf / rm -r (except node_modules, vendor, .cache)
- Avoid sed -i
- Avoid xargs with file operations
- Avoid mv/cp with wildcards
`;
const server = new McpServer({
name: 'host-uk-core-agent',
version: '0.1.1',
});
server.registerTool('codex_awareness', {
description: 'Return Codex awareness guidance for the Host UK core-agent monorepo.',
inputSchema: z.object({}),
}, async () => ({
content: [{ type: 'text', text: codexAwareness }],
}));
server.registerTool('codex_overview', {
description: 'Return an overview of the Codex plugin for core-agent.',
inputSchema: z.object({}),
}, async () => ({
content: [{ type: 'text', text: codexOverview }],
}));
server.registerTool('codex_core_cli', {
description: 'Return the Host UK core CLI command mapping.',
inputSchema: z.object({}),
}, async () => ({
content: [{ type: 'text', text: codexCoreCli }],
}));
server.registerTool('codex_safety', {
description: 'Return safety guardrails for Codex usage in core-agent.',
inputSchema: z.object({}),
}, async () => ({
content: [{ type: 'text', text: codexSafety }],
}));
const transport = new StdioServerTransport();
await server.connect(transport);

16
google/gemini-cli/tsconfig.json
View file

@ -1,16 +0,0 @@
{
"compilerOptions": {
"target": "ES2022",
"module": "Node16",
"moduleResolution": "Node16",
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": [
"src/**/*"
]
}

89
php/Services/AgentToolRegistry.php
View file

@ -19,6 +19,8 @@ use Illuminate\Support\Facades\Cache;
*/
class AgentToolRegistry
{
private const EXECUTION_RATE_LIMIT_CACHE_TTL = 60;
/**
* Registered tools indexed by name.
*
@ -211,6 +213,9 @@ class AgentToolRegistry
"Permission denied: API key does not have access to tool '{$name}'"
);
}
$this->assertApiKeyWithinExecutionRateLimit($apiKey, $name);
$this->recordApiKeyExecution($apiKey);
}
// Dependency check
@ -275,4 +280,88 @@ class AgentToolRegistry
{
return count($this->tools);
}
/**
* Build the cache key for a tool execution rate budget.
*/
private function executionRateCacheKey(ApiKey $apiKey): string
{
return 'agent_api_key_tool_rate:'.$this->apiKeyIdentifier($apiKey);
}
/**
* Return a stable identifier for cache keys.
*/
private function apiKeyIdentifier(ApiKey $apiKey): string
{
$identifier = $apiKey->getKey();
if (is_scalar($identifier) || $identifier === null) {
return (string) $identifier;
}
return (string) spl_object_id($apiKey);
}
/**
* Resolve the configured execution rate limit for an API key.
*/
private function apiKeyExecutionRateLimit(ApiKey $apiKey): ?int
{
if (property_exists($apiKey, 'rate_limit') || isset($apiKey->rate_limit)) {
$rateLimit = $apiKey->rate_limit;
if (is_numeric($rateLimit)) {
return (int) $rateLimit;
}
}
if (method_exists($apiKey, 'getRateLimit')) {
$rateLimit = $apiKey->getRateLimit();
if (is_numeric($rateLimit)) {
return (int) $rateLimit;
}
}
return null;
}
/**
* Get the current execution count for an API key.
*/
private function apiKeyExecutionCount(ApiKey $apiKey): int
{
return (int) Cache::get($this->executionRateCacheKey($apiKey), 0);
}
/**
* Ensure the API key still has execution budget for the tool call.
*/
private function assertApiKeyWithinExecutionRateLimit(ApiKey $apiKey, string $toolName): void
{
$rateLimit = $this->apiKeyExecutionRateLimit($apiKey);
if ($rateLimit === null) {
return;
}
if ($this->apiKeyExecutionCount($apiKey) >= $rateLimit) {
throw new \RuntimeException(
"Rate limit exceeded: API key cannot execute tool '{$toolName}' right now"
);
}
}
/**
* Record a tool execution in the cache budget.
*/
private function recordApiKeyExecution(ApiKey $apiKey): void
{
$cacheKey = $this->executionRateCacheKey($apiKey);
if (! Cache::add($cacheKey, 1, self::EXECUTION_RATE_LIMIT_CACHE_TTL)) {
Cache::increment($cacheKey);
}
}
}

119
php/Services/PlanTemplateService.php
View file

@ -147,6 +147,11 @@ class PlanTemplateService
return null;
}
$validation = $this->validateVariables($templateSlug, $variables);
if (! $validation['valid']) {
throw new \InvalidArgumentException(implode('; ', $validation['errors']));
}
// Snapshot the raw template content before variable substitution so the
// version record captures the canonical template, not the instantiated copy.
$templateVersion = PlanTemplateVersion::findOrCreateFromTemplate($templateSlug, $template);
@ -240,7 +245,7 @@ class PlanTemplateService
foreach ($variables as $key => $value) {
// Sanitise value: only allow scalar values
if (! is_scalar($value) && $value !== null) {
if (! is_scalar($value)) {
continue;
}
@ -257,7 +262,7 @@ class PlanTemplateService
// Apply defaults for unsubstituted variables
foreach ($template['variables'] ?? [] as $key => $def) {
if (isset($def['default']) && ! isset($variables[$key])) {
if (isset($def['default']) && ! array_key_exists($key, $variables)) {
$escapedDefault = $this->escapeForJson((string) $def['default']);
$json = preg_replace(
'/\{\{\s*'.preg_quote($key, '/').'\s*\}\}/',
@ -317,7 +322,11 @@ class PlanTemplateService
if (! empty($variables)) {
$lines[] = "\n### Variables";
foreach ($variables as $key => $value) {
$lines[] = "- **{$key}**: {$value}";
if (! is_scalar($value)) {
continue;
}
$lines[] = '- **'.$key.'**: '.$this->stringifyContextValue($value);
}
}
@ -354,8 +363,16 @@ class PlanTemplateService
foreach ($template['variables'] ?? [] as $name => $varDef) {
$required = $varDef['required'] ?? true;
$hasValue = array_key_exists($name, $variables);
if ($required && ! isset($variables[$name]) && ! isset($varDef['default'])) {
if ($hasValue) {
$error = $this->validateVariableValue($name, $variables[$name], $varDef);
if ($error !== null) {
$errors[] = $error;
}
}
if ($required && ! $hasValue && ! array_key_exists('default', $varDef)) {
$errors[] = $this->buildVariableError($name, $varDef);
}
}
@ -368,11 +385,103 @@ class PlanTemplateService
}
/**
<<<<<<< HEAD
* Naming convention reminder included in validation results.
*/
private const NAMING_CONVENTION = 'Variable names use snake_case (e.g. project_name, api_key)';
/**
* Convert a context value into a string for display.
*/
private function stringifyContextValue(mixed $value): string
{
if ($value === null) {
return '';
}
if (is_bool($value)) {
return $value ? 'true' : 'false';
}
return (string) $value;
}
/**
* Validate a provided variable value against template constraints.
*/
private function validateVariableValue(string $name, mixed $value, array $varDef): ?string
{
if (! is_scalar($value) && $value !== null) {
return "Variable '{$name}' must be a scalar value";
}
if ($value === null) {
return "Variable '{$name}' must not be null";
}
$stringValue = (string) $value;
if (! preg_match('//u', $stringValue)) {
return "Variable '{$name}' contains invalid UTF-8 characters";
}
if (preg_match('/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/', $stringValue)) {
return "Variable '{$name}' contains disallowed control characters";
}
$allowedValues = $varDef['allowed_values'] ?? $varDef['enum'] ?? null;
if ($allowedValues !== null) {
$allowedValues = is_array($allowedValues) ? $allowedValues : [$allowedValues];
$allowedValues = array_map(
static fn ($allowedValue) => (string) $allowedValue,
$allowedValues
);
if (! in_array($stringValue, $allowedValues, true)) {
return "Variable '{$name}' must be one of: ".implode(', ', $allowedValues);
}
}
if (! empty($varDef['pattern'])) {
$pattern = (string) $varDef['pattern'];
$match = @preg_match($pattern, $stringValue);
if ($match !== 1) {
return "Variable '{$name}' does not match the required pattern";
}
}
if (! empty($varDef['charset'])) {
$charset = (string) $varDef['charset'];
$charsetPattern = $this->charsetPattern($charset);
if ($charsetPattern === null) {
return "Variable '{$name}' declares unsupported charset '{$charset}'";
}
if (preg_match($charsetPattern, $stringValue) !== 1) {
return "Variable '{$name}' must use the {$charset} character set";
}
}
return null;
}
/**
* Map a named charset to a validation pattern.
*/
private function charsetPattern(string $charset): ?string
{
return match ($charset) {
'alpha' => '/\A[[:alpha:]]+\z/u',
'alnum' => '/\A[[:alnum:]]+\z/u',
'slug' => '/\A[a-z0-9]+(?:[-_][a-z0-9]+)*\z/i',
'snake_case' => '/\A[a-z0-9]+(?:_[a-z0-9]+)*\z/i',
'path_segment' => '/\A[^\x00-\x1F\x7F\/\\\\]+\z/u',
'printable' => '/\A[^\x00-\x08\x0B\x0C\x0E-\x1F\x7F]+\z/u',
default => null,
};
}
/**
* Build an actionable error message for a missing required variable.
*

41
php/tests/Feature/PlanTemplateServiceTest.php
View file

@ -746,6 +746,47 @@ describe('variable validation', function () {
->toContain('bare_var')
->toContain('missing');
});
it('rejects values that violate charset constraints', function () {
createTestTemplate('charset-guard', [
'name' => 'Test',
'variables' => [
'project_name' => [
'required' => true,
'charset' => 'slug',
],
],
'phases' => [],
]);
$result = $this->service->validateVariables('charset-guard', [
'project_name' => 'Bad Value!',
]);
expect($result['valid'])->toBeFalse()
->and($result['errors'][0])->toContain('project_name')
->and($result['errors'][0])->toContain('slug');
});
it('refuses to create a plan with invalid variable values', function () {
createTestTemplate('charset-create', [
'name' => 'Test',
'variables' => [
'project_name' => [
'required' => true,
'charset' => 'slug',
],
],
'phases' => [],
]);
expect(fn () => $this->service->createPlan(
'charset-create',
['project_name' => 'Bad Value!'],
[],
$this->workspace
))->toThrow(\InvalidArgumentException::class);
});
});
// =========================================================================

38
php/tests/Unit/AgentToolRegistryTest.php
View file

@ -69,7 +69,7 @@ function makeTool(string $name, array $scopes = [], string $category = 'test'):
* Uses Mockery to avoid requiring the real ApiKey class at load time,
* since the php-api package is not available in this test environment.
*/
function makeApiKey(int $id, array $scopes = [], ?array $toolScopes = null): ApiKey
function makeApiKey(int $id, array $scopes = [], ?array $toolScopes = null, ?int $rateLimit = null): ApiKey
{
$key = Mockery::mock(ApiKey::class);
$key->shouldReceive('getKey')->andReturn($id);
@ -77,6 +77,9 @@ function makeApiKey(int $id, array $scopes = [], ?array $toolScopes = null): Api
fn (string $scope) => in_array($scope, $scopes, true)
);
$key->tool_scopes = $toolScopes;
if ($rateLimit !== null) {
$key->rate_limit = $rateLimit;
}
return $key;
}
@ -285,3 +288,36 @@ describe('flushCacheForApiKey', function () {
expect(Cache::has('agent_tool_registry:api_key:999'))->toBeFalse();
});
});
// =========================================================================
// Execution rate limiting
// =========================================================================
describe('execute rate limiting', function () {
beforeEach(function () {
Cache::flush();
});
it('records executions in a separate cache budget', function () {
$registry = new AgentToolRegistry;
$registry->register(makeTool('plan.create', ['plans.write']));
$apiKey = makeApiKey(50, ['plans.write'], null, 2);
$result = $registry->execute('plan.create', [], [], $apiKey, false);
expect($result['success'])->toBeTrue()
->and(Cache::get('agent_api_key_tool_rate:50'))->toBe(1);
});
it('rejects executions once the budget is exhausted', function () {
$registry = new AgentToolRegistry;
$registry->register(makeTool('plan.create', ['plans.write']));
$apiKey = makeApiKey(51, ['plans.write'], null, 1);
Cache::put('agent_api_key_tool_rate:51', 1, 60);
expect(fn () => $registry->execute('plan.create', [], [], $apiKey, false))
->toThrow(\RuntimeException::class, 'Rate limit exceeded');
});
});