@agentspec/cli 0.4.0 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/cli.js +754 -418
- package/dist/cli.js.map +1 -1
- package/package.json +16 -13
package/dist/cli.js
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
import { Command } from "commander";
|
|
5
5
|
import { readFileSync as readFileSync8 } from "fs";
|
|
6
6
|
import { fileURLToPath } from "url";
|
|
7
|
-
import { dirname as
|
|
7
|
+
import { dirname as dirname5, join as join7 } from "path";
|
|
8
8
|
|
|
9
9
|
// src/commands/validate.ts
|
|
10
10
|
import chalk2 from "chalk";
|
|
@@ -98,7 +98,7 @@ function formatCiGate(result) {
|
|
|
98
98
|
function registerValidateCommand(program2) {
|
|
99
99
|
program2.command("validate <file>").description("Validate an agent.yaml manifest against the schema (no I/O)").option("--json", "Output as JSON").action(async (file, opts) => {
|
|
100
100
|
try {
|
|
101
|
-
const { manifest } = loadManifest(file, { resolve: false });
|
|
101
|
+
const { manifest, warnings } = loadManifest(file, { resolve: false });
|
|
102
102
|
if (opts.json) {
|
|
103
103
|
console.log(
|
|
104
104
|
JSON.stringify(
|
|
@@ -106,7 +106,8 @@ function registerValidateCommand(program2) {
|
|
|
106
106
|
valid: true,
|
|
107
107
|
agentName: manifest.metadata.name,
|
|
108
108
|
version: manifest.metadata.version,
|
|
109
|
-
apiVersion: manifest.apiVersion
|
|
109
|
+
apiVersion: manifest.apiVersion,
|
|
110
|
+
warnings
|
|
110
111
|
},
|
|
111
112
|
null,
|
|
112
113
|
2
|
|
@@ -122,6 +123,7 @@ function registerValidateCommand(program2) {
|
|
|
122
123
|
console.log(chalk2.gray(` Tools : ${manifest.spec.tools?.length ?? 0}`));
|
|
123
124
|
console.log(chalk2.gray(` MCP : ${manifest.spec.mcp?.servers?.length ?? 0} servers`));
|
|
124
125
|
console.log(chalk2.gray(` Memory : ${manifest.spec.memory ? "configured" : "none"}`));
|
|
126
|
+
for (const warning of warnings) console.log(chalk2.yellow(` \u26A0 ${warning}`));
|
|
125
127
|
console.log();
|
|
126
128
|
} catch (err) {
|
|
127
129
|
if (opts.json) {
|
|
@@ -152,7 +154,176 @@ function registerValidateCommand(program2) {
|
|
|
152
154
|
import { existsSync, readFileSync } from "fs";
|
|
153
155
|
import { dirname, join, resolve } from "path";
|
|
154
156
|
import chalk3 from "chalk";
|
|
155
|
-
import { loadManifest as loadManifest2, runHealthCheck } from "@agentspec/sdk";
|
|
157
|
+
import { computeHealthStatus, loadManifest as loadManifest2, runHealthCheck } from "@agentspec/sdk";
|
|
158
|
+
|
|
159
|
+
// src/deploy/compose-health.ts
|
|
160
|
+
import { CONTRACT as CONTRACT2, gatewayEnvNames as gatewayEnvNames2, secretEnvName } from "@agentspec/sdk";
|
|
161
|
+
import * as yaml2 from "js-yaml";
|
|
162
|
+
|
|
163
|
+
// src/deploy/pod-patch.ts
|
|
164
|
+
import { CONTRACT, gatewayEnvNames } from "@agentspec/sdk";
|
|
165
|
+
import * as yaml from "js-yaml";
|
|
166
|
+
function providerBaseUrl(provider) {
|
|
167
|
+
const gateway = `http://${CONTRACT.podPatch.loopback}:${CONTRACT.ports.gateway}`;
|
|
168
|
+
return provider === "openai" ? `${gateway}/v1` : gateway;
|
|
169
|
+
}
|
|
170
|
+
var DNS_LABEL_RE = /^[a-z0-9][a-z0-9-]{0,61}[a-z0-9]$|^[a-z0-9]$/;
|
|
171
|
+
function assertPortFree(port) {
|
|
172
|
+
const { agentBind, controlPlane, gateway, gatewayStats, gatewayReadiness } = CONTRACT.ports;
|
|
173
|
+
const taken = [agentBind, controlPlane, gateway, gatewayStats, gatewayReadiness];
|
|
174
|
+
if (taken.includes(port)) {
|
|
175
|
+
throw new Error(
|
|
176
|
+
`spec.api.port ${port} collides with a port the pod patch reserves (${taken.join(", ")}). Choose another spec.api.port.`
|
|
177
|
+
);
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
function assertNameFree(name) {
|
|
181
|
+
const { podPatch } = CONTRACT;
|
|
182
|
+
const reserved = [podPatch.sidecarContainer, podPatch.gatewayContainer, podPatch.gatewayConfigInitContainer];
|
|
183
|
+
if (reserved.includes(name)) {
|
|
184
|
+
throw new Error(
|
|
185
|
+
`metadata.name "${name}" collides with a container the pod patch adds (${reserved.join(", ")}). Choose a different metadata.name.`
|
|
186
|
+
);
|
|
187
|
+
}
|
|
188
|
+
}
|
|
189
|
+
function contractOwnedEnv() {
|
|
190
|
+
const { env, providerBaseUrlEnv } = CONTRACT;
|
|
191
|
+
return [env.agentHost, env.agentPort, env.gatewayKey, ...Object.values(providerBaseUrlEnv)];
|
|
192
|
+
}
|
|
193
|
+
function collectEnvRefs(manifest) {
|
|
194
|
+
return collectRefs(manifest, /\$env:([A-Za-z0-9_]+)/g);
|
|
195
|
+
}
|
|
196
|
+
function collectSecretRefs(manifest) {
|
|
197
|
+
return collectRefs(manifest, /\$secret:([A-Za-z0-9_.-]+)/g);
|
|
198
|
+
}
|
|
199
|
+
function collectRefs(manifest, pattern) {
|
|
200
|
+
const names = [...JSON.stringify(manifest).matchAll(pattern)].map((m) => m[1]);
|
|
201
|
+
return [...new Set(names)].sort();
|
|
202
|
+
}
|
|
203
|
+
function planPodPatch(manifest) {
|
|
204
|
+
const name = manifest.metadata.name;
|
|
205
|
+
if (!DNS_LABEL_RE.test(name)) {
|
|
206
|
+
throw new Error(
|
|
207
|
+
`Invalid agent name "${name}" \u2014 metadata.name must be a lowercase DNS label (a-z, 0-9, hyphens, 1-63 chars)`
|
|
208
|
+
);
|
|
209
|
+
}
|
|
210
|
+
const port = manifest.spec.api?.port ?? CONTRACT.ports.agentDefault;
|
|
211
|
+
assertPortFree(port);
|
|
212
|
+
assertNameFree(name);
|
|
213
|
+
const gatewayEnv = gatewayEnvNames(manifest);
|
|
214
|
+
const envRefs = collectEnvRefs(manifest);
|
|
215
|
+
const ownedEnv = contractOwnedEnv();
|
|
216
|
+
const agentEnvRefs = envRefs.filter((v) => !gatewayEnv.includes(v) && !ownedEnv.includes(v));
|
|
217
|
+
const secretKeys = [.../* @__PURE__ */ new Set([...agentEnvRefs, ...gatewayEnv, CONTRACT.env.gatewayKey])].sort();
|
|
218
|
+
const configVars = {
|
|
219
|
+
AGENT_NAME: name,
|
|
220
|
+
MODEL_PROVIDER: manifest.spec.model.provider,
|
|
221
|
+
MODEL_ID: manifest.spec.model.id
|
|
222
|
+
};
|
|
223
|
+
const baseUrlEnv = Object.fromEntries(
|
|
224
|
+
Object.entries(CONTRACT.providerBaseUrlEnv).map(([provider, envName]) => [
|
|
225
|
+
envName,
|
|
226
|
+
providerBaseUrl(provider)
|
|
227
|
+
])
|
|
228
|
+
);
|
|
229
|
+
return { name, port, agentEnvRefs, gatewayEnv, secretKeys, configVars, agentImage: `${name}:latest`, baseUrlEnv };
|
|
230
|
+
}
|
|
231
|
+
function dumpManifest(manifest) {
|
|
232
|
+
return yaml.dump(manifest, { lineWidth: -1, noRefs: true });
|
|
233
|
+
}
|
|
234
|
+
function gatewayConfigRenderCommand() {
|
|
235
|
+
const { podPatch, paths } = CONTRACT;
|
|
236
|
+
return ["node", paths.sidecarEntrypoint, podPatch.gatewayConfigCommand, paths.manifestFile, "--out", paths.gatewayConfigFile];
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
// src/deploy/compose-health.ts
|
|
240
|
+
var pass = (id) => ({ id, category: "env", status: "pass", severity: "error" });
|
|
241
|
+
var fail = (id, message, remediation) => ({
|
|
242
|
+
id,
|
|
243
|
+
category: "env",
|
|
244
|
+
status: "fail",
|
|
245
|
+
severity: "error",
|
|
246
|
+
message,
|
|
247
|
+
remediation
|
|
248
|
+
});
|
|
249
|
+
function checkCompose(manifest, composeText) {
|
|
250
|
+
const service = findAgentService(manifest.metadata.name, composeText);
|
|
251
|
+
if (!service) {
|
|
252
|
+
return [
|
|
253
|
+
fail(
|
|
254
|
+
"compose:service",
|
|
255
|
+
`No service "${manifest.metadata.name}" in the compose file`,
|
|
256
|
+
`Name the agent service after metadata.name ("${manifest.metadata.name}"), as 'agentspec generate --deploy compose' does.`
|
|
257
|
+
)
|
|
258
|
+
];
|
|
259
|
+
}
|
|
260
|
+
const env = serviceEnv(service);
|
|
261
|
+
return [
|
|
262
|
+
...checkDeclaredEnv(manifest, service, env),
|
|
263
|
+
...checkSecrets(manifest, service, env),
|
|
264
|
+
...checkProviderKeys(manifest, service, env)
|
|
265
|
+
];
|
|
266
|
+
}
|
|
267
|
+
function findAgentService(name, composeText) {
|
|
268
|
+
let project;
|
|
269
|
+
try {
|
|
270
|
+
project = yaml2.load(composeText);
|
|
271
|
+
} catch (err) {
|
|
272
|
+
const { line, column } = err.mark ?? {};
|
|
273
|
+
throw new Error(`Compose file is not valid YAML (line ${(line ?? 0) + 1}, column ${(column ?? 0) + 1}).`);
|
|
274
|
+
}
|
|
275
|
+
if (!project || typeof project !== "object" || !project.services) {
|
|
276
|
+
throw new Error('Not a compose file: expected a top-level "services" map. Pass the docker-compose.yaml of the agent.');
|
|
277
|
+
}
|
|
278
|
+
if (!(name in project.services)) return void 0;
|
|
279
|
+
return project.services[name] ?? {};
|
|
280
|
+
}
|
|
281
|
+
function serviceEnv({ environment }) {
|
|
282
|
+
const env = { set: /* @__PURE__ */ new Set(), passThrough: /* @__PURE__ */ new Set() };
|
|
283
|
+
const entries = Array.isArray(environment) ? environment.map((entry) => [entry.split("=")[0], entry.includes("=")]) : Object.entries(environment ?? {}).map(([name, value]) => [name, value != null]);
|
|
284
|
+
for (const [name, hasValue] of entries) (hasValue ? env.set : env.passThrough).add(name);
|
|
285
|
+
return env;
|
|
286
|
+
}
|
|
287
|
+
function hasEnvFile({ env_file }) {
|
|
288
|
+
return Array.isArray(env_file) ? env_file.length > 0 : Boolean(env_file);
|
|
289
|
+
}
|
|
290
|
+
function checkEnvVar(id, name, declared, service, env) {
|
|
291
|
+
if (env.set.has(name)) return pass(id);
|
|
292
|
+
const missing = fail(id, `${declared} is declared but the agent service does not set ${name}`, `Add ${name} to the agent service's environment.`);
|
|
293
|
+
if (env.passThrough.has(name)) {
|
|
294
|
+
return { ...missing, status: "warn", message: `${missing.message} (it is taken from compose's own environment, which is not checked)` };
|
|
295
|
+
}
|
|
296
|
+
return hasEnvFile(service) ? { ...missing, status: "warn", message: `${missing.message}; it may come from env_file` } : missing;
|
|
297
|
+
}
|
|
298
|
+
function checkDeclaredEnv(manifest, service, env) {
|
|
299
|
+
return planPodPatch(manifest).agentEnvRefs.map((v) => checkEnvVar(`env:${v}`, v, `$env:${v}`, service, env));
|
|
300
|
+
}
|
|
301
|
+
function checkSecrets(manifest, service, env) {
|
|
302
|
+
const modelSecrets = new Set(modelSecretNames(manifest));
|
|
303
|
+
return collectSecretRefs(manifest).filter((name) => !modelSecrets.has(name)).map((name) => checkEnvVar(`secret:${name}`, secretEnvName(name), `$secret:${name}`, service, env));
|
|
304
|
+
}
|
|
305
|
+
function modelSecretNames({ spec: { model } }) {
|
|
306
|
+
return [model.apiKey, model.fallback?.apiKey].flatMap((key) => key?.startsWith("$secret:") ? [key.slice("$secret:".length)] : []);
|
|
307
|
+
}
|
|
308
|
+
function checkProviderKeys(manifest, service, env) {
|
|
309
|
+
const onService = (v) => env.set.has(v) || env.passThrough.has(v);
|
|
310
|
+
const envKeys = gatewayEnvNames2(manifest).filter((v) => onService(v) && !isClientRouting(manifest, v));
|
|
311
|
+
const mounted = new Set((service.secrets ?? []).map((s) => typeof s === "string" ? s : s.source));
|
|
312
|
+
const secretKeys = modelSecretNames(manifest).filter((name) => mounted.has(name));
|
|
313
|
+
return [...envKeys, ...secretKeys].map(
|
|
314
|
+
(v) => fail(
|
|
315
|
+
`key-custody:${v}`,
|
|
316
|
+
`${v} is a provider key (or gateway setting) and must not be on the agent service`,
|
|
317
|
+
`Move ${v} to the gateway service; the agent calls the gateway with its virtual key (ADR-0019).`
|
|
318
|
+
)
|
|
319
|
+
);
|
|
320
|
+
}
|
|
321
|
+
function isClientRouting({ spec: { model } }, name) {
|
|
322
|
+
const keyEnvs = [model.apiKey, model.fallback?.apiKey].map((key) => key?.replace(/^\$env:/, ""));
|
|
323
|
+
return Object.values(CONTRACT2.providerBaseUrlEnv).includes(name) && !keyEnvs.includes(name);
|
|
324
|
+
}
|
|
325
|
+
|
|
326
|
+
// src/commands/health.ts
|
|
156
327
|
function loadDotEnv(envPath) {
|
|
157
328
|
let raw;
|
|
158
329
|
try {
|
|
@@ -173,7 +344,7 @@ function loadDotEnv(envPath) {
|
|
|
173
344
|
}
|
|
174
345
|
}
|
|
175
346
|
function registerHealthCommand(program2) {
|
|
176
|
-
program2.command("health <file>").description("Run runtime health checks against all declared dependencies").option("--json", "Output as JSON").option("--format <fmt>", "Output format: table|json", "table").option("--fail-on <level>", "Exit 1 on: error|warning|info", "error").option("--no-model", "Skip model API reachability checks").option("--no-mcp", "Skip MCP server checks").option("--no-memory", "Skip memory backend checks").option("--env-file <path>", "Load env vars from a .env file before running checks").action(
|
|
347
|
+
program2.command("health <file>").description("Run runtime health checks against all declared dependencies").option("--json", "Output as JSON").option("--format <fmt>", "Output format: table|json", "table").option("--fail-on <level>", "Exit 1 on: error|warning|info", "error").option("--no-model", "Skip model API reachability checks").option("--no-mcp", "Skip MCP server checks").option("--no-memory", "Skip memory backend checks").option("--compose <file>", "Check the agent service of a compose file instead of the local environment").option("--env-file <path>", "Load env vars from a .env file before running checks").action(
|
|
177
348
|
async (file, opts) => {
|
|
178
349
|
const manifestDir = dirname(resolve(file));
|
|
179
350
|
const envFilePath = opts.envFile ? resolve(opts.envFile) : join(manifestDir, ".env");
|
|
@@ -187,7 +358,7 @@ function registerHealthCommand(program2) {
|
|
|
187
358
|
printError(`Cannot load manifest: ${String(err)}`);
|
|
188
359
|
process.exit(1);
|
|
189
360
|
}
|
|
190
|
-
const report = await runHealthCheck(manifest.manifest, {
|
|
361
|
+
const report = opts.compose ? composeReport(manifest.manifest, opts.compose) : await runHealthCheck(manifest.manifest, {
|
|
191
362
|
checkModel: opts.model !== false,
|
|
192
363
|
checkMcp: opts.mcp !== false,
|
|
193
364
|
checkMemory: opts.memory !== false,
|
|
@@ -229,6 +400,16 @@ function registerHealthCommand(program2) {
|
|
|
229
400
|
}
|
|
230
401
|
);
|
|
231
402
|
}
|
|
403
|
+
function composeReport(manifest, composeFile) {
|
|
404
|
+
let checks;
|
|
405
|
+
try {
|
|
406
|
+
checks = checkCompose(manifest, readFileSync(resolve(composeFile), "utf-8"));
|
|
407
|
+
} catch (err) {
|
|
408
|
+
printError(`Cannot check compose file: ${err instanceof Error ? err.message : String(err)}`);
|
|
409
|
+
process.exit(1);
|
|
410
|
+
}
|
|
411
|
+
return { agentName: manifest.metadata.name, timestamp: (/* @__PURE__ */ new Date()).toISOString(), ...computeHealthStatus(checks), checks };
|
|
412
|
+
}
|
|
232
413
|
function groupByCategory(checks) {
|
|
233
414
|
const groups = {};
|
|
234
415
|
for (const check of checks) {
|
|
@@ -249,10 +430,16 @@ function shouldFail(checks, failOn) {
|
|
|
249
430
|
// src/commands/audit.ts
|
|
250
431
|
import { writeFileSync } from "fs";
|
|
251
432
|
import chalk4 from "chalk";
|
|
252
|
-
import { loadManifest as loadManifest3, runAudit,
|
|
433
|
+
import { CONTRACT as CONTRACT3, COMPLIANCE_PACKS, loadManifest as loadManifest3, runAudit, formatVerified, TrustPolicy } from "@agentspec/sdk";
|
|
253
434
|
function registerAuditCommand(program2) {
|
|
254
|
-
program2.command("audit <file>").description("Run compliance audit against configured packs").option("--pack <pack>", "Run a specific compliance pack only").option("--url <url>",
|
|
435
|
+
program2.command("audit <file>").description("Run compliance audit against configured packs").option("--pack <pack>", "Run a specific compliance pack only").option("--url <url>", `Accepted for compatibility; makes no request (audit is offline). Read live evidence from the sidecar ${CONTRACT3.sidecarPaths.gap}`).option("--trust <policy>", "Trust policy for the verified score: standard | strict", "standard").option("--json", "Output as JSON").option("--output <file>", "Write report to file").option("--fail-below <score>", "Exit 1 if score is below this threshold", "0").action(
|
|
255
436
|
async (file, opts) => {
|
|
437
|
+
if (opts.pack !== void 0 && !COMPLIANCE_PACKS.includes(opts.pack)) {
|
|
438
|
+
printError(`Unknown --pack "${opts.pack}". Valid packs: ${COMPLIANCE_PACKS.join(", ")}`);
|
|
439
|
+
process.exit(1);
|
|
440
|
+
}
|
|
441
|
+
const threshold = parseFailBelow(opts.failBelow);
|
|
442
|
+
const trust = parseTrust(opts.trust);
|
|
256
443
|
let parsed;
|
|
257
444
|
try {
|
|
258
445
|
parsed = loadManifest3(file, { resolve: false });
|
|
@@ -261,9 +448,8 @@ function registerAuditCommand(program2) {
|
|
|
261
448
|
process.exit(1);
|
|
262
449
|
}
|
|
263
450
|
const { manifest } = parsed;
|
|
264
|
-
const packs = opts.pack ? [opts.pack] : void 0;
|
|
265
|
-
const
|
|
266
|
-
const report = runAudit(manifest, { packs, proofRecords });
|
|
451
|
+
const packs = opts.pack !== void 0 ? [opts.pack] : void 0;
|
|
452
|
+
const report = runAudit(manifest, { packs, trust });
|
|
267
453
|
const outputJson = JSON.stringify(report, null, 2);
|
|
268
454
|
if (opts.output) {
|
|
269
455
|
writeFileSync(opts.output, outputJson, "utf-8");
|
|
@@ -271,12 +457,11 @@ function registerAuditCommand(program2) {
|
|
|
271
457
|
}
|
|
272
458
|
if (opts.json) {
|
|
273
459
|
console.log(outputJson);
|
|
274
|
-
|
|
275
|
-
if (report.overallScore < threshold2) process.exit(1);
|
|
460
|
+
if (report.overallScore < threshold) process.exit(1);
|
|
276
461
|
return;
|
|
277
462
|
}
|
|
278
463
|
printHeader(`AgentSpec Audit \u2014 ${manifest.metadata.name}`);
|
|
279
|
-
printScoreSummary(report
|
|
464
|
+
printScoreSummary(report);
|
|
280
465
|
console.log(
|
|
281
466
|
` Rules : ${chalk4.green(report.passedRules)} passed / ${chalk4.red(report.totalRules - report.passedRules)} failed / ${report.totalRules} total`
|
|
282
467
|
);
|
|
@@ -288,11 +473,8 @@ function registerAuditCommand(program2) {
|
|
|
288
473
|
console.log(` ${chalk4.gray(cat.padEnd(24))} ${color(String(score).padStart(3))}% ${bar}`);
|
|
289
474
|
}
|
|
290
475
|
console.log();
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
} else {
|
|
294
|
-
renderViolations(report.violations);
|
|
295
|
-
}
|
|
476
|
+
renderViolations(report.violations);
|
|
477
|
+
renderUnverified(report.verified.unverified);
|
|
296
478
|
if (report.suppressions.length > 0) {
|
|
297
479
|
console.log();
|
|
298
480
|
console.log(chalk4.bold(` Suppressions (${report.suppressions.length})`));
|
|
@@ -301,10 +483,10 @@ function registerAuditCommand(program2) {
|
|
|
301
483
|
}
|
|
302
484
|
}
|
|
303
485
|
if (report.evidenceBreakdown) {
|
|
304
|
-
formatEvidenceBreakdown(report.evidenceBreakdown
|
|
486
|
+
formatEvidenceBreakdown(report.evidenceBreakdown);
|
|
487
|
+
printSidecarAbsent();
|
|
305
488
|
}
|
|
306
489
|
console.log();
|
|
307
|
-
const threshold = parseInt(opts.failBelow ?? "0", 10);
|
|
308
490
|
if (report.overallScore < threshold) {
|
|
309
491
|
console.error(chalk4.red(` \u2717 Score ${report.overallScore} is below threshold ${threshold}`));
|
|
310
492
|
process.exit(1);
|
|
@@ -312,73 +494,48 @@ function registerAuditCommand(program2) {
|
|
|
312
494
|
}
|
|
313
495
|
);
|
|
314
496
|
}
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
printError(
|
|
497
|
+
function parseFailBelow(raw) {
|
|
498
|
+
const text2 = (raw ?? "0").trim().replace(/%$/, "");
|
|
499
|
+
const value = /^\d+(\.\d+)?$/.test(text2) ? Number(text2) : NaN;
|
|
500
|
+
if (!Number.isFinite(value) || value > 100) {
|
|
501
|
+
printError(`--fail-below must be a number between 0 and 100, got "${raw}"`);
|
|
320
502
|
process.exit(1);
|
|
321
503
|
}
|
|
322
|
-
|
|
323
|
-
const proofUrl = `${url.replace(/\/$/, "")}/proof`;
|
|
324
|
-
const res = await fetch(proofUrl, {
|
|
325
|
-
headers: { Accept: "application/json" },
|
|
326
|
-
signal: AbortSignal.timeout(5e3)
|
|
327
|
-
});
|
|
328
|
-
if (res.ok) {
|
|
329
|
-
const data = await res.json();
|
|
330
|
-
if (!Array.isArray(data)) {
|
|
331
|
-
process.stderr.write(
|
|
332
|
-
chalk4.yellow(` \u26A0 Unexpected proof response from ${proofUrl} \u2014 expected array, got ${typeof data}
|
|
333
|
-
`)
|
|
334
|
-
);
|
|
335
|
-
} else {
|
|
336
|
-
return data.filter(isProofRecord);
|
|
337
|
-
}
|
|
338
|
-
} else {
|
|
339
|
-
process.stderr.write(
|
|
340
|
-
chalk4.yellow(` \u26A0 Could not fetch proof records from ${proofUrl} (${res.status}) \u2014 showing declared score only
|
|
341
|
-
`)
|
|
342
|
-
);
|
|
343
|
-
}
|
|
344
|
-
} catch {
|
|
345
|
-
process.stderr.write(
|
|
346
|
-
chalk4.yellow(` \u26A0 Could not reach sidecar at ${url} \u2014 showing declared score only
|
|
347
|
-
`)
|
|
348
|
-
);
|
|
349
|
-
}
|
|
350
|
-
return void 0;
|
|
504
|
+
return value;
|
|
351
505
|
}
|
|
352
|
-
function
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
);
|
|
357
|
-
console.log(
|
|
358
|
-
` Proved score : ${formatGrade(report.provedGrade)} ${chalk4.bold(String(report.provedScore))}/100 \u2014 what has been verified`
|
|
359
|
-
);
|
|
360
|
-
console.log(
|
|
361
|
-
` Pending proof : ${chalk4.yellow(String(report.pendingProofCount))} rules \u2014 run external tools and POST to ${sidecarUrl}/proof/rule/:ruleId`
|
|
362
|
-
);
|
|
363
|
-
} else {
|
|
364
|
-
console.log(
|
|
365
|
-
` Score : ${formatGrade(report.grade)} ${chalk4.bold(String(report.overallScore))}/100`
|
|
366
|
-
);
|
|
506
|
+
function parseTrust(raw) {
|
|
507
|
+
const parsed = TrustPolicy.safeParse(raw);
|
|
508
|
+
if (!parsed.success) {
|
|
509
|
+
printError(`--trust must be standard or strict, got "${raw}"`);
|
|
510
|
+
process.exit(1);
|
|
367
511
|
}
|
|
512
|
+
return parsed.data;
|
|
368
513
|
}
|
|
369
|
-
function
|
|
370
|
-
|
|
514
|
+
function printScoreSummary(report) {
|
|
515
|
+
console.log(
|
|
516
|
+
` Declared score : ${formatGrade(report.grade)} ${chalk4.bold(String(report.overallScore))}/100 \u2014 what your spec says`
|
|
517
|
+
);
|
|
518
|
+
console.log(` Verified : ${chalk4.bold(formatVerified(report.verified))} \u2014 what evidence proves`);
|
|
519
|
+
}
|
|
520
|
+
var EVIDENCE_CLASS_ROWS = {
|
|
521
|
+
independent: { badge: "[I]", label: "Independent", note: "(gateway, sidecar, operator)", color: chalk4.blue },
|
|
522
|
+
"evidence-point": { badge: "[E]", label: "Evidence point", note: "(SDK calls your agent code wires)", color: chalk4.magenta },
|
|
523
|
+
offline: { badge: "[O]", label: "Offline", note: "(agent.lock review)", color: chalk4.yellow },
|
|
524
|
+
declared: { badge: "[D]", label: "Declared", note: "(manifest declarations)", color: chalk4.gray }
|
|
525
|
+
};
|
|
526
|
+
function formatEvidenceBreakdown(breakdown) {
|
|
371
527
|
console.log();
|
|
372
528
|
console.log(chalk4.bold(" Evidence Breakdown"));
|
|
373
|
-
const
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
console.log(
|
|
529
|
+
for (const cls of Object.keys(EVIDENCE_CLASS_ROWS)) {
|
|
530
|
+
const { badge, label, note, color } = EVIDENCE_CLASS_ROWS[cls];
|
|
531
|
+
const { passed, total } = breakdown[cls];
|
|
532
|
+
const count = total > 0 ? `${passed}/${total}` : "N/A";
|
|
533
|
+
console.log(` ${color(badge)} ${label.padEnd(14)} ${chalk4.cyan(count)} ${note}`);
|
|
534
|
+
}
|
|
535
|
+
}
|
|
536
|
+
function printSidecarAbsent() {
|
|
537
|
+
console.log();
|
|
538
|
+
console.log(chalk4.yellow(` \u26A0 sidecar absent: not verifiable \u2014 rules that need an independent or evidence-point source cannot be proved by an offline audit; read the sidecar's ${CONTRACT3.sidecarPaths.gap}`));
|
|
382
539
|
}
|
|
383
540
|
function progressBar(score) {
|
|
384
541
|
const width = 20;
|
|
@@ -386,34 +543,16 @@ function progressBar(score) {
|
|
|
386
543
|
const bar = "\u2588".repeat(filled) + "\u2591".repeat(width - filled);
|
|
387
544
|
return scoreColor(score)(bar);
|
|
388
545
|
}
|
|
389
|
-
function
|
|
390
|
-
|
|
391
|
-
case "declarative":
|
|
392
|
-
return chalk4.gray("[D]");
|
|
393
|
-
case "probed":
|
|
394
|
-
return chalk4.blue("[P]");
|
|
395
|
-
case "behavioral":
|
|
396
|
-
return chalk4.magenta("[B]");
|
|
397
|
-
case "external":
|
|
398
|
-
return chalk4.yellow("[X]");
|
|
399
|
-
default:
|
|
400
|
-
return chalk4.gray("[D]");
|
|
401
|
-
}
|
|
546
|
+
function evidenceBadges(classes) {
|
|
547
|
+
return classes.map((c) => EVIDENCE_CLASS_ROWS[c].color(EVIDENCE_CLASS_ROWS[c].badge)).join("");
|
|
402
548
|
}
|
|
403
|
-
function renderViolationDetail(v, badge
|
|
549
|
+
function renderViolationDetail(v, badge) {
|
|
404
550
|
console.log(`
|
|
405
551
|
${formatSeverity(v.severity)} ${badge} ${chalk4.bold(v.ruleId)} \u2014 ${chalk4.white(v.title)}`);
|
|
406
552
|
console.log(` ${chalk4.gray(v.message)}`);
|
|
407
553
|
if (v.path) console.log(` Path: ${chalk4.cyan(v.path)}`);
|
|
408
554
|
if (v.recommendation) console.log(` ${chalk4.cyan("\u2192")} ${v.recommendation}`);
|
|
409
|
-
if (v.proofTool) {
|
|
410
|
-
if (sidecarUrl) {
|
|
411
|
-
const endpoint = `POST ${sidecarUrl.replace(/\/$/, "")}/proof/rule/${v.ruleId}`;
|
|
412
|
-
console.log(` ${chalk4.yellow("\u2192 Prove:")} ${v.proofTool} \u2192 ${chalk4.cyan(endpoint)}`);
|
|
413
|
-
} else {
|
|
414
|
-
console.log(` ${chalk4.yellow("\u2192 Prove:")} ${v.proofTool}`);
|
|
415
|
-
}
|
|
416
|
-
}
|
|
555
|
+
if (v.proofTool) console.log(` ${chalk4.yellow("\u2192 Prove:")} ${v.proofTool}`);
|
|
417
556
|
if (v.proofToolUrl) console.log(` ${chalk4.blue(v.proofToolUrl)}`);
|
|
418
557
|
if (v.references?.length) {
|
|
419
558
|
for (const ref of v.references) console.log(` ${chalk4.blue(ref)}`);
|
|
@@ -425,43 +564,98 @@ function renderViolations(violations) {
|
|
|
425
564
|
return;
|
|
426
565
|
}
|
|
427
566
|
console.log(chalk4.bold(` Violations (${violations.length})`));
|
|
428
|
-
for (const v of violations) renderViolationDetail(v,
|
|
567
|
+
for (const v of violations) renderViolationDetail(v, evidenceBadges(v.evidenceClasses));
|
|
429
568
|
}
|
|
430
|
-
function
|
|
431
|
-
if (
|
|
432
|
-
|
|
433
|
-
|
|
569
|
+
function renderUnverified(unverified) {
|
|
570
|
+
if (unverified.length === 0) return;
|
|
571
|
+
console.log();
|
|
572
|
+
console.log(chalk4.bold(` Unverified (${unverified.length})`));
|
|
573
|
+
for (const u of unverified) {
|
|
574
|
+
console.log(` ${chalk4.gray("\u2013")} ${u.ruleId} ${chalk4.gray(`(${u.severity})`)}: ${u.reason.code}`);
|
|
575
|
+
}
|
|
576
|
+
}
|
|
577
|
+
|
|
578
|
+
// src/commands/register.ts
|
|
579
|
+
import chalk5 from "chalk";
|
|
580
|
+
import * as yaml3 from "js-yaml";
|
|
581
|
+
import { CONTRACT as CONTRACT4, declaredManifestSha256, loadManifest as loadManifest4, runAudit as runAudit2 } from "@agentspec/sdk";
|
|
582
|
+
var REQUEST_TIMEOUT_MS = 3e4;
|
|
583
|
+
function registerRegisterCommand(program2) {
|
|
584
|
+
program2.command("register <file>").description(`Send the declared audit report to the control plane (PUT ${CONTRACT4.controlPlanePaths.declaredAudit})`).requiredOption("--control-plane <url>", "Control plane URL (e.g. https://agentspec.example.com)").option("--agent-name <name>", "Registered agent name (defaults to metadata.name)").option("--api-key <jwt>", `Agent JWT from POST /api/v1/register (defaults to $${CONTRACT4.env.agentKey})`).action(async (file, opts) => {
|
|
585
|
+
const apiKey = resolveApiKey(opts.apiKey);
|
|
586
|
+
const { manifest, declared, raw } = loadDeclaredManifest(file);
|
|
587
|
+
const agentName = opts.agentName ?? manifest.metadata.name;
|
|
588
|
+
const report = runAudit2(manifest);
|
|
589
|
+
await putDeclaredAudit(opts.controlPlane, agentName, apiKey, {
|
|
590
|
+
manifest: declared,
|
|
591
|
+
manifestSha256: declaredManifestSha256(raw),
|
|
592
|
+
report
|
|
593
|
+
});
|
|
594
|
+
console.log(chalk5.green(` \u2713 Declared report for ${agentName} sent (score ${report.overallScore}, grade ${report.grade})`));
|
|
595
|
+
});
|
|
596
|
+
}
|
|
597
|
+
function resolveApiKey(flag) {
|
|
598
|
+
const apiKey = flag ?? process.env[CONTRACT4.env.agentKey];
|
|
599
|
+
if (!apiKey) {
|
|
600
|
+
printError(`No agent token. Set ${CONTRACT4.env.agentKey} or pass --api-key with the key from POST /api/v1/register.`);
|
|
601
|
+
process.exit(1);
|
|
434
602
|
}
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
603
|
+
return apiKey;
|
|
604
|
+
}
|
|
605
|
+
function loadDeclaredManifest(file) {
|
|
606
|
+
try {
|
|
607
|
+
const { manifest, raw } = loadManifest4(file, { resolve: false });
|
|
608
|
+
return { manifest, declared: yaml3.load(raw, { schema: yaml3.JSON_SCHEMA }), raw };
|
|
609
|
+
} catch (err) {
|
|
610
|
+
printError(`Cannot load manifest: ${String(err)}`);
|
|
611
|
+
process.exit(1);
|
|
440
612
|
}
|
|
441
|
-
|
|
442
|
-
|
|
443
|
-
|
|
444
|
-
|
|
613
|
+
}
|
|
614
|
+
async function putDeclaredAudit(controlPlane, agentName, apiKey, payload) {
|
|
615
|
+
const route = CONTRACT4.controlPlanePaths.declaredAudit.replace("{name}", encodeURIComponent(agentName));
|
|
616
|
+
let res;
|
|
617
|
+
try {
|
|
618
|
+
res = await fetch(`${controlPlane.replace(/\/+$/, "")}${route}`, {
|
|
619
|
+
method: "PUT",
|
|
620
|
+
headers: { "content-type": "application/json", authorization: `Bearer ${apiKey}` },
|
|
621
|
+
body: JSON.stringify(payload),
|
|
622
|
+
signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS)
|
|
623
|
+
});
|
|
624
|
+
} catch (err) {
|
|
625
|
+
printError(`Cannot reach the control plane at ${controlPlane}: ${String(err)}. Check --control-plane and that it is running.`);
|
|
626
|
+
process.exit(1);
|
|
445
627
|
}
|
|
446
|
-
if (
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
628
|
+
if (!res.ok) {
|
|
629
|
+
printError(`Control plane rejected the declared report (${res.status}): ${await rejectionReason(res)}${authHint(res.status)}`);
|
|
630
|
+
process.exit(1);
|
|
631
|
+
}
|
|
632
|
+
}
|
|
633
|
+
function authHint(status) {
|
|
634
|
+
if (status === 401) return `. Check the agent token: it may be expired or rotated; get a new one from POST /api/v1/register.`;
|
|
635
|
+
if (status === 403) return `. The token is for another agent: pass --agent-name matching the token's agent.`;
|
|
636
|
+
return "";
|
|
637
|
+
}
|
|
638
|
+
async function rejectionReason(res) {
|
|
639
|
+
const text2 = await res.text();
|
|
640
|
+
try {
|
|
641
|
+
const detail = JSON.parse(text2).detail;
|
|
642
|
+
return typeof detail === "string" ? detail : text2;
|
|
643
|
+
} catch {
|
|
644
|
+
return text2;
|
|
451
645
|
}
|
|
452
646
|
}
|
|
453
647
|
|
|
454
648
|
// src/commands/init.ts
|
|
455
649
|
import { writeFileSync as writeFileSync2, existsSync as existsSync2, mkdirSync } from "fs";
|
|
456
650
|
import { resolve as resolve2, join as join2 } from "path";
|
|
457
|
-
import
|
|
651
|
+
import chalk6 from "chalk";
|
|
458
652
|
import * as p from "@clack/prompts";
|
|
459
653
|
|
|
460
654
|
// src/commands/init-helpers.ts
|
|
461
655
|
var PROVIDER_DEFAULTS = {
|
|
462
656
|
openai: "gpt-4o-mini",
|
|
463
657
|
anthropic: "claude-sonnet-4-6",
|
|
464
|
-
groq: "
|
|
658
|
+
groq: "openai/gpt-oss-20b",
|
|
465
659
|
google: "gemini-2.0-flash",
|
|
466
660
|
mistral: "mistral-large-latest",
|
|
467
661
|
azure: "gpt-4o"
|
|
@@ -606,15 +800,13 @@ function generateEvalSection() {
|
|
|
606
800
|
return `
|
|
607
801
|
# \u2500\u2500 EVALUATION \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
|
|
608
802
|
evaluation:
|
|
609
|
-
framework: deepeval
|
|
610
803
|
datasets:
|
|
611
804
|
- name: qa-test
|
|
612
805
|
path: $file:eval/datasets/qa.jsonl
|
|
613
806
|
metrics:
|
|
614
|
-
-
|
|
615
|
-
- hallucination
|
|
807
|
+
- grounded
|
|
616
808
|
thresholds:
|
|
617
|
-
|
|
809
|
+
grounded: 0.95
|
|
618
810
|
ciGate: false`;
|
|
619
811
|
}
|
|
620
812
|
function generateObservabilitySection(opts) {
|
|
@@ -745,6 +937,13 @@ function generateEnvExample(name, envVars) {
|
|
|
745
937
|
}
|
|
746
938
|
return lines.join("\n") + "\n";
|
|
747
939
|
}
|
|
940
|
+
function validateAgentName(v) {
|
|
941
|
+
return /^[a-z0-9-]+$/.test(v ?? "") ? void 0 : "Must be lowercase slug (a-z, 0-9, -)";
|
|
942
|
+
}
|
|
943
|
+
function validatePort(v) {
|
|
944
|
+
const n = parseInt(v ?? "", 10);
|
|
945
|
+
return isNaN(n) || n < 1 || n > 65535 ? "Must be a valid port (1-65535)" : void 0;
|
|
946
|
+
}
|
|
748
947
|
|
|
749
948
|
// src/commands/init.ts
|
|
750
949
|
function buildDefaultOptions() {
|
|
@@ -768,7 +967,7 @@ async function runPhase1() {
|
|
|
768
967
|
name: () => p.text({
|
|
769
968
|
message: "Agent name (slug)",
|
|
770
969
|
placeholder: "my-agent",
|
|
771
|
-
validate:
|
|
970
|
+
validate: validateAgentName
|
|
772
971
|
}),
|
|
773
972
|
description: () => p.text({
|
|
774
973
|
message: "Description",
|
|
@@ -906,10 +1105,7 @@ async function runPhase3(phase2) {
|
|
|
906
1105
|
message: "API port",
|
|
907
1106
|
placeholder: "3000",
|
|
908
1107
|
initialValue: "3000",
|
|
909
|
-
validate:
|
|
910
|
-
const n = parseInt(v, 10);
|
|
911
|
-
return isNaN(n) || n < 1 || n > 65535 ? "Must be a valid port (1-65535)" : void 0;
|
|
912
|
-
}
|
|
1108
|
+
validate: validatePort
|
|
913
1109
|
});
|
|
914
1110
|
if (p.isCancel(port)) {
|
|
915
1111
|
p.cancel("Init cancelled.");
|
|
@@ -970,7 +1166,7 @@ function registerInitCommand(program2) {
|
|
|
970
1166
|
if (cmdOpts.yes) {
|
|
971
1167
|
opts = buildDefaultOptions();
|
|
972
1168
|
} else {
|
|
973
|
-
p.intro(
|
|
1169
|
+
p.intro(chalk6.cyan("Creating your agent.yaml"));
|
|
974
1170
|
const phase1 = await runPhase1();
|
|
975
1171
|
const phase2 = await runPhase2();
|
|
976
1172
|
const phase3 = await runPhase3(phase2);
|
|
@@ -989,18 +1185,18 @@ function registerInitCommand(program2) {
|
|
|
989
1185
|
...phase3
|
|
990
1186
|
};
|
|
991
1187
|
}
|
|
992
|
-
const
|
|
993
|
-
writeFileSync2(outFile,
|
|
1188
|
+
const yaml7 = generateManifest(opts);
|
|
1189
|
+
writeFileSync2(outFile, yaml7, "utf-8");
|
|
994
1190
|
scaffoldFiles(outDir, opts);
|
|
995
|
-
if (!cmdOpts.yes) p.outro(
|
|
996
|
-
else console.log(
|
|
1191
|
+
if (!cmdOpts.yes) p.outro(chalk6.green(`\u2713 Created ${outFile}`));
|
|
1192
|
+
else console.log(chalk6.green(`
|
|
997
1193
|
\u2713 Created ${outFile}
|
|
998
1194
|
`));
|
|
999
|
-
console.log(
|
|
1000
|
-
console.log(
|
|
1001
|
-
console.log(
|
|
1002
|
-
console.log(
|
|
1003
|
-
console.log(
|
|
1195
|
+
console.log(chalk6.gray(" Next steps:"));
|
|
1196
|
+
console.log(chalk6.gray(` 1. Edit ${outFile} to customize your agent`));
|
|
1197
|
+
console.log(chalk6.gray(` 2. Run: npx agentspec validate agent.yaml`));
|
|
1198
|
+
console.log(chalk6.gray(` 3. Run: npx agentspec health agent.yaml`));
|
|
1199
|
+
console.log(chalk6.gray(` 4. Run: npx agentspec audit agent.yaml`));
|
|
1004
1200
|
console.log();
|
|
1005
1201
|
});
|
|
1006
1202
|
}
|
|
@@ -1008,7 +1204,7 @@ function registerInitCommand(program2) {
|
|
|
1008
1204
|
// src/commands/generate.ts
|
|
1009
1205
|
import { existsSync as existsSync3, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync3 } from "fs";
|
|
1010
1206
|
import { basename, dirname as dirname2, join as join3, resolve as resolve3, sep } from "path";
|
|
1011
|
-
import
|
|
1207
|
+
import chalk7 from "chalk";
|
|
1012
1208
|
|
|
1013
1209
|
// src/utils/spinner.ts
|
|
1014
1210
|
import { spinner as clackSpinner } from "@clack/prompts";
|
|
@@ -1036,48 +1232,122 @@ function spinner2() {
|
|
|
1036
1232
|
}
|
|
1037
1233
|
|
|
1038
1234
|
// src/commands/generate.ts
|
|
1039
|
-
import { loadManifest as
|
|
1235
|
+
import { loadManifest as loadManifest5 } from "@agentspec/sdk";
|
|
1040
1236
|
import { generateCode, listFrameworks, resolveProvider } from "@agentspec/codegen";
|
|
1041
1237
|
|
|
1042
1238
|
// src/deploy/k8s.ts
|
|
1043
|
-
|
|
1044
|
-
var DEFAULT_AGENT_PORT = 8e3;
|
|
1045
|
-
var PROXY_PORT = 4e3;
|
|
1046
|
-
var CONTROL_PORT = 4001;
|
|
1047
|
-
var K8S_NAME_RE = /^[a-z0-9][a-z0-9-]{0,61}[a-z0-9]$|^[a-z0-9]$/;
|
|
1239
|
+
import { CONTRACT as CONTRACT5 } from "@agentspec/sdk";
|
|
1048
1240
|
function escapeYamlDoubleQuotedValue(value) {
|
|
1049
1241
|
return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
|
|
1050
1242
|
}
|
|
1051
1243
|
function generateK8sManifests(manifest) {
|
|
1052
|
-
const
|
|
1053
|
-
|
|
1054
|
-
throw new Error(
|
|
1055
|
-
`Invalid agent name "${name}" for Kubernetes \u2014 must be a lowercase DNS label (a-z, 0-9, hyphens, 1-63 chars)`
|
|
1056
|
-
);
|
|
1057
|
-
}
|
|
1058
|
-
const port = manifest.spec.api?.port ?? DEFAULT_AGENT_PORT;
|
|
1059
|
-
const envRefs = collectEnvRefs(manifest);
|
|
1244
|
+
const plan = planPodPatch(manifest);
|
|
1245
|
+
const { name, port, agentEnvRefs, gatewayEnv, secretKeys, configVars } = plan;
|
|
1060
1246
|
return {
|
|
1061
|
-
"k8s/deployment.yaml": generateDeployment(
|
|
1247
|
+
"k8s/deployment.yaml": generateDeployment(plan),
|
|
1062
1248
|
"k8s/service.yaml": generateService(name, port),
|
|
1063
|
-
"k8s/configmap.yaml": generateConfigMap(name,
|
|
1064
|
-
"k8s/
|
|
1249
|
+
"k8s/configmap.yaml": generateConfigMap(name, configVars),
|
|
1250
|
+
"k8s/manifest-configmap.yaml": generateManifestConfigMap(name, manifest),
|
|
1251
|
+
"k8s/secret.yaml.example": generateSecretExample(name, secretKeys)
|
|
1065
1252
|
};
|
|
1066
1253
|
}
|
|
1067
|
-
function
|
|
1068
|
-
|
|
1069
|
-
|
|
1070
|
-
|
|
1071
|
-
|
|
1254
|
+
function secretEnv(name, vars, indent) {
|
|
1255
|
+
return vars.map(
|
|
1256
|
+
(v) => `${indent}- name: ${v}
|
|
1257
|
+
${indent} valueFrom:
|
|
1258
|
+
${indent} secretKeyRef:
|
|
1259
|
+
${indent} name: ${name}-secrets
|
|
1260
|
+
${indent} key: ${v}`
|
|
1261
|
+
).join("\n");
|
|
1262
|
+
}
|
|
1263
|
+
function renderInitContainer() {
|
|
1264
|
+
const { podPatch, paths } = CONTRACT5;
|
|
1265
|
+
return ` - name: ${podPatch.gatewayConfigInitContainer}
|
|
1266
|
+
image: ${CONTRACT5.images.sidecar}
|
|
1267
|
+
command: [${gatewayConfigRenderCommand().join(", ")}]
|
|
1268
|
+
volumeMounts:
|
|
1269
|
+
- name: ${podPatch.manifestVolume}
|
|
1270
|
+
mountPath: ${paths.manifestDir}
|
|
1271
|
+
readOnly: true
|
|
1272
|
+
- name: ${podPatch.gatewayConfigVolume}
|
|
1273
|
+
mountPath: ${paths.gatewayConfigDir}
|
|
1274
|
+
`;
|
|
1275
|
+
}
|
|
1276
|
+
function renderAgentContainer(name, image, baseUrlEnv, agentEnvRefs) {
|
|
1277
|
+
const baseUrls = Object.entries(baseUrlEnv).map(([envName, url]) => ` - name: ${envName}
|
|
1278
|
+
value: "${url}"`).join("\n");
|
|
1279
|
+
const secrets = secretEnv(name, [...agentEnvRefs, CONTRACT5.env.gatewayKey].sort(), " ");
|
|
1280
|
+
return ` - name: ${name}
|
|
1281
|
+
image: ${image}
|
|
1282
|
+
envFrom:
|
|
1283
|
+
- configMapRef:
|
|
1284
|
+
name: ${name}-config
|
|
1285
|
+
env:
|
|
1286
|
+
- name: ${CONTRACT5.env.agentHost}
|
|
1287
|
+
value: "${CONTRACT5.podPatch.loopback}"
|
|
1288
|
+
- name: ${CONTRACT5.env.agentPort}
|
|
1289
|
+
value: "${CONTRACT5.ports.agentBind}"
|
|
1290
|
+
${baseUrls}
|
|
1291
|
+
${secrets}
|
|
1292
|
+
`;
|
|
1293
|
+
}
|
|
1294
|
+
function renderSidecarContainer(port) {
|
|
1295
|
+
const { podPatch, paths } = CONTRACT5;
|
|
1296
|
+
return ` - name: ${podPatch.sidecarContainer}
|
|
1297
|
+
image: ${CONTRACT5.images.sidecar}
|
|
1298
|
+
ports:
|
|
1299
|
+
- containerPort: ${port}
|
|
1300
|
+
name: ${podPatch.proxyPortName}
|
|
1301
|
+
- containerPort: ${CONTRACT5.ports.controlPlane}
|
|
1302
|
+
name: ${podPatch.controlPortName}
|
|
1303
|
+
env:
|
|
1304
|
+
- name: ${CONTRACT5.env.proxyPort}
|
|
1305
|
+
value: "${port}"
|
|
1306
|
+
- name: ${CONTRACT5.env.upstreamUrl}
|
|
1307
|
+
value: "http://${podPatch.loopback}:${CONTRACT5.ports.agentBind}"
|
|
1308
|
+
- name: ${CONTRACT5.env.manifestPath}
|
|
1309
|
+
value: ${paths.manifestFile}
|
|
1310
|
+
volumeMounts:
|
|
1311
|
+
- name: ${podPatch.manifestVolume}
|
|
1312
|
+
mountPath: ${paths.manifestDir}
|
|
1313
|
+
readOnly: true
|
|
1314
|
+
`;
|
|
1072
1315
|
}
|
|
1073
|
-
function
|
|
1074
|
-
const
|
|
1075
|
-
|
|
1076
|
-
|
|
1077
|
-
|
|
1078
|
-
|
|
1079
|
-
|
|
1080
|
-
|
|
1316
|
+
function renderGatewayContainer(name, gatewayEnv) {
|
|
1317
|
+
const { podPatch, paths } = CONTRACT5;
|
|
1318
|
+
const secrets = secretEnv(name, [...gatewayEnv, CONTRACT5.env.gatewayKey].sort(), " ");
|
|
1319
|
+
return ` - name: ${podPatch.gatewayContainer}
|
|
1320
|
+
image: ${CONTRACT5.images.gateway}
|
|
1321
|
+
args: [-f, ${paths.gatewayConfigFile}]
|
|
1322
|
+
env:
|
|
1323
|
+
${secrets}
|
|
1324
|
+
resources:
|
|
1325
|
+
requests:
|
|
1326
|
+
cpu: ${podPatch.gatewayCpuRequest}
|
|
1327
|
+
memory: ${podPatch.gatewayMemoryRequest}
|
|
1328
|
+
limits:
|
|
1329
|
+
memory: ${podPatch.gatewayMemoryLimit}
|
|
1330
|
+
volumeMounts:
|
|
1331
|
+
- name: ${podPatch.gatewayConfigVolume}
|
|
1332
|
+
mountPath: ${paths.gatewayConfigDir}
|
|
1333
|
+
readOnly: true
|
|
1334
|
+
- name: ${podPatch.gatewayDataVolume}
|
|
1335
|
+
mountPath: ${paths.gatewayDataDir}
|
|
1336
|
+
`;
|
|
1337
|
+
}
|
|
1338
|
+
function renderVolumes(name) {
|
|
1339
|
+
const { podPatch } = CONTRACT5;
|
|
1340
|
+
return ` volumes:
|
|
1341
|
+
- name: ${podPatch.manifestVolume}
|
|
1342
|
+
configMap:
|
|
1343
|
+
name: ${name}-manifest
|
|
1344
|
+
- name: ${podPatch.gatewayConfigVolume}
|
|
1345
|
+
emptyDir: {}
|
|
1346
|
+
- name: ${podPatch.gatewayDataVolume}
|
|
1347
|
+
emptyDir: {}
|
|
1348
|
+
`;
|
|
1349
|
+
}
|
|
1350
|
+
function generateDeployment({ name, port, agentEnvRefs, gatewayEnv, agentImage, baseUrlEnv }) {
|
|
1081
1351
|
return `apiVersion: apps/v1
|
|
1082
1352
|
kind: Deployment
|
|
1083
1353
|
metadata:
|
|
@@ -1091,32 +1361,14 @@ spec:
|
|
|
1091
1361
|
app: ${name}
|
|
1092
1362
|
template:
|
|
1093
1363
|
metadata:
|
|
1364
|
+
annotations:
|
|
1365
|
+
${CONTRACT5.podPatch.agentNameAnnotation}: ${name}
|
|
1094
1366
|
labels:
|
|
1095
1367
|
app: ${name}
|
|
1096
1368
|
spec:
|
|
1097
|
-
|
|
1098
|
-
|
|
1099
|
-
|
|
1100
|
-
ports:
|
|
1101
|
-
- containerPort: ${port}
|
|
1102
|
-
envFrom:
|
|
1103
|
-
- configMapRef:
|
|
1104
|
-
name: ${name}-config
|
|
1105
|
-
env:
|
|
1106
|
-
${secretEnvBlock}
|
|
1107
|
-
- name: agentspec-sidecar
|
|
1108
|
-
image: ${SIDECAR_IMAGE}
|
|
1109
|
-
ports:
|
|
1110
|
-
- containerPort: ${PROXY_PORT}
|
|
1111
|
-
name: proxy
|
|
1112
|
-
- containerPort: ${CONTROL_PORT}
|
|
1113
|
-
name: control
|
|
1114
|
-
env:
|
|
1115
|
-
- name: UPSTREAM_URL
|
|
1116
|
-
value: "http://localhost:${port}"
|
|
1117
|
-
- name: MANIFEST_PATH
|
|
1118
|
-
value: /manifest/agent.yaml
|
|
1119
|
-
`;
|
|
1369
|
+
initContainers:
|
|
1370
|
+
` + renderInitContainer() + ` containers:
|
|
1371
|
+
` + renderAgentContainer(name, agentImage, baseUrlEnv, agentEnvRefs) + renderSidecarContainer(port) + renderGatewayContainer(name, gatewayEnv) + renderVolumes(name);
|
|
1120
1372
|
}
|
|
1121
1373
|
function generateService(name, port) {
|
|
1122
1374
|
return `apiVersion: v1
|
|
@@ -1130,23 +1382,16 @@ spec:
|
|
|
1130
1382
|
selector:
|
|
1131
1383
|
app: ${name}
|
|
1132
1384
|
ports:
|
|
1133
|
-
- name:
|
|
1385
|
+
- name: ${CONTRACT5.podPatch.proxyPortName}
|
|
1134
1386
|
port: ${port}
|
|
1135
1387
|
targetPort: ${port}
|
|
1136
|
-
- name:
|
|
1137
|
-
port: ${
|
|
1138
|
-
targetPort: ${
|
|
1139
|
-
- name: control
|
|
1140
|
-
port: ${CONTROL_PORT}
|
|
1141
|
-
targetPort: ${CONTROL_PORT}
|
|
1388
|
+
- name: ${CONTRACT5.podPatch.controlPortName}
|
|
1389
|
+
port: ${CONTRACT5.ports.controlPlane}
|
|
1390
|
+
targetPort: ${CONTRACT5.ports.controlPlane}
|
|
1142
1391
|
`;
|
|
1143
1392
|
}
|
|
1144
|
-
function generateConfigMap(name,
|
|
1145
|
-
const data = [
|
|
1146
|
-
` AGENT_NAME: "${escapeYamlDoubleQuotedValue(name)}"`,
|
|
1147
|
-
` MODEL_PROVIDER: "${escapeYamlDoubleQuotedValue(manifest.spec.model.provider)}"`,
|
|
1148
|
-
` MODEL_ID: "${escapeYamlDoubleQuotedValue(manifest.spec.model.id)}"`
|
|
1149
|
-
].join("\n");
|
|
1393
|
+
function generateConfigMap(name, configVars) {
|
|
1394
|
+
const data = Object.entries(configVars).map(([key, value]) => ` ${key}: "${escapeYamlDoubleQuotedValue(value)}"`).join("\n");
|
|
1150
1395
|
return `apiVersion: v1
|
|
1151
1396
|
kind: ConfigMap
|
|
1152
1397
|
metadata:
|
|
@@ -1157,8 +1402,22 @@ data:
|
|
|
1157
1402
|
${data}
|
|
1158
1403
|
`;
|
|
1159
1404
|
}
|
|
1160
|
-
function
|
|
1161
|
-
const
|
|
1405
|
+
function generateManifestConfigMap(name, manifest) {
|
|
1406
|
+
const body = dumpManifest(manifest);
|
|
1407
|
+
const indented = body.trimEnd().split("\n").map((l) => ` ${l}`).join("\n");
|
|
1408
|
+
return `apiVersion: v1
|
|
1409
|
+
kind: ConfigMap
|
|
1410
|
+
metadata:
|
|
1411
|
+
name: ${name}-manifest
|
|
1412
|
+
labels:
|
|
1413
|
+
app: ${name}
|
|
1414
|
+
data:
|
|
1415
|
+
agent.yaml: |
|
|
1416
|
+
${indented}
|
|
1417
|
+
`;
|
|
1418
|
+
}
|
|
1419
|
+
function generateSecretExample(name, secretKeys) {
|
|
1420
|
+
const dataLines = secretKeys.length > 0 ? secretKeys.map((v) => ` ${v}: <base64-encoded-value> # echo -n "<value>" | base64`).join("\n") : " # No $env: references found in manifest";
|
|
1162
1421
|
return `# Example Kubernetes Secret \u2014 fill in real values and apply with:
|
|
1163
1422
|
# kubectl apply -f k8s/secret.yaml
|
|
1164
1423
|
# DO NOT commit real values. This file is a template only.
|
|
@@ -1174,8 +1433,105 @@ ${dataLines}
|
|
|
1174
1433
|
`;
|
|
1175
1434
|
}
|
|
1176
1435
|
|
|
1436
|
+
// src/deploy/compose.ts
|
|
1437
|
+
import { CONTRACT as CONTRACT6 } from "@agentspec/sdk";
|
|
1438
|
+
import * as yaml4 from "js-yaml";
|
|
1439
|
+
function generateComposeFiles(manifest) {
|
|
1440
|
+
const plan = planPodPatch(manifest);
|
|
1441
|
+
return {
|
|
1442
|
+
"compose/docker-compose.yaml": yaml4.dump(composeProject(plan), { lineWidth: -1, noRefs: true }),
|
|
1443
|
+
"compose/agent.yaml": dumpManifest(manifest),
|
|
1444
|
+
"compose/.env.example": envExample(plan.secretKeys)
|
|
1445
|
+
};
|
|
1446
|
+
}
|
|
1447
|
+
function interpolate(vars) {
|
|
1448
|
+
return Object.fromEntries(vars.map((v) => [v, `\${${v}:?set ${v} in .env}`]));
|
|
1449
|
+
}
|
|
1450
|
+
function composeProject({ name, port, agentEnvRefs, gatewayEnv, configVars, agentImage, baseUrlEnv }) {
|
|
1451
|
+
const { podPatch, paths } = CONTRACT6;
|
|
1452
|
+
const agentNamespace = `service:${name}`;
|
|
1453
|
+
return {
|
|
1454
|
+
services: {
|
|
1455
|
+
[podPatch.gatewayConfigInitContainer]: {
|
|
1456
|
+
image: CONTRACT6.images.sidecar,
|
|
1457
|
+
command: gatewayConfigRenderCommand(),
|
|
1458
|
+
volumes: [`./agent.yaml:${paths.manifestFile}:ro`, `${podPatch.gatewayConfigVolume}:${paths.gatewayConfigDir}`]
|
|
1459
|
+
},
|
|
1460
|
+
[name]: {
|
|
1461
|
+
image: agentImage,
|
|
1462
|
+
environment: {
|
|
1463
|
+
...configVars,
|
|
1464
|
+
[CONTRACT6.env.agentHost]: podPatch.loopback,
|
|
1465
|
+
[CONTRACT6.env.agentPort]: String(CONTRACT6.ports.agentBind),
|
|
1466
|
+
...baseUrlEnv,
|
|
1467
|
+
...interpolate([...agentEnvRefs, CONTRACT6.env.gatewayKey].sort())
|
|
1468
|
+
},
|
|
1469
|
+
// The sidecar and gateway share this namespace, so the agent's service publishes their ports.
|
|
1470
|
+
// The control plane accepts proof writes without a token, so it stays on the host's loopback.
|
|
1471
|
+
ports: [
|
|
1472
|
+
`${port}:${port}`,
|
|
1473
|
+
`${podPatch.loopback}:${CONTRACT6.ports.controlPlane}:${CONTRACT6.ports.controlPlane}`
|
|
1474
|
+
]
|
|
1475
|
+
},
|
|
1476
|
+
[podPatch.sidecarContainer]: {
|
|
1477
|
+
image: CONTRACT6.images.sidecar,
|
|
1478
|
+
network_mode: agentNamespace,
|
|
1479
|
+
depends_on: [name],
|
|
1480
|
+
environment: {
|
|
1481
|
+
[CONTRACT6.env.proxyPort]: String(port),
|
|
1482
|
+
[CONTRACT6.env.upstreamUrl]: `http://${podPatch.loopback}:${CONTRACT6.ports.agentBind}`,
|
|
1483
|
+
[CONTRACT6.env.manifestPath]: paths.manifestFile
|
|
1484
|
+
},
|
|
1485
|
+
volumes: [`./agent.yaml:${paths.manifestFile}:ro`]
|
|
1486
|
+
},
|
|
1487
|
+
[podPatch.gatewayContainer]: {
|
|
1488
|
+
image: CONTRACT6.images.gateway,
|
|
1489
|
+
network_mode: agentNamespace,
|
|
1490
|
+
// The gateway image is non-root and a fresh named volume is root-owned, so the data dir is a world-writable
|
|
1491
|
+
// tmpfs instead (ephemeral and sticky, like the k8s emptyDir). The gateway keeps its own UID (ADR-0002, ADR-0004).
|
|
1492
|
+
tmpfs: [`${paths.gatewayDataDir}:mode=1777`],
|
|
1493
|
+
command: ["-f", paths.gatewayConfigFile],
|
|
1494
|
+
depends_on: {
|
|
1495
|
+
[podPatch.gatewayConfigInitContainer]: { condition: "service_completed_successfully" },
|
|
1496
|
+
[name]: { condition: "service_started" }
|
|
1497
|
+
},
|
|
1498
|
+
environment: interpolate([...gatewayEnv, CONTRACT6.env.gatewayKey].sort()),
|
|
1499
|
+
volumes: [
|
|
1500
|
+
`${podPatch.gatewayConfigVolume}:${paths.gatewayConfigDir}:ro`
|
|
1501
|
+
],
|
|
1502
|
+
deploy: {
|
|
1503
|
+
resources: {
|
|
1504
|
+
reservations: { cpus: composeCpu(podPatch.gatewayCpuRequest), memory: composeMemory(podPatch.gatewayMemoryRequest) },
|
|
1505
|
+
limits: { memory: composeMemory(podPatch.gatewayMemoryLimit) }
|
|
1506
|
+
}
|
|
1507
|
+
}
|
|
1508
|
+
}
|
|
1509
|
+
},
|
|
1510
|
+
volumes: { [podPatch.gatewayConfigVolume]: {} }
|
|
1511
|
+
};
|
|
1512
|
+
}
|
|
1513
|
+
function composeMemory(quantity) {
|
|
1514
|
+
if (!/^\d+Mi$/.test(quantity)) {
|
|
1515
|
+
throw new Error(`Cannot convert memory "${quantity}" to compose; the contract uses whole Mi values (e.g. 128Mi).`);
|
|
1516
|
+
}
|
|
1517
|
+
return quantity.replace(/Mi$/, "m");
|
|
1518
|
+
}
|
|
1519
|
+
function composeCpu(quantity) {
|
|
1520
|
+
if (!/^\d+m$/.test(quantity)) {
|
|
1521
|
+
throw new Error(`Cannot convert cpu "${quantity}" to compose; the contract uses millicores (e.g. 25m).`);
|
|
1522
|
+
}
|
|
1523
|
+
return String(Number.parseInt(quantity, 10) / 1e3);
|
|
1524
|
+
}
|
|
1525
|
+
function envExample(secretKeys) {
|
|
1526
|
+
const lines = secretKeys.map((v) => `${v}=`);
|
|
1527
|
+
return `# Copy to .env and fill in real values. DO NOT commit real values.
|
|
1528
|
+
# Provider keys are read by the ${CONTRACT6.podPatch.gatewayContainer} service only.
|
|
1529
|
+
${lines.join("\n")}
|
|
1530
|
+
`;
|
|
1531
|
+
}
|
|
1532
|
+
|
|
1177
1533
|
// src/commands/generate.ts
|
|
1178
|
-
var DEPLOY_TARGETS = ["k8s", "helm"];
|
|
1534
|
+
var DEPLOY_TARGETS = ["k8s", "compose", "helm"];
|
|
1179
1535
|
function writeGeneratedFiles(files, outDir) {
|
|
1180
1536
|
const resolvedOutDir = resolve3(outDir);
|
|
1181
1537
|
mkdirSync2(resolvedOutDir, { recursive: true });
|
|
@@ -1187,7 +1543,7 @@ function writeGeneratedFiles(files, outDir) {
|
|
|
1187
1543
|
}
|
|
1188
1544
|
mkdirSync2(dirname2(outPath), { recursive: true });
|
|
1189
1545
|
writeFileSync3(outPath, content, "utf-8");
|
|
1190
|
-
console.log(` ${
|
|
1546
|
+
console.log(` ${chalk7.green("\u2713")} ${filename}`);
|
|
1191
1547
|
}
|
|
1192
1548
|
}
|
|
1193
1549
|
function copyManifestToOutput(srcFile, outDir, alreadyGenerated) {
|
|
@@ -1200,7 +1556,7 @@ function copyManifestToOutput(srcFile, outDir, alreadyGenerated) {
|
|
|
1200
1556
|
let content = readFileSync2(manifestSrc, "utf-8");
|
|
1201
1557
|
content = content.replace(/\$secret:[^\s\n'"]+/g, "<redacted>");
|
|
1202
1558
|
writeFileSync3(join3(resolvedOutDir, basename(manifestSrc)), content, "utf-8");
|
|
1203
|
-
console.log(` ${
|
|
1559
|
+
console.log(` ${chalk7.green("\u2713")} ${basename(manifestSrc)} (manifest copy)`);
|
|
1204
1560
|
} catch {
|
|
1205
1561
|
}
|
|
1206
1562
|
}
|
|
@@ -1223,11 +1579,21 @@ function validateFramework(framework) {
|
|
|
1223
1579
|
process.exit(1);
|
|
1224
1580
|
}
|
|
1225
1581
|
}
|
|
1226
|
-
|
|
1227
|
-
|
|
1582
|
+
var DETERMINISTIC_DEPLOYS = {
|
|
1583
|
+
k8s: { title: "Kubernetes", render: generateK8sManifests },
|
|
1584
|
+
compose: { title: "Docker Compose", render: generateComposeFiles }
|
|
1585
|
+
};
|
|
1586
|
+
function handleDeterministicDeploy(target, manifest, outDir, outputOpt, dryRun = false) {
|
|
1587
|
+
const { title, render } = DETERMINISTIC_DEPLOYS[target];
|
|
1588
|
+
printHeader(`AgentSpec Deploy \u2014 ${title}`);
|
|
1228
1589
|
console.log();
|
|
1229
1590
|
try {
|
|
1230
|
-
|
|
1591
|
+
const files = render(manifest);
|
|
1592
|
+
if (dryRun) {
|
|
1593
|
+
printDryRunOutput(files);
|
|
1594
|
+
return;
|
|
1595
|
+
}
|
|
1596
|
+
writeGeneratedFiles(files, outDir);
|
|
1231
1597
|
} catch (err) {
|
|
1232
1598
|
printError(String(err));
|
|
1233
1599
|
process.exit(1);
|
|
@@ -1261,15 +1627,15 @@ function writePushModeEnv(outDir) {
|
|
|
1261
1627
|
].join("\n");
|
|
1262
1628
|
writeFileSync3(join3(outDir, ".env.agentspec"), envContent, "utf-8");
|
|
1263
1629
|
console.log(
|
|
1264
|
-
` ${
|
|
1630
|
+
` ${chalk7.green("\u2713")} .env.agentspec (push mode \u2014 paste your key from agentspec register)`
|
|
1265
1631
|
);
|
|
1266
1632
|
}
|
|
1267
1633
|
function printDryRunOutput(files) {
|
|
1268
1634
|
console.log();
|
|
1269
|
-
console.log(
|
|
1635
|
+
console.log(chalk7.bold(" Files to be generated:"));
|
|
1270
1636
|
for (const [filename, content] of Object.entries(files)) {
|
|
1271
1637
|
console.log();
|
|
1272
|
-
console.log(
|
|
1638
|
+
console.log(chalk7.cyan(` \u2500\u2500 ${filename} \u2500\u2500`));
|
|
1273
1639
|
console.log(content.split("\n").map((l) => ` ${l}`).join("\n"));
|
|
1274
1640
|
}
|
|
1275
1641
|
console.log();
|
|
@@ -1277,16 +1643,16 @@ function printDryRunOutput(files) {
|
|
|
1277
1643
|
function printPostGeneration(generated, outputDir) {
|
|
1278
1644
|
console.log();
|
|
1279
1645
|
if (generated.installCommands.length > 0) {
|
|
1280
|
-
console.log(
|
|
1646
|
+
console.log(chalk7.bold(" Install commands:"));
|
|
1281
1647
|
for (const cmd of generated.installCommands) {
|
|
1282
|
-
console.log(` ${
|
|
1648
|
+
console.log(` ${chalk7.gray("$")} ${chalk7.cyan(cmd)}`);
|
|
1283
1649
|
}
|
|
1284
1650
|
console.log();
|
|
1285
1651
|
}
|
|
1286
1652
|
if (generated.envVars.length > 0) {
|
|
1287
|
-
console.log(
|
|
1653
|
+
console.log(chalk7.bold(" Required env vars:"));
|
|
1288
1654
|
for (const v of generated.envVars) {
|
|
1289
|
-
console.log(` ${
|
|
1655
|
+
console.log(` ${chalk7.gray(v)}`);
|
|
1290
1656
|
}
|
|
1291
1657
|
console.log();
|
|
1292
1658
|
}
|
|
@@ -1295,14 +1661,14 @@ function printPostGeneration(generated, outputDir) {
|
|
|
1295
1661
|
async function runDeployTarget(target, manifest, outDir, provider) {
|
|
1296
1662
|
if (target === "k8s") {
|
|
1297
1663
|
console.log();
|
|
1298
|
-
console.log(
|
|
1664
|
+
console.log(chalk7.bold(" Kubernetes manifests:"));
|
|
1299
1665
|
const deployFiles = generateK8sManifests(manifest);
|
|
1300
1666
|
writeGeneratedFiles(deployFiles, outDir);
|
|
1301
1667
|
return;
|
|
1302
1668
|
}
|
|
1303
1669
|
if (target === "helm") {
|
|
1304
1670
|
console.log();
|
|
1305
|
-
console.log(
|
|
1671
|
+
console.log(chalk7.bold(" Helm chart (LLM-generated):"));
|
|
1306
1672
|
let helmGenerated;
|
|
1307
1673
|
try {
|
|
1308
1674
|
helmGenerated = await generateCode(manifest, { framework: "helm", provider });
|
|
@@ -1334,13 +1700,13 @@ function registerGenerateCommand(program2) {
|
|
|
1334
1700
|
}
|
|
1335
1701
|
let parsed;
|
|
1336
1702
|
try {
|
|
1337
|
-
parsed =
|
|
1703
|
+
parsed = loadManifest5(file, { resolve: false });
|
|
1338
1704
|
} catch (err) {
|
|
1339
1705
|
printError(`Cannot load manifest: ${String(err)}`);
|
|
1340
1706
|
process.exit(1);
|
|
1341
1707
|
}
|
|
1342
|
-
if (opts.deploy
|
|
1343
|
-
|
|
1708
|
+
if (opts.deploy && Object.hasOwn(DETERMINISTIC_DEPLOYS, opts.deploy)) {
|
|
1709
|
+
handleDeterministicDeploy(opts.deploy, parsed.manifest, resolve3(opts.output), opts.output, opts.dryRun);
|
|
1344
1710
|
return;
|
|
1345
1711
|
}
|
|
1346
1712
|
printHeader(`AgentSpec Generate \u2014 ${opts.framework}`);
|
|
@@ -1390,12 +1756,12 @@ function registerGenerateCommand(program2) {
|
|
|
1390
1756
|
}
|
|
1391
1757
|
|
|
1392
1758
|
// src/commands/export.ts
|
|
1393
|
-
import { loadManifest as
|
|
1759
|
+
import { loadManifest as loadManifest6 } from "@agentspec/sdk";
|
|
1394
1760
|
function registerExportCommand(program2) {
|
|
1395
1761
|
program2.command("export <file>").description("Export manifest to other formats (agentcard, agents-md-block)").requiredOption("--format <fmt>", "Export format: agentcard|agents-md-block").action(async (file, opts) => {
|
|
1396
1762
|
let parsed;
|
|
1397
1763
|
try {
|
|
1398
|
-
parsed =
|
|
1764
|
+
parsed = loadManifest6(file, { resolve: false });
|
|
1399
1765
|
} catch (err) {
|
|
1400
1766
|
printError(`Cannot load manifest: ${String(err)}`);
|
|
1401
1767
|
process.exit(1);
|
|
@@ -1477,8 +1843,8 @@ npx agentspec generate agent.yaml --framework langgraph --output ./generated/
|
|
|
1477
1843
|
// src/commands/migrate.ts
|
|
1478
1844
|
import { readFileSync as readFileSync3, writeFileSync as writeFileSync4 } from "fs";
|
|
1479
1845
|
import { resolve as resolve4 } from "path";
|
|
1480
|
-
import
|
|
1481
|
-
import
|
|
1846
|
+
import chalk8 from "chalk";
|
|
1847
|
+
import * as yaml5 from "js-yaml";
|
|
1482
1848
|
import {
|
|
1483
1849
|
migrateManifest,
|
|
1484
1850
|
detectVersion,
|
|
@@ -1499,14 +1865,14 @@ function registerMigrateCommand(program2) {
|
|
|
1499
1865
|
}
|
|
1500
1866
|
let parsed;
|
|
1501
1867
|
try {
|
|
1502
|
-
parsed =
|
|
1868
|
+
parsed = yaml5.load(raw);
|
|
1503
1869
|
} catch (err) {
|
|
1504
1870
|
printError(`Invalid YAML: ${String(err)}`);
|
|
1505
1871
|
process.exit(1);
|
|
1506
1872
|
}
|
|
1507
1873
|
const fromVersion = detectVersion(parsed);
|
|
1508
|
-
console.log(
|
|
1509
|
-
console.log(
|
|
1874
|
+
console.log(chalk8.gray(` File : ${absPath}`));
|
|
1875
|
+
console.log(chalk8.gray(` Version : ${fromVersion}`));
|
|
1510
1876
|
console.log();
|
|
1511
1877
|
if (isLatestVersion(parsed)) {
|
|
1512
1878
|
printSuccess(`Already at latest version (${LATEST_API_VERSION}) \u2014 no migration needed.`);
|
|
@@ -1514,21 +1880,21 @@ function registerMigrateCommand(program2) {
|
|
|
1514
1880
|
}
|
|
1515
1881
|
const { result, migrationsApplied } = migrateManifest(parsed);
|
|
1516
1882
|
if (migrationsApplied.length === 0) {
|
|
1517
|
-
console.log(
|
|
1518
|
-
console.log(
|
|
1883
|
+
console.log(chalk8.yellow(` \u26A0 No migration path found from ${fromVersion} to ${LATEST_API_VERSION}.`));
|
|
1884
|
+
console.log(chalk8.gray(" Manual update may be required."));
|
|
1519
1885
|
console.log();
|
|
1520
1886
|
process.exit(1);
|
|
1521
1887
|
}
|
|
1522
|
-
console.log(
|
|
1888
|
+
console.log(chalk8.cyan(" Migrations applied:"));
|
|
1523
1889
|
for (const m of migrationsApplied) {
|
|
1524
|
-
console.log(
|
|
1890
|
+
console.log(chalk8.gray(` \u2022 ${m}`));
|
|
1525
1891
|
}
|
|
1526
1892
|
console.log();
|
|
1527
|
-
const migratedYaml =
|
|
1893
|
+
const migratedYaml = yaml5.dump(result, { lineWidth: 120 });
|
|
1528
1894
|
if (opts.dryRun) {
|
|
1529
|
-
console.log(
|
|
1530
|
-
console.log(
|
|
1531
|
-
console.log(
|
|
1895
|
+
console.log(chalk8.cyan(" --- Migrated manifest (dry-run) ---"));
|
|
1896
|
+
console.log(chalk8.gray(migratedYaml));
|
|
1897
|
+
console.log(chalk8.yellow(" Dry run \u2014 no files written."));
|
|
1532
1898
|
console.log();
|
|
1533
1899
|
return;
|
|
1534
1900
|
}
|
|
@@ -2005,8 +2371,8 @@ function validateManifestYaml(yamlStr) {
|
|
|
2005
2371
|
}
|
|
2006
2372
|
const result = ManifestSchema.safeParse(parsed);
|
|
2007
2373
|
if (result.success) return { valid: true };
|
|
2008
|
-
const errors = result.error.
|
|
2009
|
-
return { valid: false, errors, errorCount: result.error.
|
|
2374
|
+
const errors = result.error.issues.map((e) => ` - ${e.path.join(".") || "(root)"}: ${e.message}`).join("\n");
|
|
2375
|
+
return { valid: false, errors, errorCount: result.error.issues.length };
|
|
2010
2376
|
}
|
|
2011
2377
|
function runClaudeCodeProfile(srcDir) {
|
|
2012
2378
|
const manifest = buildManifestFromClaudeConfig(srcDir);
|
|
@@ -2116,31 +2482,21 @@ function registerScanCommand(program2) {
|
|
|
2116
2482
|
|
|
2117
2483
|
// src/commands/diff.ts
|
|
2118
2484
|
import { readFileSync as readFileSync6 } from "fs";
|
|
2119
|
-
import
|
|
2485
|
+
import * as yaml6 from "js-yaml";
|
|
2120
2486
|
|
|
2121
2487
|
// src/utils/diff-score.ts
|
|
2122
2488
|
import { scoreToGrade } from "@agentspec/sdk";
|
|
2123
2489
|
var DIFF_SCORE_TABLE = {
|
|
2124
2490
|
// ── Guardrails ─────────────────────────────────────────────────────────────
|
|
2125
|
-
"spec.guardrails.
|
|
2491
|
+
"spec.guardrails.input": {
|
|
2126
2492
|
severity: "HIGH",
|
|
2127
2493
|
scoreImpact: -15,
|
|
2128
|
-
description: "
|
|
2129
|
-
},
|
|
2130
|
-
"spec.guardrails.rate_limit": {
|
|
2131
|
-
severity: "HIGH",
|
|
2132
|
-
scoreImpact: -10,
|
|
2133
|
-
description: "Rate limiting removed \u2014 DoS risk increased"
|
|
2494
|
+
description: "Input guardrail removed or changed \u2014 re-check input filtering"
|
|
2134
2495
|
},
|
|
2135
|
-
"spec.guardrails.
|
|
2496
|
+
"spec.guardrails.output": {
|
|
2136
2497
|
severity: "HIGH",
|
|
2137
2498
|
scoreImpact: -10,
|
|
2138
|
-
description: "Output
|
|
2139
|
-
},
|
|
2140
|
-
"spec.guardrails.pii_scrubber": {
|
|
2141
|
-
severity: "HIGH",
|
|
2142
|
-
scoreImpact: -12,
|
|
2143
|
-
description: "PII scrubbing removed \u2014 sensitive data may leak in outputs"
|
|
2499
|
+
description: "Output guardrail removed or changed \u2014 re-check output validation"
|
|
2144
2500
|
},
|
|
2145
2501
|
// ── Model ──────────────────────────────────────────────────────────────────
|
|
2146
2502
|
"spec.model.apiKey": {
|
|
@@ -2148,7 +2504,7 @@ var DIFF_SCORE_TABLE = {
|
|
|
2148
2504
|
scoreImpact: -12,
|
|
2149
2505
|
description: "Model API key reference removed \u2014 agent will fail to authenticate"
|
|
2150
2506
|
},
|
|
2151
|
-
"spec.model.
|
|
2507
|
+
"spec.model.id": {
|
|
2152
2508
|
severity: "MEDIUM",
|
|
2153
2509
|
scoreImpact: -5,
|
|
2154
2510
|
description: "Model changed \u2014 re-evaluate compliance for new model"
|
|
@@ -2164,26 +2520,26 @@ var DIFF_SCORE_TABLE = {
|
|
|
2164
2520
|
description: "Fallback model removed \u2014 no resilience on primary model failure"
|
|
2165
2521
|
},
|
|
2166
2522
|
// ── Evaluation ─────────────────────────────────────────────────────────────
|
|
2167
|
-
"spec.
|
|
2168
|
-
severity: "MEDIUM",
|
|
2169
|
-
scoreImpact: -8,
|
|
2170
|
-
description: "Eval hooks removed \u2014 regression detection disabled"
|
|
2171
|
-
},
|
|
2172
|
-
"spec.eval.datasets": {
|
|
2523
|
+
"spec.evaluation.datasets": {
|
|
2173
2524
|
severity: "MEDIUM",
|
|
2174
2525
|
scoreImpact: -5,
|
|
2175
|
-
description: "
|
|
2526
|
+
description: "Evaluation datasets removed or changed \u2014 regression coverage reduced"
|
|
2176
2527
|
},
|
|
2177
2528
|
// ── Memory ─────────────────────────────────────────────────────────────────
|
|
2178
|
-
"spec.memory.
|
|
2529
|
+
"spec.memory.hygiene.piiScrubFields": {
|
|
2179
2530
|
severity: "HIGH",
|
|
2180
2531
|
scoreImpact: -10,
|
|
2181
|
-
description: "Memory PII scrubbing removed \u2014 stored data may contain PII"
|
|
2532
|
+
description: "Memory PII scrubbing removed or changed \u2014 stored data may contain PII"
|
|
2182
2533
|
},
|
|
2183
|
-
"spec.memory.
|
|
2534
|
+
"spec.memory.shortTerm.ttlSeconds": {
|
|
2184
2535
|
severity: "LOW",
|
|
2185
2536
|
scoreImpact: -3,
|
|
2186
|
-
description: "
|
|
2537
|
+
description: "Short-term memory TTL removed or changed \u2014 data may be retained indefinitely"
|
|
2538
|
+
},
|
|
2539
|
+
"spec.memory.longTerm.ttlDays": {
|
|
2540
|
+
severity: "LOW",
|
|
2541
|
+
scoreImpact: -3,
|
|
2542
|
+
description: "Long-term memory TTL removed or changed \u2014 data may be retained indefinitely"
|
|
2187
2543
|
},
|
|
2188
2544
|
// ── Tools (additions) ──────────────────────────────────────────────────────
|
|
2189
2545
|
"spec.tools[+]": {
|
|
@@ -2217,18 +2573,14 @@ function flattenObject(obj, prefix = "") {
|
|
|
2217
2573
|
if (value !== null && typeof value === "object" && !Array.isArray(value)) {
|
|
2218
2574
|
Object.assign(result, flattenObject(value, fullKey));
|
|
2219
2575
|
} else if (Array.isArray(value)) {
|
|
2220
|
-
|
|
2221
|
-
|
|
2222
|
-
|
|
2223
|
-
|
|
2224
|
-
|
|
2225
|
-
|
|
2226
|
-
|
|
2227
|
-
|
|
2228
|
-
result[itemKey] = item;
|
|
2229
|
-
}
|
|
2230
|
-
});
|
|
2231
|
-
}
|
|
2576
|
+
value.forEach((item, idx) => {
|
|
2577
|
+
const itemKey = `${fullKey}.${idx}`;
|
|
2578
|
+
if (item !== null && typeof item === "object") {
|
|
2579
|
+
Object.assign(result, flattenObject(item, itemKey));
|
|
2580
|
+
} else {
|
|
2581
|
+
result[itemKey] = item;
|
|
2582
|
+
}
|
|
2583
|
+
});
|
|
2232
2584
|
} else {
|
|
2233
2585
|
result[fullKey] = value;
|
|
2234
2586
|
}
|
|
@@ -2236,15 +2588,15 @@ function flattenObject(obj, prefix = "") {
|
|
|
2236
2588
|
return result;
|
|
2237
2589
|
}
|
|
2238
2590
|
function lookupScore(property, changeType) {
|
|
2591
|
+
if (changeType === "added") {
|
|
2592
|
+
return { severity: "LOW", scoreImpact: 0, description: `New field added: ${property}` };
|
|
2593
|
+
}
|
|
2239
2594
|
if (DIFF_SCORE_TABLE[property]) return DIFF_SCORE_TABLE[property];
|
|
2240
2595
|
const parts = property.split(".");
|
|
2241
2596
|
for (let i = parts.length - 1; i > 0; i--) {
|
|
2242
2597
|
const candidate = parts.slice(0, i).join(".");
|
|
2243
2598
|
if (DIFF_SCORE_TABLE[candidate]) return DIFF_SCORE_TABLE[candidate];
|
|
2244
2599
|
}
|
|
2245
|
-
if (changeType === "added") {
|
|
2246
|
-
return { severity: "LOW", scoreImpact: 0, description: `New field added: ${property}` };
|
|
2247
|
-
}
|
|
2248
2600
|
return {
|
|
2249
2601
|
severity: "LOW",
|
|
2250
2602
|
scoreImpact: -2,
|
|
@@ -2351,8 +2703,8 @@ function registerDiffCommand(program2) {
|
|
|
2351
2703
|
let fromRaw;
|
|
2352
2704
|
let toRaw;
|
|
2353
2705
|
try {
|
|
2354
|
-
fromRaw =
|
|
2355
|
-
toRaw =
|
|
2706
|
+
fromRaw = yaml6.load(readFileSync6(fromPath, "utf-8"), { schema: yaml6.JSON_SCHEMA });
|
|
2707
|
+
toRaw = yaml6.load(readFileSync6(toPath, "utf-8"), { schema: yaml6.JSON_SCHEMA });
|
|
2356
2708
|
} catch (err) {
|
|
2357
2709
|
console.error(`Error loading manifests: ${err.message}`);
|
|
2358
2710
|
process.exit(1);
|
|
@@ -2385,7 +2737,7 @@ function registerDiffCommand(program2) {
|
|
|
2385
2737
|
// src/commands/generate-policy.ts
|
|
2386
2738
|
import { mkdirSync as mkdirSync3, writeFileSync as writeFileSync6 } from "fs";
|
|
2387
2739
|
import { join as join6, resolve as resolve7 } from "path";
|
|
2388
|
-
import { loadManifest as
|
|
2740
|
+
import { loadManifest as loadManifest7 } from "@agentspec/sdk";
|
|
2389
2741
|
function sanitizePackageName(name) {
|
|
2390
2742
|
return name.replace(/-/g, "_");
|
|
2391
2743
|
}
|
|
@@ -2398,8 +2750,8 @@ function generateRegoPolicy(manifest) {
|
|
|
2398
2750
|
lines.push(`# Agent: ${agentName}`);
|
|
2399
2751
|
lines.push(`# Generated: ${(/* @__PURE__ */ new Date()).toISOString()}`);
|
|
2400
2752
|
lines.push(`#`);
|
|
2401
|
-
lines.push(`#
|
|
2402
|
-
lines.push(`#
|
|
2753
|
+
lines.push(`# The sidecar's /gap endpoint queries OPA with an input built from the`);
|
|
2754
|
+
lines.push(`# manifest and its probes.`);
|
|
2403
2755
|
lines.push(`# Only deny rules relevant to this agent's manifest declarations are included.`);
|
|
2404
2756
|
lines.push(`#`);
|
|
2405
2757
|
lines.push(`# OPA query: POST /v1/data/agentspec/agent/${packageName}/deny`);
|
|
@@ -2418,7 +2770,7 @@ function generateRegoPolicy(manifest) {
|
|
|
2418
2770
|
if (inputGuardrails.length > 0) {
|
|
2419
2771
|
lines.push(`# \u2500\u2500 Input guardrail enforcement \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`);
|
|
2420
2772
|
lines.push(`# Each declared input guardrail MUST appear in input.guardrails_invoked.`);
|
|
2421
|
-
lines.push(`# The
|
|
2773
|
+
lines.push(`# The sidecar does not populate that list yet: it sends it empty.`);
|
|
2422
2774
|
lines.push(``);
|
|
2423
2775
|
for (const g of inputGuardrails) {
|
|
2424
2776
|
const ruleId = g.type.replace(/-/g, "_") + "_not_invoked";
|
|
@@ -2449,16 +2801,6 @@ function generateRegoPolicy(manifest) {
|
|
|
2449
2801
|
}
|
|
2450
2802
|
}
|
|
2451
2803
|
}
|
|
2452
|
-
if (spec.model.costControls?.maxMonthlyUSD !== void 0) {
|
|
2453
|
-
lines.push(`# \u2500\u2500 Cost control enforcement \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`);
|
|
2454
|
-
lines.push(`# Monthly cost projected from daily spend \xD7 30.`);
|
|
2455
|
-
lines.push(``);
|
|
2456
|
-
lines.push(`deny contains "monthly_cost_limit_exceeded" if {`);
|
|
2457
|
-
lines.push(` input.request_type == "llm_call"`);
|
|
2458
|
-
lines.push(` input.cost_today_usd * 30 > data.maxMonthlyUSD`);
|
|
2459
|
-
lines.push(`}`);
|
|
2460
|
-
lines.push(``);
|
|
2461
|
-
}
|
|
2462
2804
|
const ttlSeconds = spec.memory?.shortTerm?.ttlSeconds;
|
|
2463
2805
|
if (ttlSeconds !== void 0) {
|
|
2464
2806
|
lines.push(`# \u2500\u2500 Memory TTL enforcement \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`);
|
|
@@ -2471,16 +2813,19 @@ function generateRegoPolicy(manifest) {
|
|
|
2471
2813
|
}
|
|
2472
2814
|
const destructiveTools = (spec.tools ?? []).filter((t) => t.annotations?.destructiveHint === true).map((t) => t.name);
|
|
2473
2815
|
if (destructiveTools.length > 0) {
|
|
2474
|
-
lines.push(`# \u2500\u2500 Destructive
|
|
2475
|
-
lines.push(`# Tools annotated destructiveHint=true
|
|
2816
|
+
lines.push(`# \u2500\u2500 Destructive tools \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500`);
|
|
2817
|
+
lines.push(`# Tools annotated destructiveHint=true are always denied here; only the gateway approval token (Phase 5) lifts that.`);
|
|
2476
2818
|
lines.push(``);
|
|
2477
|
-
lines.push(`deny contains "
|
|
2819
|
+
lines.push(`deny contains "destructive_tool_requires_gateway_approval_token" if {`);
|
|
2478
2820
|
lines.push(` some tool in input.tools_called`);
|
|
2479
2821
|
lines.push(` tool in data.destructiveTools`);
|
|
2480
|
-
lines.push(` not input.user_confirmed`);
|
|
2481
2822
|
lines.push(`}`);
|
|
2482
2823
|
lines.push(``);
|
|
2483
2824
|
}
|
|
2825
|
+
if (!lines.some((l) => l.startsWith("deny contains"))) {
|
|
2826
|
+
lines.push(`deny := set()`);
|
|
2827
|
+
lines.push(``);
|
|
2828
|
+
}
|
|
2484
2829
|
return lines.join("\n");
|
|
2485
2830
|
}
|
|
2486
2831
|
function generateDataJson(manifest) {
|
|
@@ -2503,9 +2848,6 @@ function generateDataJson(manifest) {
|
|
|
2503
2848
|
if (spec.memory?.shortTerm?.ttlSeconds !== void 0) {
|
|
2504
2849
|
data.shortTermTtlSeconds = spec.memory.shortTerm.ttlSeconds;
|
|
2505
2850
|
}
|
|
2506
|
-
if (spec.model.costControls?.maxMonthlyUSD !== void 0) {
|
|
2507
|
-
data.maxMonthlyUSD = spec.model.costControls.maxMonthlyUSD;
|
|
2508
|
-
}
|
|
2509
2851
|
if (spec.model.costControls?.alertAtUSD !== void 0) {
|
|
2510
2852
|
data.alertAtUSD = spec.model.costControls.alertAtUSD;
|
|
2511
2853
|
}
|
|
@@ -2526,7 +2868,7 @@ function registerGeneratePolicyCommand(program2) {
|
|
|
2526
2868
|
async (file, opts) => {
|
|
2527
2869
|
let manifest;
|
|
2528
2870
|
try {
|
|
2529
|
-
const result2 =
|
|
2871
|
+
const result2 = loadManifest7(file, { resolve: false });
|
|
2530
2872
|
manifest = result2.manifest;
|
|
2531
2873
|
} catch (err) {
|
|
2532
2874
|
printError(`Cannot load manifest: ${String(err)}`);
|
|
@@ -2567,8 +2909,9 @@ function registerGeneratePolicyCommand(program2) {
|
|
|
2567
2909
|
// src/commands/evaluate.ts
|
|
2568
2910
|
import { readFileSync as readFileSync7, existsSync as existsSync6, realpathSync as realpathSync2 } from "fs";
|
|
2569
2911
|
import { resolve as resolve8, dirname as dirname3, sep as sep2 } from "path";
|
|
2570
|
-
import
|
|
2571
|
-
import {
|
|
2912
|
+
import chalk9 from "chalk";
|
|
2913
|
+
import { createHash } from "crypto";
|
|
2914
|
+
import { loadManifest as loadManifest8 } from "@agentspec/sdk";
|
|
2572
2915
|
function loadDataset(datasetPath) {
|
|
2573
2916
|
if (!existsSync6(datasetPath)) {
|
|
2574
2917
|
throw new Error(`Dataset file not found: ${datasetPath}`);
|
|
@@ -2613,15 +2956,49 @@ async function sendToAgent(baseUrl, chatPath, input, timeoutMs) {
|
|
|
2613
2956
|
function scoreStringMatch(expected, actual) {
|
|
2614
2957
|
return actual.toLowerCase().includes(expected.toLowerCase());
|
|
2615
2958
|
}
|
|
2616
|
-
|
|
2959
|
+
var STRING_MATCH_JUDGE = "string-match";
|
|
2960
|
+
var STRING_MATCH_RUBRIC_HASH = createHash("sha256").update("evaluate: case-insensitive substring match").digest("hex");
|
|
2961
|
+
function wilsonInterval(passed, n) {
|
|
2962
|
+
if (n === 0) return [0, 1];
|
|
2963
|
+
const z = 1.96;
|
|
2964
|
+
const p2 = passed / n;
|
|
2965
|
+
const denom = 1 + z * z / n;
|
|
2966
|
+
const centre = (p2 + z * z / (2 * n)) / denom;
|
|
2967
|
+
const margin = z * Math.sqrt(p2 * (1 - p2) / n + z * z / (4 * n * n)) / denom;
|
|
2968
|
+
return [Math.max(0, centre - margin), Math.min(1, centre + margin)];
|
|
2969
|
+
}
|
|
2970
|
+
function gradeThresholds(minimums, passRate) {
|
|
2971
|
+
return Object.entries(minimums).map(
|
|
2972
|
+
([metric, minimum]) => metric === "pass_rate" && passRate !== null ? { metric, minimum, value: passRate, status: passRate >= minimum ? "pass" : "fail" } : { metric, minimum, status: "not_verifiable" }
|
|
2973
|
+
);
|
|
2974
|
+
}
|
|
2975
|
+
function toEvalResult(graded, passed, total, datasetName, window) {
|
|
2976
|
+
const [ciLow, ciHigh] = wilsonInterval(passed, total);
|
|
2977
|
+
return {
|
|
2978
|
+
metric: graded.metric,
|
|
2979
|
+
n: total,
|
|
2980
|
+
passRate: graded.value,
|
|
2981
|
+
ciLow,
|
|
2982
|
+
ciHigh,
|
|
2983
|
+
threshold: graded.minimum,
|
|
2984
|
+
window,
|
|
2985
|
+
judgeModel: STRING_MATCH_JUDGE,
|
|
2986
|
+
rubricHash: STRING_MATCH_RUBRIC_HASH,
|
|
2987
|
+
source: "independent",
|
|
2988
|
+
dataset: datasetName
|
|
2989
|
+
};
|
|
2990
|
+
}
|
|
2991
|
+
function buildReport(results, datasetName, agentUrl, manifest, window = { start: (/* @__PURE__ */ new Date()).toISOString(), end: (/* @__PURE__ */ new Date()).toISOString() }) {
|
|
2617
2992
|
const total = results.length;
|
|
2618
2993
|
const passed = results.filter((r) => r.pass).length;
|
|
2619
|
-
const passRate = total === 0 ?
|
|
2620
|
-
const
|
|
2994
|
+
const passRate = total === 0 ? null : passed / total;
|
|
2995
|
+
const minimums = manifest.spec.evaluation?.thresholds ?? {};
|
|
2996
|
+
const thresholds = gradeThresholds(minimums, passRate);
|
|
2997
|
+
const evalResults = thresholds.filter((t) => t.status !== "not_verifiable").map((t) => toEvalResult(t, passed, total, datasetName, window));
|
|
2621
2998
|
const ciGate = manifest.spec.evaluation?.ciGate ?? false;
|
|
2622
2999
|
let ciGateResult = "N/A";
|
|
2623
|
-
if (ciGate &&
|
|
2624
|
-
ciGateResult =
|
|
3000
|
+
if (ciGate && thresholds.length > 0) {
|
|
3001
|
+
ciGateResult = thresholds.every((t) => t.status === "pass") ? "PASS" : "FAIL";
|
|
2625
3002
|
}
|
|
2626
3003
|
return {
|
|
2627
3004
|
dataset: datasetName,
|
|
@@ -2630,7 +3007,9 @@ function buildReport(results, datasetName, agentUrl, manifest) {
|
|
|
2630
3007
|
metrics: {
|
|
2631
3008
|
pass_rate: passRate
|
|
2632
3009
|
},
|
|
2633
|
-
threshold,
|
|
3010
|
+
threshold: minimums["pass_rate"],
|
|
3011
|
+
thresholds,
|
|
3012
|
+
evalResults,
|
|
2634
3013
|
ciGateResult,
|
|
2635
3014
|
samples: results
|
|
2636
3015
|
};
|
|
@@ -2638,33 +3017,40 @@ function buildReport(results, datasetName, agentUrl, manifest) {
|
|
|
2638
3017
|
function printTable(report) {
|
|
2639
3018
|
printHeader(`AgentSpec Evaluate \u2014 ${report.dataset}`);
|
|
2640
3019
|
console.log(
|
|
2641
|
-
` Evaluating: ${
|
|
3020
|
+
` Evaluating: ${chalk9.bold(report.dataset)} ${chalk9.gray(String(report.totalSamples) + " samples")} agent: ${chalk9.cyan(report.agentUrl)}`
|
|
2642
3021
|
);
|
|
2643
|
-
console.log(
|
|
3022
|
+
console.log(chalk9.gray(" " + "\u2500".repeat(65)));
|
|
2644
3023
|
console.log();
|
|
2645
3024
|
for (const s of report.samples) {
|
|
2646
|
-
const icon = s.pass ?
|
|
2647
|
-
const expected =
|
|
3025
|
+
const icon = s.pass ? chalk9.green(" \u2713") : chalk9.red(" \u2717");
|
|
3026
|
+
const expected = chalk9.gray(`"${s.expected}"`);
|
|
2648
3027
|
if (s.error) {
|
|
2649
|
-
console.log(`${icon} ${String(s.index + 1).padStart(2)} ${
|
|
3028
|
+
console.log(`${icon} ${String(s.index + 1).padStart(2)} ${chalk9.gray(s.input.slice(0, 50))} \u2192 ${chalk9.red("error: " + s.error)}`);
|
|
2650
3029
|
} else if (s.pass) {
|
|
2651
|
-
console.log(`${icon} ${String(s.index + 1).padStart(2)} ${
|
|
3030
|
+
console.log(`${icon} ${String(s.index + 1).padStart(2)} ${chalk9.gray(s.input.slice(0, 50))} \u2192 found ${expected} ${chalk9.gray("[" + s.latencyMs + "ms]")}`);
|
|
2652
3031
|
} else {
|
|
2653
|
-
console.log(`${icon} ${String(s.index + 1).padStart(2)} ${
|
|
3032
|
+
console.log(`${icon} ${String(s.index + 1).padStart(2)} ${chalk9.gray(s.input.slice(0, 50))} \u2192 expected ${expected} not found ${chalk9.gray("[" + s.latencyMs + "ms]")}`);
|
|
2654
3033
|
}
|
|
2655
3034
|
}
|
|
2656
3035
|
console.log();
|
|
2657
|
-
console.log(
|
|
3036
|
+
console.log(chalk9.bold(" Results"));
|
|
2658
3037
|
const { pass_rate } = report.metrics;
|
|
2659
|
-
|
|
2660
|
-
|
|
2661
|
-
|
|
2662
|
-
|
|
2663
|
-
|
|
2664
|
-
)
|
|
3038
|
+
if (pass_rate !== null) {
|
|
3039
|
+
const pct = Math.round(pass_rate * 100);
|
|
3040
|
+
const pctColor = scoreColor(pct);
|
|
3041
|
+
const threshStr = report.threshold !== void 0 ? `(threshold: ${Math.round(report.threshold * 100)}%)` : "(no threshold declared)";
|
|
3042
|
+
console.log(
|
|
3043
|
+
` pass_rate ${pctColor(pct + "%")} ${chalk9.gray(threshStr)} ${formatCiGate(report.ciGateResult)}`
|
|
3044
|
+
);
|
|
3045
|
+
}
|
|
3046
|
+
for (const t of report.thresholds.filter((t2) => t2.status === "not_verifiable")) {
|
|
3047
|
+
console.log(
|
|
3048
|
+
` ${t.metric.padEnd(13)} ${chalk9.yellow("not_verifiable")} ${chalk9.gray(`(minimum ${Math.round(t.minimum * 100)}%; evaluate cannot compute it)`)}`
|
|
3049
|
+
);
|
|
3050
|
+
}
|
|
2665
3051
|
console.log();
|
|
2666
3052
|
console.log(` ciGate: ${formatCiGate(report.ciGateResult)}`);
|
|
2667
|
-
console.log(` Exit code: ${report.ciGateResult === "FAIL" ?
|
|
3053
|
+
console.log(` Exit code: ${report.ciGateResult === "FAIL" ? chalk9.red("1") : chalk9.green("0")}`);
|
|
2668
3054
|
console.log();
|
|
2669
3055
|
}
|
|
2670
3056
|
function printJSON(report) {
|
|
@@ -2710,7 +3096,7 @@ function registerEvaluateCommand(program2) {
|
|
|
2710
3096
|
async (file, opts) => {
|
|
2711
3097
|
let parsed;
|
|
2712
3098
|
try {
|
|
2713
|
-
parsed =
|
|
3099
|
+
parsed = loadManifest8(file, { resolve: false });
|
|
2714
3100
|
} catch (err) {
|
|
2715
3101
|
printError(`Cannot load manifest: ${String(err)}`);
|
|
2716
3102
|
process.exit(1);
|
|
@@ -2778,8 +3164,9 @@ function registerEvaluateCommand(program2) {
|
|
|
2778
3164
|
}
|
|
2779
3165
|
}
|
|
2780
3166
|
const chatPath = resolveChatEndpoint(manifest);
|
|
3167
|
+
const start = (/* @__PURE__ */ new Date()).toISOString();
|
|
2781
3168
|
const results = await runInference(samples, opts.url, chatPath, timeoutMs);
|
|
2782
|
-
const report = buildReport(results, opts.dataset, opts.url, manifest);
|
|
3169
|
+
const report = buildReport(results, opts.dataset, opts.url, manifest, { start, end: (/* @__PURE__ */ new Date()).toISOString() });
|
|
2783
3170
|
if (opts.json) {
|
|
2784
3171
|
printJSON(report);
|
|
2785
3172
|
} else {
|
|
@@ -2790,84 +3177,9 @@ function registerEvaluateCommand(program2) {
|
|
|
2790
3177
|
);
|
|
2791
3178
|
}
|
|
2792
3179
|
|
|
2793
|
-
// src/commands/probe.ts
|
|
2794
|
-
import { spawnSync } from "child_process";
|
|
2795
|
-
import { existsSync as existsSync7 } from "fs";
|
|
2796
|
-
import chalk9 from "chalk";
|
|
2797
|
-
function registerProbeCommand(program2) {
|
|
2798
|
-
const probe = program2.command("probe").description("Run external probes to generate compliance proof records");
|
|
2799
|
-
probe.command("pii <file>").description("Scan agent outputs or logs for unredacted PII (proves SEC-LLM-06, MEM-01, OBS-03)").option("--log-file <path>", "Log file to scan line-by-line (proves OBS-03)").option("--text <text>", "Text to scan for PII; repeat for multiple (proves SEC-LLM-06 + MEM-01)", collect, []).option("--sidecar-url <url>", "Sidecar URL to submit proof on pass (e.g. http://localhost:4001)").option("--submit", "Auto-submit proof to sidecar when scan passes (requires --sidecar-url)").option("--threshold <float>", "Minimum Presidio confidence score to report as PII (default: 0.7)").option("--json", "Output ProbeScanResult as JSON").action(
|
|
2800
|
-
(file, opts) => {
|
|
2801
|
-
if (opts.logFile && opts.text && opts.text.length > 0) {
|
|
2802
|
-
console.error(chalk9.red(" \u2717 --log-file and --text are mutually exclusive"));
|
|
2803
|
-
process.exit(1);
|
|
2804
|
-
}
|
|
2805
|
-
if (!opts.logFile && (!opts.text || opts.text.length === 0)) {
|
|
2806
|
-
console.error(chalk9.red(" \u2717 Provide --log-file <path> or --text <text> (at least one required)"));
|
|
2807
|
-
process.exit(1);
|
|
2808
|
-
}
|
|
2809
|
-
if (opts.submit && !opts.sidecarUrl) {
|
|
2810
|
-
console.error(chalk9.red(" \u2717 --submit requires --sidecar-url"));
|
|
2811
|
-
process.exit(1);
|
|
2812
|
-
}
|
|
2813
|
-
if (opts.threshold !== void 0) {
|
|
2814
|
-
const t = parseFloat(opts.threshold);
|
|
2815
|
-
if (isNaN(t) || t < 0 || t > 1) {
|
|
2816
|
-
console.error(chalk9.red(" \u2717 --threshold must be a number between 0.0 and 1.0"));
|
|
2817
|
-
process.exit(1);
|
|
2818
|
-
}
|
|
2819
|
-
}
|
|
2820
|
-
if (opts.logFile && !existsSync7(opts.logFile)) {
|
|
2821
|
-
console.error(chalk9.red(` \u2717 Log file not found: ${opts.logFile}`));
|
|
2822
|
-
process.exit(1);
|
|
2823
|
-
}
|
|
2824
|
-
const pyArgs = ["-m", "agentspec.presidio_probe", "--manifest", file];
|
|
2825
|
-
if (opts.logFile) {
|
|
2826
|
-
pyArgs.push("--log-file", opts.logFile);
|
|
2827
|
-
}
|
|
2828
|
-
for (const t of opts.text ?? []) {
|
|
2829
|
-
pyArgs.push("--text", t);
|
|
2830
|
-
}
|
|
2831
|
-
if (opts.sidecarUrl) {
|
|
2832
|
-
pyArgs.push("--sidecar-url", opts.sidecarUrl);
|
|
2833
|
-
}
|
|
2834
|
-
if (opts.submit) {
|
|
2835
|
-
pyArgs.push("--submit");
|
|
2836
|
-
}
|
|
2837
|
-
if (opts.threshold) {
|
|
2838
|
-
pyArgs.push("--threshold", opts.threshold);
|
|
2839
|
-
}
|
|
2840
|
-
if (opts.json) {
|
|
2841
|
-
pyArgs.push("--json");
|
|
2842
|
-
}
|
|
2843
|
-
const python = resolvePython();
|
|
2844
|
-
if (!python) {
|
|
2845
|
-
console.error(chalk9.red(" \u2717 Python 3 not found. Install Python 3.10+ to use agentspec probe."));
|
|
2846
|
-
process.exit(1);
|
|
2847
|
-
}
|
|
2848
|
-
const result = spawnSync(python, pyArgs, { stdio: "inherit" });
|
|
2849
|
-
if (result.error) {
|
|
2850
|
-
console.error(chalk9.red(` \u2717 Failed to run Presidio probe: ${result.error.message}`));
|
|
2851
|
-
console.error(chalk9.gray(` Ensure the agentspec Python SDK is installed: pip install agentspec`));
|
|
2852
|
-
process.exit(1);
|
|
2853
|
-
}
|
|
2854
|
-
process.exit(result.status ?? 1);
|
|
2855
|
-
}
|
|
2856
|
-
);
|
|
2857
|
-
}
|
|
2858
|
-
function collect(val, prev) {
|
|
2859
|
-
return [...prev, val];
|
|
2860
|
-
}
|
|
2861
|
-
function resolvePython() {
|
|
2862
|
-
for (const bin of ["python3", "python"]) {
|
|
2863
|
-
const probe = spawnSync(bin, ["--version"], { stdio: "pipe" });
|
|
2864
|
-
if (probe.status === 0) return bin;
|
|
2865
|
-
}
|
|
2866
|
-
return null;
|
|
2867
|
-
}
|
|
2868
|
-
|
|
2869
3180
|
// src/commands/provider-status.ts
|
|
2870
3181
|
import chalk10 from "chalk";
|
|
3182
|
+
import { CONTRACT as CONTRACT7 } from "@agentspec/sdk";
|
|
2871
3183
|
import {
|
|
2872
3184
|
probeProviders
|
|
2873
3185
|
} from "@agentspec/codegen";
|
|
@@ -2953,9 +3265,9 @@ function renderAnthropicApi(result) {
|
|
|
2953
3265
|
}
|
|
2954
3266
|
const baseURL = getString(d, "baseURL");
|
|
2955
3267
|
if (baseURL) {
|
|
2956
|
-
row(
|
|
3268
|
+
row(CONTRACT7.providerBaseUrlEnv.anthropic, chalk10.cyan(baseURL), tick);
|
|
2957
3269
|
} else {
|
|
2958
|
-
row(
|
|
3270
|
+
row(CONTRACT7.providerBaseUrlEnv.anthropic, chalk10.dim("not set (using default)"), dash);
|
|
2959
3271
|
}
|
|
2960
3272
|
}
|
|
2961
3273
|
function renderOpenAICompatible(result) {
|
|
@@ -3079,14 +3391,38 @@ function registerProviderStatusCommand(program2) {
|
|
|
3079
3391
|
});
|
|
3080
3392
|
}
|
|
3081
3393
|
|
|
3394
|
+
// src/commands/gateway-config.ts
|
|
3395
|
+
import { mkdirSync as mkdirSync4, writeFileSync as writeFileSync7 } from "fs";
|
|
3396
|
+
import { dirname as dirname4 } from "path";
|
|
3397
|
+
import { describeManifestError, loadManifest as loadManifest9, renderGatewayConfig } from "@agentspec/sdk";
|
|
3398
|
+
function registerGatewayConfigCommand(program2) {
|
|
3399
|
+
program2.command("gateway-config <file>").description("Render the agentgateway config from an agent.yaml manifest").option("--out <path>", "Write the config to this file instead of stdout").action((file, opts) => {
|
|
3400
|
+
try {
|
|
3401
|
+
const { manifest } = loadManifest9(file, { resolve: false });
|
|
3402
|
+
const rendered = renderGatewayConfig(manifest);
|
|
3403
|
+
if (!opts.out) {
|
|
3404
|
+
process.stdout.write(rendered);
|
|
3405
|
+
return;
|
|
3406
|
+
}
|
|
3407
|
+
mkdirSync4(dirname4(opts.out), { recursive: true });
|
|
3408
|
+
writeFileSync7(opts.out, rendered);
|
|
3409
|
+
} catch (err) {
|
|
3410
|
+
printError(`gateway-config failed for ${file}:
|
|
3411
|
+
${describeManifestError(err)}`);
|
|
3412
|
+
process.exit(1);
|
|
3413
|
+
}
|
|
3414
|
+
});
|
|
3415
|
+
}
|
|
3416
|
+
|
|
3082
3417
|
// src/cli.ts
|
|
3083
|
-
var _dir =
|
|
3418
|
+
var _dir = dirname5(fileURLToPath(import.meta.url));
|
|
3084
3419
|
var { version } = JSON.parse(readFileSync8(join7(_dir, "../package.json"), "utf8"));
|
|
3085
3420
|
var program = new Command();
|
|
3086
3421
|
program.name("agentspec").description("Universal Agent Manifest System \u2014 validate, health-check, audit, and generate agents").version(version);
|
|
3087
3422
|
registerValidateCommand(program);
|
|
3088
3423
|
registerHealthCommand(program);
|
|
3089
3424
|
registerAuditCommand(program);
|
|
3425
|
+
registerRegisterCommand(program);
|
|
3090
3426
|
registerInitCommand(program);
|
|
3091
3427
|
registerGenerateCommand(program);
|
|
3092
3428
|
registerExportCommand(program);
|
|
@@ -3094,8 +3430,8 @@ registerMigrateCommand(program);
|
|
|
3094
3430
|
registerScanCommand(program);
|
|
3095
3431
|
registerDiffCommand(program);
|
|
3096
3432
|
registerGeneratePolicyCommand(program);
|
|
3433
|
+
registerGatewayConfigCommand(program);
|
|
3097
3434
|
registerEvaluateCommand(program);
|
|
3098
|
-
registerProbeCommand(program);
|
|
3099
3435
|
registerProviderStatusCommand(program);
|
|
3100
3436
|
program.parse(process.argv);
|
|
3101
3437
|
//# sourceMappingURL=cli.js.map
|