@nyxa/automation 0.1.0

package/dist/workflow.js

@@ -0,0 +1,530 @@
+import { randomUUID } from "node:crypto";
+import { realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { throwIfAborted } from "./cancellation.js";
+import { AutomationEventDispatcher, } from "./events.js";
+import { AutomationError, automationErrorDetails, contextualizeAutomationError, } from "./errors.js";
+import { isWithinDirectory } from "./filesystem.js";
+import { harnessName, runHarness, } from "./harness.js";
+import { acquireWorkspaceAccess, RunConcurrencyLimiter, } from "./run-coordination.js";
+import { RunJournal } from "./run-journal.js";
+const workflowDefinitionBrand = Symbol.for("@nyxa/automation/workflow-definition");
+const workflowRunner = Symbol.for("@nyxa/automation/workflow-runner");
+const workflowInputSchema = Symbol.for("@nyxa/automation/workflow-input-schema");
+const workflowOutputSchema = Symbol.for("@nyxa/automation/workflow-output-schema");
+const workflowHarness = Symbol.for("@nyxa/automation/workflow-harness");
+export function defineWorkflow(options) {
+    const inputSchema = options.input;
+    const outputSchema = options.output;
+    const harness = options.harness;
+    return Object.freeze({
+        [workflowDefinitionBrand]: true,
+        [workflowInputSchema]: inputSchema,
+        [workflowOutputSchema]: outputSchema,
+        [workflowHarness]: harness,
+        [workflowRunner]: options.run,
+    });
+}
+export function isWorkflowDefinition(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const candidate = value;
+    return (candidate[workflowDefinitionBrand] === true &&
+        typeof candidate[workflowRunner] === "function");
+}
+export function executeWorkflow(definition, options) {
+    return executeWorkflowWithControls(definition, options);
+}
+export async function executeWorkflowWithControls(definition, options, forceSignal) {
+    const cancellation = createExecutionCancellation(options?.signal);
+    try {
+        return await executeWorkflowExecution(definition, options, cancellation.signal, cancellation.abort, forceSignal);
+    }
+    finally {
+        cancellation.dispose();
+    }
+}
+async function executeWorkflowExecution(definition, options, executionSignal, abortExecution, forceSignal) {
+    const hasInput = options !== undefined && Object.hasOwn(options, "input");
+    const inputSchema = definition[workflowInputSchema];
+    const workflowId = randomUUID();
+    const workspaceRoot = path.resolve(options?.workspaceRoot ?? process.cwd());
+    const journalMode = runJournalMode(options?.record);
+    const journal = journalMode === false
+        ? undefined
+        : await RunJournal.create(workflowId, journalMode, workspaceRoot);
+    const events = new AutomationEventDispatcher(options?.onEvent, journal === undefined
+        ? undefined
+        : (event, content) => journal.append(event, content), abortExecution);
+    const concurrency = new RunConcurrencyLimiter(options?.concurrency);
+    let input;
+    try {
+        if (inputSchema === undefined) {
+            if (hasInput) {
+                throw new AutomationError("WORKFLOW_INPUT_UNEXPECTED", "This Workflow Definition does not declare a Workflow Input contract.");
+            }
+            input = undefined;
+        }
+        else {
+            if (!hasInput) {
+                throw new AutomationError("WORKFLOW_INPUT_INVALID", "A Workflow Input is required by this Workflow Definition.");
+            }
+            const parsedInput = inputSchema.safeParse(options?.input);
+            if (!parsedInput.success) {
+                throw new AutomationError("WORKFLOW_INPUT_INVALID", "The Workflow Input does not satisfy its contract.", { cause: parsedInput.error });
+            }
+            input = parsedInput.data;
+        }
+    }
+    catch (cause) {
+        const error = contextualizeAutomationError(cause, "WORKFLOW_EXECUTION_FAILED", "The Workflow execution failed unexpectedly.", { workflowId });
+        await journal?.append({
+            error: automationErrorDetails(error),
+            sequence: 0,
+            timestamp: new Date().toISOString(),
+            type: "workflow.failed",
+            workflowId,
+        }, hasInput ? { input: options?.input } : undefined);
+        throw error;
+    }
+    await events.emit({ type: "workflow.started", workflowId }, hasInput ? { input: options?.input } : undefined);
+    const activeRuns = new Set();
+    const context = Object.freeze({
+        input,
+        signal: executionSignal,
+        run(prompt, runOptions) {
+            return executeContextRun(prompt, runOptions);
+        },
+        session(sessionOptions = {}) {
+            const harness = sessionOptions?.harness ?? definition[workflowHarness];
+            const cwd = sessionOptions?.cwd;
+            const sessionEnvironment = sessionOptions.env === undefined
+                ? undefined
+                : Object.freeze({ ...sessionOptions.env });
+            const state = {
+                busy: false,
+                nativeSessionId: undefined,
+                sessionId: randomUUID(),
+                sessionName: sessionOptions?.name,
+                state: "new",
+            };
+            return Object.freeze({
+                run(prompt, runOptions) {
+                    if (state.busy) {
+                        return Promise.reject(new AutomationError("SESSION_BUSY", "A Session cannot run concurrently on the same handle.", {
+                            harness: harnessName(harness),
+                            sessionId: state.sessionId,
+                            workflowId,
+                        }));
+                    }
+                    if (state.state === "unavailable") {
+                        return Promise.reject(new AutomationError("SESSION_UNAVAILABLE", "The Session can no longer prove conversation continuity.", {
+                            harness: harnessName(harness),
+                            sessionId: state.sessionId,
+                            workflowId,
+                        }));
+                    }
+                    state.busy = true;
+                    const { cwd: _ignoredCwd, harness: _ignoredHarness, ...sessionRunOptions } = runOptions;
+                    const environment = mergeEnvironmentOverrides(sessionEnvironment, sessionRunOptions.env);
+                    return executeContextRun(prompt, {
+                        ...sessionRunOptions,
+                        ...(cwd === undefined ? {} : { cwd }),
+                        ...(environment === undefined ? {} : { env: environment }),
+                        ...(harness === undefined ? {} : { harness }),
+                    }, state).finally(() => {
+                        state.busy = false;
+                    });
+                },
+            });
+        },
+    });
+    function executeContextRun(prompt, runOptions, explicitSession) {
+        const harness = runOptions?.harness ?? definition[workflowHarness];
+        const runId = randomUUID();
+        const sessionId = explicitSession?.sessionId ?? randomUUID();
+        const runName = runOptions?.name;
+        const selectedHarnessName = harnessName(harness);
+        const correlation = {
+            harness: selectedHarnessName,
+            runId,
+            runName,
+            sessionId,
+            sessionName: explicitSession?.sessionName,
+            workflowId,
+        };
+        const execution = performRun();
+        activeRuns.add(execution);
+        void execution.then(() => activeRuns.delete(execution), () => activeRuns.delete(execution));
+        return execution;
+        async function performRun() {
+            let started = false;
+            let continuityProven = false;
+            let timeout;
+            const runAbort = new AbortController();
+            const cancelRun = () => runAbort.abort(executionSignal.reason);
+            executionSignal.addEventListener("abort", cancelRun, { once: true });
+            if (executionSignal.aborted) {
+                cancelRun();
+            }
+            try {
+                throwIfAborted(runAbort.signal);
+                if (!isAccessPolicy(runOptions?.access)) {
+                    throw new AutomationError("RUN_POLICY_INVALID", "A Run requires an explicit Access Policy.");
+                }
+                const approval = runOptions.approval ?? "deny";
+                if (!isApprovalPolicy(approval)) {
+                    throw new AutomationError("RUN_POLICY_INVALID", "A Run Approval Policy must be either deny or auto.");
+                }
+                if (!isRunTimeout(runOptions.timeout)) {
+                    throw new AutomationError("RUN_POLICY_INVALID", "A Run timeout must be a positive finite duration or false.");
+                }
+                if (runOptions.timeout !== false) {
+                    timeout = setTimeout(() => runAbort.abort(new AutomationError("RUN_TIMED_OUT", "The Run exceeded its timeout.")), runOptions.timeout ?? 30 * 60 * 1_000);
+                    timeout.unref();
+                }
+                const directories = await resolveRunWorkingDirectory(workspaceRoot, runOptions.cwd);
+                const environment = createRunEnvironment(runOptions.env);
+                const releaseWorkspace = acquireWorkspaceAccess(directories.workspaceRoot, runOptions.access);
+                try {
+                    const releaseConcurrency = await concurrency.acquire(runAbort.signal);
+                    try {
+                        throwIfAborted(runAbort.signal);
+                        const request = {
+                            access: runOptions.access,
+                            approval,
+                            emitNativeEvent: (event) => events.emit({
+                                ...correlation,
+                                type: "run.native",
+                                harness: selectedHarnessName,
+                                native: { portable: false, event },
+                            }),
+                            environment,
+                            ...(explicitSession?.nativeSessionId === undefined
+                                ? {}
+                                : { nativeSessionId: explicitSession.nativeSessionId }),
+                            prompt,
+                            runId,
+                            signal: runAbort.signal,
+                            ...(forceSignal === undefined ? {} : { forceSignal }),
+                            ...(explicitSession === undefined
+                                ? {}
+                                : {
+                                    sessionReady(nativeSessionId) {
+                                        explicitSession.nativeSessionId = nativeSessionId;
+                                        explicitSession.state = "ready";
+                                        continuityProven = true;
+                                    },
+                                }),
+                            async start() {
+                                await events.emit({ ...correlation, type: "run.started" }, { environment, prompt });
+                                started = true;
+                            },
+                            workingDirectory: directories.workingDirectory,
+                        };
+                        const result = runOptions?.output === undefined
+                            ? await runHarness(harness, request)
+                            : await runHarness(harness, {
+                                ...request,
+                                output: runOptions.output,
+                            });
+                        await events.emit({
+                            ...correlation,
+                            type: "run.completed",
+                            harness: selectedHarnessName,
+                        }, { result });
+                        return result;
+                    }
+                    finally {
+                        releaseConcurrency();
+                    }
+                }
+                finally {
+                    releaseWorkspace();
+                }
+            }
+            catch (cause) {
+                const error = contextualizeAutomationError(cause, "HARNESS_PROCESS_FAILED", "The Run failed unexpectedly.", {
+                    harness: selectedHarnessName,
+                    runId,
+                    sessionId,
+                    workflowId,
+                });
+                if (explicitSession !== undefined &&
+                    (isRunInterruption(error) || (started && !continuityProven))) {
+                    explicitSession.state = "unavailable";
+                }
+                if (!events.failed && started) {
+                    await events.emit({
+                        ...correlation,
+                        type: "run.failed",
+                        error: automationErrorDetails(error),
+                        harness: error.harness,
+                    });
+                }
+                throw error;
+            }
+            finally {
+                if (timeout !== undefined) {
+                    clearTimeout(timeout);
+                }
+                executionSignal.removeEventListener("abort", cancelRun);
+            }
+        }
+    }
+    try {
+        throwIfAborted(executionSignal);
+        const workflowExecution = Promise.resolve(definition[workflowRunner](context));
+        const result = await awaitWorkflowOrCancellation(workflowExecution, executionSignal, activeRuns);
+        throwIfAborted(executionSignal);
+        const outputSchema = definition[workflowOutputSchema];
+        if (outputSchema !== undefined) {
+            const parsedOutput = outputSchema.safeParse(result);
+            if (!parsedOutput.success) {
+                throw new AutomationError("WORKFLOW_OUTPUT_INVALID", "The Workflow Result does not satisfy its contract.", { cause: parsedOutput.error });
+            }
+            assertJsonSerializable(parsedOutput.data);
+            await events.emit({
+                type: "workflow.completed",
+                result: parsedOutput.data,
+                workflowId,
+            });
+            return parsedOutput.data;
+        }
+        assertJsonSerializable(result);
+        await events.emit({ type: "workflow.completed", result, workflowId });
+        return result;
+    }
+    catch (cause) {
+        const error = contextualizeAutomationError(cause, "WORKFLOW_EXECUTION_FAILED", "The Workflow execution failed unexpectedly.", { workflowId });
+        if (!events.failed) {
+            await events.emit({
+                type: "workflow.failed",
+                error: automationErrorDetails(error),
+                workflowId,
+            });
+        }
+        throw error;
+    }
+}
+function createExecutionCancellation(externalSignal) {
+    const controller = new AbortController();
+    if (externalSignal === undefined) {
+        return {
+            abort: (reason) => controller.abort(reason),
+            dispose() { },
+            signal: controller.signal,
+        };
+    }
+    if (!(externalSignal instanceof AbortSignal)) {
+        throw new TypeError("Workflow signal must be an AbortSignal.");
+    }
+    const cancel = () => controller.abort(new AutomationError("RUN_CANCELLED", "The Workflow was cancelled."));
+    externalSignal.addEventListener("abort", cancel, { once: true });
+    if (externalSignal.aborted) {
+        cancel();
+    }
+    return {
+        abort: (reason) => controller.abort(reason),
+        dispose: () => externalSignal.removeEventListener("abort", cancel),
+        signal: controller.signal,
+    };
+}
+function runJournalMode(value) {
+    if (value === undefined) {
+        return "metadata";
+    }
+    if (value === false || value === "full" || value === "metadata") {
+        return value;
+    }
+    throw new TypeError("Workflow record mode must be metadata, full, or false.");
+}
+function awaitWorkflowOrCancellation(workflowExecution, signal, activeRuns) {
+    return new Promise((resolve, reject) => {
+        let terminal = false;
+        const cancel = () => {
+            if (terminal) {
+                return;
+            }
+            terminal = true;
+            signal.removeEventListener("abort", cancel);
+            void Promise.allSettled([...activeRuns]).then(() => reject(signal.reason));
+        };
+        signal.addEventListener("abort", cancel, { once: true });
+        if (signal.aborted) {
+            cancel();
+        }
+        void workflowExecution.then((result) => {
+            if (terminal) {
+                return;
+            }
+            terminal = true;
+            signal.removeEventListener("abort", cancel);
+            resolve(result);
+        }, (cause) => {
+            if (terminal) {
+                return;
+            }
+            terminal = true;
+            signal.removeEventListener("abort", cancel);
+            reject(cause);
+        });
+    });
+}
+function isAccessPolicy(value) {
+    return value === "read" || value === "write-workspace" || value === "full";
+}
+function isApprovalPolicy(value) {
+    return value === "deny" || value === "auto";
+}
+function isRunTimeout(value) {
+    return (value === undefined ||
+        value === false ||
+        (typeof value === "number" && Number.isFinite(value) && value > 0));
+}
+function isRunInterruption(error) {
+    return error.code === "RUN_CANCELLED" || error.code === "RUN_TIMED_OUT";
+}
+async function resolveRunWorkingDirectory(workspaceRoot, cwd) {
+    if (cwd !== undefined && typeof cwd !== "string") {
+        throw new AutomationError("RUN_CWD_INVALID", "A Run cwd must be a path relative to the Workspace root.");
+    }
+    if (typeof cwd === "string" && path.isAbsolute(cwd)) {
+        throw new AutomationError("RUN_CWD_INVALID", "A Run cwd must be relative to the Workspace root.");
+    }
+    const candidate = path.resolve(workspaceRoot, cwd ?? ".");
+    if (!isWithinDirectory(workspaceRoot, candidate)) {
+        throw new AutomationError("RUN_CWD_INVALID", "A Run cwd must stay within the Workspace root.");
+    }
+    let canonicalWorkspace;
+    let canonicalCandidate;
+    try {
+        [canonicalWorkspace, canonicalCandidate] = await Promise.all([
+            realpath(workspaceRoot),
+            realpath(candidate),
+        ]);
+    }
+    catch (cause) {
+        throw new AutomationError("RUN_CWD_INVALID", "A Run cwd must resolve to an existing directory in the Workspace.", { cause });
+    }
+    if (!isWithinDirectory(canonicalWorkspace, canonicalCandidate)) {
+        throw new AutomationError("RUN_CWD_INVALID", "A Run cwd must not resolve outside the Workspace root.");
+    }
+    try {
+        if (!(await stat(canonicalCandidate)).isDirectory()) {
+            throw new TypeError("The Run cwd is not a directory.");
+        }
+    }
+    catch (cause) {
+        throw new AutomationError("RUN_CWD_INVALID", "A Run cwd must resolve to an existing directory in the Workspace.", { cause });
+    }
+    return {
+        workspaceRoot: canonicalWorkspace,
+        workingDirectory: canonicalCandidate,
+    };
+}
+function createRunEnvironment(overrides) {
+    const environment = { ...process.env };
+    if (overrides === undefined) {
+        return environment;
+    }
+    if (typeof overrides !== "object" || overrides === null) {
+        throw new AutomationError("RUN_POLICY_INVALID", "Run environment overrides must be an object.");
+    }
+    for (const [name, value] of Object.entries(overrides)) {
+        if (value === undefined) {
+            delete environment[name];
+        }
+        else if (typeof value === "string") {
+            environment[name] = value;
+        }
+        else {
+            throw new AutomationError("RUN_POLICY_INVALID", "Run environment values must be strings or undefined.");
+        }
+    }
+    return environment;
+}
+function mergeEnvironmentOverrides(sessionEnvironment, runEnvironment) {
+    if (sessionEnvironment === undefined) {
+        return runEnvironment;
+    }
+    if (runEnvironment === undefined) {
+        return sessionEnvironment;
+    }
+    return Object.freeze({ ...sessionEnvironment, ...runEnvironment });
+}
+function assertJsonSerializable(result) {
+    if (result === undefined) {
+        return;
+    }
+    try {
+        assertJsonValue(result, new Set());
+    }
+    catch (cause) {
+        throw new AutomationError("WORKFLOW_OUTPUT_INVALID", "The Workflow Result must be JSON-serializable.", { cause });
+    }
+}
+function assertJsonValue(value, ancestors) {
+    if (value === null ||
+        typeof value === "boolean" ||
+        typeof value === "string") {
+        return;
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new TypeError("JSON numbers must be finite.");
+        }
+        return;
+    }
+    if (typeof value !== "object") {
+        throw new TypeError(`Unsupported JSON value: ${typeof value}.`);
+    }
+    if (ancestors.has(value)) {
+        throw new TypeError("Circular references are not JSON-serializable.");
+    }
+    ancestors.add(value);
+    try {
+        if (Array.isArray(value)) {
+            assertJsonArray(value, ancestors);
+            return;
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            throw new TypeError("JSON objects must have a plain object prototype.");
+        }
+        for (const key of Reflect.ownKeys(value)) {
+            if (typeof key === "symbol") {
+                throw new TypeError("JSON objects cannot contain symbol keys.");
+            }
+            const descriptor = Object.getOwnPropertyDescriptor(value, key);
+            if (descriptor?.enumerable !== true) {
+                throw new TypeError("JSON object properties must be enumerable.");
+            }
+            assertJsonValue(Reflect.get(value, key), ancestors);
+        }
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function assertJsonArray(value, ancestors) {
+    for (const key of Reflect.ownKeys(value)) {
+        if (key === "length") {
+            continue;
+        }
+        if (typeof key === "symbol" ||
+            !Number.isInteger(Number(key)) ||
+            String(Number(key)) !== key ||
+            Number(key) < 0 ||
+            Number(key) >= value.length) {
+            throw new TypeError("JSON arrays cannot contain extra properties.");
+        }
+    }
+    for (let index = 0; index < value.length; index += 1) {
+        if (!Object.hasOwn(value, index)) {
+            throw new TypeError("Sparse arrays are not JSON-serializable.");
+        }
+        assertJsonValue(value[index], ancestors);
+    }
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@nyxa/automation",
+  "version": "0.1.0",
+  "description": "Execute trusted TypeScript Workflows with local Harness CLIs.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Nyxa07/automation.git"
+  },
+  "homepage": "https://github.com/Nyxa07/automation#readme",
+  "bugs": {
+    "url": "https://github.com/Nyxa07/automation/issues"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "automation": "./dist/cli.js"
+  },
+  "files": [
+    "dist/**/*.d.ts",
+    "dist/**/*.js",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test tests/**/*.test.js && npm run test:types",
+    "test:integration": "npm run build && node --test tests/integration/*.test.js",
+    "test:types": "npm run build && tsc -p tests/types/tsconfig.json"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "^0.23.0",
+    "tsx": "^4.23.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1",
+    "typescript": "^7.0.2"
+  }
+}