@toist/aja 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to `@toist/aja` are recorded here.
 
+## Unreleased
+
+## 0.6.1 — 2026-05-05
+
+Fix published @toist/aja dependency resolution for embedded runners and include the typed runner client/smoke-test surface.
+
+- Added `createRunnerClient()` typed HTTP adapter, exported from
+  `@toist/aja` and `@toist/aja/client`, for driving runner instances
+  without hard-coding API paths.
+- Added `smoke:client` script that starts an embedded runner, drives it via
+  the client, and verifies persisted node outputs.
+- Changed published package dependencies on `@toist/spec` and `@toist/ui`
+  from workspace protocol to concrete `0.6.1` versions so external embeds
+  install transitive runtime packages correctly.
+- Documented the v1 embedded-instance limit: one runner per process.
+
 ## 0.6.0 — 2026-05-05
 
 Lockstep version bump alongside `@toist/in@0.6.0`. No functional changes

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@toist/aja",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./client": "./src/client.ts"
   },
   "files": [
     "src/",
@@ -13,11 +14,12 @@
     "CHANGELOG.md"
   ],
   "scripts": {
-    "dev": "bun --watch src/server.ts"
+    "dev": "bun --watch src/server.ts",
+    "smoke:client": "bun test/client-smoke.ts"
   },
   "dependencies": {
-    "@toist/spec": "0.6.0",
-    "@toist/ui": "0.6.0",
+    "@toist/spec": "0.6.1",
+    "@toist/ui": "0.6.1",
     "hono": "^4.7.7",
     "proper-lockfile": "^4.1.2"
   },

package/src/client.ts

@@ -0,0 +1,305 @@
+// 2121
+// Typed HTTP client for a running @toist/aja instance.
+//
+// This is the public de-facto adapter for hosts (Pi, tests, external tools)
+// that want to drive the runner over its HTTP API without hard-coding paths.
+
+import type { NodeKindManifest, ValidateResult } from "@toist/spec"
+
+export interface RunnerClientOptions {
+  /** Runner API base URL. Accepts either the API root
+   *  (`http://localhost:2132/api`) or the runner root
+   *  (`http://localhost:2132`); the client normalizes to `/api`. */
+  baseUrl: string
+  /** Optional fetch implementation for tests or non-Bun runtimes. */
+  fetch?: typeof fetch
+  /** Extra headers sent with every request (e.g. auth). */
+  headers?: HeadersInit
+}
+
+export class RunnerHttpError extends Error {
+  constructor(
+    public readonly status: number,
+    public readonly statusText: string,
+    public readonly body: unknown,
+  ) {
+    super(`Runner HTTP ${status} ${statusText}`)
+    this.name = "RunnerHttpError"
+  }
+}
+
+export interface PipelineSummary {
+  id: string
+  label: string
+  description?: string
+  nodeCount: number
+}
+
+export interface PipelineSource {
+  id: string
+  yaml: string
+}
+
+export interface PipelineSaveResult {
+  id?: string
+  ok?: boolean
+  errors?: string[]
+  error?: string
+  [key: string]: unknown
+}
+
+export interface StepResult {
+  id: string
+  kind: string
+  label: string
+  status: "complete" | "failed"
+  params?: Record<string, unknown>
+  input?: Record<string, unknown>
+  output?: unknown
+  error?: string
+  duration_ms: number
+}
+
+export interface PipelineTaskRef {
+  id: number
+  kind: string
+  prompt: string
+  schema: unknown
+  assignee: string | null
+  responseToken: string
+}
+
+export type PipelineRunResponse =
+  | { id: number; pipeline: string; status: "done"; result: unknown; steps: StepResult[] }
+  | { id: number; pipeline: string; status: "suspended"; suspendedAt: string; task: PipelineTaskRef; steps: StepResult[] }
+  | { id: number; pipeline: string; status: "error"; error: string }
+
+export interface RunListItem {
+  id: number
+  pipeline: string
+  status: string
+  payload: string | null
+  result: string | null
+  steps: string | null
+  error: string | null
+  started_at: string
+  finished_at?: string | null
+  current_node?: string | null
+  updated_at?: string | null
+  trigger?: string
+}
+
+export interface RunNodeOutput {
+  nodeId: string
+  output: unknown
+  startedAt: string
+  finishedAt: string
+}
+
+export interface RunLogLine {
+  id: number
+  ts: string
+  level: "info" | "warn" | "error" | string
+  msg: string | null
+}
+
+export interface TaskListItem {
+  id: number
+  run_id: number
+  node_id: string
+  kind: string
+  prompt: string | null
+  assignee: string | null
+  status: "open" | "answered" | "expired" | "cancelled"
+  created_at: string
+  responded_at: string | null
+  pipeline: string | null
+}
+
+export interface TaskFull {
+  id: number
+  runId: number
+  pipeline: string | null
+  nodeId: string
+  kind: string
+  prompt: string
+  schema: unknown
+  assignee: string | null
+  responseToken: string
+  status: "open" | "answered" | "expired" | "cancelled"
+}
+
+export interface ResourceTypeSummary {
+  name: string
+  description?: string
+  schema: Record<string, unknown>
+}
+
+export interface ResourceRecord {
+  id: number
+  name: string
+  type: string
+  fields: Record<string, unknown>
+  created_at: string
+  updated_at: string
+}
+
+export interface RunnerClient {
+  instance: {
+    root(): Promise<unknown>
+    get(): Promise<unknown>
+  }
+  kinds: {
+    list(): Promise<{ kinds: NodeKindManifest[] }>
+    invoke(id: string, body?: { params?: Record<string, unknown>; input?: Record<string, unknown>; confirm?: boolean }): Promise<unknown>
+  }
+  pipelines: {
+    list(): Promise<PipelineSummary[]>
+    get(id: string): Promise<unknown>
+    source(id: string): Promise<PipelineSource>
+    validate(input: { yaml: string } | { spec: unknown }): Promise<ValidateResult>
+    create(yaml: string): Promise<PipelineSaveResult>
+    update(id: string, yaml: string): Promise<PipelineSaveResult>
+    run(id: string, payload?: Record<string, unknown>): Promise<PipelineRunResponse>
+  }
+  runs: {
+    list(opts?: { pipeline?: string; limit?: number }): Promise<RunListItem[]>
+    get(id: number): Promise<RunListItem>
+    nodes(id: number): Promise<RunNodeOutput[]>
+    logs(id: number): Promise<RunLogLine[]>
+  }
+  tasks: {
+    list(opts?: { status?: string; runId?: number; assignee?: string; limit?: number }): Promise<TaskListItem[]>
+    get(id: number): Promise<TaskFull>
+    respond(runId: number, taskId: number, body: { token: string; response: unknown; respondedBy?: string }): Promise<PipelineRunResponse>
+  }
+  resources: {
+    types(): Promise<ResourceTypeSummary[]>
+    list(): Promise<ResourceRecord[]>
+    get(name: string): Promise<ResourceRecord>
+    upsert(name: string, type: string, fields: Record<string, unknown>): Promise<ResourceRecord>
+    put(name: string, body: { type?: string; fields?: Record<string, unknown> }): Promise<ResourceRecord>
+    delete(name: string): Promise<void>
+  }
+}
+
+export function createRunnerClient(options: RunnerClientOptions): RunnerClient {
+  const base = normalizeBaseUrl(options.baseUrl)
+  const f = options.fetch ?? fetch
+
+  async function request<T>(path: string, init: RequestInit = {}, opts: { allowErrorJson?: boolean } = {}): Promise<T> {
+    const headers = new Headers(options.headers)
+    if (init.body !== undefined && !headers.has("Content-Type")) headers.set("Content-Type", "application/json")
+    if (init.headers) new Headers(init.headers).forEach((v, k) => headers.set(k, v))
+
+    const r = await f(`${base}${path}`, { ...init, headers })
+    const body = await readJsonOrText(r)
+    if (!r.ok && !opts.allowErrorJson) throw new RunnerHttpError(r.status, r.statusText, body)
+    return body as T
+  }
+
+  const json = (value: unknown) => JSON.stringify(value ?? {})
+
+  return {
+    instance: {
+      root: () => request<unknown>("/"),
+      get:  () => request<unknown>("/instance"),
+    },
+
+    kinds: {
+      list:   () => request<{ kinds: NodeKindManifest[] }>("/manifest"),
+      invoke: (id, body = {}) => request<unknown>(`/kinds/${enc(id)}/invoke`, {
+        method: "POST",
+        body: json(body),
+      }),
+    },
+
+    pipelines: {
+      list:   () => request<PipelineSummary[]>("/pipelines"),
+      get:    (id) => request<unknown>(`/pipelines/${enc(id)}`),
+      source: (id) => request<PipelineSource>(`/pipelines/${enc(id)}/source`),
+      validate: (input) => request<ValidateResult>("/pipelines/validate", {
+        method: "POST",
+        body: json(input),
+      }, { allowErrorJson: true }),
+      create: (yaml) => request<PipelineSaveResult>("/pipelines", {
+        method: "POST",
+        body: json({ yaml }),
+      }),
+      update: (id, yaml) => request<PipelineSaveResult>(`/pipelines/${enc(id)}`, {
+        method: "PUT",
+        body: json({ yaml }),
+      }),
+      run: (id, payload = {}) => request<PipelineRunResponse>(`/pipelines/${enc(id)}/run`, {
+        method: "POST",
+        body: json(payload),
+      }),
+    },
+
+    runs: {
+      list: (opts = {}) => request<RunListItem[]>(`/runs${query({ pipeline: opts.pipeline, limit: opts.limit })}`),
+      get:   (id) => request<RunListItem>(`/runs/${id}`),
+      nodes: (id) => request<RunNodeOutput[]>(`/runs/${id}/nodes`),
+      logs:  (id) => request<RunLogLine[]>(`/runs/${id}/logs`),
+    },
+
+    tasks: {
+      list: (opts = {}) => request<TaskListItem[]>(`/tasks${query({
+        status: opts.status,
+        run_id: opts.runId,
+        assignee: opts.assignee,
+        limit: opts.limit,
+      })}`),
+      get: (id) => request<TaskFull>(`/tasks/${id}`),
+      respond: (runId, taskId, body) => request<PipelineRunResponse>(`/runs/${runId}/tasks/${taskId}/respond`, {
+        method: "POST",
+        body: json(body),
+      }),
+    },
+
+    resources: {
+      types: () => request<ResourceTypeSummary[]>("/resource-types"),
+      list:  () => request<ResourceRecord[]>("/resources"),
+      get:   (name) => request<ResourceRecord>(`/resources/${enc(name)}`),
+      upsert: (name, type, fields) => request<ResourceRecord>("/resources", {
+        method: "POST",
+        body: json({ name, type, fields }),
+      }),
+      put: (name, body) => request<ResourceRecord>(`/resources/${enc(name)}`, {
+        method: "PUT",
+        body: json(body),
+      }),
+      delete: async (name) => {
+        await request<unknown>(`/resources/${enc(name)}`, { method: "DELETE" })
+      },
+    },
+  }
+}
+
+function normalizeBaseUrl(input: string): string {
+  const trimmed = input.replace(/\/+$/, "")
+  return trimmed.endsWith("/api") ? trimmed : `${trimmed}/api`
+}
+
+function enc(value: string): string {
+  return encodeURIComponent(value)
+}
+
+function query(values: Record<string, string | number | undefined>): string {
+  const q = new URLSearchParams()
+  for (const [k, v] of Object.entries(values)) {
+    if (v !== undefined) q.set(k, String(v))
+  }
+  const s = q.toString()
+  return s ? `?${s}` : ""
+}
+
+async function readJsonOrText(response: Response): Promise<unknown> {
+  if (response.status === 204) return null
+  const text = await response.text()
+  if (!text) return null
+  const ct = response.headers.get("content-type") ?? ""
+  if (ct.includes("application/json")) return JSON.parse(text)
+  try { return JSON.parse(text) }
+  catch { return text }
+}

package/src/index.ts

@@ -10,6 +10,27 @@
 // Lifecycle entry — what hosts call to start an instance.
 export { startRunner, type StartRunnerOptions, type RunnerHandle } from "./startRunner.ts"
 
+// Typed HTTP client — what external hosts/tools use to drive an instance.
+export {
+  createRunnerClient,
+  RunnerHttpError,
+  type RunnerClient,
+  type RunnerClientOptions,
+  type PipelineSummary,
+  type PipelineSource,
+  type PipelineSaveResult,
+  type StepResult,
+  type PipelineTaskRef,
+  type PipelineRunResponse,
+  type RunListItem,
+  type RunNodeOutput,
+  type RunLogLine,
+  type TaskListItem,
+  type TaskFull,
+  type ResourceTypeSummary,
+  type ResourceRecord,
+} from "./client.ts"
+
 // Kind registration — must be called before startRunner.
 export { register, getKind, manifest } from "./kinds/index.ts"
 

package/src/pipeline.ts

@@ -305,6 +305,10 @@ export async function runPipeline(
     if (o.result.kind === "complete") {
       results[winner.id] = o.result.output
       done.add(winner.id)
+      // Persist every completed node output, not only pre-suspend checkpoints.
+      // This keeps /runs/:id/nodes and runs.nodeOutput useful for normal done
+      // runs, while preserving the same resume-skip storage semantics.
+      persistNodeOutputs(runtimeDb(), baseCtx.runId, { [winner.id]: o.result.output })
       steps.push({
         id: winner.id, kind: node.kind, label, status: "complete",
         params: o.params, input: o.input, output: o.result.output,

package/src/server.ts

@@ -351,7 +351,7 @@ apiApp.get("/tasks", (c) => {
   const limit    = Number(c.req.query("limit") ?? 200)
 
   const where: string[] = []
-  const args: unknown[] = []
+  const args: Array<string | number> = []
   if (status !== "all") { where.push("t.status = ?");   args.push(status) }
   if (assignee)         { where.push("t.assignee = ?"); args.push(assignee) }
   if (runId)            { where.push("t.run_id = ?");   args.push(Number(runId)) }
@@ -464,6 +464,19 @@ apiApp.get("/runs/:id", (c) => {
   return c.json(row)
 })
 
+apiApp.get("/runs/:id/nodes", (c) => {
+  const runId = Number(c.req.param("id"))
+  const rows = runtimeDb().prepare(
+    "SELECT node_id, output_json, started_at, finished_at FROM node_outputs WHERE run_id = ? ORDER BY started_at ASC",
+  ).all(runId) as Array<{ node_id: string; output_json: string | null; started_at: string; finished_at: string }>
+  return c.json(rows.map((r) => ({
+    nodeId: r.node_id,
+    output: r.output_json != null ? JSON.parse(r.output_json) as unknown : null,
+    startedAt: r.started_at,
+    finishedAt: r.finished_at,
+  })))
+})
+
 apiApp.get("/runs/:id/logs", (c) => {
   const runId = Number(c.req.param("id"))
   const rows = runtimeDb().prepare(
@@ -473,7 +486,8 @@ apiApp.get("/runs/:id/logs", (c) => {
 })
 
 // ─── lifecycle ───────────────────────────────────────────────────────────────
-setInterval(() => cache.prune(), 5 * 60 * 1000)
+const cachePruneTimer = setInterval(() => cache.prune(), 5 * 60 * 1000)
+cachePruneTimer.unref?.()
 
 const PORT = Number(process.env.PORT ?? 2132)
 

package/src/startRunner.ts

@@ -61,6 +61,10 @@ export interface RunnerHandle {
 }
 
 export async function startRunner(options: StartRunnerOptions): Promise<RunnerHandle> {
+  // v1 embedded limit: one runner per process. config/db/registry/server
+  // modules keep process-global state; hosts that need multiple isolated
+  // runners should spawn separate processes until createRunnerInstance-style
+  // state encapsulation lands.
   setRootDir(options.rootDir)
   setDisableUi(options.disableUi ?? false)
   setDisableWatch(options.disableWatch ?? false)
@@ -74,11 +78,12 @@ export async function startRunner(options: StartRunnerOptions): Promise<RunnerHa
   const mod = await import("./server.ts")
   const fetch = mod.fetch as (req: Request) => Response | Promise<Response>
 
-  const server: Server = Bun.serve({ port: options.port, fetch })
-  console.log(`[runner] http://localhost:${server.port}`)
+  const server: Server<undefined> = Bun.serve({ port: options.port, fetch })
+  const port = server.port ?? options.port
+  console.log(`[runner] http://localhost:${port}`)
 
   return {
-    port: server.port,
+    port,
     async stop() {
       server.stop()
       await closeDbs()