@controlvector/cv-agent 1.11.1 → 1.13.0

package/dist/utils/git-credentials.js

@@ -0,0 +1,171 @@
+"use strict";
+/**
+ * Git credential handling for the cv-hub git host.
+ *
+ * The cv-hub REST API accepts a session/API token that is a JWT. The cv-hub
+ * GIT host does NOT accept that JWT for push; only a minted cv_pat (an opaque
+ * personal access token) authenticates. cv-agent onboarding historically wrote
+ * the JWT into ~/.git-credentials, so non-interactive pushes failed.
+ *
+ * This module distinguishes the two token kinds, selects the git-capable one,
+ * derives the git host from the resolved API URL, and configures git to use a
+ * cv-agent credential helper (`cva git-credential`) scoped to the cv-hub host.
+ * The helper reads the cv_pat from the existing mode-0600 credentials file on
+ * demand, so the token is never embedded in a remote URL and no new plaintext
+ * copy is created.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GIT_USERNAME = exports.GIT_PAT_FIELD = void 0;
+exports.isJwt = isJwt;
+exports.isGitCapable = isGitCapable;
+exports.selectGitToken = selectGitToken;
+exports.resolveGitHost = resolveGitHost;
+exports.parseCredentialInput = parseCredentialInput;
+exports.buildCredentialResponse = buildCredentialResponse;
+exports.configureGitCredentialHelper = configureGitCredentialHelper;
+exports.mintGitPat = mintGitPat;
+const node_child_process_1 = require("node:child_process");
+/** Credentials-file field that holds the git-capable cv_pat. */
+exports.GIT_PAT_FIELD = 'CV_HUB_GIT_PAT';
+/**
+ * Username presented for cv-hub git Basic auth. cv-hub ignores the username and
+ * validates the cv_pat carried in the password, but git's Basic auth requires a
+ * non-empty username, so we send a stable placeholder.
+ */
+exports.GIT_USERNAME = 'git';
+const DEFAULT_GIT_HOST = 'git.hub.controlvector.io';
+/**
+ * True if the token is a JSON Web Token: three base64url segments whose header
+ * begins with the encoding of `{"alg` (i.e. `eyJ`). cv-hub session/API tokens
+ * are JWTs; the git host rejects them.
+ */
+function isJwt(token) {
+    if (!token)
+        return false;
+    return /^eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]*$/.test(token.trim());
+}
+/** True if the token can be used as a git credential (present and not a JWT). */
+function isGitCapable(token) {
+    return !!token && !isJwt(token);
+}
+/**
+ * Choose the token git should use. A dedicated git cv_pat wins; the API token
+ * is only used if it is itself git-capable (not a JWT). A JWT is never returned
+ * for git. Returns null when no git-capable token is available.
+ */
+function selectGitToken(gitPat, apiPat) {
+    if (isGitCapable(gitPat))
+        return gitPat.trim();
+    if (isGitCapable(apiPat))
+        return apiPat.trim();
+    return null;
+}
+/** Derive the cv-hub git host from the resolved API URL (api.* -> git.*). */
+function resolveGitHost(apiUrl) {
+    if (!apiUrl)
+        return DEFAULT_GIT_HOST;
+    try {
+        return new URL(apiUrl).host.replace(/^api\./, 'git.');
+    }
+    catch {
+        return DEFAULT_GIT_HOST;
+    }
+}
+/** Parse git credential helper stdin (key=value lines) into a query object. */
+function parseCredentialInput(input) {
+    const q = {};
+    for (const line of input.split('\n')) {
+        const idx = line.indexOf('=');
+        if (idx === -1)
+            continue;
+        const key = line.slice(0, idx).trim();
+        const val = line.slice(idx + 1).trim();
+        if (key === 'protocol')
+            q.protocol = val;
+        else if (key === 'host')
+            q.host = val;
+        else if (key === 'path')
+            q.path = val;
+        else if (key === 'username')
+            q.username = val;
+    }
+    return q;
+}
+/**
+ * Build the git credential helper `get` response for a query, given the
+ * resolved git host and the git-capable token. Returns an empty string when the
+ * query is not for the cv-hub git host or no git-capable token is available, so
+ * git falls back (or fails) instead of presenting a wrong credential.
+ */
+function buildCredentialResponse(query, gitHost, token) {
+    if (!token)
+        return '';
+    if (query.host && query.host !== gitHost)
+        return '';
+    return `username=${exports.GIT_USERNAME}\npassword=${token}\n`;
+}
+function gitConfig(args) {
+    try {
+        (0, node_child_process_1.execFileSync)('git', ['config', ...args], { stdio: 'pipe' });
+    }
+    catch {
+        // Tolerate expected failures (e.g. --unset-all with nothing to remove).
+    }
+}
+/**
+ * Configure git (global scope) to use the cv-agent credential helper for the
+ * cv-hub git host only. Neutralizes any inherited helper (e.g. the plain
+ * `store`) for that host so the cv-agent helper is authoritative and no
+ * plaintext copy is persisted on `git credential approve`.
+ *
+ * No token is written to any git config; only the helper invocation is stored.
+ * Idempotent.
+ */
+function configureGitCredentialHelper(gitHost, helperCommand = 'cva git-credential') {
+    const key = `credential.https://${gitHost}.helper`;
+    // Drop any prior cv-agent entries at this scope (idempotency).
+    gitConfig(['--global', '--unset-all', key]);
+    // Empty value resets the inherited helper list (including a global `store`)
+    // for this host; then add the cv-agent helper as the sole active helper.
+    gitConfig(['--global', '--add', key, '']);
+    gitConfig(['--global', '--add', key, `!${helperCommand}`]);
+    return {
+        gitHost,
+        scope: `https://${gitHost}`,
+        helperCommand,
+        method: 'cva-credential-helper (reads ~/.config/cv-hub/credentials, mode 0600)',
+    };
+}
+// ============================================================================
+// cv_pat minting
+// ============================================================================
+/**
+ * Mint a git-capable cv_pat from a session/access token via the cv-hub API,
+ * mirroring the cv-git onboarding token mint. Returns null on any failure and
+ * never returns a JWT. Makes a live API call, so callers must gate it on real
+ * onboarding (not test/verification runs).
+ */
+async function mintGitPat(apiUrl, accessToken, username) {
+    try {
+        const res = await fetch(`${apiUrl}/api/user/tokens`, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Authorization: `Bearer ${accessToken}`,
+            },
+            body: JSON.stringify({
+                name: `cv-agent-${username || 'auto'}`,
+                scopes: ['repo:read', 'repo:write'],
+                expiresInDays: 365,
+            }),
+        });
+        if (!res.ok)
+            return null;
+        const data = (await res.json());
+        return isGitCapable(data.token) ? data.token.trim() : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=git-credentials.js.map

package/dist/utils/git-credentials.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-credentials.js","sourceRoot":"","sources":["../../src/utils/git-credentials.ts"],"names":[],"mappings":"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"}

package/dist/utils/meter.d.ts

@@ -0,0 +1,59 @@
+/**
+ * cv-meter token-metering plumbing.
+ *
+ * Pure helpers (no I/O) so the env wiring is unit-testable. The agent reads
+ * meter config once at startup and injects it into every Claude Code spawn;
+ * cv-code (the producer) reads CVMETER_* from that env and emits usage events.
+ */
+import type { CvaConfig, MeterEnforce } from './config.js';
+export interface MeterResolution {
+    url?: string;
+    token?: string;
+    enforce: MeterEnforce;
+    org?: string;
+}
+/**
+ * Resolve meter config from agent config + process env.
+ * Config file wins over env (explicit config beats ambient environment).
+ */
+export declare function resolveMeterConfig(config: Partial<CvaConfig>, env: NodeJS.ProcessEnv): MeterResolution;
+export type MeterReasonCode = 'OK' | 'SOFT_WARN' | 'HARD_DENY' | 'NO_BUDGET';
+export type MeterAction = 'allow' | 'warn' | 'deny';
+export interface MeterCheckScopes {
+    user?: string;
+    project?: string;
+    task?: string;
+    org?: string;
+}
+export interface MeterCheckResult {
+    action: MeterAction;
+    reasonCode: MeterReasonCode;
+    reason: string;
+    governingKey?: string;
+}
+export declare function mapReasonToAction(code: MeterReasonCode): MeterAction;
+export declare function resolveErrorAction(enforce: MeterEnforce): MeterAction;
+export declare function pollBackoffMs(baseIntervalMs: number, denyStreak: number, capMs?: number): number;
+export declare function noteDeny(cache: Map<string, number>, governingKey: string | undefined, now: number, ttlMs?: number): void;
+export declare function checkDenyCache(cache: Map<string, number>, scopes: MeterCheckScopes, now: number): boolean;
+/**
+ * Call cv-meter POST /v1/check. Returns the mapped server verdict on HTTP 200, or
+ * null on any error/timeout/non-200 (caller applies resolveErrorAction). Never throws.
+ * ~1s target timeout, 3s hard ceiling. Side-effect-free ⇒ safe to skip/retry.
+ */
+export declare function meterCheck(meter: MeterResolution, org: string, scopes: MeterCheckScopes, timeoutMs?: number): Promise<MeterCheckResult | null>;
+/**
+ * Inject resolved meter config into a spawn env (mutates in place).
+ * The token is only set when a URL is present — a token without an endpoint is
+ * useless and we don't want to leak it into a child that won't meter.
+ */
+export declare function applyMeterEnv(targetEnv: NodeJS.ProcessEnv, meter: MeterResolution): void;
+/**
+ * Clone a base spawn env and stamp the per-task CVMETER_TASK_ID.
+ *
+ * Returns a fresh object so the daemon's base env is never mutated — this is
+ * what prevents one task's id from leaking into the next task's events. The id
+ * is only stamped when metering is active (CVMETER_URL present in the base env).
+ */
+export declare function stampTaskEnv(baseEnv: NodeJS.ProcessEnv, taskId: string): NodeJS.ProcessEnv;
+//# sourceMappingURL=meter.d.ts.map

package/dist/utils/meter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"meter.d.ts","sourceRoot":"","sources":["../../src/utils/meter.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3D,MAAM,WAAW,eAAe;IAC9B,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,YAAY,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,OAAO,CAAC,SAAS,CAAC,EAC1B,GAAG,EAAE,MAAM,CAAC,UAAU,GACrB,eAAe,CAOjB;AAOD,MAAM,MAAM,eAAe,GAAG,IAAI,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;AAC7E,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AACpD,MAAM,WAAW,gBAAgB;IAAG,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE;AAClG,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,WAAW,CAAC;IACpB,UAAU,EAAE,eAAe,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAGD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,GAAG,WAAW,CAEpE;AAGD,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,WAAW,CAErE;AAID,wBAAgB,aAAa,CAAC,cAAc,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,SAAa,GAAG,MAAM,CAGpG;AAID,wBAAgB,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,YAAY,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,SAAS,GAAG,IAAI,CAExH;AACD,wBAAgB,cAAc,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAQzG;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAC9B,KAAK,EAAE,eAAe,EACtB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,gBAAgB,EACxB,SAAS,SAAO,GACf,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAyBlC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,CAAC,UAAU,EAAE,KAAK,EAAE,eAAe,GAAG,IAAI,CAIxF;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,UAAU,CAM1F"}

package/dist/utils/meter.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * cv-meter token-metering plumbing.
+ *
+ * Pure helpers (no I/O) so the env wiring is unit-testable. The agent reads
+ * meter config once at startup and injects it into every Claude Code spawn;
+ * cv-code (the producer) reads CVMETER_* from that env and emits usage events.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveMeterConfig = resolveMeterConfig;
+exports.mapReasonToAction = mapReasonToAction;
+exports.resolveErrorAction = resolveErrorAction;
+exports.pollBackoffMs = pollBackoffMs;
+exports.noteDeny = noteDeny;
+exports.checkDenyCache = checkDenyCache;
+exports.meterCheck = meterCheck;
+exports.applyMeterEnv = applyMeterEnv;
+exports.stampTaskEnv = stampTaskEnv;
+/**
+ * Resolve meter config from agent config + process env.
+ * Config file wins over env (explicit config beats ambient environment).
+ */
+function resolveMeterConfig(config, env) {
+    return {
+        url: config.meter_url ?? env.CVMETER_URL,
+        token: config.meter_token ?? env.CVMETER_TOKEN,
+        enforce: (config.meter_enforce ?? env.CVMETER_ENFORCE ?? 'off'),
+        org: config.meter_org ?? env.CVMETER_ORG,
+    };
+}
+// Pure: map the server's reason_code to a gate action. NO_BUDGET/OK ⇒ allow.
+function mapReasonToAction(code) {
+    return code === 'HARD_DENY' ? 'deny' : code === 'SOFT_WARN' ? 'warn' : 'allow';
+}
+// Pure: on a check error/timeout, fail-open (allow) unless configured fail_closed (deny).
+function resolveErrorAction(enforce) {
+    return enforce === 'fail_closed' ? 'deny' : 'allow';
+}
+// Pure: poll sleep with exponential backoff after consecutive budget denials (cap 5 min).
+// denyStreak 0 ⇒ base interval; resets are the caller's job (any allow/warn sets streak 0).
+function pollBackoffMs(baseIntervalMs, denyStreak, capMs = 5 * 60_000) {
+    if (denyStreak <= 0)
+        return baseIntervalMs;
+    return Math.min(baseIntervalMs * 2 ** Math.min(denyStreak - 1, 6), capMs);
+}
+// Pure: negative-cache of denied scope keys → expiry, so a burst of same-scope tasks
+// doesn't fire N /v1/check calls for a scope already known over-cap.
+function noteDeny(cache, governingKey, now, ttlMs = 90_000) {
+    if (governingKey)
+        cache.set(governingKey, now + ttlMs);
+}
+function checkDenyCache(cache, scopes, now) {
+    for (const [k, v] of Object.entries(scopes)) {
+        if (!v)
+            continue;
+        const until = cache.get(`${k}:${v}`);
+        if (until && until > now)
+            return true;
+        if (until && until <= now)
+            cache.delete(`${k}:${v}`); // lazy eviction
+    }
+    return false;
+}
+/**
+ * Call cv-meter POST /v1/check. Returns the mapped server verdict on HTTP 200, or
+ * null on any error/timeout/non-200 (caller applies resolveErrorAction). Never throws.
+ * ~1s target timeout, 3s hard ceiling. Side-effect-free ⇒ safe to skip/retry.
+ */
+async function meterCheck(meter, org, scopes, timeoutMs = 1000) {
+    if (!meter.url)
+        return null;
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), Math.min(timeoutMs, 3000));
+    try {
+        const res = await fetch(`${meter.url.replace(/\/$/, '')}/v1/check`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...(meter.token ? { Authorization: `Bearer ${meter.token}` } : {}) },
+            body: JSON.stringify({ org, scopes }),
+            signal: ctl.signal,
+        });
+        if (!res.ok)
+            return null; // 400/401/403/5xx are errors, not budget denials
+        const body = await res.json();
+        const g = body.governing;
+        return {
+            action: mapReasonToAction(body.reason_code),
+            reasonCode: body.reason_code,
+            reason: body.reason ?? '',
+            governingKey: g ? `${g.scope}:${g.scope_id}` : undefined,
+        };
+    }
+    catch {
+        return null; // timeout / network / abort
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Inject resolved meter config into a spawn env (mutates in place).
+ * The token is only set when a URL is present — a token without an endpoint is
+ * useless and we don't want to leak it into a child that won't meter.
+ */
+function applyMeterEnv(targetEnv, meter) {
+    if (!meter.url)
+        return;
+    targetEnv.CVMETER_URL = meter.url;
+    if (meter.token)
+        targetEnv.CVMETER_TOKEN = meter.token;
+}
+/**
+ * Clone a base spawn env and stamp the per-task CVMETER_TASK_ID.
+ *
+ * Returns a fresh object so the daemon's base env is never mutated — this is
+ * what prevents one task's id from leaking into the next task's events. The id
+ * is only stamped when metering is active (CVMETER_URL present in the base env).
+ */
+function stampTaskEnv(baseEnv, taskId) {
+    const taskEnv = { ...baseEnv };
+    if (taskEnv.CVMETER_URL) {
+        taskEnv.CVMETER_TASK_ID = taskId;
+    }
+    return taskEnv;
+}
+//# sourceMappingURL=meter.js.map

package/dist/utils/meter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"meter.js","sourceRoot":"","sources":["../../src/utils/meter.ts"],"names":[],"mappings":"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"}

package/dist/utils/profile.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Agent profiles (P14). A profile is data, not a fork: a manifest + system prompt +
+ * tool policy that constrains what a cva session can do. It is loaded at start and
+ * enforced as a hard gate, so a profiled session cannot exceed its manifest no matter
+ * what the model attempts. cv-deploy (P15) is the first profile.
+ *
+ * This module is pure and self-contained: the manifest schema, the loader, and the
+ * enforcement decisions (tool policy, task-type routing, scope ceiling, base semver
+ * gate) are all here as testable functions. agent.ts wires them into the run loop and
+ * the permission relay; the frozen contract other profiles author against is SPEC.md.
+ */
+import { z } from 'zod';
+/**
+ * The profile manifest. `.strict()` at every level makes an unknown key an ERROR, not
+ * a warning (P14 item 2): a typo or a key from a newer schema fails the load loudly
+ * rather than being silently ignored.
+ */
+export declare const ProfileManifestSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    base: z.ZodString;
+    system_prompt: z.ZodString;
+    tools: z.ZodObject<{
+        allow: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        deny: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>;
+    task_types: z.ZodArray<z.ZodString>;
+    credential_scopes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    limits: z.ZodDefault<z.ZodObject<{
+        max_turns: z.ZodOptional<z.ZodNumber>;
+        max_tool_calls: z.ZodOptional<z.ZodNumber>;
+        timeout_s: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type ProfileManifest = z.infer<typeof ProfileManifestSchema>;
+export declare class ProfileError extends Error {
+    readonly detail: Record<string, unknown>;
+    constructor(message: string, detail?: Record<string, unknown>);
+}
+/** Validate an already-parsed object as a manifest. Throws ProfileError on any issue. */
+export declare function validateManifest(input: unknown): ProfileManifest;
+/**
+ * Check the manifest `base` constraint against the running host. The grammar is
+ * frozen (SPEC): `[<host-name>] <op> <version>`, op one of >= > <= < =, version a
+ * bare `major.minor.patch`; a bare version with no op means `=`. A host-name token,
+ * when present, must match hostName (a profile for a different host is refused).
+ */
+export declare function checkBaseConstraint(base: string, hostName: string, hostVersion: string): {
+    ok: boolean;
+    reason?: string;
+};
+/**
+ * A tool spec's base name. Claude Code tools appear as "Bash" or scoped like
+ * "Bash(git*)"; policy entries may be "Bash", "Bash(*)", or "Bash(git*)". Policy is
+ * evaluated by base name so an allow/deny of "Bash" covers every Bash invocation.
+ */
+export declare function toolBaseName(spec: string): string;
+export interface ToolDecision {
+    allowed: boolean;
+    reason?: string;
+}
+/**
+ * The tool-policy decision: a deny-list entry wins over an allow-list entry, and
+ * absence from the allow-list means denied. This is the hard gate the relay and the
+ * auto-approve allowlist are both built from.
+ */
+export declare function evaluateTool(manifest: ProfileManifest, tool: string): ToolDecision;
+/** The `--allowedTools` list for auto-approve mode: allow entries not shadowed by a deny. */
+export declare function allowedToolsList(manifest: ProfileManifest): string[];
+/** Pull the tool name out of a Claude Code permission prompt, or null if not present. */
+export declare function extractToolFromPrompt(promptText: string): string | null;
+/**
+ * The relay decision for a permission prompt under a profile. A tool the profile
+ * denies is refused AT THE RELAY (action "deny" -> the relay answers no); an allowed
+ * (or unidentifiable) tool falls through to the normal human/CV-Hub relay. The profile
+ * only hard-denies; it never auto-approves what the operator would otherwise gate.
+ */
+export declare function relayPermissionDecision(manifest: ProfileManifest, promptText: string): {
+    action: 'deny' | 'relay';
+    tool?: string;
+    reason?: string;
+};
+/** A dispatched task whose type is outside `task_types` is refused (before any model call). */
+export declare function checkTaskType(manifest: ProfileManifest, taskType: string): ToolDecision;
+/**
+ * Apply the credential-scope ceiling: keep only offered scopes that the profile
+ * permits, dropping anything broader. The profile's credential_scopes is a MAXIMUM,
+ * so this is the intersection (offered that is within the ceiling).
+ */
+export declare function capScopes(ceiling: string[], offered: string[]): string[];
+export interface LoadedProfile {
+    manifest: ProfileManifest;
+    systemPrompt: string;
+    /** Directory the manifest was loaded from (system_prompt resolves against it). */
+    dir: string;
+    /** The spec the caller passed (a path or an @scope/pkg). */
+    source: string;
+}
+export interface LoadProfileOptions {
+    /** Running host version, e.g. the cva version, for the base gate. */
+    hostVersion: string;
+    /** Host binary name the base constraint may name. Defaults to "cv-agent". */
+    hostName?: string;
+    /** Injectable file reader (tests). Defaults to fs.readFileSync utf8. */
+    readFile?: (path: string) => string;
+    /** Injectable package resolver for @scope/pkg specs (tests). Defaults to require.resolve. */
+    resolvePackage?: (spec: string) => string;
+}
+/**
+ * Resolve a profile spec to a manifest file path. A spec beginning with "@" (or any
+ * bare package name) is resolved as a package whose root holds profile.yaml; anything
+ * else is a filesystem path (a directory implies <dir>/profile.yaml, a file is used
+ * as-is).
+ */
+export declare function resolveProfileSpec(spec: string, opts: LoadProfileOptions): string;
+/**
+ * Load and validate a profile: resolve the spec, parse + strictly validate the
+ * manifest, gate the host version against `base`, then load the system prompt. Every
+ * failure is a ProfileError with a specific reason (P14: unknown keys, bad semver, and
+ * a failed base gate are all hard errors).
+ */
+export declare function loadProfile(spec: string, opts: LoadProfileOptions): LoadedProfile;
+//# sourceMappingURL=profile.d.ts.map

package/dist/utils/profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile.d.ts","sourceRoot":"","sources":["../../src/utils/profile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAMH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAuBxB;;;;GAIG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;kBAcvB,CAAC;AAEZ,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEpE,qBAAa,YAAa,SAAQ,KAAK;IAGnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;gBADxC,OAAO,EAAE,MAAM,EACN,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM;CAKhD;AAED,yFAAyF;AACzF,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAOhE;AAsBD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAuBlC;AAMD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGjD;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAOlF;AAED,6FAA6F;AAC7F,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,EAAE,CAGpE;AAED,yFAAyF;AACzF,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGvE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,eAAe,EACzB,UAAU,EAAE,MAAM,GACjB;IAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAM9D;AAMD,+FAA+F;AAC/F,wBAAgB,aAAa,CAAC,QAAQ,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,CAMvF;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAGxE;AAMD,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,eAAe,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,kFAAkF;IAClF,GAAG,EAAE,MAAM,CAAC;IACZ,4DAA4D;IAC5D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;IACpC,6FAA6F;IAC7F,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;CAC3C;AAMD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAOjF;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,kBAAkB,GAAG,aAAa,CAyCjF"}