@nyxa/automation 0.1.0

package/dist/opencode.js

@@ -0,0 +1,164 @@
+import { AutomationError } from "./errors.js";
+import { createHarnessPreflight, harnessProcessExitError, runHarnessProcess, } from "./harness-process.js";
+import { createHarness, harnessProcessControls, } from "./harness.js";
+import { promptWithOutputContract } from "./harness-prompt.js";
+const HARNESS_NAME = "OpenCode";
+export const OPENCODE_HARNESS_PREFLIGHT = {
+    harnessName: HARNESS_NAME,
+    minimumVersion: [1, 18, 4],
+    unsupportedVersionMessage: "OpenCode CLI 1.18.4 or later is required.",
+    versionPattern: /(?:\bopencode\s+)?(\d+)\.(\d+)\.(\d+)(?:-([0-9a-z.-]+))?(?:\+[0-9a-z.-]+)?(?:\s|$)/iu,
+};
+const preflightOpenCode = createHarnessPreflight(OPENCODE_HARNESS_PREFLIGHT);
+export function opencode(options = {}) {
+    const configuredOptions = Object.freeze({ ...options });
+    return createHarness({
+        name: HARNESS_NAME,
+        async run(request) {
+            if (request.access !== "full") {
+                throw new AutomationError("HARNESS_CAPABILITY_UNSUPPORTED", "OpenCode cannot guarantee read or write-workspace Access Policies because its CLI does not sandbox shell commands to the Workspace.");
+            }
+            const executable = await preflightOpenCode(configuredOptions.executable ?? "opencode", request.environment, harnessProcessControls(request));
+            return executeOpenCode(executable, configuredOptions, request);
+        },
+    });
+}
+async function executeOpenCode(executable, options, request) {
+    const arguments_ = ["run", "--format", "json"];
+    if (options.model !== undefined) {
+        arguments_.push("--model", options.model);
+    }
+    if (options.effort !== undefined) {
+        arguments_.push("--variant", options.effort);
+    }
+    if (request.approval === "auto") {
+        arguments_.push("--auto");
+    }
+    if (request.nativeSessionId !== undefined) {
+        arguments_.push("--session", request.nativeSessionId);
+    }
+    arguments_.push(promptWithOutputContract(request));
+    await request.start();
+    let nativeSessionId;
+    let nativeFailure;
+    const textParts = [];
+    const result = await runHarnessProcess(executable, arguments_, request.workingDirectory, HARNESS_NAME, {
+        environment: request.environment,
+        ...harnessProcessControls(request),
+        async onStdoutLine(line) {
+            if (line.trim().length === 0) {
+                return;
+            }
+            const event = parseOpenCodeEvent(line);
+            await request.emitNativeEvent(event);
+            const eventSessionId = opencodeSessionId(event);
+            if (nativeSessionId !== undefined &&
+                eventSessionId !== nativeSessionId) {
+                throw new AutomationError("HARNESS_PROTOCOL_ERROR", "OpenCode emitted events for different Sessions.");
+            }
+            if (request.nativeSessionId !== undefined &&
+                eventSessionId !== request.nativeSessionId) {
+                throw new AutomationError("HARNESS_PROTOCOL_ERROR", "OpenCode resumed a different Session than requested.");
+            }
+            nativeSessionId = eventSessionId;
+            const text = completedOpenCodeText(event);
+            if (text !== undefined) {
+                textParts.push(text);
+            }
+            nativeFailure ??= opencodeFailureDiagnostic(event);
+        },
+    });
+    if (result.exitCode !== 0) {
+        throw harnessProcessExitError(HARNESS_NAME, {
+            ...result,
+            stderr: result.stderr.trim().length === 0 && nativeFailure !== undefined
+                ? nativeFailure
+                : result.stderr,
+        });
+    }
+    if (nativeSessionId === undefined) {
+        throw new AutomationError("HARNESS_PROTOCOL_ERROR", "OpenCode completed without a Session identifier.");
+    }
+    if (textParts.length === 0) {
+        if (request.output !== undefined) {
+            request.sessionReady?.(nativeSessionId);
+            throw new AutomationError("RUN_OUTPUT_INVALID", "The OpenCode Run completed without structured output.", { cause: new TypeError("Missing completed OpenCode text event.") });
+        }
+        throw new AutomationError("HARNESS_PROTOCOL_ERROR", "OpenCode completed without a textual result.");
+    }
+    const response = textParts.join("\n");
+    if (request.output === undefined) {
+        return { nativeSessionId, value: response };
+    }
+    try {
+        return {
+            nativeSessionId,
+            value: JSON.parse(response),
+        };
+    }
+    catch (cause) {
+        request.sessionReady?.(nativeSessionId);
+        throw new AutomationError("RUN_OUTPUT_INVALID", "The OpenCode Run returned malformed structured output.", { cause });
+    }
+}
+function parseOpenCodeEvent(line) {
+    try {
+        return JSON.parse(line);
+    }
+    catch (cause) {
+        throw new AutomationError("HARNESS_PROTOCOL_ERROR", "OpenCode emitted malformed JSONL.", { cause });
+    }
+}
+function opencodeSessionId(event) {
+    if (typeof event !== "object" || event === null) {
+        throw new AutomationError("HARNESS_PROTOCOL_ERROR", "OpenCode emitted an event without a valid Session identifier.");
+    }
+    const sessionId = event.sessionID;
+    if (typeof sessionId !== "string" || sessionId.length === 0) {
+        throw new AutomationError("HARNESS_PROTOCOL_ERROR", "OpenCode emitted an event without a valid Session identifier.");
+    }
+    return sessionId;
+}
+function completedOpenCodeText(event) {
+    if (typeof event !== "object" || event === null) {
+        return undefined;
+    }
+    const candidate = event;
+    if (candidate.type !== "text" ||
+        candidate.part?.type !== "text" ||
+        candidate.part.time?.end === undefined ||
+        typeof candidate.part.text !== "string") {
+        return undefined;
+    }
+    return candidate.part.text;
+}
+function opencodeFailureDiagnostic(event) {
+    if (typeof event !== "object" ||
+        event === null ||
+        event.type !== "error") {
+        return undefined;
+    }
+    const error = event.error;
+    if (typeof error === "string") {
+        return error;
+    }
+    if (typeof error === "object" && error !== null) {
+        const data = error.data;
+        if (typeof data === "object" && data !== null) {
+            const message = data.message;
+            if (typeof message === "string") {
+                return message;
+            }
+        }
+        const message = error.message;
+        if (typeof message === "string") {
+            return message;
+        }
+    }
+    try {
+        return JSON.stringify(error);
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/run-coordination.d.ts

@@ -0,0 +1,10 @@
+import type { AccessPolicy } from "./harness.js";
+type Release = () => void;
+export declare class RunConcurrencyLimiter {
+    #private;
+    constructor(limit: number | undefined);
+    acquire(signal?: AbortSignal): Promise<Release>;
+}
+export declare function isConcurrencyLimit(value: unknown): value is number;
+export declare function acquireWorkspaceAccess(workspaceRoot: string, access: AccessPolicy): Release;
+export {};

package/dist/run-coordination.js

@@ -0,0 +1,96 @@
+import { throwIfAborted } from "./cancellation.js";
+import { AutomationError } from "./errors.js";
+const DEFAULT_CONCURRENCY = 4;
+const workspaceAccesses = new Map();
+export class RunConcurrencyLimiter {
+    #limit;
+    #waiters = [];
+    #active = 0;
+    constructor(limit) {
+        const resolvedLimit = limit ?? DEFAULT_CONCURRENCY;
+        if (!isConcurrencyLimit(resolvedLimit)) {
+            throw new TypeError("Workflow concurrency must be a positive integer.");
+        }
+        this.#limit = resolvedLimit;
+    }
+    async acquire(signal) {
+        throwIfAborted(signal);
+        if (this.#active < this.#limit) {
+            this.#active += 1;
+        }
+        else {
+            await new Promise((resolve, reject) => {
+                const cleanup = () => signal?.removeEventListener("abort", cancel);
+                const waiter = {
+                    grant() {
+                        cleanup();
+                        resolve();
+                    },
+                };
+                const cancel = () => {
+                    const index = this.#waiters.indexOf(waiter);
+                    if (index === -1) {
+                        return;
+                    }
+                    this.#waiters.splice(index, 1);
+                    cleanup();
+                    reject(signal?.reason);
+                };
+                this.#waiters.push(waiter);
+                signal?.addEventListener("abort", cancel, { once: true });
+                if (signal?.aborted === true) {
+                    cancel();
+                }
+            });
+        }
+        let released = false;
+        return () => {
+            if (released) {
+                return;
+            }
+            released = true;
+            const next = this.#waiters.shift();
+            if (next === undefined) {
+                this.#active -= 1;
+            }
+            else {
+                next.grant();
+            }
+        };
+    }
+}
+export function isConcurrencyLimit(value) {
+    return Number.isSafeInteger(value) && value >= 1;
+}
+export function acquireWorkspaceAccess(workspaceRoot, access) {
+    const current = workspaceAccesses.get(workspaceRoot);
+    const write = access === "write-workspace" || access === "full";
+    if ((write && current !== undefined) ||
+        (!write && current?.writer === true)) {
+        throw new AutomationError("WORKSPACE_CONCURRENCY_CONFLICT", "The Workspace is already used by a concurrent Run with incompatible access.");
+    }
+    const state = current ?? { readers: 0, writer: false };
+    if (write) {
+        state.writer = true;
+    }
+    else {
+        state.readers += 1;
+    }
+    workspaceAccesses.set(workspaceRoot, state);
+    let released = false;
+    return () => {
+        if (released) {
+            return;
+        }
+        released = true;
+        if (write) {
+            state.writer = false;
+        }
+        else {
+            state.readers -= 1;
+        }
+        if (!state.writer && state.readers === 0) {
+            workspaceAccesses.delete(workspaceRoot);
+        }
+    };
+}

package/dist/run-journal.d.ts

@@ -0,0 +1,14 @@
+import type { AutomationEvent } from "./events.js";
+export type RunJournalMode = "full" | "metadata";
+export interface RunJournalContent {
+    readonly environment?: Readonly<Record<string, string | undefined>>;
+    readonly input?: unknown;
+    readonly prompt?: string;
+    readonly result?: unknown;
+}
+export declare class RunJournal {
+    #private;
+    private constructor();
+    static create(workflowId: string, mode: RunJournalMode, workspaceRoot: string): Promise<RunJournal>;
+    append(event: AutomationEvent, content?: RunJournalContent): Promise<void>;
+}

package/dist/run-journal.js

@@ -0,0 +1,129 @@
+import { homedir } from "node:os";
+import { mkdir, realpath, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { AutomationError, contextualizeAutomationError, } from "./errors.js";
+import { isWithinDirectory } from "./filesystem.js";
+export class RunJournal {
+    #filePath;
+    #mode;
+    #runStartedAt = new Map();
+    #executionStartedAt;
+    constructor(filePath, mode, executionStartedAt) {
+        this.#filePath = filePath;
+        this.#mode = mode;
+        this.#executionStartedAt = executionStartedAt;
+    }
+    static async create(workflowId, mode, workspaceRoot) {
+        try {
+            const [directory, canonicalWorkspaceRoot] = await Promise.all([
+                canonicalizePotentialPath(path.join(userStateDirectory(), "automation", "run-journals")),
+                canonicalizePotentialPath(workspaceRoot),
+            ]);
+            if (isWithinDirectory(canonicalWorkspaceRoot, directory)) {
+                throw new AutomationError("RUN_JOURNAL_UNAVAILABLE", "Run Journal directory must be outside the Workspace. Disable recording or configure a user state directory outside it.");
+            }
+            await mkdir(directory, { mode: 0o700, recursive: true });
+            const filePath = path.join(directory, `${workflowId}.jsonl`);
+            await writeFile(filePath, "", { flag: "wx", mode: 0o600 });
+            return new RunJournal(filePath, mode, Date.now());
+        }
+        catch (cause) {
+            throw contextualizeAutomationError(cause, "RUN_JOURNAL_UNAVAILABLE", "Could not initialize the Run Journal.", { workflowId });
+        }
+    }
+    async append(event, content) {
+        const entry = this.#entry(event, content);
+        await writeFile(this.#filePath, `${JSON.stringify(entry)}\n`, {
+            flag: "a",
+        });
+    }
+    #entry(event, content) {
+        const timestamp = Date.parse(event.timestamp);
+        const publicMetadata = redactSensitiveEventContent(event);
+        const lifecycle = this.#lifecycle(event, timestamp);
+        return {
+            ...publicMetadata,
+            ...lifecycle,
+            ...(this.#mode === "full" ? sensitiveEventContent(event, content) : {}),
+        };
+    }
+    #lifecycle(event, timestamp) {
+        if (event.type === "workflow.started") {
+            return { state: "started" };
+        }
+        if (event.type === "workflow.completed") {
+            return {
+                durationMs: Math.max(0, timestamp - this.#executionStartedAt),
+                state: "completed",
+            };
+        }
+        if (event.type === "workflow.failed") {
+            return {
+                durationMs: Math.max(0, timestamp - this.#executionStartedAt),
+                state: "failed",
+            };
+        }
+        if (event.type === "run.started") {
+            this.#runStartedAt.set(event.runId, timestamp);
+            return { state: "started" };
+        }
+        if (event.type === "run.completed" || event.type === "run.failed") {
+            return {
+                durationMs: Math.max(0, timestamp - (this.#runStartedAt.get(event.runId) ?? timestamp)),
+                state: event.type === "run.completed" ? "completed" : "failed",
+            };
+        }
+        return {};
+    }
+}
+async function canonicalizePotentialPath(targetPath) {
+    let existingPath = path.resolve(targetPath);
+    const missingSegments = [];
+    while (true) {
+        try {
+            return path.join(await realpath(existingPath), ...missingSegments);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                throw error;
+            }
+            const parent = path.dirname(existingPath);
+            if (parent === existingPath) {
+                throw error;
+            }
+            missingSegments.unshift(path.basename(existingPath));
+            existingPath = parent;
+        }
+    }
+}
+function sensitiveEventContent(event, content) {
+    return {
+        ...(event.type === "run.native" ? { native: event.native } : {}),
+        ...(event.type === "workflow.completed" ? { result: event.result } : {}),
+        ...content,
+    };
+}
+function redactSensitiveEventContent(event) {
+    if (event.type === "workflow.completed") {
+        const { result: _result, ...metadata } = event;
+        return metadata;
+    }
+    if (event.type === "run.native") {
+        const { native: _native, ...metadata } = event;
+        return metadata;
+    }
+    return { ...event };
+}
+function userStateDirectory() {
+    const xdgStateHome = process.env.XDG_STATE_HOME;
+    if (xdgStateHome !== undefined && path.isAbsolute(xdgStateHome)) {
+        return xdgStateHome;
+    }
+    if (process.platform === "win32") {
+        return process.env.LOCALAPPDATA ?? path.join(homedir(), "AppData", "Local");
+    }
+    if (process.platform === "darwin") {
+        return path.join(homedir(), "Library", "Application Support");
+    }
+    return path.join(homedir(), ".local", "state");
+}

package/dist/schema.d.ts

@@ -0,0 +1,167 @@
+import type { JsonPrimitive } from "./json.js";
+export type SchemaPathSegment = number | string;
+export type SchemaIssueCode = "invalid_enum_value" | "invalid_literal" | "invalid_string" | "invalid_type" | "invalid_union" | "too_big" | "too_small" | "unrecognized_key";
+export interface SchemaIssue {
+    readonly code: SchemaIssueCode;
+    readonly path: readonly SchemaPathSegment[];
+    readonly message: string;
+    readonly [detail: string]: unknown;
+}
+export type SafeParseResult<TValue> = {
+    readonly success: true;
+    readonly data: TValue;
+} | {
+    readonly success: false;
+    readonly error: SchemaValidationError;
+};
+export type JSONSchema = Readonly<Record<string, unknown>>;
+declare const schemaOutput: unique symbol;
+declare const schemaOptional: unique symbol;
+declare const schemaParser: unique symbol;
+declare const schemaJson: unique symbol;
+interface ParseResult<TValue> {
+    readonly value?: TValue;
+    readonly issues: readonly SchemaIssue[];
+}
+export interface Schema<TValue, TOptional extends boolean = false> {
+    readonly [schemaOutput]: TValue;
+    readonly [schemaOptional]: TOptional;
+    parse(value: unknown): TValue;
+    safeParse(value: unknown): SafeParseResult<TValue>;
+    describe(description: string): Schema<TValue, TOptional>;
+    nullable(): Schema<TValue | null, TOptional>;
+    optional(): Schema<TValue | undefined, true>;
+    toJSONSchema(): JSONSchema;
+}
+type AnySchema = Schema<any, boolean>;
+type InferAnySchema<TSchema extends AnySchema> = TSchema[typeof schemaOutput];
+export type InferSchema<TSchema extends AnySchema> = TSchema[typeof schemaOutput];
+export declare class SchemaValidationError extends Error {
+    readonly issues: readonly SchemaIssue[];
+    constructor(issues: readonly SchemaIssue[]);
+}
+declare abstract class BaseSchema<TValue, TOptional extends boolean = false> implements Schema<TValue, TOptional> {
+    #private;
+    readonly [schemaOutput]: TValue;
+    readonly [schemaOptional]: TOptional;
+    protected constructor(optional: TOptional, description?: string);
+    protected get description(): string | undefined;
+    parse(value: unknown): TValue;
+    safeParse(value: unknown): SafeParseResult<TValue>;
+    describe(description: string): this;
+    nullable(): Schema<TValue | null, TOptional>;
+    optional(): Schema<TValue | undefined, true>;
+    toJSONSchema(): JSONSchema;
+    protected abstract cloneWithDescription(description: string): BaseSchema<TValue, TOptional>;
+    abstract [schemaParser](value: unknown, path: readonly SchemaPathSegment[]): ParseResult<TValue>;
+    abstract [schemaJson](): JSONSchema;
+}
+interface StringConstraints {
+    readonly maximumLength: number | undefined;
+    readonly minimumLength: number | undefined;
+    readonly pattern: string | undefined;
+}
+export declare class StringSchema extends BaseSchema<string> {
+    #private;
+    constructor(constraints?: StringConstraints, description?: string);
+    minLength(minimumLength: number): StringSchema;
+    maxLength(maximumLength: number): StringSchema;
+    pattern(pattern: string): StringSchema;
+    protected cloneWithDescription(description: string): StringSchema;
+    [schemaParser](value: unknown, path: readonly SchemaPathSegment[]): ParseResult<string>;
+    [schemaJson](): JSONSchema;
+}
+interface NumberConstraints {
+    readonly maximum: number | undefined;
+    readonly minimum: number | undefined;
+    readonly integer: boolean;
+}
+export declare class NumberSchema<TInteger extends boolean = false> extends BaseSchema<number> {
+    #private;
+    constructor(integer?: TInteger, constraints?: Omit<NumberConstraints, "integer">, description?: string);
+    minimum(minimum: number): NumberSchema<TInteger>;
+    maximum(maximum: number): NumberSchema<TInteger>;
+    protected cloneWithDescription(description: string): NumberSchema<TInteger>;
+    [schemaParser](value: unknown, path: readonly SchemaPathSegment[]): ParseResult<number>;
+    [schemaJson](): JSONSchema;
+}
+export declare class BooleanSchema extends BaseSchema<boolean> {
+    constructor(description?: string);
+    protected cloneWithDescription(description: string): BooleanSchema;
+    [schemaParser](value: unknown, path: readonly SchemaPathSegment[]): ParseResult<boolean>;
+    [schemaJson](): JSONSchema;
+}
+export declare class NullSchema extends BaseSchema<null> {
+    constructor(description?: string);
+    protected cloneWithDescription(description: string): NullSchema;
+    [schemaParser](value: unknown, path: readonly SchemaPathSegment[]): ParseResult<null>;
+    [schemaJson](): JSONSchema;
+}
+export declare class LiteralSchema<TValue extends JsonPrimitive> extends BaseSchema<TValue> {
+    #private;
+    constructor(expected: TValue, description?: string);
+    protected cloneWithDescription(description: string): LiteralSchema<TValue>;
+    [schemaParser](value: unknown, path: readonly SchemaPathSegment[]): ParseResult<TValue>;
+    [schemaJson](): JSONSchema;
+}
+export declare class EnumSchema<TValues extends readonly JsonPrimitive[]> extends BaseSchema<TValues[number]> {
+    #private;
+    constructor(values: TValues, description?: string);
+    protected cloneWithDescription(description: string): EnumSchema<TValues>;
+    [schemaParser](value: unknown, path: readonly SchemaPathSegment[]): ParseResult<TValues[number]>;
+    [schemaJson](): JSONSchema;
+}
+interface ArrayConstraints {
+    readonly maximumItems: number | undefined;
+    readonly minimumItems: number | undefined;
+}
+export declare class ArraySchema<TItemSchema extends AnySchema> extends BaseSchema<InferAnySchema<TItemSchema>[]> {
+    #private;
+    constructor(item: TItemSchema, constraints?: ArrayConstraints, description?: string);
+    minItems(minimumItems: number): ArraySchema<TItemSchema>;
+    maxItems(maximumItems: number): ArraySchema<TItemSchema>;
+    protected cloneWithDescription(description: string): ArraySchema<TItemSchema>;
+    [schemaParser](value: unknown, path: readonly SchemaPathSegment[]): ParseResult<InferAnySchema<TItemSchema>[]>;
+    [schemaJson](): JSONSchema;
+}
+type SchemaShape = Readonly<Record<string, AnySchema>>;
+type OptionalShapeKeys<TShape extends SchemaShape> = {
+    [TKey in keyof TShape]-?: TShape[TKey] extends Schema<any, true> ? TKey : never;
+}[keyof TShape];
+type RequiredShapeKeys<TShape extends SchemaShape> = Exclude<keyof TShape, OptionalShapeKeys<TShape>>;
+type Simplify<TValue> = {
+    [TKey in keyof TValue]: TValue[TKey];
+};
+type ObjectSchemaValue<TShape extends SchemaShape> = Simplify<{
+    -readonly [TKey in RequiredShapeKeys<TShape>]: InferAnySchema<TShape[TKey]>;
+} & {
+    -readonly [TKey in OptionalShapeKeys<TShape>]?: Exclude<InferAnySchema<TShape[TKey]>, undefined>;
+}>;
+export declare class ObjectSchema<TShape extends SchemaShape> extends BaseSchema<ObjectSchemaValue<TShape>> {
+    #private;
+    constructor(shape: TShape, description?: string);
+    protected cloneWithDescription(description: string): ObjectSchema<TShape>;
+    [schemaParser](value: unknown, path: readonly SchemaPathSegment[]): ParseResult<ObjectSchemaValue<TShape>>;
+    [schemaJson](): JSONSchema;
+}
+type UnionSchemaValue<TSchemas extends readonly AnySchema[]> = InferAnySchema<TSchemas[number]>;
+export declare class UnionSchema<TSchemas extends readonly AnySchema[]> extends BaseSchema<UnionSchemaValue<TSchemas>> {
+    #private;
+    constructor(schemas: TSchemas, description?: string);
+    protected cloneWithDescription(description: string): UnionSchema<TSchemas>;
+    [schemaParser](value: unknown, path: readonly SchemaPathSegment[]): ParseResult<UnionSchemaValue<TSchemas>>;
+    [schemaJson](): JSONSchema;
+}
+export declare const schema: Readonly<{
+    array: <TItemSchema extends AnySchema>(item: TItemSchema) => ArraySchema<TItemSchema>;
+    boolean: () => BooleanSchema;
+    enum: <const TValues extends readonly JsonPrimitive[]>(values: TValues) => EnumSchema<TValues>;
+    integer: () => NumberSchema<true>;
+    literal: <const TValue extends JsonPrimitive>(value: TValue) => LiteralSchema<TValue>;
+    null: () => NullSchema;
+    number: () => NumberSchema;
+    object: <const TShape extends SchemaShape>(shape: TShape) => ObjectSchema<TShape>;
+    string: () => StringSchema;
+    union: <const TSchemas extends readonly AnySchema[]>(schemas: TSchemas) => UnionSchema<TSchemas>;
+}>;
+export {};