agentera 3.0.0-dev.5 → 3.0.0-dev.51

package/dist/cli/commands/durability.js

@@ -0,0 +1,81 @@
+import { resolvePath } from "../../core/paths.js";
+import { resolveSourceRoot } from "../../core/sourceRoot.js";
+import { emitStructured } from "../structured.js";
+import { stateDurabilityContract } from "../../state/archiveDiscovery.js";
+import { StateRetrievalFailure } from "../../state/directRetrieval.js";
+import { inspectDurability, renderDurabilityText, } from "../../state/durability.js";
+import { entityArtifactValues } from "../../state/entityStorage.js";
+export function requestedDurabilityFormat(argv) {
+    for (let index = 0; index < argv.length; index += 1) {
+        if (argv[index] === "--format") {
+            const value = argv[index + 1];
+            if (value === "json" || value === "yaml")
+                return value;
+        }
+        if (argv[index].startsWith("--format=")) {
+            const value = argv[index].slice("--format=".length);
+            if (value === "json" || value === "yaml")
+                return value;
+        }
+    }
+    return "text";
+}
+export function validateDurabilityArgs(args, sourceRoot) {
+    const contract = stateDurabilityContract(sourceRoot);
+    const validArtifacts = entityArtifactValues(sourceRoot);
+    if (args.number !== undefined)
+        throw entityDurabilityFailure("entity mode rejects --number; use --artifact ARTIFACT --id ID", args.artifact, args.id ?? undefined, validArtifacts);
+    if (!args.artifact || !args.id)
+        throw entityDurabilityFailure("entity-mode durability requires --artifact ARTIFACT --id ID", args.artifact, args.id ?? undefined, validArtifacts);
+    if (!/^[a-z]{10}$/.test(args.id))
+        throw entityDurabilityFailure(`entity ID '${args.id}' must be ten lowercase letters`, args.artifact, args.id, validArtifacts);
+    if (args.artifact && !validArtifacts.includes(args.artifact)) {
+        throw entityDurabilityFailure(`unsupported durability artifact '${args.artifact}'`, args.artifact, args.id ?? undefined, validArtifacts);
+    }
+    if (args.limit !== undefined && (args.limit < 1 || args.limit > contract.maximumLimit)) {
+        throw entityDurabilityFailure(`argument --limit must be between 1 and ${contract.maximumLimit}`, args.artifact, args.id ?? undefined, validArtifacts);
+    }
+}
+export function entityDurabilityFailure(message, artifact, id, validValues) {
+    return new StateRetrievalFailure({
+        schemaVersion: "agentera.stateFailure.v1",
+        status: "fail",
+        error: {
+            class: "invalid_request",
+            message,
+            syntax: "agentera check durability --artifact ARTIFACT --id ID --format json",
+            example: "agentera check durability --artifact progress --id qjtrmnpvka --format json",
+            recovery: "Use one bare entity ID returned by the artifact list; no state was changed.",
+            ...(artifact ? { artifact } : {}),
+            ...(id ? { id } : {}),
+            ...(validValues ? { valid_values: validValues } : {}),
+        },
+    }, 2);
+}
+export function emitDurabilityFailure(failure, format, io) {
+    const out = io.out ?? ((text) => process.stdout.write(text));
+    if (format === "json" || format === "yaml")
+        emitStructured(failure.body, format, out);
+    else {
+        const details = failure.body.error;
+        out([
+            `Error: ${details.message}`,
+            `Class: ${details.class}`,
+            `Syntax: ${details.syntax}`,
+            `Example: ${details.example}`,
+            `Recovery: ${details.recovery}`,
+        ].join("\n") + "\n");
+    }
+    return failure.exitCode;
+}
+export function cmdDurability(args, io = {}) {
+    const output = io.out ?? ((text) => process.stdout.write(text));
+    const response = inspectDurability(resolvePath(args.project ?? process.cwd()), args, { sourceRoot: resolveSourceRoot() });
+    if (args.format === "json" || args.format === "yaml") {
+        emitStructured(response, args.format, output);
+    }
+    else {
+        renderDurabilityText(response, output);
+    }
+    return 0;
+}

package/dist/cli/commands/glossaryAdvice.js

@@ -0,0 +1,138 @@
+import fs from "node:fs";
+import { acquireGlossaryInputs } from "../../analytics/glossaryInputAcquisition.js";
+import { GlossaryAdviceInputError, resolveGlossaryAdvice, } from "../../analytics/glossaryAdviceResolution.js";
+import { loadYamlMapping } from "../../core/yaml.js";
+import { glossaryAdviceContract } from "../../registries/glossaryAdviceContract.js";
+import { discoverSchemasDir } from "../appContext.js";
+import { emitInvalidInput } from "../errors.js";
+import { registryArtifactPath } from "../orientation.js";
+import { emitStructured } from "../structured.js";
+const contract = glossaryAdviceContract();
+const COMMAND = contract.command.replace("REQUEST", "<file|->");
+const RECOVERY = `Correct the bounded request and retry ${COMMAND}; no state was changed.`;
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function invalid(io, body) {
+    return emitInvalidInput(io, { format: "json", body: { ...body, recovery: RECOVERY } });
+}
+function parseArgs(argv) {
+    let input;
+    for (let index = 0; index < argv.length; index += 1) {
+        const [name, inline] = argv[index].split("=", 2);
+        if (name !== "--input" && name !== "--format") {
+            return {
+                class: "unrecognized_argument",
+                message: `unrecognized arguments: ${name}`,
+                syntax: COMMAND,
+            };
+        }
+        const value = inline ?? argv[++index];
+        if (!value || value.startsWith("--")) {
+            return {
+                class: "missing_argument",
+                message: `${name} requires a value`,
+                syntax: `${name} VALUE`,
+            };
+        }
+        if (name === "--format" && value !== "json") {
+            return {
+                class: "invalid_choice",
+                message: "glossary-advice requires --format json",
+                valid_values: ["json"],
+            };
+        }
+        if (name === "--input") {
+            if (input !== undefined)
+                return { class: "mutually_exclusive", message: "--input may only be supplied once" };
+            input = value;
+        }
+    }
+    return input ?? { class: "missing_argument", message: "--input is required", syntax: COMMAND };
+}
+function readRequest(source, io) {
+    const bytes = source === "-"
+        ? Buffer.from(io.stdin ? io.stdin() : fs.readFileSync(0))
+        : fs.readFileSync(source);
+    if (bytes.length > contract.maxRequestUtf8Bytes)
+        throw new Error("over bound");
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    const request = mapping(loadYamlMapping(text));
+    if (!request)
+        throw new Error("not a mapping");
+    return request;
+}
+function validatedRequest(request) {
+    const keys = Object.keys(request);
+    if (keys.some((key) => !contract.requestFields.includes(key)) ||
+        contract.requestFields.slice(0, 2).some((key) => !(key in request))) {
+        return {
+            class: "schema_violation",
+            message: "glossary advice request fields are invalid",
+            valid_values: contract.requestFields,
+        };
+    }
+    if (request.schema_version !== contract.requestSchemaVersion ||
+        typeof request.requested_term !== "string") {
+        return {
+            class: "schema_violation",
+            message: `request must use ${contract.requestSchemaVersion} with one string requested_term`,
+            valid_values: [contract.requestSchemaVersion],
+        };
+    }
+    if (request.host_review === undefined || request.host_review === null)
+        return { requestedTerm: request.requested_term };
+    const review = mapping(request.host_review);
+    if (!review ||
+        JSON.stringify(Object.keys(review).sort()) !==
+            JSON.stringify([...contract.hostReviewFields].sort())) {
+        return {
+            class: "schema_violation",
+            message: "host_review fields are invalid",
+            valid_values: contract.hostReviewFields,
+        };
+    }
+    return {
+        requestedTerm: request.requested_term,
+        hostReview: {
+            relation: review.relation,
+            candidate_owner: review.candidate_owner,
+            candidate_term: review.candidate_term,
+        },
+    };
+}
+export function runGlossaryAdviceCommand(argv, io) {
+    const parsedArgs = parseArgs(argv);
+    if (typeof parsedArgs !== "string")
+        return invalid(io, parsedArgs);
+    let request;
+    try {
+        request = readRequest(parsedArgs, io);
+    }
+    catch {
+        return invalid(io, {
+            class: "invalid_format",
+            message: "--input must be one readable bounded UTF-8 YAML or JSON mapping",
+        });
+    }
+    const parsed = validatedRequest(request);
+    if ("class" in parsed)
+        return invalid(io, parsed);
+    try {
+        const profilePath = registryArtifactPath("profile", discoverSchemasDir());
+        const advice = resolveGlossaryAdvice(parsed.requestedTerm, acquireGlossaryInputs(process.cwd(), profilePath), parsed.hostReview);
+        emitStructured({
+            schemaVersion: contract.schemaVersion,
+            command: "report glossary-advice",
+            status: "ok",
+            advice,
+        }, "json", io.out ?? ((text) => process.stdout.write(text)));
+        return 0;
+    }
+    catch (error) {
+        const code = error instanceof GlossaryAdviceInputError ? error.code : "invalid_acquisition";
+        return invalid(io, { class: "invalid_request", message: `glossary advice failed: ${code}` });
+    }
+}

package/dist/cli/commands/lint.js

@@ -9,29 +9,7 @@ const LINT_CHECKS = [
     ["abstraction", "Add a concrete anchor such as a path, line number, metric, command, identifier, or quote."],
     ["filler", "Remove the named filler phrase category before writing the artifact."],
 ];
-const LINT_CANONICAL_LABELS = {
-    changelog: "CHANGELOG.md",
-    decisions: "DECISIONS.md",
-    design: "DESIGN.md",
-    docs: "DOCS.md",
-    health: "HEALTH.md",
-    plan: "PLAN.md",
-    progress: "PROGRESS.md",
-    todo: "TODO.md",
-    vision: "VISION.md",
-    experiments: "EXPERIMENTS.md",
-};
-const VALIDATE_ARTIFACT_LABELS = [
-    "CHANGELOG.md",
-    "DECISIONS.md",
-    "DESIGN.md",
-    "DOCS.md",
-    "HEALTH.md",
-    "PLAN.md",
-    "PROGRESS.md",
-    "TODO.md",
-    "VISION.md",
-];
+import { VALIDATE_ARTIFACT_PROTOCOL_IDS, normalizeArtifactProtocolId } from "../../registries/artifactProtocolIds.js";
 function lintSchemaName(artifact, schemas) {
     if (artifact in schemas)
         return artifact;
@@ -48,24 +26,14 @@ function lintSchemaName(artifact, schemas) {
         return stem;
     return null;
 }
-function lintCanonicalLabel(schemaName, info, artifact) {
-    if (schemaName in LINT_CANONICAL_LABELS)
-        return LINT_CANONICAL_LABELS[schemaName];
-    const record = info.record;
-    if (record && record.displayName)
-        return record.displayName;
-    if (VALIDATE_ARTIFACT_LABELS.includes(artifact))
-        return artifact;
-    const upper = artifact.trim().toUpperCase();
-    if (VALIDATE_ARTIFACT_LABELS.includes(upper))
-        return upper;
-    return artifact;
+function lintCanonicalLabel(schemaName, _info, artifact) {
+    return normalizeArtifactProtocolId(artifact) ?? schemaName;
 }
 function resolveLintArtifactFile(artifact) {
     const schemas = loadSchemas(discoverSchemasDir());
     const schemaName = lintSchemaName(artifact, schemas);
     if (schemaName === null) {
-        const validLabels = VALIDATE_ARTIFACT_LABELS.join(", ");
+        const validLabels = VALIDATE_ARTIFACT_PROTOCOL_IDS.join(", ");
         throw new Error(`unsupported artifact ${pyRepr(artifact)}; provide --file or --text, ` +
             "or use a schema name from `agentera query --list-artifacts` " +
             `or a canonical label (${validLabels})`);
@@ -112,6 +80,9 @@ function isFileSafe(p) {
         return false;
     }
 }
+function isVerbosityAuthorityError(detail) {
+    return detail.startsWith("verbosity authority error");
+}
 function lintChecks(text, artifact, fullArtifact) {
     const verbosityCheck = fullArtifact ? checkFullFileVerbosity(text, artifact) : checkVerbosity(text, artifact);
     const raw = {
@@ -127,14 +98,16 @@ function lintChecks(text, artifact, fullArtifact) {
             name,
             status: passed ? "pass" : "fail",
             detail,
-            action: passed ? "" : actions[name],
+            action: passed
+                ? ""
+                : name === "verbosity" && isVerbosityAuthorityError(detail)
+                    ? "Repair the verbosity budget authority or its owning artifact schema, then retry lint."
+                    : actions[name],
         });
     }
     return checks;
 }
-export function lintPayload(args) {
-    const [text, source, fullArtifact, budgetArtifact] = lintInputText(args);
-    const artifact = budgetArtifact || String(args.artifact);
+function lintPayloadForContent(artifact, text, source, fullArtifact, strict = false) {
     validateAgentString(artifact, "artifact");
     const checks = lintChecks(text, artifact, fullArtifact);
     const failures = checks.filter((c) => c.status === "fail");
@@ -143,15 +116,24 @@ export function lintPayload(args) {
         status: failures.length > 0 ? "fail" : "pass",
         artifact,
         source,
-        strict: Boolean(args.strict),
+        strict,
         checks,
         summary: {
             failed: failures.length,
             passed: checks.length - failures.length,
-            advisory: !args.strict,
+            advisory: !strict,
         },
     };
 }
+/** Runs the same full-artifact checks as `check lint --file` without a staging file. */
+export function lintFullArtifactPayload(artifact, content) {
+    return lintPayloadForContent(artifact, content, "candidate", true, true);
+}
+export function lintPayload(args) {
+    const [text, source, fullArtifact, budgetArtifact] = lintInputText(args);
+    const artifact = budgetArtifact || String(args.artifact);
+    return lintPayloadForContent(artifact, text, source, fullArtifact, Boolean(args.strict));
+}
 function emitLintText(payload, out) {
     const failures = payload.checks.filter((c) => c.status === "fail");
     out(`lint ${payload.status}: ${payload.artifact} (${payload.source})\n`);
@@ -174,6 +156,6 @@ export function cmdLint(args, io = {}) {
     else {
         emitLintText(payload, out);
     }
-    return payload.status === "fail" ? 1 : 0;
+    const operationalFailure = payload.checks.some((check) => check.status === "fail" && isVerbosityAuthorityError(check.detail));
+    return operationalFailure || (args.strict && payload.status === "fail") ? 1 : 0;
 }
-//# sourceMappingURL=lint.js.map

package/dist/cli/commands/personalGlossary.js

@@ -0,0 +1,176 @@
+import fs from "node:fs";
+import { updatePersonalGlossaryProfile } from "../../analytics/personalGlossaryProfile.js";
+import { loadYamlMapping } from "../../core/yaml.js";
+import { personalGlossaryOutputContract } from "../../registries/glossaryEntryContract.js";
+import { emitInvalidInput } from "../errors.js";
+import { emitStructured } from "../structured.js";
+const REQUEST_FIELDS = ["schema_version", "profile_path", "as_of", "fresh_entries", "retained_history"];
+const HISTORY_FIELDS = ["source_id", "evidence_anchor", "source_kind", "signal_type"];
+const RECOVERY = "Correct the request and retry the same command; no profile bytes were changed.";
+function mapping(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function calendarDate(value) {
+    if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return false;
+    const date = new Date(`${value}T00:00:00.000Z`);
+    return !Number.isNaN(date.getTime()) && date.toISOString().slice(0, 10) === value;
+}
+function invalid(io, body) {
+    return emitInvalidInput(io, { format: "json", body: { ...body, recovery: body.recovery ?? RECOVERY } });
+}
+function parseArgs(argv) {
+    let input;
+    let dryRun = false;
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
+        const [name, inline] = argument.split("=", 2);
+        if (name === "--dry-run") {
+            if (inline !== undefined)
+                return { class: "unrecognized_argument", message: "--dry-run does not accept a value" };
+            dryRun = true;
+            continue;
+        }
+        if (name === "--input" || name === "--format") {
+            const value = inline ?? argv[++index];
+            if (!value || value.startsWith("--"))
+                return { class: "missing_argument", message: `${name} requires a value`, syntax: `${name} VALUE` };
+            if (name === "--format") {
+                if (value !== "json")
+                    return { class: "invalid_choice", message: `argument --format: invalid choice: '${value}' (choose from 'json')`, valid_values: ["json"] };
+            }
+            else {
+                if (input !== undefined)
+                    return { class: "mutually_exclusive", message: "--input may only be supplied once" };
+                input = value;
+            }
+            continue;
+        }
+        return { class: "unrecognized_argument", message: `unrecognized arguments: ${argument}`, syntax: "agentera report profile-glossary --input <file|-> [--dry-run] --format json" };
+    }
+    if (!input)
+        return { class: "missing_argument", message: "--input is required", syntax: "agentera report profile-glossary --input <file|-> [--dry-run] --format json" };
+    return { input, dryRun };
+}
+function readRequest(source, io) {
+    let bytes;
+    if (source === "-")
+        bytes = Buffer.from(io.stdin ? io.stdin() : fs.readFileSync(0));
+    else
+        bytes = fs.readFileSync(source);
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    const parsed = mapping(loadYamlMapping(text));
+    if (!parsed)
+        throw new Error("request is not a mapping");
+    return parsed;
+}
+function validateRequest(value) {
+    const contract = personalGlossaryOutputContract();
+    const keys = Object.keys(value);
+    const unsupported = keys.filter((key) => !REQUEST_FIELDS.includes(key));
+    const missing = REQUEST_FIELDS.filter((key) => !(key in value));
+    if (unsupported.length > 0 || missing.length > 0) {
+        return { class: "schema_violation", message: `request fields are invalid${missing.length ? `; missing: ${missing.join(", ")}` : ""}${unsupported.length ? `; unsupported: ${unsupported.join(", ")}` : ""}`, valid_values: REQUEST_FIELDS };
+    }
+    if (value.schema_version !== contract.requestSchemaVersion) {
+        return { class: "schema_violation", message: `schema_version must be ${contract.requestSchemaVersion}`, valid_values: [contract.requestSchemaVersion] };
+    }
+    if (typeof value.profile_path !== "string" || value.profile_path.trim() === "") {
+        return { class: "invalid_request", message: "profile_path must be the exact non-empty path returned by prime profile context", valid_values: ["profile_context.profile.path"] };
+    }
+    if (!calendarDate(value.as_of)) {
+        return { class: "invalid_request", message: "as_of must be an ISO calendar date", valid_values: ["YYYY-MM-DD"] };
+    }
+    if (!Array.isArray(value.fresh_entries) || value.fresh_entries.some((entry) => !mapping(entry))) {
+        return { class: "invalid_request", message: "fresh_entries must be a list of shared personal glossary entries", valid_values: ["fresh_entries: []"] };
+    }
+    for (const [index, raw] of value.fresh_entries.entries()) {
+        const entry = mapping(raw);
+        const temporal = mapping(entry.temporal);
+        if (!temporal || !calendarDate(temporal.observed_at) || !calendarDate(temporal.last_confirmed_at)) {
+            return { class: "invalid_request", message: `fresh_entries[${index}].temporal requires observed_at and last_confirmed_at ISO calendar dates`, valid_values: ["YYYY-MM-DD"] };
+        }
+        if (!["stable", "durable", "situational"].includes(entry.permanence)) {
+            return { class: "invalid_request", message: `fresh_entries[${index}].permanence is invalid`, valid_values: ["stable", "durable", "situational"] };
+        }
+        const provenance = mapping(entry.provenance);
+        if (!provenance || !["personal_explicit_definition", "personal_inferred_usage"].includes(String(provenance.kind))) {
+            return { class: "invalid_request", message: `fresh_entries[${index}].provenance.kind is invalid`, valid_values: ["personal_explicit_definition", "personal_inferred_usage"] };
+        }
+    }
+    if (!Array.isArray(value.retained_history) || value.retained_history.some((row) => !mapping(row))) {
+        return { class: "invalid_request", message: "retained_history must be a list", valid_values: ["retained_history: []"] };
+    }
+    for (const [index, raw] of value.retained_history.entries()) {
+        const row = mapping(raw);
+        if (JSON.stringify(Object.keys(row).sort()) !== JSON.stringify([...HISTORY_FIELDS].sort()) || HISTORY_FIELDS.some((field) => typeof row[field] !== "string" || String(row[field]).trim() === "")) {
+            return { class: "invalid_request", message: `retained_history[${index}] must contain exactly ${HISTORY_FIELDS.join(", ")}`, valid_values: HISTORY_FIELDS };
+        }
+    }
+    return null;
+}
+function admissionContext(rows) {
+    const retainedHistory = new Map();
+    for (const raw of rows) {
+        const row = mapping(raw);
+        const anchor = String(row.evidence_anchor);
+        if (retainedHistory.has(anchor))
+            return { class: "conflict", message: `retained_history contains duplicate evidence_anchor '${anchor}'`, valid_values: ["one row per evidence_anchor"] };
+        retainedHistory.set(anchor, { sourceId: String(row.source_id), sourceKind: String(row.source_kind), signalType: String(row.signal_type) });
+    }
+    return { retainedHistory };
+}
+export function runPersonalGlossaryCommand(argv, io) {
+    const parsed = parseArgs(argv);
+    if ("class" in parsed)
+        return invalid(io, parsed);
+    let request;
+    try {
+        request = readRequest(parsed.input, io);
+    }
+    catch {
+        return invalid(io, { class: "invalid_format", message: "--input must be a readable UTF-8 YAML or JSON mapping", valid_values: ["YAML mapping", "JSON object"] });
+    }
+    const requestError = validateRequest(request);
+    if (requestError)
+        return invalid(io, requestError);
+    const profilePath = String(request.profile_path);
+    try {
+        if (!fs.statSync(profilePath).isFile())
+            throw new Error("not a regular file");
+    }
+    catch {
+        return invalid(io, { class: "invalid_request", message: `profile_path is not an existing readable PROFILE.md file: ${profilePath}`, valid_values: ["existing PROFILE.md path from profile_context.profile.path"] });
+    }
+    const context = admissionContext(request.retained_history);
+    if ("class" in context)
+        return invalid(io, context);
+    try {
+        const result = updatePersonalGlossaryProfile({
+            profilePath,
+            asOf: String(request.as_of),
+            freshEntries: request.fresh_entries,
+            retainedHistory: context,
+            dryRun: parsed.dryRun,
+        });
+        const candidateStatus = result.changed ? "changed" : "unchanged";
+        emitStructured({
+            schemaVersion: "agentera.personalGlossaryUpdate.v1",
+            command: "report profile-glossary",
+            status: parsed.dryRun ? "dry_run_candidate" : result.changed ? "changed" : "unchanged_replay",
+            dry_run: parsed.dryRun,
+            candidate_status: candidateStatus,
+            profile_path: profilePath,
+            entry_count: result.entries.length,
+        }, "json", io.out ?? ((text) => process.stdout.write(text)));
+        return 0;
+    }
+    catch (error) {
+        const message = error.message;
+        return invalid(io, {
+            class: /conflict|duplicate|ambiguous/i.test(message) ? "conflict" : "invalid_request",
+            message,
+            valid_values: ["stable", "durable", "situational", "personal_explicit_definition", "personal_inferred_usage"],
+        });
+    }
+}