@agenthippo-ai/agenthippo 0.1.1 → 1.110.9

package/out/pack/lease-schema.js

@@ -0,0 +1,270 @@
+"use strict";
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) AgentHippo.ai. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DENY_SCOPE_ALIASES = exports.DENY_MODE_ALIASES = exports.STRICTEST_DENY_MODE = exports.DENY_MODES = exports.DENY_SCOPES = exports.STRICTEST_ON_BREACH = exports.ON_BREACH_ALIASES = exports.ON_BREACH_ACTIONS = exports.DEPRECATED_CAP_SPELLINGS = exports.LEASE_CAP_ALIASES = exports.LEASE_CAP_FIELDS = void 0;
+exports.parseCapPolicy = parseCapPolicy;
+exports.parseLease = parseLease;
+// ---------------------------------------------------------------------------------------------
+// Vocabulary tables — extend these, not the code below
+// ---------------------------------------------------------------------------------------------
+/** Numeric cap fields, and what a valid value looks like. */
+exports.LEASE_CAP_FIELDS = {
+    maxTurnsPerSession: { kind: 'positive-int' },
+    maxSessionSeconds: { kind: 'positive-int' },
+    maxConcurrentSandboxes: { kind: 'positive-int' },
+};
+/**
+ * Alternative spellings for cap fields, mapped onto the canonical name.
+ *
+ * The extension point for vocabulary migrations. Adding a row is the entire change — there is no
+ * second place that reads a cap field, so an alias added here works for leases, env and CLI flags
+ * at once.
+ */
+exports.LEASE_CAP_ALIASES = {
+    /** Pre-rename vocabulary: a "cell" is what a sandbox used to be called. */
+    maxConcurrentCells: 'maxConcurrentSandboxes',
+};
+/** Deprecated cap spellings → the message an operator should see. Keyed by the OLD name. */
+exports.DEPRECATED_CAP_SPELLINGS = {
+    maxConcurrentCells: 'maxConcurrentSandboxes',
+    AGENTHIPPO_MAX_CONCURRENT_CELLS: 'AGENTHIPPO_MAX_CONCURRENT_SANDBOXES',
+    'destroy-cell': 'destroy-sandbox',
+    '--max-concurrent-cells': '--max-concurrent-sandboxes',
+};
+/**
+ * Breach actions, ordered by STRICTNESS. An unrecognised value clamps to the highest strictness
+ * in this table, never to the lowest and never to "unset".
+ */
+exports.ON_BREACH_ACTIONS = {
+    'revoke-inference': { strictness: 1 },
+    'destroy-sandbox': { strictness: 2 },
+};
+/** Alternative spellings for breach actions. Same extension point as `LEASE_CAP_ALIASES`. */
+exports.ON_BREACH_ALIASES = {
+    /** Pre-rename vocabulary. Deliberately mapped rather than dropped: dropping it SOFTENED the action. */
+    'destroy-cell': 'destroy-sandbox',
+};
+/** The strictest action this build knows about — where an unrecognised value lands. */
+exports.STRICTEST_ON_BREACH = Object.keys(exports.ON_BREACH_ACTIONS)
+    .reduce((a, b) => (exports.ON_BREACH_ACTIONS[a].strictness >= exports.ON_BREACH_ACTIONS[b].strictness ? a : b));
+/** Deny-rule scopes. An unknown scope rejects the document — see rule 1 above. */
+exports.DENY_SCOPES = ['session', 'user', 'pack'];
+/** Deny-rule modes, ordered by strictness for the same reason `onBreach` is. */
+exports.DENY_MODES = { drain: { strictness: 1 }, kill: { strictness: 2 } };
+exports.STRICTEST_DENY_MODE = 'kill';
+/** Alternative spellings for deny modes / scopes, for the back-compat layer. */
+exports.DENY_MODE_ALIASES = {};
+exports.DENY_SCOPE_ALIASES = {};
+const isPlainObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/**
+ * A cap value the meter can actually compare against.
+ *
+ * Rejects — never coerces — strings. `parseInt("lots")` is NaN and `Number("")` is 0; both would
+ * turn a control-plane typo into a disabled or absurd cap. A cap that cannot be read is a lease
+ * that cannot be trusted.
+ */
+function parseCapNumber(field, raw) {
+    if (typeof raw !== 'number') {
+        return { ok: false, reason: `${field} must be a number, got ${typeof raw} (${JSON.stringify(raw)})` };
+    }
+    if (!Number.isFinite(raw)) {
+        return { ok: false, reason: `${field} must be finite, got ${raw}` };
+    }
+    if (raw <= 0) {
+        // 0 has meant "unlimited" for --max-turns-per-session since before caps existed, but from a
+        // control plane it is far more likely to be an unset field serialised as a number. Refuse
+        // rather than guess which meaning was intended.
+        return { ok: false, reason: `${field} must be greater than 0, got ${raw} (omit the field for "unbounded")` };
+    }
+    if (!Number.isInteger(raw)) {
+        return { ok: false, reason: `${field} must be a whole number, got ${raw}` };
+    }
+    return { ok: true, value: raw };
+}
+/**
+ * Validate a cap policy from an untrusted source.
+ *
+ * Also used by `capsFromEnv`, so a local flag and a control-plane field are held to exactly the
+ * same standard — the alternative is two vocabularies that drift.
+ */
+function parseCapPolicy(raw, where = 'caps') {
+    if (raw === undefined || raw === null) {
+        return { ok: true, caps: {}, warnings: [] };
+    }
+    if (!isPlainObject(raw)) {
+        return { ok: false, reason: `${where} must be an object` };
+    }
+    const warnings = [];
+    const caps = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (value === undefined || value === null) {
+            continue;
+        }
+        if (key === 'onBreach') {
+            continue;
+        }
+        const canonical = (key in exports.LEASE_CAP_FIELDS ? key : exports.LEASE_CAP_ALIASES[key]);
+        if (!canonical) {
+            // Unknown cap fields are TOLERATED (a newer control plane may send a cap this build does
+            // not implement) but never silently: an operator must be able to see that the bound they
+            // configured is not being enforced by this version.
+            warnings.push(`${where}.${key} is not a cap this build understands and is NOT being enforced`);
+            continue;
+        }
+        const parsed = parseCapNumber(`${where}.${key}`, value);
+        if (!parsed.ok) {
+            return { ok: false, reason: parsed.reason };
+        }
+        caps[canonical] = parsed.value;
+    }
+    const rawBreach = raw.onBreach;
+    if (rawBreach !== undefined && rawBreach !== null) {
+        if (typeof rawBreach !== 'string') {
+            return { ok: false, reason: `${where}.onBreach must be a string, got ${typeof rawBreach}` };
+        }
+        const canonical = (rawBreach in exports.ON_BREACH_ACTIONS ? rawBreach : exports.ON_BREACH_ALIASES[rawBreach]);
+        if (canonical) {
+            caps.onBreach = canonical;
+        }
+        else {
+            // FAIL CLOSED, LOUDLY. Leaving it unset let an unrecognised value fall through mergeCaps
+            // and soften the breach action from destroy-sandbox to revoke-inference — a typo in the
+            // control plane weakening enforcement is the exact failure mode this guards.
+            caps.onBreach = exports.STRICTEST_ON_BREACH;
+            warnings.push(`${where}.onBreach="${rawBreach}" is not an action this build understands. ` +
+                `Failing CLOSED to "${exports.STRICTEST_ON_BREACH}" (the strictest known action). ` +
+                `Known actions: ${Object.keys(exports.ON_BREACH_ACTIONS).join(', ')}.`);
+        }
+    }
+    return { ok: true, caps, warnings };
+}
+function parseDenyRule(raw, index) {
+    if (!isPlainObject(raw)) {
+        return { ok: false, reason: `deny[${index}] must be an object` };
+    }
+    const warnings = [];
+    const rawScope = raw.scope;
+    if (typeof rawScope !== 'string') {
+        return { ok: false, reason: `deny[${index}].scope must be a string` };
+    }
+    const scope = exports.DENY_SCOPES.includes(rawScope)
+        ? rawScope
+        : exports.DENY_SCOPE_ALIASES[rawScope];
+    if (!scope) {
+        // Rejecting the document is the fail-closed choice: a rule this build cannot evaluate is a
+        // stop order it would silently not apply, while the console reports it as applied.
+        return { ok: false, reason: `deny[${index}].scope "${rawScope}" is not a scope this build understands (known: ${exports.DENY_SCOPES.join(', ')})` };
+    }
+    if (typeof raw.match !== 'string' || raw.match.length === 0) {
+        return { ok: false, reason: `deny[${index}].match must be a non-empty string` };
+    }
+    const rawMode = raw.mode;
+    if (typeof rawMode !== 'string') {
+        return { ok: false, reason: `deny[${index}].mode must be a string` };
+    }
+    let mode = (rawMode in exports.DENY_MODES ? rawMode : exports.DENY_MODE_ALIASES[rawMode]);
+    if (!mode) {
+        // Same asymmetry as onBreach: clamp UP. A stop order whose mode we cannot read is treated as
+        // the strictest one, never dropped and never softened.
+        mode = exports.STRICTEST_DENY_MODE;
+        warnings.push(`deny[${index}].mode="${rawMode}" is not a mode this build understands. ` +
+            `Failing CLOSED to "${exports.STRICTEST_DENY_MODE}". Known modes: ${Object.keys(exports.DENY_MODES).join(', ')}.`);
+    }
+    const rule = { scope, match: raw.match, mode };
+    if (raw.reason !== undefined) {
+        if (typeof raw.reason !== 'string') {
+            return { ok: false, reason: `deny[${index}].reason must be a string` };
+        }
+        rule.reason = raw.reason;
+    }
+    if (raw.until !== undefined && raw.until !== null) {
+        if (typeof raw.until !== 'number' || !Number.isFinite(raw.until)) {
+            return { ok: false, reason: `deny[${index}].until must be a finite epoch-seconds number` };
+        }
+        rule.until = raw.until;
+    }
+    if (raw.user !== undefined && raw.user !== null) {
+        if (typeof raw.user !== 'string') {
+            return { ok: false, reason: `deny[${index}].user must be a string` };
+        }
+        rule.user = raw.user;
+    }
+    if (raw.followUser !== undefined && raw.followUser !== null) {
+        if (typeof raw.followUser !== 'boolean') {
+            return { ok: false, reason: `deny[${index}].followUser must be a boolean` };
+        }
+        rule.followUser = raw.followUser;
+    }
+    return { ok: true, rule, warnings };
+}
+/**
+ * Parse and validate a whole lease document.
+ *
+ * **This is the exported validator the back-compat/alias work layers onto.** Adding a row to
+ * `LEASE_CAP_ALIASES`, `ON_BREACH_ALIASES`, `DENY_MODE_ALIASES` or `DENY_SCOPE_ALIASES` is
+ * sufficient; there is no second place that reads a lease field.
+ */
+function parseLease(raw) {
+    if (!isPlainObject(raw)) {
+        return { ok: false, reason: 'lease must be a JSON object' };
+    }
+    const warnings = [];
+    if (typeof raw.pack !== 'string' || raw.pack.length === 0) {
+        return { ok: false, reason: 'lease.pack must be a non-empty string' };
+    }
+    if (typeof raw.enabled !== 'boolean') {
+        // Not coerced. `enabled: "false"` is truthy in JavaScript, so a string here would lift the
+        // kill switch rather than apply it — the single most dangerous coercion in this document.
+        return { ok: false, reason: `lease.enabled must be a boolean, got ${typeof raw.enabled}` };
+    }
+    if (typeof raw.expiresAt !== 'number' || !Number.isFinite(raw.expiresAt)) {
+        return { ok: false, reason: `lease.expiresAt must be a finite epoch-seconds number, got ${JSON.stringify(raw.expiresAt)}` };
+    }
+    const lease = { pack: raw.pack, enabled: raw.enabled, expiresAt: raw.expiresAt };
+    for (const key of ['version', 'imageDigest', 'reason']) {
+        const v = raw[key];
+        if (v === undefined || v === null) {
+            continue;
+        }
+        if (typeof v !== 'string') {
+            return { ok: false, reason: `lease.${key} must be a string, got ${typeof v}` };
+        }
+        lease[key] = v;
+    }
+    for (const key of ['requireSignedPack', 'requireSignedLease']) {
+        const v = raw[key];
+        if (v === undefined || v === null) {
+            continue;
+        }
+        if (typeof v !== 'boolean') {
+            return { ok: false, reason: `lease.${key} must be a boolean, got ${typeof v}` };
+        }
+        lease[key] = v;
+    }
+    if (raw.caps !== undefined && raw.caps !== null) {
+        const caps = parseCapPolicy(raw.caps, 'lease.caps');
+        if (!caps.ok) {
+            return { ok: false, reason: caps.reason };
+        }
+        lease.caps = caps.caps;
+        warnings.push(...caps.warnings);
+    }
+    if (raw.deny !== undefined && raw.deny !== null) {
+        if (!Array.isArray(raw.deny)) {
+            return { ok: false, reason: 'lease.deny must be an array' };
+        }
+        const rules = [];
+        for (let i = 0; i < raw.deny.length; i++) {
+            const parsed = parseDenyRule(raw.deny[i], i);
+            if (!parsed.ok) {
+                return { ok: false, reason: parsed.reason };
+            }
+            rules.push(parsed.rule);
+            warnings.push(...parsed.warnings);
+        }
+        lease.deny = rules;
+    }
+    return { ok: true, lease, warnings };
+}