@nifrajs/coding-agent 3.2.0

package/dist/workflows.d.ts

@@ -0,0 +1,98 @@
+export interface WorkflowContext {
+    readonly signal: AbortSignal;
+    readonly values: ReadonlyMap<string, unknown>;
+    set(name: string, value: unknown): void;
+    run(step: WorkflowStep): Promise<unknown>;
+}
+export type WorkflowStep = {
+    readonly type: "task";
+    readonly id: string;
+    readonly run: (context: WorkflowContext) => unknown | PromiseLike<unknown>;
+} | {
+    readonly type: "sequence";
+    readonly steps: readonly WorkflowStep[];
+} | {
+    readonly type: "parallel";
+    readonly steps: readonly WorkflowStep[];
+    readonly maxConcurrency?: number;
+} | {
+    readonly type: "verify";
+    readonly id: string;
+    readonly run: (context: WorkflowContext) => unknown | PromiseLike<boolean | {
+        readonly ok: boolean;
+        readonly report?: unknown;
+    }>;
+} | {
+    readonly type: "approve";
+    readonly id: string;
+    readonly reason: string;
+    readonly run: (context: WorkflowContext) => unknown | PromiseLike<boolean>;
+} | {
+    readonly type: "retry";
+    readonly step: WorkflowStep;
+    readonly attempts?: number;
+    readonly backoffMs?: number;
+} | {
+    readonly type: "branch";
+    readonly id: string;
+    readonly when: (context: WorkflowContext) => boolean | PromiseLike<boolean>;
+    readonly then: WorkflowStep;
+    readonly otherwise?: WorkflowStep;
+} | {
+    readonly type: "checkpoint";
+    readonly id: string;
+    readonly run: (context: WorkflowContext) => unknown | PromiseLike<unknown>;
+} | {
+    readonly type: "handoff";
+    readonly id: string;
+    readonly run: (context: WorkflowContext) => unknown | PromiseLike<unknown>;
+};
+export interface WorkflowRunnerOptions {
+    readonly signal?: AbortSignal;
+    readonly maxSteps?: number;
+    readonly maxDepth?: number;
+    readonly onEvent?: (event: WorkflowEvent) => void | PromiseLike<void>;
+    readonly exposeErrorStacks?: boolean;
+}
+export type WorkflowEvent = {
+    readonly type: "step.started";
+    readonly id: string;
+} | {
+    readonly type: "step.completed";
+    readonly id: string;
+    readonly output?: unknown;
+} | {
+    readonly type: "step.failed";
+    readonly id: string;
+    readonly error: string;
+    readonly stack?: string;
+} | {
+    readonly type: "approval.required";
+    readonly id: string;
+    readonly reason: string;
+} | {
+    readonly type: "checkpoint.created";
+    readonly id: string;
+};
+export interface WorkflowResult {
+    readonly ok: boolean;
+    readonly values: ReadonlyMap<string, unknown>;
+    readonly completed: readonly string[];
+    readonly error?: string;
+    readonly stack?: string;
+}
+/** Bounded orchestration primitives. The kernel knows no provider, UI, or framework package. */
+export declare class WorkflowRunner {
+    private readonly options;
+    private readonly values;
+    private readonly completed;
+    private steps;
+    constructor(options?: WorkflowRunnerOptions);
+    run(step: WorkflowStep): Promise<WorkflowResult>;
+    private context;
+    private execute;
+    private single;
+    private parallel;
+    private emit;
+}
+//# sourceMappingURL=workflows.d.ts.map

package/dist/workflows.d.ts.map

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

package/dist/workflows.js

@@ -0,0 +1,174 @@
+import { publicErrorDetails } from "./errors.js";
+/** Bounded orchestration primitives. The kernel knows no provider, UI, or framework package. */
+export class WorkflowRunner {
+    options;
+    values = new Map();
+    completed = [];
+    steps = 0;
+    constructor(options = {}) {
+        this.options = {
+            ...options,
+            maxSteps: options.maxSteps ?? 128,
+            maxDepth: options.maxDepth ?? 8,
+        };
+        if (!Number.isSafeInteger(this.options.maxSteps) || this.options.maxSteps < 1)
+            throw new RangeError("workflow: maxSteps must be positive");
+        if (!Number.isSafeInteger(this.options.maxDepth) || this.options.maxDepth < 1)
+            throw new RangeError("workflow: maxDepth must be positive");
+    }
+    async run(step) {
+        try {
+            await this.execute(step, 0);
+            return {
+                ok: true,
+                values: new Map(this.values),
+                completed: Object.freeze([...this.completed]),
+            };
+        }
+        catch (error) {
+            const details = publicErrorDetails(error, "workflow failed", this.options.exposeErrorStacks === true);
+            return {
+                ok: false,
+                values: new Map(this.values),
+                completed: Object.freeze([...this.completed]),
+                error: details.message,
+                ...(details.stack === undefined ? {} : { stack: details.stack }),
+            };
+        }
+    }
+    context() {
+        return {
+            signal: this.options.signal ?? new AbortController().signal,
+            values: this.values,
+            set: (name, value) => this.values.set(name, value),
+            run: (step) => this.execute(step, 1),
+        };
+    }
+    async execute(step, depth) {
+        if (depth > this.options.maxDepth)
+            throw new Error("workflow max depth exceeded");
+        if (++this.steps > this.options.maxSteps)
+            throw new Error("workflow max steps exceeded");
+        if (this.options.signal?.aborted)
+            throw new Error("workflow cancelled");
+        switch (step.type) {
+            case "task":
+                return this.single(step.id, () => step.run(this.context()));
+            case "verify": {
+                const result = await this.single(step.id, () => step.run(this.context()));
+                const ok = typeof result === "boolean" ? result : isVerificationResult(result) && result.ok;
+                if (!ok)
+                    throw new Error(`verification failed: ${step.id}`);
+                return result;
+            }
+            case "approve": {
+                await this.emit({ type: "approval.required", id: step.id, reason: step.reason });
+                const approved = await this.single(step.id, () => step.run(this.context()));
+                if (approved !== true)
+                    throw new Error(`approval denied: ${step.id}`);
+                return approved;
+            }
+            case "checkpoint": {
+                const result = await this.single(step.id, () => step.run(this.context()));
+                await this.emit({ type: "checkpoint.created", id: step.id });
+                return result;
+            }
+            case "handoff":
+                return this.single(step.id, () => step.run(this.context()));
+            case "sequence": {
+                const results = [];
+                for (const child of step.steps)
+                    results.push(await this.execute(child, depth + 1));
+                return results;
+            }
+            case "parallel":
+                return this.parallel(step.steps, step.maxConcurrency ?? step.steps.length, depth);
+            case "retry": {
+                const attempts = step.attempts ?? 3;
+                if (!Number.isSafeInteger(attempts) || attempts < 1 || attempts > 16)
+                    throw new RangeError("workflow: attempts must be between 1 and 16");
+                let last;
+                for (let attempt = 0; attempt < attempts; attempt++) {
+                    try {
+                        return await this.execute(step.step, depth + 1);
+                    }
+                    catch (error) {
+                        last = error;
+                        if (attempt + 1 < attempts && (step.backoffMs ?? 0) > 0)
+                            await delay(Math.min(step.backoffMs * (attempt + 1), 10_000), this.options.signal);
+                    }
+                }
+                throw last instanceof Error ? last : new Error(String(last));
+            }
+            case "branch": {
+                const selected = await this.single(step.id, () => step.when(this.context()));
+                return selected === true
+                    ? this.execute(step.then, depth + 1)
+                    : step.otherwise === undefined
+                        ? undefined
+                        : this.execute(step.otherwise, depth + 1);
+            }
+        }
+    }
+    async single(id, run) {
+        await this.emit({ type: "step.started", id });
+        try {
+            const output = await run();
+            this.completed.push(id);
+            await this.emit({ type: "step.completed", id, ...(output === undefined ? {} : { output }) });
+            return output;
+        }
+        catch (error) {
+            const details = publicErrorDetails(error, "workflow step failed", this.options.exposeErrorStacks === true);
+            await this.emit({
+                type: "step.failed",
+                id,
+                error: details.message,
+                ...(details.stack === undefined ? {} : { stack: details.stack }),
+            });
+            throw error;
+        }
+    }
+    async parallel(steps, maxConcurrency, depth) {
+        if (!Number.isSafeInteger(maxConcurrency) || maxConcurrency < 1)
+            throw new RangeError("workflow: maxConcurrency must be positive");
+        const outputs = new Array(steps.length);
+        let next = 0;
+        const worker = async () => {
+            for (;;) {
+                const index = next++;
+                if (index >= steps.length)
+                    return;
+                outputs[index] = await this.execute(steps[index], depth + 1);
+            }
+        };
+        await Promise.all(Array.from({ length: Math.min(maxConcurrency, steps.length) }, () => worker()));
+        return outputs;
+    }
+    async emit(event) {
+        await this.options.onEvent?.(event);
+    }
+}
+async function delay(ms, signal) {
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(resolve, ms);
+        if (signal === undefined)
+            return;
+        if (signal.aborted) {
+            clearTimeout(timer);
+            reject(new Error("workflow cancelled"));
+            return;
+        }
+        signal.addEventListener("abort", () => {
+            clearTimeout(timer);
+            reject(new Error("workflow cancelled"));
+        }, { once: true });
+    });
+}
+function isVerificationResult(value) {
+    return (value !== null &&
+        typeof value === "object" &&
+        !Array.isArray(value) &&
+        typeof value.ok === "boolean");
+}
+//# sourceMappingURL=workflows.js.map

package/dist/workflows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflows.js","sourceRoot":"","sources":["../src/workflows.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAA;AAsFhD,gGAAgG;AAChG,MAAM,OAAO,cAAc;IACR,OAAO,CACD;IACN,MAAM,GAAG,IAAI,GAAG,EAAmB,CAAA;IACnC,SAAS,GAAa,EAAE,CAAA;IACjC,KAAK,GAAG,CAAC,CAAA;IAEjB,YAAY,UAAiC,EAAE;QAC7C,IAAI,CAAC,OAAO,GAAG;YACb,GAAG,OAAO;YACV,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,GAAG;YACjC,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,CAAC;SAChC,CAAA;QACD,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,QAAQ,GAAG,CAAC;YAC3E,MAAM,IAAI,UAAU,CAAC,qCAAqC,CAAC,CAAA;QAC7D,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,QAAQ,GAAG,CAAC;YAC3E,MAAM,IAAI,UAAU,CAAC,qCAAqC,CAAC,CAAA;IAC/D,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,IAAkB;QAC1B,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAA;YAC3B,OAAO;gBACL,EAAE,EAAE,IAAI;gBACR,MAAM,EAAE,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC;gBAC5B,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;aAC9C,CAAA;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,OAAO,GAAG,kBAAkB,CAChC,KAAK,EACL,iBAAiB,EACjB,IAAI,CAAC,OAAO,CAAC,iBAAiB,KAAK,IAAI,CACxC,CAAA;YACD,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,MAAM,EAAE,IAAI,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC;gBAC5B,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC;gBAC7C,KAAK,EAAE,OAAO,CAAC,OAAO;gBACtB,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;aACjE,CAAA;QACH,CAAC;IACH,CAAC;IAEO,OAAO;QACb,OAAO;YACL,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,IAAI,eAAe,EAAE,CAAC,MAAM;YAC3D,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,GAAG,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC;YAClD,GAAG,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;SACrC,CAAA;IACH,CAAC;IAEO,KAAK,CAAC,OAAO,CAAC,IAAkB,EAAE,KAAa;QACrD,IAAI,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAA;QACjF,IAAI,EAAE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAA;QACxF,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO;YAAE,MAAM,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAA;QACvE,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;YAClB,KAAK,MAAM;gBACT,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;YAC7D,KAAK,QAAQ,CAAC,CAAC,CAAC;gBACd,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;gBACzE,MAAM,EAAE,GAAG,OAAO,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,oBAAoB,CAAC,MAAM,CAAC,IAAI,MAAM,CAAC,EAAE,CAAA;gBAC3F,IAAI,CAAC,EAAE;oBAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,CAAC,EAAE,EAAE,CAAC,CAAA;gBAC3D,OAAO,MAAM,CAAA;YACf,CAAC;YACD,KAAK,SAAS,CAAC,CAAC,CAAC;gBACf,MAAM,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,mBAAmB,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAA;gBAChF,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;gBAC3E,IAAI,QAAQ,KAAK,IAAI;oBAAE,MAAM,IAAI,KAAK,CAAC,oBAAoB,IAAI,CAAC,EAAE,EAAE,CAAC,CAAA;gBACrE,OAAO,QAAQ,CAAA;YACjB,CAAC;YACD,KAAK,YAAY,CAAC,CAAC,CAAC;gBAClB,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;gBACzE,MAAM,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,oBAAoB,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC,CAAA;gBAC5D,OAAO,MAAM,CAAA;YACf,CAAC;YACD,KAAK,SAAS;gBACZ,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;YAC7D,KAAK,UAAU,CAAC,CAAC,CAAC;gBAChB,MAAM,OAAO,GAAc,EAAE,CAAA;gBAC7B,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK;oBAAE,OAAO,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAA;gBAClF,OAAO,OAAO,CAAA;YAChB,CAAC;YACD,KAAK,UAAU;gBACb,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,cAAc,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,CAAA;YACnF,KAAK,OAAO,CAAC,CAAC,CAAC;gBACb,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,CAAC,CAAA;gBACnC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,QAAQ,GAAG,CAAC,IAAI,QAAQ,GAAG,EAAE;oBAClE,MAAM,IAAI,UAAU,CAAC,6CAA6C,CAAC,CAAA;gBACrE,IAAI,IAAa,CAAA;gBACjB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,QAAQ,EAAE,OAAO,EAAE,EAAE,CAAC;oBACpD,IAAI,CAAC;wBACH,OAAO,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CAAA;oBACjD,CAAC;oBAAC,OAAO,KAAK,EAAE,CAAC;wBACf,IAAI,GAAG,KAAK,CAAA;wBACZ,IAAI,OAAO,GAAG,CAAC,GAAG,QAAQ,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,CAAC,GAAG,CAAC;4BACrD,MAAM,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,SAAU,GAAG,CAAC,OAAO,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;oBACvF,CAAC;gBACH,CAAC;gBACD,MAAM,IAAI,YAAY,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA;YAC9D,CAAC;YACD,KAAK,QAAQ,CAAC,CAAC,CAAC;gBACd,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;gBAC5E,OAAO,QAAQ,KAAK,IAAI;oBACtB,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC;oBACpC,CAAC,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS;wBAC5B,CAAC,CAAC,SAAS;wBACX,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,GAAG,CAAC,CAAC,CAAA;YAC/C,CAAC;QACH,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,MAAM,CAAC,EAAU,EAAE,GAAyC;QACxE,MAAM,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,cAAc,EAAE,EAAE,EAAE,CAAC,CAAA;QAC7C,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,GAAG,EAAE,CAAA;YAC1B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;YACvB,MAAM,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,EAAE,EAAE,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,CAAA;YAC5F,OAAO,MAAM,CAAA;QACf,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,OAAO,GAAG,kBAAkB,CAChC,KAAK,EACL,sBAAsB,EACtB,IAAI,CAAC,OAAO,CAAC,iBAAiB,KAAK,IAAI,CACxC,CAAA;YACD,MAAM,IAAI,CAAC,IAAI,CAAC;gBACd,IAAI,EAAE,aAAa;gBACnB,EAAE;gBACF,KAAK,EAAE,OAAO,CAAC,OAAO;gBACtB,GAAG,CAAC,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;aACjE,CAAC,CAAA;YACF,MAAM,KAAK,CAAA;QACb,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,QAAQ,CACpB,KAA8B,EAC9B,cAAsB,EACtB,KAAa;QAEb,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,cAAc,CAAC,IAAI,cAAc,GAAG,CAAC;YAC7D,MAAM,IAAI,UAAU,CAAC,2CAA2C,CAAC,CAAA;QACnE,MAAM,OAAO,GAAc,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAA;QAClD,IAAI,IAAI,GAAG,CAAC,CAAA;QACZ,MAAM,MAAM,GAAG,KAAK,IAAmB,EAAE;YACvC,SAAS,CAAC;gBACR,MAAM,KAAK,GAAG,IAAI,EAAE,CAAA;gBACpB,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM;oBAAE,OAAM;gBACjC,OAAO,CAAC,KAAK,CAAC,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAE,EAAE,KAAK,GAAG,CAAC,CAAC,CAAA;YAC/D,CAAC;QACH,CAAC,CAAA;QACD,MAAM,OAAO,CAAC,GAAG,CACf,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,cAAc,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,CAAC,CAC/E,CAAA;QACD,OAAO,OAAO,CAAA;IAChB,CAAC;IAEO,KAAK,CAAC,IAAI,CAAC,KAAoB;QACrC,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAA;IACrC,CAAC;CACF;AAED,KAAK,UAAU,KAAK,CAAC,EAAU,EAAE,MAA+B;IAC9D,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC1C,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,EAAE,CAAC,CAAA;QACrC,IAAI,MAAM,KAAK,SAAS;YAAE,OAAM;QAChC,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,YAAY,CAAC,KAAK,CAAC,CAAA;YACnB,MAAM,CAAC,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC,CAAA;YACvC,OAAM;QACR,CAAC;QACD,MAAM,CAAC,gBAAgB,CACrB,OAAO,EACP,GAAG,EAAE;YACH,YAAY,CAAC,KAAK,CAAC,CAAA;YACnB,MAAM,CAAC,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC,CAAA;QACzC,CAAC,EACD,EAAE,IAAI,EAAE,IAAI,EAAE,CACf,CAAA;IACH,CAAC,CAAC,CAAA;AACJ,CAAC;AAED,SAAS,oBAAoB,CAC3B,KAAc;IAEd,OAAO,CACL,KAAK,KAAK,IAAI;QACd,OAAO,KAAK,KAAK,QAAQ;QACzB,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACrB,OAAQ,KAAmC,CAAC,EAAE,KAAK,SAAS,CAC7D,CAAA;AACH,CAAC"}

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@nifrajs/coding-agent",
+  "version": "3.2.0",
+  "description": "Standalone, extensible Nifra coding-agent host and CLI.",
+  "keywords": [
+    "bun",
+    "typescript",
+    "nifra",
+    "agent",
+    "coding-agent",
+    "cli",
+    "workflows"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "nifra-agent": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./extensions": {
+      "bun": "./src/extensions.ts",
+      "types": "./dist/extensions.d.ts",
+      "default": "./dist/extensions.js"
+    },
+    "./verification": {
+      "bun": "./src/verification.ts",
+      "types": "./dist/verification.d.ts",
+      "default": "./dist/verification.js"
+    },
+    "./rpc": {
+      "bun": "./src/rpc.ts",
+      "types": "./dist/rpc.d.ts",
+      "default": "./dist/rpc.js"
+    },
+    "./orchestration": {
+      "bun": "./src/orchestration/index.ts",
+      "types": "./dist/orchestration/index.d.ts",
+      "default": "./dist/orchestration/index.js"
+    },
+    "./registry": {
+      "bun": "./src/registry.ts",
+      "types": "./dist/registry.d.ts",
+      "default": "./dist/registry.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "EXTENSIONS.md",
+    "PERFORMANCE.md",
+    "REGISTRY.md",
+    "SECURITY.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && bun run ../../scripts/fix-dts.ts dist"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nifrajs/agent": "3.2.0",
+    "@nifrajs/agent-protocol": "3.2.0",
+    "@nifrajs/jobs": "3.2.0",
+    "@nifrajs/pi": "3.2.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nifrajs/nifra.git",
+    "directory": "packages/coding-agent"
+  },
+  "bugs": {
+    "url": "https://github.com/nifrajs/nifra/issues"
+  },
+  "homepage": "https://github.com/nifrajs/nifra#readme"
+}

package/src/approvals.ts

@@ -0,0 +1,249 @@
+import {
+  type AgentApprovalRequiredEvent,
+  type AgentApprovalResolvedEvent,
+  coordinateIsFresh,
+  coordinatesMatch,
+  type DecisionCoordinate,
+  nextApprovalState,
+} from "@nifrajs/agent-protocol"
+
+export interface ApprovalRequest {
+  readonly id: string
+  readonly sessionId: string
+  readonly turnId?: string
+  readonly action: string
+  readonly capability: string
+  readonly reason?: string
+  /**
+   * Optional decision-boundary coordinate. When present, {@link ApprovalManager.resolveMatched}
+   * admits a decision only if it names this exact run, node, capability, request id, and vector, and
+   * arrives before expiry. Coordinate-less approvals keep their original untyped {@link resolve} path.
+   */
+  readonly coordinate?: DecisionCoordinate
+  readonly createdAt: number
+  readonly expiresAt: number
+}
+
+/** Stable, content-free reasons a coordinate-matched resolution is refused. */
+export type ApprovalMatchRejection =
+  | "unknown_boundary"
+  | "identity_mismatch"
+  | "stale_vector"
+  | "expired"
+  | "illegal_transition"
+
+export type ApprovalMatchResult =
+  | { readonly ok: true; readonly decision: ApprovalDecision }
+  | { readonly ok: false; readonly code: ApprovalMatchRejection }
+
+export interface ApprovalDecision {
+  readonly approvalId: string
+  readonly approved: boolean
+  readonly reason?: string
+  readonly at: number
+}
+
+export interface ApprovalManagerOptions {
+  readonly maxPending?: number
+  readonly timeoutMs?: number
+  readonly onRequired?: (request: ApprovalRequest) => void | PromiseLike<void>
+  readonly onResolved?: (decision: ApprovalDecision) => void | PromiseLike<void>
+}
+
+interface PendingApproval {
+  readonly request: ApprovalRequest
+  readonly resolve: (approved: boolean) => void
+  readonly timer: ReturnType<typeof setTimeout>
+}
+
+/**
+ * Small approval broker shared by RPC, Workbench, and workflow extensions.
+ *
+ * Approval state is deliberately bounded and expires closed (denied) by default. It is a policy
+ * seam, not a security boundary: filesystem/process isolation still belongs to the host or OS.
+ */
+export class ApprovalManager {
+  private readonly options: Required<Pick<ApprovalManagerOptions, "maxPending" | "timeoutMs">> &
+    ApprovalManagerOptions
+  private readonly pendingApprovals = new Map<string, PendingApproval>()
+
+  constructor(options: ApprovalManagerOptions = {}) {
+    this.options = {
+      ...options,
+      maxPending: options.maxPending ?? 32,
+      timeoutMs: options.timeoutMs ?? 5 * 60_000,
+    }
+    if (!Number.isSafeInteger(this.options.maxPending) || this.options.maxPending < 1)
+      throw new RangeError("approvals: maxPending must be positive")
+    if (
+      !Number.isSafeInteger(this.options.timeoutMs) ||
+      this.options.timeoutMs < 1 ||
+      this.options.timeoutMs > 24 * 60 * 60_000
+    )
+      throw new RangeError("approvals: timeoutMs must be between 1ms and 24h")
+  }
+
+  get pending(): readonly ApprovalRequest[] {
+    return Object.freeze([...this.pendingApprovals.values()].map(({ request }) => request))
+  }
+
+  /** Convert a streamed backend approval event into a resolvable pending request. */
+  async observe(event: AgentApprovalRequiredEvent): Promise<ApprovalRequest | undefined> {
+    if (this.pendingApprovals.has(event.approvalId))
+      return this.pendingApprovals.get(event.approvalId)?.request
+    return this.create({
+      id: event.approvalId,
+      sessionId: event.sessionId,
+      turnId: event.turnId,
+      action: event.action,
+      capability: event.capability,
+      ...(event.reason === undefined ? {} : { reason: event.reason }),
+    })
+  }
+
+  /** Publish a pending approval without waiting for its decision (useful for transports). */
+  async offer(
+    input: Omit<ApprovalRequest, "createdAt" | "expiresAt">,
+  ): Promise<ApprovalRequest | undefined> {
+    return this.create(input)
+  }
+
+  /** Create a host-owned approval that can be awaited by a workflow or extension. */
+  async request(input: Omit<ApprovalRequest, "createdAt" | "expiresAt">): Promise<boolean> {
+    const request = await this.offer(input)
+    if (request === undefined) return false
+    const pending = this.pendingApprovals.get(request.id)
+    if (pending === undefined) return false
+    return new Promise<boolean>((resolve) => {
+      // Replace the resolver only for this host-owned request; observed backend requests are
+      // intentionally notification-only and are resolved through `resolve`.
+      const current = this.pendingApprovals.get(request.id)
+      if (current === undefined) return resolve(false)
+      this.pendingApprovals.set(request.id, { ...current, resolve })
+    })
+  }
+
+  /**
+   * Resolve an approval that was opened with a {@link DecisionCoordinate}, admitting the decision only
+   * when it matches the live boundary and is still fresh. Every failure is content-free and fails
+   * closed: an unknown id, a coordinate-less approval, a mismatched or superseded coordinate, or an
+   * expired boundary resumes no work. This adds a typed path alongside the untyped {@link resolve}; it
+   * never loosens it.
+   */
+  resolveMatched(
+    coordinate: DecisionCoordinate,
+    approved: boolean,
+    now: number = Date.now(),
+  ): ApprovalMatchResult {
+    const pending = this.pendingApprovals.get(coordinate.requestId)
+    if (pending === undefined) return { ok: false, code: "unknown_boundary" }
+    const bound = pending.request.coordinate
+    if (bound === undefined) return { ok: false, code: "identity_mismatch" }
+    if (!coordinatesMatch(bound, coordinate))
+      return {
+        ok: false,
+        code: bound.vector !== coordinate.vector ? "stale_vector" : "identity_mismatch",
+      }
+    if (!coordinateIsFresh(bound, now)) {
+      this.resolve(coordinate.requestId, false, "approval expired")
+      return { ok: false, code: "expired" }
+    }
+    if (nextApprovalState("pending", approved ? "approve" : "deny") === undefined)
+      return { ok: false, code: "illegal_transition" }
+    const decision = this.resolve(coordinate.requestId, approved)
+    if (decision === undefined) return { ok: false, code: "unknown_boundary" }
+    return { ok: true, decision }
+  }
+
+  resolve(approvalId: string, approved: boolean, reason?: string): ApprovalDecision | undefined {
+    const pending = this.pendingApprovals.get(approvalId)
+    if (pending === undefined) return undefined
+    clearTimeout(pending.timer)
+    this.pendingApprovals.delete(approvalId)
+    pending.resolve(approved === true)
+    const decision: ApprovalDecision = {
+      approvalId,
+      approved: approved === true,
+      ...(reason === undefined ? {} : { reason: reason.slice(0, 512) }),
+      at: Date.now(),
+    }
+    void this.options.onResolved?.(decision)
+    return decision
+  }
+
+  close(): void {
+    for (const approvalId of this.pendingApprovals.keys())
+      this.resolve(approvalId, false, "approval manager closed")
+  }
+
+  private async create(
+    input: Omit<ApprovalRequest, "createdAt" | "expiresAt">,
+  ): Promise<ApprovalRequest | undefined> {
+    if (this.pendingApprovals.size >= this.options.maxPending) return undefined
+    if (!/^[A-Za-z0-9._:-]{1,128}$/.test(input.id))
+      throw new TypeError("approvals: approval id is invalid")
+    if (!/^[A-Za-z0-9._:-]{1,128}$/.test(input.sessionId))
+      throw new TypeError("approvals: session id is invalid")
+    if (!input.action || input.action.length > 512)
+      throw new TypeError("approvals: action is empty or too long")
+    if (!input.capability || input.capability.length > 128)
+      throw new TypeError("approvals: capability is empty or too long")
+    const createdAt = Date.now()
+    const request: ApprovalRequest = Object.freeze({
+      ...input,
+      ...(input.turnId === undefined ? {} : { turnId: input.turnId }),
+      ...(input.reason === undefined ? {} : { reason: input.reason.slice(0, 512) }),
+      ...(input.coordinate === undefined ? {} : { coordinate: input.coordinate }),
+      createdAt,
+      expiresAt: createdAt + this.options.timeoutMs,
+    })
+    let resolveApproval = (_approved: boolean): void => {}
+    const timer = setTimeout(() => {
+      this.resolve(request.id, false, "approval timed out")
+    }, this.options.timeoutMs)
+    ;(timer as unknown as { unref?: () => void }).unref?.()
+    const pending: PendingApproval = {
+      request,
+      resolve: (approved) => resolveApproval(approved),
+      timer,
+    }
+    this.pendingApprovals.set(request.id, pending)
+    await this.options.onRequired?.(request)
+    // A backend-observed request is resolved through `resolve`; a host request swaps this closure
+    // from the promise below before returning to the workflow.
+    resolveApproval = (_approved: boolean): void => {}
+    return request
+  }
+}
+
+export function approvalRequestFromEvent(event: AgentApprovalRequiredEvent): ApprovalRequest {
+  return Object.freeze({
+    id: event.approvalId,
+    sessionId: event.sessionId,
+    turnId: event.turnId,
+    action: event.action,
+    capability: event.capability,
+    ...(event.reason === undefined ? {} : { reason: event.reason }),
+    createdAt: event.at,
+    expiresAt: event.at + 5 * 60_000,
+  })
+}
+
+export function approvalResolvedEvent(
+  sessionId: string,
+  seq: number,
+  decision: ApprovalDecision,
+  turnId?: string,
+): AgentApprovalResolvedEvent {
+  return Object.freeze({
+    version: 1 as const,
+    sessionId,
+    seq,
+    at: decision.at,
+    type: "approval.resolved" as const,
+    ...(turnId === undefined ? {} : { turnId }),
+    approvalId: decision.approvalId,
+    approved: decision.approved,
+    ...(decision.reason === undefined ? {} : { reason: decision.reason }),
+  })
+}