@2kw/ai 6.2.0-dev.14 → 6.2.0-dev.25

package/README.md

@@ -99,7 +99,7 @@ kubectl-style contexts switch between organizations and environments:
 | `prompts` | Versioned prompt management, labels, compilation, testing |
 | `extractions` | Create extractions (text, file, images), list, re-run, estimate tokens |
 | `convert` | Convert PDF, DOCX, XLSX, images, and 20+ formats to Markdown/text/HTML/JSON |
-| `ai` | Chat completions, Responses (agent or direct model, streaming), and model listing via the OpenAI-compatible gateway |
+| `ai` | Chat completions, Responses (agent or direct model), and model listing via the OpenAI-compatible gateway |
 | `transcribe` | Transcribe audio (FLAC, MP3, MP4, OGG, WAV, WebM) |
 | `datasets` | Build datasets and dataset versions for evaluation |
 | `experiments` | Run experiments against datasets |
@@ -109,7 +109,7 @@ kubectl-style contexts switch between organizations and environments:
 | `providers` | Manage BYOK AI providers |
 | `analytics` | Usage analytics: spend, quality, providers, errors |
 | `billing` | Check subscription tier and usage limits |
-| `agents` | Manage agents, versions, labels, approvals, and tool catalogs |
+| `agents` | Run agents and decide approvals; apply, export and scaffold agent.yaml; manage versions, labels, approvals and tool catalogs |
 | `conversations` | Create and manage conversations and their items |
 | `knowledge` | Manage knowledge bases, documents, search, and citations |
 | `files` | Upload, download, and manage files |

package/dist/agent-config/export.d.ts

@@ -0,0 +1,31 @@
+import type { AgentConfig } from "./validate.js";
+export declare function secretEnvName(toolName: string): string;
+/**
+ * `apply` resolves `${NAME}` in every string value and reads `$${` as a literal `${`. Stored text is
+ * escaped so an exported file re-applies unchanged; run before `redactSecrets` inserts real placeholders.
+ */
+export declare function escapePlaceholders<T>(value: T): T;
+/** The API returns webhook secrets in plaintext (#669); exported files carry placeholders instead. */
+export declare function redactSecrets(tools: Record<string, unknown>[] | undefined): {
+    tools: Record<string, unknown>[] | undefined;
+    envNames: string[];
+};
+/**
+ * Tool entries the backend stores but never runs (planner/runtime-injected or executor-less,
+ * e.g. a console-stored `web_search`). agent.yaml cannot author them, so export drops them.
+ */
+export declare function dropInertTools(tools: Record<string, unknown>[] | undefined): {
+    tools: Record<string, unknown>[] | undefined;
+    dropped: string[];
+};
+export declare function versionToConfig(agent: {
+    name: string;
+    description?: string | null;
+}, version: Record<string, unknown>): AgentConfig;
+export declare function toAgentYaml(config: AgentConfig, meta: {
+    agent: string;
+    label: string;
+    versionNumber: number | null;
+    date: string;
+}): string;
+//# sourceMappingURL=export.d.ts.map

package/dist/agent-config/export.js

@@ -0,0 +1,87 @@
+import { stringify } from "yaml";
+import { CliUsageError } from "../lib/errors.js";
+import { isEmptyValue } from "./plan.js";
+import { AGENT_SCHEMA_ID, NON_AUTHORABLE_TOOL_TYPES } from "./schema.js";
+export function secretEnvName(toolName) {
+    return `AGENT_${toolName.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_SECRET`;
+}
+/**
+ * `apply` resolves `${NAME}` in every string value and reads `$${` as a literal `${`. Stored text is
+ * escaped so an exported file re-applies unchanged; run before `redactSecrets` inserts real placeholders.
+ */
+export function escapePlaceholders(value) {
+    const walk = (v) => {
+        // A function replacer: in a replacement string `$$` would collapse to a single `$`.
+        if (typeof v === "string")
+            return v.replaceAll("${", () => "$${");
+        if (Array.isArray(v))
+            return v.map(walk);
+        if (v && typeof v === "object")
+            return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, walk(x)]));
+        return v;
+    };
+    return walk(value);
+}
+/** The API returns webhook secrets in plaintext (#669); exported files carry placeholders instead. */
+export function redactSecrets(tools) {
+    if (!tools)
+        return { tools, envNames: [] };
+    // env name → the tool that claimed it; two tools sharing one variable would get one secret on re-apply.
+    const owners = new Map();
+    const redacted = tools.map((tool) => {
+        if (typeof tool.secret !== "string" || tool.secret === "")
+            return tool;
+        const toolName = String(tool.name ?? "tool");
+        const name = secretEnvName(toolName);
+        const owner = owners.get(name);
+        if (owner !== undefined) {
+            throw new CliUsageError(`Tools "${owner}" and "${toolName}" both map to ${name}; rename one tool or export with --include-secrets.`);
+        }
+        owners.set(name, toolName);
+        return { ...tool, secret: `\${${name}}` };
+    });
+    return { tools: redacted, envNames: [...owners.keys()] };
+}
+/**
+ * Tool entries the backend stores but never runs (planner/runtime-injected or executor-less,
+ * e.g. a console-stored `web_search`). agent.yaml cannot author them, so export drops them.
+ */
+export function dropInertTools(tools) {
+    if (!tools)
+        return { tools, dropped: [] };
+    const dropped = [];
+    const kept = tools.filter((tool) => {
+        const type = tool.type;
+        if (typeof type === "string" && Object.hasOwn(NON_AUTHORABLE_TOOL_TYPES, type)) {
+            dropped.push(type);
+            return false;
+        }
+        return true;
+    });
+    return { tools: kept.length ? kept : undefined, dropped };
+}
+export function versionToConfig(agent, version) {
+    const config = { name: agent.name };
+    if (!isEmptyValue(agent.description))
+        config.description = agent.description;
+    // One model exports as `model`, as before lists existed; a list exports as `models` alone (model is its first entry).
+    const models = Array.isArray(version.models) ? version.models : [];
+    if (models.length > 1)
+        config.models = models;
+    else
+        config.model = version.model ?? models[0];
+    for (const field of ["instructions", "tools", "hitlPolicy", "options", "skills"]) {
+        if (!isEmptyValue(version[field]))
+            config[field] = version[field];
+    }
+    return config;
+}
+export function toAgentYaml(config, meta) {
+    const version = meta.versionNumber !== null ? ` (version ${meta.versionNumber})` : "";
+    const header = [
+        `# yaml-language-server: $schema=${AGENT_SCHEMA_ID}`,
+        `# exported from ${meta.agent}@${meta.label}${version} on ${meta.date}`,
+    ].join("\n");
+    return `${header}\n${stringify(config, { lineWidth: 0 })}`;
+}
+//# sourceMappingURL=export.js.map

package/dist/agent-config/file.d.ts

@@ -0,0 +1,20 @@
+import { type AgentConfig } from "./validate.js";
+export declare function parseAgentText(text: string, format: "yaml" | "json", source: string): unknown;
+/**
+ * Resolves `${NAME}` placeholders in every string of `value` from `env`; `$${` stays a literal `${`.
+ * A resolved value is reported as a secret only if it was resolved inside the string value of a key
+ * named `secret` (at any depth), or its variable name matches SECRET|TOKEN|PASSWORD|PASSWD|PASS|API_?KEY|
+ * KEY|PRIVATE|CREDENTIAL|AUTH. Other resolved values (hosts, model names) are not secrets. Empty values
+ * are never secrets. Missing names are listed once each, in first-seen order.
+ */
+export declare function interpolateEnv(value: unknown, env: Record<string, string | undefined>): {
+    value: unknown;
+    missing: string[];
+    secrets: string[];
+};
+export declare function maskSecrets<T>(value: T, secrets: string[]): T;
+export declare function loadAgentConfig(path: string, env: Record<string, string | undefined>, readStdin?: () => string): {
+    config: AgentConfig;
+    secrets: string[];
+};
+//# sourceMappingURL=file.d.ts.map

package/dist/agent-config/file.js

@@ -0,0 +1,137 @@
+import { readFileSync } from "node:fs";
+import { extname } from "node:path";
+import { parse, YAMLParseError } from "yaml";
+import { CliUsageError } from "../lib/errors.js";
+import { validateAgentConfig } from "./validate.js";
+const PLACEHOLDER = /\$\$\{|\$\{([A-Z_][A-Z0-9_]*)\}/g;
+/** Variable names whose value is a secret wherever it is used. */
+const SECRET_NAME = /(SECRET|TOKEN|PASSWORD|PASSWD|PASS|API_?KEY|KEY|PRIVATE|CREDENTIAL|AUTH)/;
+const BOM = "\uFEFF";
+export function parseAgentText(text, format, source) {
+    const body = text.startsWith(BOM) ? text.slice(BOM.length) : text;
+    if (format === "json") {
+        try {
+            return JSON.parse(body);
+        }
+        catch (err) {
+            throw new CliUsageError(`${source}: ${err.message}`);
+        }
+    }
+    try {
+        return parse(body);
+    }
+    catch (err) {
+        if (err instanceof YAMLParseError) {
+            const pos = err.linePos?.[0];
+            const where = pos ? `${pos.line}:${pos.col}` : "?";
+            // The first line ends with " at line L, column C:", which the prefix already says.
+            const first = err.message.split("\n")[0];
+            const at = first.indexOf(" at line ");
+            throw new CliUsageError(`${source}:${where}: ${at === -1 ? first : first.slice(0, at)}`);
+        }
+        // e.g. an unresolved alias throws a ReferenceError: still a problem with the file, not the CLI.
+        throw new CliUsageError(`${source}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Resolves `${NAME}` placeholders in every string of `value` from `env`; `$${` stays a literal `${`.
+ * A resolved value is reported as a secret only if it was resolved inside the string value of a key
+ * named `secret` (at any depth), or its variable name matches SECRET|TOKEN|PASSWORD|PASSWD|PASS|API_?KEY|
+ * KEY|PRIVATE|CREDENTIAL|AUTH. Other resolved values (hosts, model names) are not secrets. Empty values
+ * are never secrets. Missing names are listed once each, in first-seen order.
+ */
+export function interpolateEnv(value, env) {
+    const missing = new Set();
+    const secrets = new Set();
+    const walk = (v, key) => {
+        if (typeof v === "string") {
+            return v.replace(PLACEHOLDER, (match, name) => {
+                if (!name)
+                    return "${";
+                const resolved = env[name];
+                if (resolved === undefined) {
+                    missing.add(name);
+                    return match;
+                }
+                if (resolved && (key === "secret" || SECRET_NAME.test(name)))
+                    secrets.add(resolved);
+                return resolved;
+            });
+        }
+        if (Array.isArray(v))
+            return v.map((x) => walk(x));
+        if (v && typeof v === "object")
+            return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, walk(x, k)]));
+        return v;
+    };
+    const out = walk(value);
+    return { value: out, missing: [...missing], secrets: [...secrets] };
+}
+/** Replaces every occurrence of every secret in `text` with `***`; overlapping or adjacent matches become one mask. */
+function maskText(text, secrets) {
+    const ranges = [];
+    for (const secret of secrets) {
+        for (let at = text.indexOf(secret); at !== -1; at = text.indexOf(secret, at + 1)) {
+            ranges.push([at, at + secret.length]);
+        }
+    }
+    if (!ranges.length)
+        return text;
+    ranges.sort((a, b) => a[0] - b[0] || b[1] - a[1]);
+    const merged = [];
+    for (const [start, end] of ranges) {
+        const last = merged[merged.length - 1];
+        if (last && start <= last[1])
+            last[1] = Math.max(last[1], end);
+        else
+            merged.push([start, end]);
+    }
+    let out = "";
+    let cursor = 0;
+    for (const [start, end] of merged) {
+        out += `${text.slice(cursor, start)}***`;
+        cursor = end;
+    }
+    return out + text.slice(cursor);
+}
+export function maskSecrets(value, secrets) {
+    const known = [...new Set(secrets.filter((s) => s.length > 0))].sort((a, b) => b.length - a.length);
+    const walk = (v, key) => {
+        if (key === "secret" && typeof v === "string")
+            return "***";
+        if (typeof v === "string")
+            return maskText(v, known);
+        if (Array.isArray(v))
+            return v.map((x) => walk(x));
+        if (v && typeof v === "object")
+            return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, walk(x, k)]));
+        return v;
+    };
+    return walk(value);
+}
+function readAgentFile(path) {
+    try {
+        return readFileSync(path, "utf-8");
+    }
+    catch (err) {
+        const code = err.code;
+        throw new CliUsageError(`${path}: cannot read file (${code ?? err.message})`);
+    }
+}
+export function loadAgentConfig(path, env, readStdin = () => readFileSync(0, "utf-8")) {
+    const fromStdin = path === "-";
+    const source = fromStdin ? "stdin" : path;
+    const text = fromStdin ? readStdin() : readAgentFile(path);
+    const format = !fromStdin && extname(path).toLowerCase() === ".json" ? "json" : "yaml";
+    const parsed = parseAgentText(text, format, source);
+    const { value, missing, secrets } = interpolateEnv(parsed, env);
+    if (missing.length) {
+        throw new CliUsageError(`Missing environment variables: ${missing.join(", ")}`);
+    }
+    const issues = validateAgentConfig(value);
+    if (issues.length) {
+        throw new CliUsageError(`${source} is invalid:\n${issues.map((i) => `  ${i.pointer}: ${i.message}`).join("\n")}`);
+    }
+    return { config: value, secrets };
+}
+//# sourceMappingURL=file.js.map

package/dist/agent-config/plan.d.ts

@@ -0,0 +1,33 @@
+import type { AgentConfig } from "./validate.js";
+/** Version fields a file carries; any change publishes a new version. */
+export declare const CONFIG_FIELDS: readonly ["model", "models", "instructions", "tools", "hitlPolicy", "options", "skills"];
+/**
+ * The ordered model list a file or a stored version stands for (#591): `models` when non-empty, else `[model]`.
+ * The backend stores both (`model` = `models[0]`) and backfills `models` from `model`, so the list is what compares.
+ */
+export declare function effectiveModels(source: {
+    model?: unknown;
+    models?: unknown;
+} | undefined): string[];
+export type ApplyAction = "created" | "versioned" | "updated" | "unchanged";
+export interface FieldChange {
+    field: string;
+    from: unknown;
+    to: unknown;
+}
+export interface ApplyPlan {
+    action: ApplyAction;
+    changes: FieldChange[];
+    configChanged: boolean;
+    descriptionChanged: boolean;
+}
+export declare function isEmptyValue(v: unknown): boolean;
+/** Stable JSON: object keys sorted at every depth (jsonb does not keep key order). */
+export declare function canonical(v: unknown): string;
+export declare function planApply(config: AgentConfig, existing?: {
+    agent: {
+        description?: string | null;
+    };
+    latest?: Record<string, unknown>;
+}): ApplyPlan;
+//# sourceMappingURL=plan.d.ts.map

package/dist/agent-config/plan.js

@@ -0,0 +1,100 @@
+/** Version fields a file carries; any change publishes a new version. */
+export const CONFIG_FIELDS = ["model", "models", "instructions", "tools", "hitlPolicy", "options", "skills"];
+/**
+ * The ordered model list a file or a stored version stands for (#591): `models` when non-empty, else `[model]`.
+ * The backend stores both (`model` = `models[0]`) and backfills `models` from `model`, so the list is what compares.
+ */
+export function effectiveModels(source) {
+    if (Array.isArray(source?.models) && source.models.length > 0)
+        return source.models.map(String);
+    return typeof source?.model === "string" && source.model !== "" ? [source.model] : [];
+}
+export function isEmptyValue(v) {
+    if (v === null || v === undefined || v === "")
+        return true;
+    if (Array.isArray(v))
+        return v.length === 0;
+    if (typeof v === "object")
+        return Object.keys(v).length === 0;
+    return false;
+}
+/** Stable JSON: object keys sorted at every depth (jsonb does not keep key order). */
+export function canonical(v) {
+    const sort = (x) => {
+        if (Array.isArray(x))
+            return x.map(sort);
+        if (x && typeof x === "object") {
+            return Object.fromEntries(Object.keys(x).sort().map((k) => [k, sort(x[k])]));
+        }
+        return x;
+    };
+    return JSON.stringify(sort(v)) ?? "undefined";
+}
+function same(a, b) {
+    if (isEmptyValue(a) && isEmptyValue(b))
+        return true;
+    return canonical(a) === canonical(b);
+}
+const shown = (v) => (isEmptyValue(v) ? undefined : v);
+/**
+ * The backend stores every skill binding with an explicit, trimmed ref: a missing or null ref becomes "latest"
+ * (SkillBindings.java), so a missing or blank ref compares as "latest" and any other ref compares trimmed.
+ */
+function withDefaultRefs(field, v) {
+    if (field !== "skills" || !Array.isArray(v))
+        return v;
+    return v.map((b) => {
+        if (!b || typeof b !== "object")
+            return b;
+        const ref = b.ref;
+        if (ref == null)
+            return { ...b, ref: "latest" };
+        if (typeof ref !== "string")
+            return b;
+        return { ...b, ref: ref.trim() === "" ? "latest" : ref.trim() };
+    });
+}
+export function planApply(config, existing) {
+    const desired = config;
+    const changes = [];
+    const descriptionFrom = existing?.agent.description;
+    const descriptionChanged = !same(descriptionFrom, config.description);
+    if (descriptionChanged)
+        changes.push({ field: "description", from: shown(descriptionFrom), to: shown(config.description) });
+    let configChanged = false;
+    // Order matters: the first entry is the default. A single-model change reads as `model`, as before lists existed.
+    const modelsFrom = effectiveModels(existing?.latest);
+    const modelsTo = effectiveModels(config);
+    if (canonical(modelsFrom) !== canonical(modelsTo)) {
+        configChanged = true;
+        if (modelsFrom.length <= 1 && modelsTo.length <= 1) {
+            changes.push({ field: "model", from: modelsFrom[0], to: modelsTo[0] });
+        }
+        else {
+            changes.push({ field: "models", from: shown(modelsFrom), to: shown(modelsTo) });
+        }
+    }
+    for (const field of CONFIG_FIELDS) {
+        if (field === "model" || field === "models")
+            continue;
+        const from = existing?.latest?.[field];
+        if (!same(withDefaultRefs(field, from), withDefaultRefs(field, desired[field]))) {
+            configChanged = true;
+            changes.push({ field, from: shown(from), to: shown(desired[field]) });
+        }
+    }
+    // An existing agent without any version always needs its first version, even if the diff is empty.
+    if (existing && !existing.latest)
+        configChanged = true;
+    let action;
+    if (!existing)
+        action = "created";
+    else if (configChanged)
+        action = "versioned";
+    else if (descriptionChanged)
+        action = "updated";
+    else
+        action = "unchanged";
+    return { action, changes, configChanged, descriptionChanged };
+}
+//# sourceMappingURL=plan.js.map