@nifrajs/coding-agent 3.2.0

package/dist/extensions.js

@@ -0,0 +1,284 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync, realpathSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { WorkflowRunner, } from "./workflows.js";
+/** Discover only project-local extension files; no home-directory or dependency scan is implicit. */
+export async function discoverExtensions(cwd) {
+    const directory = resolve(cwd, ".nifra/extensions");
+    if (!existsSync(directory))
+        return Object.freeze([]);
+    const roots = [];
+    for await (const path of new Bun.Glob("**/*").scan({ cwd: directory, dot: false })) {
+        if (/\.(?:ts|tsx|js|jsx)$/.test(path))
+            roots.push(join(".nifra/extensions", path));
+    }
+    return Object.freeze(roots.sort());
+}
+/** Parse an extension without activating it. This is a fast syntax gate before staging. */
+export async function validateExtensionModule(path) {
+    const source = await Bun.file(path).text();
+    const loader = /\.tsx?$/.test(path) ? "tsx" : "js";
+    try {
+        new Bun.Transpiler({ loader }).transformSync(source);
+    }
+    catch (error) {
+        throw new Error(`extension validation failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Transactional TypeScript extension loader for the Nifra-native backend.
+ *
+ * This loader only activates explicitly supplied files. It never scans a project implicitly and it
+ * leaves the previous extension graph intact when a staged reload fails.
+ */
+export class ExtensionHost {
+    options;
+    active = [];
+    commands = new Map();
+    tools = new Map();
+    workflows = new Map();
+    subagents = new Map();
+    providers = new Map();
+    handlers = new Map();
+    revision = "0";
+    constructor(options) {
+        this.options = Object.freeze({
+            ...options,
+            roots: Object.freeze([...options.roots]),
+            trustedCapabilities: Object.freeze([...(options.trustedCapabilities ?? [])]),
+        });
+    }
+    get extensions() {
+        return this.active;
+    }
+    get currentRevision() {
+        return this.revision;
+    }
+    get availableCommands() {
+        return Object.freeze([...this.commands.keys()].sort());
+    }
+    get availableTools() {
+        return Object.freeze([...this.tools.values()]);
+    }
+    get availableWorkflows() {
+        return Object.freeze([...this.workflows.keys()].sort());
+    }
+    get availableSubagents() {
+        return Object.freeze([...this.subagents.values()]);
+    }
+    get availableProviders() {
+        return Object.freeze([...this.providers.values()]);
+    }
+    async reload() {
+        let pathError;
+        const paths = this.options.roots
+            .map((root) => resolve(this.options.cwd, root))
+            .filter((path) => {
+            if (!isWithin(this.options.cwd, path)) {
+                pathError = `extension path escapes project root: ${path}`;
+                return false;
+            }
+            if (!existsSync(path))
+                return false;
+            try {
+                if (!isWithin(this.options.cwd, realpathSync(path))) {
+                    pathError = `extension path escapes project root: ${path}`;
+                    return false;
+                }
+                return true;
+            }
+            catch {
+                pathError = `extension path could not be resolved: ${path}`;
+                return false;
+            }
+        });
+        const next = [];
+        const nextCommands = new Map();
+        const nextTools = new Map();
+        const nextWorkflows = new Map();
+        const nextSubagents = new Map();
+        const nextProviders = new Map();
+        const nextHandlers = new Map();
+        try {
+            if (pathError !== undefined)
+                throw new Error(pathError);
+            for (const path of paths) {
+                await this.options.validate?.(path);
+                const loaded = await this.loadOne(path, nextCommands, nextTools, nextWorkflows, nextSubagents, nextProviders, nextHandlers);
+                next.push(loaded);
+            }
+            const previous = this.active;
+            this.active = Object.freeze(next);
+            this.commands = nextCommands;
+            this.tools = nextTools;
+            this.workflows = nextWorkflows;
+            this.subagents = nextSubagents;
+            this.providers = nextProviders;
+            this.handlers = nextHandlers;
+            this.revision = `${Date.now().toString(36)}-${next.length}`;
+            for (const extension of previous) {
+                try {
+                    await extension.dispose?.();
+                }
+                catch (error) {
+                    this.options.onError?.({ path: extension.path, error });
+                }
+            }
+            return {
+                revision: this.revision,
+                loaded: Object.freeze(next.map((extension) => extension.id)),
+                disabled: [],
+                rolledBack: false,
+            };
+        }
+        catch (error) {
+            for (const extension of next.reverse()) {
+                try {
+                    await extension.dispose?.();
+                }
+                catch {
+                    /* staged cleanup is best effort */
+                }
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            this.options.onError?.({ path: paths[next.length] ?? this.options.cwd, error });
+            return {
+                revision: this.revision,
+                loaded: Object.freeze(this.active.map((extension) => extension.id)),
+                disabled: Object.freeze(paths.slice(next.length)),
+                rolledBack: true,
+                error: message,
+            };
+        }
+    }
+    async close() {
+        const active = this.active;
+        this.active = [];
+        this.commands = new Map();
+        this.tools = new Map();
+        this.workflows = new Map();
+        this.subagents = new Map();
+        this.providers = new Map();
+        this.handlers = new Map();
+        for (const extension of active)
+            await extension.dispose?.();
+    }
+    command(name) {
+        return this.commands.get(name);
+    }
+    tool(name) {
+        return this.tools.get(name);
+    }
+    workflow(name) {
+        return this.workflows.get(name);
+    }
+    subagent(name) {
+        return this.subagents.get(name);
+    }
+    provider(name) {
+        return this.providers.get(name);
+    }
+    async runWorkflow(name, options = {}) {
+        const workflow = this.workflows.get(name);
+        if (workflow === undefined)
+            throw new Error(`unknown extension workflow: ${name}`);
+        const step = await workflow(this.context());
+        return new WorkflowRunner(options).run(step);
+    }
+    async emit(event, payload) {
+        for (const handler of this.handlers.get(event) ?? [])
+            await handler(payload, this.context());
+    }
+    async loadOne(path, commands, tools, workflows, subagents, providers, handlers) {
+        const module = (await import(__rewriteRelativeImportExtension(`${path}?revision=${Date.now()}-${Math.random()}`)));
+        if (typeof module.default !== "function")
+            throw new Error(`extension ${path} has no default factory`);
+        const capabilities = Object.freeze([...(module.capabilities ?? [])]);
+        const trusted = new Set(this.options.trustedCapabilities ?? []);
+        const denied = capabilities.find((capability) => !trusted.has(capability));
+        if (denied !== undefined)
+            throw new Error(`extension ${path} requires untrusted capability: ${denied}`);
+        const context = this.context(commands, tools, workflows, subagents, providers, handlers);
+        const result = await module.default(context);
+        return Object.freeze({
+            id: module.id ?? path,
+            path,
+            capabilities,
+            ...(result &&
+                typeof result === "object" &&
+                "dispose" in result &&
+                typeof result.dispose === "function"
+                ? { dispose: result.dispose }
+                : {}),
+        });
+    }
+    context(commands = this.commands, tools = this.tools, workflows = this.workflows, subagents = this.subagents, providers = this.providers, handlers = this.handlers) {
+        return {
+            cwd: this.options.cwd,
+            registerCommand: (name, handler) => {
+                if (!/^[a-z][a-z0-9._-]{0,63}$/.test(name))
+                    throw new Error(`invalid extension command: ${name}`);
+                if (commands.has(name))
+                    throw new Error(`duplicate extension command: ${name}`);
+                commands.set(name, handler);
+            },
+            registerTool: (tool) => {
+                if (!/^[a-z][a-z0-9._-]{0,63}$/.test(tool.name))
+                    throw new Error(`invalid extension tool: ${tool.name}`);
+                if (tools.has(tool.name))
+                    throw new Error(`duplicate extension tool: ${tool.name}`);
+                const denied = (tool.capabilities ?? []).find((capability) => !(this.options.trustedCapabilities ?? []).includes(capability));
+                if (denied !== undefined)
+                    throw new Error(`extension tool ${tool.name} requires untrusted capability: ${denied}`);
+                tools.set(tool.name, tool);
+            },
+            registerWorkflow: (name, workflow) => {
+                if (!/^[a-z][a-z0-9._-]{0,63}$/.test(name))
+                    throw new Error(`invalid extension workflow: ${name}`);
+                if (workflows.has(name))
+                    throw new Error(`duplicate extension workflow: ${name}`);
+                workflows.set(name, workflow);
+            },
+            registerSubagent: (role) => {
+                if (!/^[a-z][a-z0-9._-]{0,63}$/.test(role.name))
+                    throw new Error(`invalid extension subagent: ${role.name}`);
+                if (subagents.has(role.name))
+                    throw new Error(`duplicate extension subagent: ${role.name}`);
+                subagents.set(role.name, Object.freeze({ ...role }));
+            },
+            registerProvider: (provider) => {
+                if (!/^[a-z][a-z0-9._-]{0,63}$/.test(provider.name))
+                    throw new Error(`invalid extension provider: ${provider.name}`);
+                if (providers.has(provider.name))
+                    throw new Error(`duplicate extension provider: ${provider.name}`);
+                providers.set(provider.name, Object.freeze({ ...provider }));
+            },
+            on: (event, handler) => {
+                if (!/^[a-z][a-z0-9._-]{0,63}$/.test(event))
+                    throw new Error(`invalid extension event: ${event}`);
+                const current = handlers.get(event) ?? [];
+                handlers.set(event, [...current, handler]);
+            },
+        };
+    }
+}
+function isWithin(root, candidate) {
+    const canonical = (path) => {
+        try {
+            return realpathSync(path);
+        }
+        catch {
+            return resolve(path);
+        }
+    };
+    const relativePath = relative(canonical(root), canonical(candidate));
+    return relativePath === "" || (!relativePath.startsWith("..") && !relativePath.includes("/.."));
+}
+//# sourceMappingURL=extensions.js.map

package/dist/extensions.js.map

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

package/dist/handoffs.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Handoff coordinator: the typed state machine for a delegated boundary within a run.
+ *
+ * This sits beside {@link ApprovalManager} rather than inside it. An approval answers a yes/no gate;
+ * a handoff moves ownership of a paused node between roles (open, optionally assign an owner, then
+ * accept, decline, resolve, expire, or cancel). The coordinator composes an {@link ApprovalManager}
+ * when a handoff also needs a yes/no gate, so existing approval semantics are extended, never
+ * weakened.
+ *
+ * Every boundary is addressed by a content-free {@link DecisionCoordinate}. A decision that names a
+ * different run, node, capability, or request id fails `identity_mismatch`; one carrying a superseded
+ * child vector fails `stale_vector`; one arriving at or past expiry expires the boundary closed and
+ * fails `expired`; one whose transition is absent from the {@link nextHandoffState} table fails
+ * `illegal_transition`; and one that would let a non-owner act on an assigned boundary fails
+ * `authority_expanded`. Nothing here stores or returns a prompt, a free-text reason, tool data, or a
+ * payload - only structural coordinates and a state.
+ */
+import { type DecisionCoordinate, type HandoffLifecycleState } from "@nifrajs/agent-protocol";
+import type { ApprovalManager } from "./approvals.js";
+import { ChildVectorTracker } from "./orchestration/policy.js";
+/** Stable, content-free reasons the coordinator refuses a handoff request or decision. */
+export type HandoffRejection = "unknown_boundary" | "identity_mismatch" | "stale_vector" | "expired" | "illegal_transition" | "authority_expanded" | "duplicate" | "invalid_handoff";
+/** Thrown on any refused handoff operation. `code` is the machine-addressable reason. */
+export declare class HandoffError extends Error {
+    readonly code: HandoffRejection;
+    constructor(code: HandoffRejection);
+}
+/** Content-free projection of one handoff boundary for a list/inspect view. */
+export interface HandoffView {
+    readonly requestId: string;
+    readonly runId: string;
+    readonly nodeId: string;
+    readonly capability: string;
+    readonly vector: number;
+    readonly expiresAt: number;
+    readonly state: HandoffLifecycleState;
+    /** Opaque origin role. */
+    readonly from: string;
+    /** Opaque owner role once assigned. */
+    readonly to?: string;
+}
+export interface OpenHandoffInput {
+    readonly runId: string;
+    readonly nodeId: string;
+    readonly capability: string;
+    readonly requestId: string;
+    /** Opaque origin role. */
+    readonly from: string;
+    /** Milliseconds until the boundary expires closed. Falls back to the coordinator default. */
+    readonly expiresInMs?: number;
+    /** When true, a paired approval is opened on the composed {@link ApprovalManager}, if present. */
+    readonly requireApproval?: boolean;
+    readonly sessionId?: string;
+}
+/** A decision against a live boundary. The coordinate must match the boundary exactly. */
+export interface HandoffDecision {
+    readonly coordinate: DecisionCoordinate;
+    /** Owner role to assign (for `assign`) or the actor claiming to own the boundary (accept/resolve). */
+    readonly by?: string;
+}
+export interface HandoffCoordinatorOptions {
+    readonly vectors?: ChildVectorTracker;
+    readonly approvals?: ApprovalManager;
+    readonly defaultTtlMs?: number;
+    readonly maxPending?: number;
+    /** Injectable clock (epoch ms). Defaults to {@link Date.now}. */
+    readonly now?: () => number;
+}
+export declare class HandoffCoordinator {
+    private readonly vectors;
+    private readonly approvals;
+    private readonly defaultTtlMs;
+    private readonly maxPending;
+    private readonly now;
+    private readonly records;
+    constructor(options?: HandoffCoordinatorOptions);
+    /** Open a pending handoff. Allocates the run's next monotonic child vector. */
+    open(input: OpenHandoffInput): HandoffView;
+    /** Every boundary, or - with `activeOnly` - just those still awaiting a decision. */
+    list(activeOnly?: boolean): readonly HandoffView[];
+    /** Inspect one boundary by request id, or `undefined` when unknown. */
+    inspect(requestId: string): HandoffView | undefined;
+    assign(decision: HandoffDecision): HandoffView;
+    accept(decision: HandoffDecision): HandoffView;
+    decline(decision: HandoffDecision): HandoffView;
+    /** Resolve a boundary, resuming exactly the one matching paused node. */
+    resolve(decision: HandoffDecision): HandoffView;
+    expire(decision: HandoffDecision): HandoffView;
+    cancel(decision: HandoffDecision): HandoffView;
+    private drive;
+    private settle;
+    private settleApproval;
+    private isTerminal;
+    private activeCount;
+    private view;
+}
+//# sourceMappingURL=handoffs.d.ts.map

package/dist/handoffs.d.ts.map

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

package/dist/handoffs.js

@@ -0,0 +1,199 @@
+/**
+ * Handoff coordinator: the typed state machine for a delegated boundary within a run.
+ *
+ * This sits beside {@link ApprovalManager} rather than inside it. An approval answers a yes/no gate;
+ * a handoff moves ownership of a paused node between roles (open, optionally assign an owner, then
+ * accept, decline, resolve, expire, or cancel). The coordinator composes an {@link ApprovalManager}
+ * when a handoff also needs a yes/no gate, so existing approval semantics are extended, never
+ * weakened.
+ *
+ * Every boundary is addressed by a content-free {@link DecisionCoordinate}. A decision that names a
+ * different run, node, capability, or request id fails `identity_mismatch`; one carrying a superseded
+ * child vector fails `stale_vector`; one arriving at or past expiry expires the boundary closed and
+ * fails `expired`; one whose transition is absent from the {@link nextHandoffState} table fails
+ * `illegal_transition`; and one that would let a non-owner act on an assigned boundary fails
+ * `authority_expanded`. Nothing here stores or returns a prompt, a free-text reason, tool data, or a
+ * payload - only structural coordinates and a state.
+ */
+import { coordinateIsFresh, coordinatesMatch, nextHandoffState, } from "@nifrajs/agent-protocol";
+import { ChildVectorTracker } from "./orchestration/policy.js";
+const ID_TOKEN = /^[A-Za-z0-9._:-]{1,128}$/;
+/** Thrown on any refused handoff operation. `code` is the machine-addressable reason. */
+export class HandoffError extends Error {
+    code;
+    constructor(code) {
+        super(`handoff: ${code}`);
+        this.code = code;
+        this.name = "HandoffError";
+    }
+}
+const DEFAULT_TTL_MS = 5 * 60_000;
+const DEFAULT_MAX_PENDING = 64;
+export class HandoffCoordinator {
+    vectors;
+    approvals;
+    defaultTtlMs;
+    maxPending;
+    now;
+    records = new Map();
+    constructor(options = {}) {
+        this.vectors = options.vectors ?? new ChildVectorTracker();
+        this.approvals = options.approvals;
+        this.defaultTtlMs = options.defaultTtlMs ?? DEFAULT_TTL_MS;
+        this.maxPending = options.maxPending ?? DEFAULT_MAX_PENDING;
+        this.now = options.now ?? Date.now;
+        if (!Number.isSafeInteger(this.defaultTtlMs) || this.defaultTtlMs < 1)
+            throw new RangeError("handoff: defaultTtlMs must be positive");
+        if (!Number.isSafeInteger(this.maxPending) || this.maxPending < 1)
+            throw new RangeError("handoff: maxPending must be positive");
+    }
+    /** Open a pending handoff. Allocates the run's next monotonic child vector. */
+    open(input) {
+        if (!ID_TOKEN.test(input.runId) ||
+            !ID_TOKEN.test(input.nodeId) ||
+            !ID_TOKEN.test(input.requestId) ||
+            !input.capability ||
+            input.capability.length > 128 ||
+            !input.from ||
+            input.from.length > 128)
+            throw new HandoffError("invalid_handoff");
+        if (this.records.has(input.requestId))
+            throw new HandoffError("duplicate");
+        if (this.activeCount() >= this.maxPending)
+            throw new HandoffError("invalid_handoff");
+        const ttl = input.expiresInMs ?? this.defaultTtlMs;
+        if (!Number.isSafeInteger(ttl) || ttl < 1)
+            throw new HandoffError("invalid_handoff");
+        const coordinate = Object.freeze({
+            runId: input.runId,
+            nodeId: input.nodeId,
+            capability: input.capability,
+            requestId: input.requestId,
+            vector: this.vectors.open(input.runId),
+            expiresAt: this.now() + ttl,
+        });
+        const record = {
+            coordinate,
+            state: "pending",
+            from: input.from,
+            to: undefined,
+            sessionId: input.sessionId,
+            requireApproval: input.requireApproval === true,
+        };
+        this.records.set(input.requestId, record);
+        if (record.requireApproval && this.approvals !== undefined)
+            void this.approvals.offer({
+                id: input.requestId,
+                sessionId: input.sessionId ?? input.runId,
+                action: "handoff",
+                capability: input.capability,
+            });
+        return this.view(record);
+    }
+    /** Every boundary, or - with `activeOnly` - just those still awaiting a decision. */
+    list(activeOnly = false) {
+        const views = [];
+        for (const record of this.records.values()) {
+            if (activeOnly && this.isTerminal(record.state))
+                continue;
+            views.push(this.view(record));
+        }
+        return Object.freeze(views);
+    }
+    /** Inspect one boundary by request id, or `undefined` when unknown. */
+    inspect(requestId) {
+        const record = this.records.get(requestId);
+        return record === undefined ? undefined : this.view(record);
+    }
+    assign(decision) {
+        if (decision.by === undefined || !decision.by || decision.by.length > 128)
+            throw new HandoffError("invalid_handoff");
+        return this.drive("assign", decision, decision.by);
+    }
+    accept(decision) {
+        return this.drive("accept", decision);
+    }
+    decline(decision) {
+        return this.drive("decline", decision);
+    }
+    /** Resolve a boundary, resuming exactly the one matching paused node. */
+    resolve(decision) {
+        return this.drive("resolve", decision);
+    }
+    expire(decision) {
+        return this.drive("expire", decision);
+    }
+    cancel(decision) {
+        return this.drive("cancel", decision);
+    }
+    drive(op, decision, assignee) {
+        const record = this.records.get(decision.coordinate.requestId);
+        if (record === undefined)
+            throw new HandoffError("unknown_boundary");
+        if (!coordinatesMatch(record.coordinate, decision.coordinate)) {
+            throw new HandoffError(record.coordinate.vector !== decision.coordinate.vector
+                ? "stale_vector"
+                : "identity_mismatch");
+        }
+        // Expiry is checked before the transition and, except for an explicit `expire`/`cancel`, is
+        // terminal: a decision that arrives at or past the deadline expires the boundary closed and
+        // resumes no work.
+        if (op !== "expire" && op !== "cancel" && !coordinateIsFresh(record.coordinate, this.now())) {
+            if (!this.isTerminal(record.state))
+                this.settle(record, "expired");
+            throw new HandoffError("expired");
+        }
+        // An assigned boundary may only be acted on by its owner. A different actor is an authority
+        // expansion, not a routine mismatch.
+        if (record.to !== undefined &&
+            (op === "accept" || op === "decline" || op === "resolve") &&
+            decision.by !== record.to)
+            throw new HandoffError("authority_expanded");
+        const next = nextHandoffState(record.state, op);
+        if (next === undefined)
+            throw new HandoffError("illegal_transition");
+        if (op === "assign")
+            record.to = assignee;
+        record.state = next;
+        if (this.isTerminal(next))
+            this.settleApproval(record, op);
+        return this.view(record);
+    }
+    settle(record, state) {
+        record.state = state;
+        this.settleApproval(record, "expire");
+    }
+    settleApproval(record, op) {
+        if (!record.requireApproval || this.approvals === undefined)
+            return;
+        this.approvals.resolve(record.coordinate.requestId, op === "accept" || op === "resolve");
+    }
+    isTerminal(state) {
+        return (state === "accepted" ||
+            state === "declined" ||
+            state === "resolved" ||
+            state === "expired" ||
+            state === "cancelled");
+    }
+    activeCount() {
+        let count = 0;
+        for (const record of this.records.values())
+            if (!this.isTerminal(record.state))
+                count++;
+        return count;
+    }
+    view(record) {
+        return Object.freeze({
+            requestId: record.coordinate.requestId,
+            runId: record.coordinate.runId,
+            nodeId: record.coordinate.nodeId,
+            capability: record.coordinate.capability,
+            vector: record.coordinate.vector,
+            expiresAt: record.coordinate.expiresAt,
+            state: record.state,
+            from: record.from,
+            ...(record.to === undefined ? {} : { to: record.to }),
+        });
+    }
+}
+//# sourceMappingURL=handoffs.js.map

package/dist/handoffs.js.map

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