wicked-core-ts 0.1.0

package/index.d.ts

@@ -0,0 +1,159 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/* auto-generated by NAPI-RS */
+
+/**
+ * Options for [`Core::launch_run`]. `clisJson` is a JSON array of `AgenticCli` seats (the council
+ * roster); `Core.registryRoster()` returns the production roster ready to pass here.
+ */
+export interface LaunchOptions {
+  /** The free-text problem to decompose into ordered work units. */
+  problem: string
+  /** A stable session/run id (empty → the caller must supply one; Core requires an explicit id here). */
+  sessionId: string
+  /** JSON array of `AgenticCli` seats — the council roster for this run. */
+  clisJson: string
+  /** `shared` (default) | `isolated` — the collection-scope mode. */
+  entityMode?: string
+  /** Human-confirm gate policy: `none` (default) | `all` | `before:<ord>`. */
+  humanConfirm?: string
+  /** The id of a registered repo to run within (creates an isolated worktree). Omit for a repo-less run. */
+  repoRef?: string
+}
+/**
+ * A handle to a wicked-core runtime. Construct with [`Core::spawn`] (production engine: real
+ * council + wrapped-CLI subprocesses) or [`Core::spawn_stub`] (deterministic offline engine).
+ */
+export declare class Core {
+  /**
+   * Spawn the store actor over the estate db at `path` with the PRODUCTION engine (real council
+   * dispatcher + real wrapped-CLI step runner — runs actual agentic CLIs). The actor lives until
+   * every handle is dropped.
+   */
+  static spawn(path: string): Core
+  /**
+   * Spawn the store actor with the STUB engine — a deterministic council dispatcher +
+   * `StubStepRunner`, no subprocesses. For tests / offline runs that must not touch a real LLM.
+   */
+  static spawnStub(path: string): Core
+  /**
+   * The production council roster (built-ins ∪ the user's `~/.config/wicked-council/clis.toml`),
+   * as a JSON array of `AgenticCli` — pass straight into `launchRun`'s `clisJson`.
+   */
+  static registryRoster(): string
+  /**
+   * Subscribe to the live [`CoreEvent`] stream. `callback` follows the Node error-first
+   * convention — `(err, eventJson)` — and is invoked once per event with the event serialized as
+   * a JSON string (`{ type, ...fields }`); parse it in JS. Events arrive in emission order. Call
+   * this BEFORE `launchRun` to catch the whole sequence, and HOLD the returned [`Subscription`]:
+   * `close()` / `unsubscribe()` stops delivery and tears the pump thread + callback down.
+   *
+   * NOTE (ordering): async methods resolve their Promise off a libuv worker thread, while events
+   * are delivered from a separate pump thread — so an event emitted by a call MAY be observed by
+   * this callback slightly AFTER that call's Promise resolves. Await the event you need (as the
+   * smoke does) rather than assuming it precedes the method's resolution.
+   */
+  subscribe(callback: (err: Error | null, eventJson: string) => void): Subscription
+  /** Liveness probe — emits a `Heartbeat` to subscribers and resolves once the actor acks (`"ok"`). */
+  ping(): Promise<string>
+  /**
+   * Launch an interactive, resumable run: plans + distributes, then executes each unit off-thread
+   * (or pauses at a human-confirm gate). Resolves to the run id. Progress arrives as `CoreEvent`s
+   * — `subscribe()` first. Rejects with a busy error if a run with that id is already in flight.
+   */
+  launchRun(opts: LaunchOptions): Promise<string>
+  /**
+   * Resume an interactive run from its persisted cursor (after a pause, crash, or fresh process).
+   * Resolves to the resulting status token.
+   */
+  resumeRun(runId: string): Promise<string>
+  /**
+   * Resolve a human-confirm gate on a PAUSED run. `approve=true` proceeds (optionally applying
+   * `amend` to the next unit's instruction); `approve=false` rejects → cancels the run. Resolves
+   * to the resulting status token. Rejects if the run is not paused at a gate.
+   */
+  confirmGate(runId: string, approve: boolean, amend?: string | undefined | null): Promise<string>
+  /**
+   * Cancel a run — mark it terminally `Cancelled` and stop advancing it. Resolves to the status
+   * token. Safe whether the run is executing or paused.
+   */
+  cancelRun(runId: string): Promise<string>
+  /** The agent session ids currently on the store, as a JSON array of strings. */
+  sessions(): Promise<string>
+  /**
+   * Every session + its ordered units, as a JSON array of `{ session, units }` objects (the read
+   * a UI builds its project list from).
+   */
+  sessionsDetail(): Promise<string>
+  /** A unit's captured work output (transcript), as a JSON value — a string, or `null` if none. */
+  workOutput(unitId: string): Promise<string>
+  /**
+   * Register a git repository the orchestrator can run within. Validates it is a git repo with
+   * ≥1 commit; resolves to the persisted `RepoEntry` as a JSON object.
+   */
+  registerRepo(name: string, rootPath: string): Promise<string>
+  /** List every registered repository, as a JSON array of `RepoEntry` objects. */
+  listRepos(): Promise<string>
+  /**
+   * Open a PTY terminal session running `cmd` (or the login shell if omitted) in `cwd`, sized
+   * `cols`x`rows`. `governed=false` is a loud, opt-in UNGOVERNED operator shell that bypasses the
+   * gate-hook (DES §7); pass `true` for the governed default. Resolves the new terminal id. Output
+   * arrives as `terminalOutput` events, so `subscribe()` FIRST to catch `terminalOpened` + bytes.
+   */
+  openTerminal(cwd: string, cmd: Array<string> | undefined | null, cols: number, rows: number, governed: boolean): Promise<string>
+  /**
+   * Write raw input bytes (keystrokes) to a terminal. The `bytes` Buffer is copied to an owned
+   * `Vec<u8>` on the Node thread (a cheap memcpy — keystroke payloads are tiny) so the blocking
+   * write can run off-thread without moving a JS-owned Buffer across threads. Resolves `"ok"`;
+   * rejects if the terminal id is unknown or the write fails.
+   */
+  writeTerminal(id: string, bytes: Buffer): Promise<string>
+  /**
+   * Resize a terminal's PTY to `cols`x`rows`. Resolves `"ok"`; rejects if the terminal id is
+   * unknown or the resize fails.
+   */
+  resizeTerminal(id: string, cols: number, rows: number): Promise<string>
+  /**
+   * Close a terminal: the actor kills the child, joins the reader thread, and drops the registry +
+   * I/O entries (no orphaned process/thread). Resolves `"ok"` once teardown completes; a
+   * `terminalExited` event is emitted. Rejects on an unknown id.
+   */
+  closeTerminal(id: string): Promise<string>
+}
+/**
+ * A live event subscription returned by [`Core::subscribe`]. Owns the FIFO pump thread + its
+ * [`ThreadsafeFunction`]. `close()` / `unsubscribe()` tears both down deterministically (set the
+ * stop flag → join the pump, which drops the event `Receiver` so the actor prunes its sender →
+ * abort the tsfn). Idempotent; dropping the JS handle without an explicit close also stops the pump.
+ */
+export declare class Subscription {
+  /**
+   * Stop delivering events and release the pump thread + `ThreadsafeFunction`. Idempotent and
+   * safe on a normal shutdown path; after it returns the pump is joined and the tsfn aborted, so
+   * the callback will not fire again. This is the teardown that makes re-subscribe leak-free and
+   * lets a plain `main()` return promptly.
+   */
+  close(): void
+  /** Alias for [`Subscription::close`]. */
+  unsubscribe(): void
+}
+
+// ─── hand-authored (not napi-generated): see scripts/finalize-dts.mjs ───
+/**
+ * A CoreEvent, delivered as a JSON string to the {@link Core.subscribe} callback. Discriminated on
+ * `type`. Fields vary by variant (see wicked-core `CoreEvent`): e.g.
+ * `sessionStarted` `{session, problem}`, `unitPlanned` `{session, ord, description}`,
+ * `unitDistributed` `{session, ord, cli}`, `awaitingHuman` `{session, ord, prompt}`,
+ * `gateDecided` `{session, ord, allow}`, `unitDone`/`unitExecuting`/`resumed` `{session, ord}`,
+ * `sessionCompleted` `{session}`, `sessionFailed` `{session, ord}`, `error` `{session, message}`.
+ * PTY terminal sessions emit `terminalOpened` `{id, cwd}`, `terminalOutput` `{id, seq, bytesB64}`
+ * (raw output base64-encoded in `bytesB64`), and `terminalExited` `{id, status}`.
+ */
+export interface CoreEventJson {
+  type: string
+  session?: string
+  ord?: number
+  [k: string]: unknown
+}
+// ─── end hand-authored ───

package/index.js

@@ -0,0 +1,316 @@
+/* tslint:disable */
+/* eslint-disable */
+/* prettier-ignore */
+
+/* auto-generated by NAPI-RS */
+
+const { existsSync, readFileSync } = require('fs')
+const { join } = require('path')
+
+const { platform, arch } = process
+
+let nativeBinding = null
+let localFileExisted = false
+let loadError = null
+
+function isMusl() {
+  // For Node 10
+  if (!process.report || typeof process.report.getReport !== 'function') {
+    try {
+      const lddPath = require('child_process').execSync('which ldd').toString().trim()
+      return readFileSync(lddPath, 'utf8').includes('musl')
+    } catch (e) {
+      return true
+    }
+  } else {
+    const { glibcVersionRuntime } = process.report.getReport().header
+    return !glibcVersionRuntime
+  }
+}
+
+switch (platform) {
+  case 'android':
+    switch (arch) {
+      case 'arm64':
+        localFileExisted = existsSync(join(__dirname, 'wicked-core-ts.android-arm64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./wicked-core-ts.android-arm64.node')
+          } else {
+            nativeBinding = require('wicked-core-ts-android-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm':
+        localFileExisted = existsSync(join(__dirname, 'wicked-core-ts.android-arm-eabi.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./wicked-core-ts.android-arm-eabi.node')
+          } else {
+            nativeBinding = require('wicked-core-ts-android-arm-eabi')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Android ${arch}`)
+    }
+    break
+  case 'win32':
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(
+          join(__dirname, 'wicked-core-ts.win32-x64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./wicked-core-ts.win32-x64-msvc.node')
+          } else {
+            nativeBinding = require('wicked-core-ts-win32-x64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'ia32':
+        localFileExisted = existsSync(
+          join(__dirname, 'wicked-core-ts.win32-ia32-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./wicked-core-ts.win32-ia32-msvc.node')
+          } else {
+            nativeBinding = require('wicked-core-ts-win32-ia32-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'wicked-core-ts.win32-arm64-msvc.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./wicked-core-ts.win32-arm64-msvc.node')
+          } else {
+            nativeBinding = require('wicked-core-ts-win32-arm64-msvc')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Windows: ${arch}`)
+    }
+    break
+  case 'darwin':
+    localFileExisted = existsSync(join(__dirname, 'wicked-core-ts.darwin-universal.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./wicked-core-ts.darwin-universal.node')
+      } else {
+        nativeBinding = require('wicked-core-ts-darwin-universal')
+      }
+      break
+    } catch {}
+    switch (arch) {
+      case 'x64':
+        localFileExisted = existsSync(join(__dirname, 'wicked-core-ts.darwin-x64.node'))
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./wicked-core-ts.darwin-x64.node')
+          } else {
+            nativeBinding = require('wicked-core-ts-darwin-x64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      case 'arm64':
+        localFileExisted = existsSync(
+          join(__dirname, 'wicked-core-ts.darwin-arm64.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./wicked-core-ts.darwin-arm64.node')
+          } else {
+            nativeBinding = require('wicked-core-ts-darwin-arm64')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on macOS: ${arch}`)
+    }
+    break
+  case 'freebsd':
+    if (arch !== 'x64') {
+      throw new Error(`Unsupported architecture on FreeBSD: ${arch}`)
+    }
+    localFileExisted = existsSync(join(__dirname, 'wicked-core-ts.freebsd-x64.node'))
+    try {
+      if (localFileExisted) {
+        nativeBinding = require('./wicked-core-ts.freebsd-x64.node')
+      } else {
+        nativeBinding = require('wicked-core-ts-freebsd-x64')
+      }
+    } catch (e) {
+      loadError = e
+    }
+    break
+  case 'linux':
+    switch (arch) {
+      case 'x64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'wicked-core-ts.linux-x64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./wicked-core-ts.linux-x64-musl.node')
+            } else {
+              nativeBinding = require('wicked-core-ts-linux-x64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'wicked-core-ts.linux-x64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./wicked-core-ts.linux-x64-gnu.node')
+            } else {
+              nativeBinding = require('wicked-core-ts-linux-x64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'wicked-core-ts.linux-arm64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./wicked-core-ts.linux-arm64-musl.node')
+            } else {
+              nativeBinding = require('wicked-core-ts-linux-arm64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'wicked-core-ts.linux-arm64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./wicked-core-ts.linux-arm64-gnu.node')
+            } else {
+              nativeBinding = require('wicked-core-ts-linux-arm64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'arm':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'wicked-core-ts.linux-arm-musleabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./wicked-core-ts.linux-arm-musleabihf.node')
+            } else {
+              nativeBinding = require('wicked-core-ts-linux-arm-musleabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'wicked-core-ts.linux-arm-gnueabihf.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./wicked-core-ts.linux-arm-gnueabihf.node')
+            } else {
+              nativeBinding = require('wicked-core-ts-linux-arm-gnueabihf')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 'riscv64':
+        if (isMusl()) {
+          localFileExisted = existsSync(
+            join(__dirname, 'wicked-core-ts.linux-riscv64-musl.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./wicked-core-ts.linux-riscv64-musl.node')
+            } else {
+              nativeBinding = require('wicked-core-ts-linux-riscv64-musl')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        } else {
+          localFileExisted = existsSync(
+            join(__dirname, 'wicked-core-ts.linux-riscv64-gnu.node')
+          )
+          try {
+            if (localFileExisted) {
+              nativeBinding = require('./wicked-core-ts.linux-riscv64-gnu.node')
+            } else {
+              nativeBinding = require('wicked-core-ts-linux-riscv64-gnu')
+            }
+          } catch (e) {
+            loadError = e
+          }
+        }
+        break
+      case 's390x':
+        localFileExisted = existsSync(
+          join(__dirname, 'wicked-core-ts.linux-s390x-gnu.node')
+        )
+        try {
+          if (localFileExisted) {
+            nativeBinding = require('./wicked-core-ts.linux-s390x-gnu.node')
+          } else {
+            nativeBinding = require('wicked-core-ts-linux-s390x-gnu')
+          }
+        } catch (e) {
+          loadError = e
+        }
+        break
+      default:
+        throw new Error(`Unsupported architecture on Linux: ${arch}`)
+    }
+    break
+  default:
+    throw new Error(`Unsupported OS: ${platform}, architecture: ${arch}`)
+}
+
+if (!nativeBinding) {
+  if (loadError) {
+    throw loadError
+  }
+  throw new Error(`Failed to load native binding`)
+}
+
+const { Core, Subscription } = nativeBinding
+
+module.exports.Core = Core
+module.exports.Subscription = Subscription

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "wicked-core-ts",
+  "version": "0.1.0",
+  "description": "Node/TypeScript bindings (napi-rs) for wicked-core: drive the in-process orchestration engine from JS/TS.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mikeparcewski/wicked-core.git"
+  },
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "index.d.ts"
+  ],
+  "napi": {
+    "name": "wicked-core-ts",
+    "package": {
+      "name": "wicked-core-ts"
+    },
+    "triples": {
+      "defaults": false,
+      "additional": [
+        "x86_64-apple-darwin",
+        "aarch64-apple-darwin",
+        "x86_64-unknown-linux-gnu",
+        "aarch64-unknown-linux-gnu",
+        "x86_64-pc-windows-msvc"
+      ]
+    }
+  },
+  "engines": {
+    "node": ">= 20"
+  },
+  "scripts": {
+    "build": "napi build --platform --release && node scripts/finalize-dts.mjs",
+    "build:debug": "napi build --platform && node scripts/finalize-dts.mjs",
+    "smoke": "node smoke.mjs",
+    "smoke:lifecycle": "node smoke-lifecycle.mjs",
+    "smoke:terminal": "node smoke-terminal.mjs",
+    "smoke:all": "node smoke.mjs && node smoke-lifecycle.mjs && node smoke-terminal.mjs"
+  },
+  "optionalDependencies": {
+    "wicked-core-ts-darwin-arm64": "0.1.0",
+    "wicked-core-ts-darwin-x64": "0.1.0",
+    "wicked-core-ts-linux-arm64-gnu": "0.1.0",
+    "wicked-core-ts-linux-x64-gnu": "0.1.0",
+    "wicked-core-ts-win32-x64-msvc": "0.1.0"
+  },
+  "devDependencies": {
+    "@napi-rs/cli": "^2.18.4"
+  }
+}