@nyxa/automation 0.1.0

package/README.md

@@ -0,0 +1,559 @@
+# @nyxa/automation
+
+Write trusted TypeScript Workflows and execute them explicitly from Node.js or
+the `automation` CLI. Node.js 22 or later is required.
+
+## Security and responsibility
+
+A Workflow is trusted local code, not a sandboxed configuration file. It runs
+with the permissions of the process that starts Automation and can use the same
+filesystem, environment, and network access as that process. Only execute
+Workflows whose source you trust, and choose each Run's Access Policy
+deliberately.
+
+Automation invokes the user's local Codex, Claude Code, Kimi Code, and OpenCode
+CLIs.
+Their authentication, subscriptions, and quotas remain the user's
+responsibility; Automation does not manage provider accounts, credentials,
+billing, or limits.
+
+## Install
+
+```sh
+npm install --save-dev @nyxa/automation
+```
+
+The package includes its TypeScript runtime loader. A project does not need a
+global TypeScript or `tsx` installation to run a Workflow.
+
+## Initialize an existing project
+
+Run `init` from a project that already has a `package.json`. It refuses to
+overwrite the requested Workflow and detects npm, pnpm, or Yarn from the
+project lockfile before offering to add Automation as a development dependency:
+
+```sh
+npx @nyxa/automation init workflows/first.ts
+```
+
+Choose the Harness explicitly for non-interactive use. `--no-install` only
+generates the Workflow; `--yes` accepts installation and, when `--harness` is
+omitted, selects a Harness only if exactly one local Harness is operational.
+
+```sh
+npx @nyxa/automation init workflows/codex.ts --harness codex --yes
+npx @nyxa/automation init workflows/claude.ts --harness claude-code --no-install
+npx @nyxa/automation init workflows/kimi.ts --harness kimi-code --no-install
+npx @nyxa/automation init workflows/opencode.ts --harness opencode --no-install
+```
+
+The generated Workflow imports only the selected Harness, requests a documented
+structured result, and handles a `needs_input` result with ordinary TypeScript
+control flow.
+
+## Diagnose the local environment
+
+Run `doctor` before a Workflow to check Node.js, the project-local Automation
+package, and the installed Codex, Claude Code, Kimi Code, and OpenCode
+Harnesses:
+
+```sh
+npx automation doctor
+npx automation doctor --harness codex
+npx automation doctor --harness claude-code
+npx automation doctor --harness kimi-code
+npx automation doctor --harness opencode
+```
+
+The command checks Harness versions and verifies authentication headlessly.
+For Kimi Code it performs the ACP initialization and authentication handshake;
+it never launches `kimi login`. For OpenCode it reads `opencode auth list` and
+considers authentication verified only when the CLI reports a stored credential
+or authentication environment variable. It does not import a Workflow, change
+project files, install software, or start an interactive authentication flow.
+Without a filter, one fully operational Harness is sufficient and missing
+Harnesses are reported as warnings. With `--harness`, the requested Harness
+must be fully operational.
+
+## Define a Workflow
+
+```ts
+// workflow.ts
+import { defineWorkflow } from "@nyxa/automation";
+
+const workflow = defineWorkflow({
+  async run() {
+    return { status: "ready", count: 1 };
+  },
+});
+
+export default workflow;
+```
+
+Importing this module only creates an inert Workflow Definition. Execution is
+always explicit:
+
+```ts
+import { executeWorkflow } from "@nyxa/automation";
+import workflow from "./workflow.js";
+
+const result = await executeWorkflow(workflow);
+// result is inferred as { status: string; count: number }
+```
+
+## Run Codex
+
+Use the local Codex CLI as a Harness. Automation requires Codex CLI 0.144.0 or
+later, performs the version preflight once per resolved executable, and keeps
+the user's existing authentication and local configuration.
+
+```ts
+import { codex, defineWorkflow } from "@nyxa/automation";
+
+const workflow = defineWorkflow({
+  harness: codex(),
+  async run(context) {
+    return context.run("Inspect this project and summarize its architecture.", {
+      access: "read",
+    });
+  },
+});
+
+export default workflow;
+```
+
+Runs are headless and require an explicit Access Policy. A Run can replace the
+Workflow's default Harness, and Codex-specific options are only passed when
+declared:
+
+```ts
+const reviewHarness = codex({
+  executable: "/opt/codex/bin/codex",
+  model: "gpt-test",
+  effort: "high",
+  profile: "ci",
+});
+
+const reviewWorkflow = defineWorkflow({
+  async run(context) {
+    return context.run("Review the proposed change.", {
+      access: "read",
+      harness: reviewHarness,
+      name: "review",
+    });
+  },
+});
+```
+
+## Run Claude Code
+
+Use `claudeCode()` to run the same Workflow contract with the local Claude Code
+CLI. Automation requires Claude Code 2.1.205 or later. Omitting an option keeps
+the corresponding local Harness configuration; Automation does not require a
+model name or reasoning effort.
+
+```ts
+import { claudeCode, defineWorkflow } from "@nyxa/automation";
+
+const workflow = defineWorkflow({
+  harness: claudeCode({
+    model: "claude-test",
+    effort: "high",
+    fallbackModel: "claude-fallback",
+    maxTurns: 8,
+    maxBudgetUsd: 2,
+  }),
+  run: (context) =>
+    context.run("Inspect this project and summarize its architecture.", {
+      access: "read",
+    }),
+});
+
+export default workflow;
+```
+
+## Run Kimi Code
+
+Use `kimiCode()` with Kimi Code CLI 0.28.1 or later. Automation starts the
+official `kimi acp` server over stdio; ACP remains an adapter-private transport,
+so the portable Workflow, Run, Session, event, and error APIs do not expose
+JSON-RPC details. Install and authenticate Kimi Code separately before running
+the Workflow.
+
+```ts
+import { defineWorkflow, kimiCode } from "@nyxa/automation";
+
+const workflow = defineWorkflow({
+  harness: kimiCode({
+    executable: "/opt/kimi/bin/kimi",
+    model: "kimi-for-coding",
+    effort: "high",
+  }),
+  run: (context) =>
+    context.run("Implement the requested change.", {
+      access: "full",
+      approval: "deny",
+    }),
+});
+
+export default workflow;
+```
+
+Kimi model catalogs declare their own effort levels, so `effort` intentionally
+accepts a string and is checked against the options advertised by the selected
+model. An unsupported model or effort fails with
+`HARNESS_CAPABILITY_UNSUPPORTED`.
+
+## Run OpenCode
+
+Use `opencode()` with OpenCode CLI 1.18.4 or later. Automation invokes
+`opencode run --format json`, keeps the local OpenCode configuration and
+authentication, exposes completed JSONL records as native events, and resumes
+explicit Sessions with the native OpenCode Session identifier.
+
+```ts
+import { defineWorkflow, opencode } from "@nyxa/automation";
+
+const workflow = defineWorkflow({
+  harness: opencode({
+    executable: "/opt/opencode/bin/opencode",
+    model: "provider/model",
+    effort: "high",
+  }),
+  run: (context) =>
+    context.run("Implement the requested change.", {
+      access: "full",
+      approval: "deny",
+    }),
+});
+
+export default workflow;
+```
+
+OpenCode calls provider-specific reasoning levels “variants”, so Automation
+maps the typed `effort` option to its native `--variant` flag. The adapter does
+not accept arbitrary CLI arguments or override the locally configured default
+agent.
+
+All four factories accept an optional executable path, model, and effort. Codex
+also accepts a local profile; Claude Code also accepts a fallback model, maximum
+turn count, and budget in US dollars. A Run can override the Workflow's default
+Harness without changing the portable Run API.
+
+## Continue a Session explicitly
+
+Create a lazy Session handle when several sequential Runs should share one
+native Codex, Claude Code, Kimi Code, or OpenCode conversation:
+
+```ts
+const workflow = defineWorkflow({
+  async run(context) {
+    const session = context.session({
+      harness: codex({ model: "gpt-test", effort: "high" }),
+      cwd: "packages/api",
+      env: { REVIEW_MODE: "security" },
+      name: "authentication-review",
+    });
+
+    await session.run("Inspect the authentication flow.", { access: "read" });
+    return session.run("Propose the smallest safe change.", {
+      access: "write-workspace",
+      approval: "deny",
+    });
+  },
+});
+```
+
+Creating the handle does not inspect or start the Harness. Its Harness
+configuration, `cwd`, environment overlay, and optional observability `name`
+are fixed at creation. Each `session.run()` keeps its own Access Policy,
+Approval Policy, Run name, and Output Contract, and may override or remove
+variables from the Session environment.
+Runs on one handle are sequential: an overlapping call fails immediately with
+`SESSION_BUSY`.
+
+After a clean native completion, later Runs resume the same conversation. If a
+process or protocol failure makes continuity uncertain, the handle becomes
+unavailable and later calls fail with `SESSION_UNAVAILABLE`; Automation never
+silently creates a replacement. Ordinary `context.run()` calls and separate
+Workflow executions always start independent Sessions.
+
+## Control Run execution
+
+Every Run declares an `access` ceiling: `read`, `write-workspace`, or `full`.
+The Approval Policy defaults to `deny`; `approval: "auto"` uses only a native
+automatic mechanism and fails with `HARNESS_CAPABILITY_UNSUPPORTED` when the
+selected Harness cannot provide one. The v1 API has no human approval mode.
+
+```ts
+await context.run("Update the package documentation.", {
+  access: "write-workspace",
+  approval: "deny",
+  cwd: "packages/docs",
+  env: {
+    CI: "1",
+    DEBUG: undefined,
+  },
+});
+```
+
+`cwd` is resolved from the execution's Workspace root and must remain inside
+it, including after symbolic links are resolved. Harness processes inherit the
+host environment; `env` overlays string values and removes variables assigned
+`undefined`.
+
+An execution admits up to four concurrent Runs by default. Set another positive
+integer through the library or CLI when the Workflow should use a different
+global limit:
+
+```ts
+await executeWorkflow(workflow, { concurrency: 2 });
+```
+
+```sh
+npx automation workflow.ts --concurrency 2
+```
+
+Several `read` Runs can share a Workspace within that limit. A
+`write-workspace` or `full` Run requires exclusive access and fails immediately
+with `WORKSPACE_CONCURRENCY_CONFLICT` when another Run is already reading or
+writing the same canonical Workspace root. Automation does not queue that
+conflict or create an isolated Workspace. To run writes in parallel, invoke the
+Workflows with explicitly distinct `workspaceRoot` directories.
+
+Each Run has a 30-minute timeout by default. Set `timeout` in milliseconds or
+use `false` for an intentionally unbounded Run. Expiration fails the Run with
+`RUN_TIMED_OUT`, terminates the Harness process tree, and makes an explicit
+Session unavailable because its continuity can no longer be proven.
+
+```ts
+await context.run("Perform the long-running review.", {
+  access: "read",
+  timeout: 5 * 60 * 1_000,
+});
+```
+
+Pass an `AbortSignal` to cancel a complete Workflow execution. The Workflow
+Context exposes the execution signal so trusted Workflow logic can stop its own
+non-Run work too. Cancellation fails active Runs with `RUN_CANCELLED` and
+releases their concurrency slots and Workspace access.
+
+```ts
+const controller = new AbortController();
+const result = executeWorkflow(workflow, { signal: controller.signal });
+
+controller.abort();
+await result;
+```
+
+In the CLI, the first Ctrl-C requests cancellation and allows up to five
+seconds for cleanup. A second Ctrl-C forces the Harness process tree to stop
+immediately. User-requested cancellation exits with status `130`; human mode
+does not write a Workflow Result, while `--json` keeps `stdout` as Automation
+Events JSONL only.
+
+Codex maps the three access levels to its native sandboxes and rejects
+automatic approval because its headless CLI has no non-human equivalent.
+Claude Code maps the same levels to its permission and sandbox mechanisms and
+uses its native `auto` mode when requested.
+
+Kimi Code currently exposes no native ceiling that can guarantee `read` or
+`write-workspace`, so its adapter refuses those Access Policies before starting
+ACP. It supports only `full`: `approval: "deny"` selects ACP `default` mode and
+rejects permission requests, while `approval: "auto"` selects ACP `auto` mode.
+Interactive questions are always cancelled because Runs remain headless.
+
+OpenCode also exposes no native shell sandbox that can guarantee `read` or
+`write-workspace`, so those policies fail before the CLI is inspected or
+started. It supports only `full`: with `approval: "deny"`, native permission
+requests are rejected; with `approval: "auto"`, Automation passes OpenCode's
+`--auto` flag. OpenCode's explicit local permission denials remain effective.
+
+| Harness | `read` | `write-workspace` | `full` / `deny` | `full` / `auto` |
+| --- | --- | --- | --- | --- |
+| Codex | native read-only sandbox | native workspace sandbox | native full access, approvals denied | unsupported |
+| Claude Code | native plan mode | native edit sandbox | native bypass mode | native auto mode |
+| Kimi Code | unsupported | unsupported | ACP `default`, permissions denied | ACP `auto`, questions cancelled |
+| OpenCode | unsupported | unsupported | full local CLI access, permission requests denied | full local CLI access, native `--auto` |
+
+Runs never open an interactive input channel. Automation appends a headless
+instruction to every prompt, and the Claude Code adapter disables its native
+`AskUserQuestion` tool. If missing information is an expected outcome, model it
+as a branch of the Output Contract and handle the typed value with ordinary
+TypeScript control flow:
+
+```ts
+const outcome = schema.union([
+  schema.object({
+    status: schema.literal("completed"),
+    result: schema.string(),
+  }).describe("Use when the task can be completed."),
+  schema.object({
+    status: schema.literal("needs_input"),
+    question: schema.string(),
+    choices: schema.array(schema.string()),
+  }).describe("Use when required information is missing."),
+]);
+
+const result = await context.run("Choose the deployment target.", {
+  access: "read",
+  output: outcome,
+});
+
+if (result.status === "needs_input") {
+  return result;
+}
+```
+
+`needs_input` is an ordinary valid business result, not a Run Failure or a
+reserved engine status. Codex and Claude Code receive the generated JSON Schema
+through their native structured-output mechanisms. Kimi Code and OpenCode
+receive the schema in the prompt and must return one JSON value without
+surrounding text; their adapters parse it strictly. In every case Automation
+validates the returned value independently before exposing it to the Workflow.
+
+## Observe execution
+
+`executeWorkflow()` can deliver an ordered stream of correlated Automation
+Events. Every event carries a Workflow identifier, sequence number, and
+timestamp. Run events also carry technical Run and Session identifiers plus an
+optional non-unique `name`.
+
+```ts
+const result = await executeWorkflow(workflow, {
+  async onEvent(event) {
+    await persistEvent(event);
+
+    if (event.type === "run.failed") {
+      console.error(event.error.code, event.runId);
+    }
+  },
+});
+```
+
+Observers are awaited one at a time. If an observer fails, Automation stops all
+active Harness processes and rejects with `EVENT_OBSERVER_FAILED`. Native
+Harness events are available on `run.native` under an explicitly non-portable
+envelope: `event.native` is `{ portable: false, event: unknown }`.
+
+Execution failures use `AutomationError` with a stable `code`, the available
+Workflow, Run, and Session identifiers, the Harness name, and an optional
+native `cause`. Use `isAutomationError()` to narrow unknown failures.
+Authentication refusals use `HARNESS_NOT_AUTHENTICATED`, unsupported
+model-effort combinations use `HARNESS_CAPABILITY_UNSUPPORTED`, and a Run
+Journal that cannot be initialized uses `RUN_JOURNAL_UNAVAILABLE`.
+
+## Record executions safely
+
+Every execution creates a JSONL Run Journal in the user's private state
+directory, outside the Workspace. By default, the journal contains ordered
+Automation Event metadata, identifiers, names, durations, states, and portable
+errors. It omits Workflow Inputs, prompts, Workflow Results, structured Run
+outputs, native events, and environment values.
+
+Use `record: "full"` only when sensitive diagnostic content may be persisted:
+
+```ts
+await executeWorkflow(workflow, {
+  record: "full",
+});
+```
+
+Disable the journal with `record: false` or `--no-record`:
+
+```ts
+await executeWorkflow(workflow, { record: false });
+```
+
+```sh
+npx automation workflow.ts --no-record
+```
+
+On Linux, journals use `$XDG_STATE_HOME/automation/run-journals` when that
+variable contains an absolute path, otherwise
+`~/.local/state/automation/run-journals`. Run Journals are diagnostic only:
+Automation never reads them as a cache or checkpoint, and every invocation
+starts the Workflow again from its Workflow Input. If the configured state
+directory resolves inside the Workspace, Automation refuses to create the
+journal; configure a state directory outside the Workspace or disable
+recording for that invocation.
+
+## Validate Workflow boundaries
+
+Use the built-in portable schema DSL for Workflow Inputs and Results. Schemas
+also validate values directly with `parse()` or `safeParse()`.
+
+```ts
+import { defineWorkflow, executeWorkflow, schema } from "@nyxa/automation";
+
+const workflow = defineWorkflow({
+  input: schema.object({
+    name: schema.string().minLength(1).describe("The person to greet"),
+    language: schema.enum(["en", "fr"]).optional(),
+  }),
+  output: schema.object({ message: schema.string() }),
+  run({ input }) {
+    return { message: `Hello ${input.name}` };
+  },
+});
+
+const result = await executeWorkflow(workflow, {
+  input: { name: "Nyxa", language: "en" },
+});
+```
+
+## Run from the CLI
+
+The direct and explicit forms are equivalent:
+
+```sh
+npx automation workflow.ts
+npx automation run workflow.ts
+```
+
+Provide a declared Workflow Input as inline JSON, from a file, or from standard
+input. These sources are mutually exclusive.
+
+```sh
+npx automation workflow.ts --input '{"name":"Nyxa"}'
+npx automation workflow.ts --input-file input.json
+printf '%s' '{"name":"Nyxa"}' | npx automation workflow.ts --input -
+```
+
+Use `--json` for a JSONL stream containing only Automation Events on `stdout`.
+The terminal `workflow.completed` event carries the Workflow Result.
+
+```sh
+npx automation workflow.ts --json
+```
+
+Strings are written to `stdout` as-is, other JSON values are serialized, and
+an absent result writes nothing. Diagnostics use `stderr`; argument and module
+loading errors exit with status `2`, while execution failures exit with status
+`1`, successful execution exits with `0`, and cancelled execution exits with
+`130`. Human-mode Run progress is also written to `stderr`, keeping `stdout`
+reserved for the Workflow Result.
+
+## v1 scope
+
+The v1 package includes the TypeScript library, CLI, schema DSL, and the Codex,
+Claude Code, Kimi Code, and OpenCode Harness Adapters backed by their local
+CLIs. It supports typed Workflow Inputs and Results, Output Contracts, explicit
+Sessions, headless policies, Automation Events, Run Journals, `init`, and
+`doctor`.
+
+The following remain outside the v1 contract:
+
+- direct provider API calls and model SDKs;
+- a public plugin API for third-party Harness Adapters;
+- interactive questions or human approvals during a Run;
+- built-in retries, backoff, or idempotency guarantees;
+- transparent resume, checkpoints, or cached Run reuse;
+- automatic creation of isolated Workspaces or worktrees;
+- arbitrary native Harness CLI arguments; and
+- automated real-Harness smoke tests requiring installations, accounts, or
+  subscriptions.
+
+Retries and repeated Runs must be explicit TypeScript control flow. Run
+Journals are diagnostic records only and never enable transparent execution
+resume.

package/dist/cancellation.d.ts

@@ -0,0 +1 @@
+export declare function throwIfAborted(signal: AbortSignal | undefined): void;

package/dist/cancellation.js

@@ -0,0 +1,5 @@
+export function throwIfAborted(signal) {
+    if (signal?.aborted === true) {
+        throw signal.reason;
+    }
+}

package/dist/claude-code.d.ts

@@ -0,0 +1,19 @@
+import { type Harness } from "./harness.js";
+import type { NoExtraKeys } from "./type-utils.js";
+export declare const CLAUDE_CODE_HARNESS_PREFLIGHT: {
+    readonly harnessName: "Claude Code";
+    readonly minimumVersion: readonly [2, 1, 205];
+    readonly unsupportedVersionMessage: "Claude Code CLI 2.1.205 or later is required.";
+    readonly versionPattern: RegExp;
+};
+export type ClaudeCodeEffort = "low" | "medium" | "high" | "xhigh" | "max" | "ultracode";
+export interface ClaudeCodeOptions {
+    readonly executable?: string;
+    readonly model?: string;
+    readonly effort?: ClaudeCodeEffort;
+    readonly fallbackModel?: string;
+    readonly maxTurns?: number;
+    readonly maxBudgetUsd?: number;
+}
+export declare function claudeCode(): Harness;
+export declare function claudeCode<const TOptions extends ClaudeCodeOptions>(options: TOptions & NoExtraKeys<TOptions, ClaudeCodeOptions>): Harness;