agentera 3.0.0-dev.13 → 3.0.0-dev.15

package/dist/state/write/fields.js

@@ -0,0 +1,62 @@
+import { ArtifactSchemaValidator } from "../../hooks/validateArtifact/index.js";
+function schemaEntry(schema, fieldPath) {
+    const leaf = fieldPath.split(".").at(-1);
+    for (const value of Object.values(schema)) {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            continue;
+        for (const entry of Object.values(value)) {
+            if (entry &&
+                typeof entry === "object" &&
+                !Array.isArray(entry) &&
+                String(entry.field ?? "") === leaf) {
+                return entry;
+            }
+        }
+    }
+    return null;
+}
+function valuesFromValidation(entry) {
+    if (!entry || !Array.isArray(entry.validation))
+        return undefined;
+    for (const raw of entry.validation) {
+        const match = /Must be one of:\s*(.+)$/i.exec(String(raw));
+        if (match)
+            return match[1]
+                .split(",")
+                .map((v) => v.trim())
+                .filter(Boolean);
+    }
+    return undefined;
+}
+export function projectedFields(spec, validator = new ArtifactSchemaValidator()) {
+    const schema = validator.loadSchema(spec.artifact);
+    if (!schema)
+        return spec.fields;
+    return spec.fields.map((field) => {
+        const entry = schemaEntry(schema, field.field);
+        return {
+            ...field,
+            required: field.required ?? Boolean(entry?.required),
+            validValues: field.validValues ?? valuesFromValidation(entry),
+            description: field.description ?? (entry?.description ? String(entry.description) : undefined),
+        };
+    });
+}
+export function schemaBudget(artifact, validator = new ArtifactSchemaValidator()) {
+    const schema = validator.loadSchema(artifact);
+    const result = {};
+    if (!schema ||
+        !schema.BUDGET ||
+        typeof schema.BUDGET !== "object" ||
+        Array.isArray(schema.BUDGET))
+        return result;
+    for (const entry of Object.values(schema.BUDGET)) {
+        if (!entry || typeof entry !== "object" || Array.isArray(entry))
+            continue;
+        const scope = String(entry.scope ?? "");
+        const key = scope.includes("full_file") ? "full_file_max_words" : "per_entry_max_words";
+        result[key] = typeof entry.max_words === "number" ? entry.max_words : null;
+    }
+    return result;
+}
+//# sourceMappingURL=fields.js.map

package/dist/state/write/fields.js.map

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

package/dist/state/write/index.js

@@ -0,0 +1,11 @@
+export * from "./operations.js";
+export * from "./fields.js";
+export * from "./input.js";
+export * from "./assign.js";
+export * from "./explain.js";
+export * from "./lock.js";
+export * from "./transaction.js";
+export * from "./validate.js";
+export * from "./serialize.js";
+export * from "./errors.js";
+//# sourceMappingURL=index.js.map

package/dist/state/write/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/state/write/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC"}

package/dist/state/write/input.js

@@ -0,0 +1,22 @@
+import fs from "node:fs";
+import { loadYamlMapping } from "../../core/yaml.js";
+export function loadStructuredInput(source, readStdin) {
+    let text;
+    if (source === "-")
+        text = readStdin();
+    else {
+        try {
+            text = fs.readFileSync(source, "utf8");
+        }
+        catch {
+            throw new Error(`input file '${source}' is not readable`);
+        }
+    }
+    try {
+        return loadYamlMapping(text);
+    }
+    catch (error) {
+        throw new Error(`input is not valid YAML or JSON: ${error.message}`);
+    }
+}
+//# sourceMappingURL=input.js.map

package/dist/state/write/input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input.js","sourceRoot":"","sources":["../../../src/state/write/input.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAEzB,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD,MAAM,UAAU,mBAAmB,CACjC,MAAc,EACd,SAAuB;IAEvB,IAAI,IAAY,CAAC;IACjB,IAAI,MAAM,KAAK,GAAG;QAAE,IAAI,GAAG,SAAS,EAAE,CAAC;SAClC,CAAC;QACJ,IAAI,CAAC;YACH,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACzC,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,KAAK,CAAC,eAAe,MAAM,mBAAmB,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC;IACD,IAAI,CAAC;QACH,OAAO,eAAe,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,oCAAqC,KAAe,CAAC,OAAO,EAAE,CAAC,CAAC;IAClF,CAAC;AACH,CAAC"}

package/dist/state/write/lock.js

@@ -0,0 +1,108 @@
+import fs from "node:fs";
+import path from "node:path";
+import { assertRealpathBoundary } from "../../registries/artifactRegistry.js";
+const sleepArray = new Int32Array(new SharedArrayBuffer(4));
+const INITIALIZATION_GRACE_MS = 250;
+function malformedLockIsStale(lockPath) {
+    try {
+        return Date.now() - fs.statSync(lockPath).mtimeMs >= INITIALIZATION_GRACE_MS;
+    }
+    catch {
+        return true;
+    }
+}
+function ownerIsDead(lockPath) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+        if (!Number.isInteger(parsed.pid))
+            return malformedLockIsStale(lockPath);
+        if (parsed.pid === process.pid)
+            return false;
+        try {
+            process.kill(parsed.pid, 0);
+            return false;
+        }
+        catch (error) {
+            return error.code === "ESRCH";
+        }
+    }
+    catch {
+        return malformedLockIsStale(lockPath);
+    }
+}
+export function acquireWriterLock(projectRoot, timeoutMs = 2000) {
+    const dir = path.join(projectRoot, ".agentera");
+    assertRealpathBoundary(projectRoot, dir, "writer lock");
+    const createdDir = !fs.existsSync(dir);
+    fs.mkdirSync(dir, { recursive: true });
+    const lockPath = path.join(dir, ".writer.lock");
+    const deadline = Date.now() + timeoutMs;
+    while (true) {
+        let fd;
+        let createdLock = false;
+        try {
+            fd = fs.openSync(lockPath, "wx");
+            createdLock = true;
+            fs.writeFileSync(fd, JSON.stringify({ pid: process.pid, created_at: new Date().toISOString() }) + "\n");
+            fs.closeSync(fd);
+            fd = undefined;
+            let released = false;
+            return {
+                path: lockPath,
+                release: () => {
+                    if (released)
+                        return;
+                    released = true;
+                    try {
+                        fs.unlinkSync(lockPath);
+                    }
+                    catch {
+                        /* already released */
+                    }
+                    if (createdDir) {
+                        try {
+                            fs.rmdirSync(dir);
+                        }
+                        catch {
+                            /* a published artifact or peer now owns the directory */
+                        }
+                    }
+                },
+            };
+        }
+        catch (error) {
+            if (fd !== undefined) {
+                try {
+                    fs.closeSync(fd);
+                }
+                catch {
+                    /* acquisition already failed */
+                }
+            }
+            if (createdLock) {
+                try {
+                    fs.unlinkSync(lockPath);
+                }
+                catch {
+                    /* acquisition already failed */
+                }
+            }
+            if (error.code !== "EEXIST")
+                throw error;
+            if (ownerIsDead(lockPath)) {
+                try {
+                    fs.unlinkSync(lockPath);
+                }
+                catch {
+                    /* raced with another writer */
+                }
+                continue;
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`writer lock timeout at '${lockPath}'; retry the command after the active writer finishes`);
+            }
+            Atomics.wait(sleepArray, 0, 0, 25);
+        }
+    }
+}
+//# sourceMappingURL=lock.js.map

package/dist/state/write/lock.js.map

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

package/dist/state/write/operations.js

@@ -0,0 +1,181 @@
+export const WRITABLE_ARTIFACTS = ["progress", "decisions", "plan", "health"];
+export const WRITE_VERBS = [
+    "append",
+    "update",
+    "set-status",
+    "archive",
+    "create",
+    "explain",
+];
+const progressAppend = [
+    {
+        flag: "--type",
+        field: "type",
+        kind: "string",
+        required: true,
+        validValues: ["feat", "fix", "docs", "refactor", "chore", "test"],
+    },
+    {
+        flag: "--phase",
+        field: "phase",
+        kind: "string",
+        required: true,
+        validValues: ["envision", "deliberate", "plan", "build", "audit"],
+    },
+    { flag: "--what", field: "what", kind: "string", required: true },
+    { flag: "--intent", field: "context.intent", kind: "string", required: true },
+    { flag: "--timestamp", field: "timestamp", kind: "datetime", required: false },
+    { flag: "--inspiration", field: "inspiration", kind: "string" },
+    { flag: "--discovered", field: "discovered", kind: "string" },
+    { flag: "--verified", field: "verified", kind: "string" },
+    { flag: "--next", field: "next", kind: "string" },
+    { flag: "--constraints", field: "context.constraints", kind: "string" },
+    { flag: "--unknowns", field: "context.unknowns", kind: "string" },
+    { flag: "--scope", field: "context.scope", kind: "string" },
+];
+const decisionAppend = [
+    { flag: "--question", field: "question", kind: "string", required: true },
+    { flag: "--context", field: "context", kind: "string", required: true },
+    { flag: "--alternative-chosen", field: "alternatives.chosen", kind: "string", required: true },
+    {
+        flag: "--alternative-rejected",
+        field: "alternatives.rejected",
+        kind: "string_list",
+        repeatable: true,
+    },
+    { flag: "--choice", field: "choice", kind: "string", required: true },
+    { flag: "--reasoning", field: "reasoning", kind: "string", required: true },
+    {
+        flag: "--confidence",
+        field: "confidence",
+        kind: "string",
+        required: true,
+        validValues: ["firm", "provisional", "exploratory"],
+    },
+    { flag: "--feeds-into", field: "feeds_into", kind: "string" },
+    { flag: "--date", field: "date", kind: "date", required: false },
+];
+const decisionUpdate = [
+    { flag: "--number", field: "number", kind: "integer", required: true },
+    {
+        flag: "--satisfaction-state",
+        field: "satisfaction.state",
+        kind: "string",
+        required: true,
+        validValues: ["open", "provisionally_satisfied", "user_confirmed_satisfied"],
+    },
+    { flag: "--satisfaction-evidence", field: "satisfaction.evidence", kind: "string" },
+    { flag: "--confirmed-by", field: "satisfaction.user_confirmation.confirmed_by", kind: "string" },
+    { flag: "--confirmed-at", field: "satisfaction.user_confirmation.confirmed_at", kind: "string" },
+];
+const planTaskFields = [
+    { flag: "--name", field: "name", kind: "string", required: true },
+    { flag: "--depends-on", field: "depends_on", kind: "integer_list", repeatable: true },
+    { flag: "--acceptance", field: "acceptance", kind: "string_list", repeatable: true },
+    {
+        flag: "--status",
+        field: "status",
+        kind: "string",
+        required: false,
+        validValues: ["complete", "in_progress", "pending", "blocked"],
+    },
+];
+const SPECS = [
+    { artifact: "progress", verb: "append", fields: progressAppend, compacts: true },
+    { artifact: "decisions", verb: "append", fields: decisionAppend, compacts: true },
+    { artifact: "decisions", verb: "update", fields: decisionUpdate },
+    { artifact: "plan", verb: "append", fields: planTaskFields },
+    {
+        artifact: "plan",
+        verb: "update",
+        fields: [
+            { flag: "--task", field: "task", kind: "integer", required: true },
+            ...planTaskFields
+                .filter((field) => field.field !== "status")
+                .map((field) => ({ ...field, required: false })),
+            { flag: "--evidence", field: "evidence", kind: "string" },
+            { flag: "--blocked-reason", field: "blocked_reason", kind: "string" },
+            { flag: "--surprise", field: "surprise", kind: "string" },
+        ],
+    },
+    {
+        artifact: "plan",
+        verb: "set-status",
+        fields: [
+            { flag: "--task", field: "task", kind: "integer" },
+            {
+                flag: "--status",
+                field: "status",
+                kind: "string",
+                required: true,
+                validValues: ["active", "complete", "in_progress", "pending", "blocked"],
+            },
+        ],
+    },
+    { artifact: "plan", verb: "archive", fields: [], allowForce: true },
+    {
+        artifact: "plan",
+        verb: "create",
+        fields: [],
+        inputRoot: "complete plan document",
+        cliOwnedFields: ["previous_plan_archived"],
+        allowForce: true,
+    },
+    {
+        artifact: "health",
+        verb: "append",
+        fields: [],
+        inputRoot: "one audit entry",
+        cliOwnedFields: ["number"],
+        compacts: true,
+    },
+];
+export function operationSpec(artifact, verb) {
+    return SPECS.find((spec) => spec.artifact === artifact && spec.verb === verb) ?? null;
+}
+export function verbsForArtifact(artifact) {
+    if (!WRITABLE_ARTIFACTS.includes(artifact))
+        return [];
+    return [
+        ...SPECS.filter((spec) => spec.artifact === artifact).map((spec) => spec.verb),
+        "explain",
+    ];
+}
+export function isWriteVerb(value) {
+    return Boolean(value && WRITE_VERBS.includes(value));
+}
+export function isWritableArtifact(value) {
+    return WRITABLE_ARTIFACTS.includes(value);
+}
+export function stateWriterArtifactContract(artifact) {
+    if (!isWritableArtifact(artifact))
+        return null;
+    const verbs = verbsForArtifact(artifact);
+    const mutations = verbs.filter((verb) => verb !== "explain");
+    return {
+        artifact,
+        mutations,
+        explain_command: `agentera state ${artifact} explain --format json`,
+        explain_by_verb: Object.fromEntries(mutations.map((verb) => [
+            verb,
+            `agentera state ${artifact} explain --verb ${verb} --format json`,
+        ])),
+        supports_dry_run: true,
+    };
+}
+export function stateWriterContract(targets = WRITABLE_ARTIFACTS) {
+    const uniqueTargets = [...new Set(targets)];
+    const artifacts = uniqueTargets
+        .map(stateWriterArtifactContract)
+        .filter((entry) => entry !== null);
+    return {
+        schemaVersion: "agentera.stateWriterDiscovery.v1",
+        namespace: "agentera state",
+        policy: "Use the state writer for supported artifact mutations; do not hand-edit those artifacts during normal capability execution.",
+        authority: "runtime operation registry",
+        discovery_command: "agentera schema --format json",
+        artifacts,
+        unsupported_targets: uniqueTargets.filter((target) => !isWritableArtifact(target)),
+    };
+}
+//# sourceMappingURL=operations.js.map

package/dist/state/write/operations.js.map

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

package/dist/state/write/serialize.js

@@ -0,0 +1,2 @@
+export { dumpYamlMapping } from "../../core/yaml.js";
+//# sourceMappingURL=serialize.js.map

package/dist/state/write/serialize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.js","sourceRoot":"","sources":["../../../src/state/write/serialize.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC"}