tulingcode 0.1.0

package/src/workflow/sandbox.ts

@@ -0,0 +1,280 @@
+import {
+  getQuickJS,
+  shouldInterruptAfterDeadline,
+  type QuickJSContext,
+  type QuickJSDeferredPromise,
+  type QuickJSHandle,
+} from "quickjs-emscripten"
+
+/** An injected host function: receives already-marshaled JS args, returns a JS value or Promise. */
+export type HostFn = (...args: unknown[]) => unknown | Promise<unknown>
+
+export type SandboxOptions = {
+  /** Wall-clock budget for the whole script; default 12h. */
+  deadlineMs?: number
+  /** Memory cap in bytes; default 64 MiB. */
+  memoryLimitBytes?: number
+  /** JSON value injected into the guest as the global `args`. */
+  args?: unknown
+  /** Seed for the in-guest Math.random PRNG. Same seed ⇒ identical sequence
+   * (required for resume replay). Different seeds ⇒ different sequences (so
+   * sampling-style scripts get fresh coverage across unrelated runs). The
+   * runtime passes a hash of runID so resume gets the same seed naturally;
+   * tests / one-off callers that don't care can omit this. */
+  seed?: number
+}
+
+const DEFAULT_DEADLINE_MS = 12 * 60 * 60 * 1000
+const DEFAULT_MEMORY = 64 * 1024 * 1024
+/** Fallback seed when no caller-supplied seed is set. Stable so the existing
+ * single-shot tests stay deterministic. The runtime always passes seed=hash(runID)
+ * so production paths never see this default. */
+const DEFAULT_PRNG_SEED = 0x9e3779b9
+
+// Pure-guest helpers. parallel/pipeline do NO throttling — concurrency is
+// enforced by the host semaphore inside the agent() hook. They also do NOT
+// catch: a throwing thunk/stage rejects the batch (fails loud with the guest
+// stack). agent() is never-throw for agent failures (returns null), so the
+// only throws reaching here are script-logic errors, which SHOULD fail loud
+// rather than become silent nulls that poison downstream .map/.filter.
+const PRELUDE = `
+globalThis.parallel = (thunks) =>
+  Promise.all(thunks.map((t) => Promise.resolve().then(t)));
+globalThis.pipeline = (items, ...stages) =>
+  Promise.all(items.map((item, index) =>
+    stages.reduce((acc, stage) => acc.then((prev) => stage(prev, item, index)), Promise.resolve(item))));
+// Minimal, deterministic URL for dedup/host-extraction in workflow scripts.
+// The bare QuickJS guest has no Web URL. Covers protocol/hostname/pathname/
+// search/hash — enough for normURL-style dedup — and THROWS on inputs without
+// a scheme+host, so scripts' try/catch fallbacks behave like the real URL.
+globalThis.URL = class URL {
+  constructor(input) {
+    const str = String(input);
+    const m = /^([a-zA-Z][a-zA-Z0-9+.-]*:)\\/\\/([^/?#]*)([^?#]*)(\\?[^#]*)?(#.*)?$/.exec(str);
+    if (!m) throw new TypeError("Invalid URL: " + str);
+    this.protocol = m[1].toLowerCase();
+    this.hostname = m[2];
+    this.pathname = m[3] || "/";
+    this.search = m[4] || "";
+    this.hash = m[5] || "";
+    this.host = m[2];
+  }
+  toString() { return this.protocol + "//" + this.host + this.pathname + this.search + this.hash; }
+};
+`
+
+/**
+ * Run a workflow script body inside an isolated quickjs-emscripten context.
+ * Pure Promise boundary — knows nothing of Effect or actors. `hooks` are host
+ * functions injected as guest globals. Returns the script's resolved value
+ * (dumped out of the guest by value).
+ *
+ * Hard constraints encapsulated here (validated by the 2026-06-01 spike):
+ *  - sync-promise bridge (newPromise + executePendingJobs), NOT asyncify
+ *  - a concurrent pump alongside resolvePromise so host-promises settle
+ *  - every QuickJSHandle disposed before context dispose (else process abort)
+ */
+export async function evalScript(body: string, hooks: Record<string, HostFn>, opts: SandboxOptions = {}): Promise<unknown> {
+  const QuickJS = await getQuickJS()
+  const rt = QuickJS.newRuntime()
+  rt.setMemoryLimit(opts.memoryLimitBytes ?? DEFAULT_MEMORY)
+  rt.setInterruptHandler(shouldInterruptAfterDeadline(Date.now() + (opts.deadlineMs ?? DEFAULT_DEADLINE_MS)))
+  const vm = rt.newContext()
+
+  // Arena: every handle we create goes here and is disposed in `finally`.
+  const arena: QuickJSHandle[] = []
+  // Deferreds for async hooks: tracked so an UNSETTLED one (script returned
+  // while a host-promise is still in flight) is still disposed before context
+  // dispose — otherwise vm.dispose() hard-aborts on the live GC object.
+  const deferreds: QuickJSDeferredPromise[] = []
+  const track = <H extends QuickJSHandle>(h: H): H => {
+    arena.push(h)
+    return h
+  }
+
+  try {
+    injectHooks(vm, hooks, track, deferreds)
+    // Determinism: the guest is a bare quickjs-emscripten JS engine — no Web/Node
+    // APIs exist (no crypto/performance/fetch/timers/process/Temporal/gc; all
+    // already undefined). We neutralize the JS built-ins whose output or timing is
+    // nondeterministic so resume replay stays sound:
+    //   - Date — deleted (nondeterministic wall-clock; scripts must not depend on it).
+    //   - Math.random — REPLACED with a SEEDED PRNG keyed on the run's seed (the
+    //     runtime passes a hash of runID, so a resume of the SAME run gets the SAME
+    //     sequence — the replay-correctness invariant — and two UNRELATED runs of
+    //     the same script get DIFFERENT sequences — so sampling-style scripts
+    //     (e.g. lifetime-classify's verification sample) get fresh coverage across
+    //     runs instead of repeating the same picks. The fallback DEFAULT_PRNG_SEED
+    //     is only used by tests/one-off callers that don't pass a seed.
+    //   - WeakRef / FinalizationRegistry — deleted (expose GC liveness/callback
+    //     scheduling, which differs across runs and would silently diverge on replay).
+    const seed = (opts.seed ?? DEFAULT_PRNG_SEED) >>> 0
+    const strip = vm.evalCode(`
+      delete globalThis.Date;
+      (function () {
+        // mulberry32 — tiny seeded PRNG; deterministic for a given seed.
+        let s = ${seed} >>> 0;
+        Math.random = function () {
+          s = (s + 0x6d2b79f5) >>> 0;
+          let t = s;
+          t = Math.imul(t ^ (t >>> 15), t | 1);
+          t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+          return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+        };
+      })();
+      delete globalThis.WeakRef;
+      delete globalThis.FinalizationRegistry;
+    `)
+    if (strip.error) {
+      strip.error.dispose()
+    } else {
+      strip.value.dispose()
+    }
+    const pre = vm.evalCode(PRELUDE)
+    if (pre.error) {
+      const err = vm.dump(pre.error)
+      pre.error.dispose()
+      throw new Error(`workflow prelude error: ${typeof err === "string" ? err : JSON.stringify(err)}`)
+    }
+    pre.value.dispose()
+    // Inject args as a guest global (by value).
+    const argsHandle = marshalIn(vm, opts.args ?? null)
+    vm.setProp(vm.global, "args", argsHandle)
+    argsHandle.dispose()
+    const wrapped = `(async () => {\n${body}\n})()`
+    const evalRes = vm.evalCode(wrapped)
+    if (evalRes.error) {
+      const err = vm.dump(evalRes.error)
+      evalRes.error.dispose()
+      throw new Error(`workflow script error: ${typeof err === "string" ? err : JSON.stringify(err)}`)
+    }
+    const promiseHandle = track(evalRes.value)
+    // Concurrent pump: a BACKSTOP that drains guest microtasks while we await
+    // the guest promise. NOTE: agent() results do NOT depend on this loop's
+    // latency — injectHooks already calls executePendingJobs() synchronously the
+    // moment a host promise settles (resolve/reject/settled below). This pump
+    // only catches guest-INTERNAL pending jobs (e.g. a parallel() Promise.all
+    // advancing between host settles).
+    //
+    // Adaptive cadence to avoid idle CPU churn: a guest parked for minutes on a
+    // slow agent() has no pending jobs, so a fixed 1ms interval would burn 1000
+    // wakeups/sec for nothing. Instead we self-reschedule: stay FAST right after
+    // finding work, and back off to SLOW once the guest has been idle for a
+    // window. idleTicks resets to 0 whenever work is found, so a busy guest
+    // stays at FAST_MS the whole time; a truly-parked guest decays to SLOW_MS.
+    // This NEVER stops polling, so it cannot deadlock — worst case it adds
+    // <=SLOW_MS latency to a guest-internal chain that wakes during an idle gap.
+    const FAST_MS = 1
+    const SLOW_MS = 50
+    const FAST_WINDOW = 50
+    let pumpTimer: ReturnType<typeof setTimeout> | undefined
+    let idleTicks = 0
+    const pumpOnce = () => {
+      if (rt.hasPendingJob()) {
+        rt.executePendingJobs()
+        idleTicks = 0
+      } else {
+        idleTicks++
+      }
+      pumpTimer = setTimeout(pumpOnce, idleTicks < FAST_WINDOW ? FAST_MS : SLOW_MS)
+    }
+    pumpTimer = setTimeout(pumpOnce, FAST_MS)
+    // Host-side wall-clock deadline. The runtime interrupt handler above only
+    // fires while the guest is executing bytecode, so it kills runaway
+    // *synchronous* guest code (e.g. `while(true){}`) — but NOT a guest parked
+    // on a pending host promise (a hanging agent() resolves to a host Promise
+    // that never settles, leaving the runtime with no pending jobs to interrupt).
+    // This timer is the true kill-switch for that case: it races resolvePromise
+    // and rejects when the budget elapses. The `finally` below still disposes the
+    // unsettled deferred before the context, so no process abort on cleanup.
+    let deadlineTimer: ReturnType<typeof setTimeout> | undefined
+    const deadline = new Promise<never>((_, reject) => {
+      deadlineTimer = setTimeout(
+        () => reject(new Error("workflow script deadline exceeded")),
+        opts.deadlineMs ?? DEFAULT_DEADLINE_MS,
+      )
+    })
+    try {
+      const resolved = await Promise.race([vm.resolvePromise(promiseHandle), deadline])
+      if (resolved.error) {
+        const err = vm.dump(resolved.error)
+        resolved.error.dispose()
+        throw new Error(`workflow script rejected: ${typeof err === "string" ? err : JSON.stringify(err)}`)
+      }
+      const valueHandle = track(resolved.value)
+      return vm.dump(valueHandle)
+    } finally {
+      clearTimeout(pumpTimer)
+      clearTimeout(deadlineTimer)
+    }
+  } finally {
+    // Dispose deferreds BEFORE the arena/context: an unsettled deferred still
+    // owns live guest handles, and vm.dispose() aborts the process if any
+    // GC object is still alive. Disposing a settled deferred is a no-op.
+    for (const d of deferreds) {
+      if (d.alive) d.dispose()
+    }
+    for (const h of arena) {
+      if (h.alive) h.dispose()
+    }
+    vm.dispose()
+    rt.dispose()
+  }
+}
+
+function injectHooks(
+  vm: QuickJSContext,
+  hooks: Record<string, HostFn>,
+  track: <H extends QuickJSHandle>(h: H) => H,
+  deferreds: QuickJSDeferredPromise[],
+): void {
+  for (const [name, fn] of Object.entries(hooks)) {
+    const fnHandle = vm.newFunction(name, (...argHandles) => {
+      const args = argHandles.map((h) => vm.dump(h))
+      const out = fn(...args)
+      if (out instanceof Promise) {
+        const promise = vm.newPromise()
+        deferreds.push(promise)
+        out.then(
+          (value) => {
+            // A late settle may arrive after the context is disposed (script
+            // returned without awaiting). Bail before touching a dead context.
+            if (!vm.alive) return
+            const vh = marshalIn(vm, value)
+            promise.resolve(vh)
+            vh.dispose()
+            vm.runtime.executePendingJobs()
+          },
+          (err) => {
+            if (!vm.alive) return
+            const eh = vm.newString(err instanceof Error ? err.message : String(err))
+            promise.reject(eh)
+            eh.dispose()
+            vm.runtime.executePendingJobs()
+          },
+        )
+        promise.settled.then(() => {
+          if (vm.alive) vm.runtime.executePendingJobs()
+        })
+        return promise.handle
+      }
+      return marshalIn(vm, out)
+    })
+    vm.setProp(vm.global, name, track(fnHandle))
+  }
+}
+
+/** Marshal a host JS value INTO the guest (by copy via JSON for structured data). */
+function marshalIn(vm: QuickJSContext, value: unknown): QuickJSHandle {
+  if (value === undefined || value === null) return vm.undefined
+  if (typeof value === "string") return vm.newString(value)
+  if (typeof value === "number") return vm.newNumber(value)
+  if (typeof value === "boolean") return value ? vm.true : vm.false
+  const json = vm.newString(JSON.stringify(value))
+  const parseRes = vm.evalCode("JSON.parse")
+  const parseFn = vm.unwrapResult(parseRes)
+  const out = vm.callFunction(parseFn, vm.undefined, json)
+  json.dispose()
+  parseFn.dispose()
+  return vm.unwrapResult(out)
+}

package/src/workflow/workflow.sql.ts

@@ -0,0 +1,31 @@
+import { sqliteTable, text, integer, index } from "drizzle-orm/sqlite-core"
+import { SessionTable } from "../session/session.sql"
+import type { SessionID } from "../session/schema"
+import { Timestamps } from "../storage/schema.sql"
+
+export const WorkflowRunTable = sqliteTable(
+  "workflow_run",
+  {
+    id: text().primaryKey(),
+    session_id: text()
+      .$type<SessionID>()
+      .notNull()
+      .references(() => SessionTable.id, { onDelete: "cascade" }),
+    name: text().notNull(),
+    status: text().$type<"running" | "completed" | "failed" | "cancelled">().notNull(),
+    running: integer().notNull().default(0),
+    succeeded: integer().notNull().default(0),
+    failed: integer().notNull().default(0),
+    current_phase: text(),
+    parent_actor_id: text(),
+    args: text({ mode: "json" }),
+    script_sha: text(),
+    agent_timeout_ms: integer(),
+    error: text(),
+    ...Timestamps,
+  },
+  (table) => [
+    index("workflow_run_session_idx").on(table.session_id),
+    index("workflow_run_status_idx").on(table.status),
+  ],
+)

package/src/workflow/workspace.ts

@@ -0,0 +1,69 @@
+import path from "path"
+import { Filesystem } from "@/util"
+import { Glob } from "@tuling-ai/shared/util/glob"
+
+// Resolve a guest-supplied relative path against the workspace root, refusing
+// any path that escapes the root by LEXICAL means (parent traversal `..`, or an
+// escaping-absolute path). The jail is the sandbox boundary for the orchestrator
+// script's own file IO — distinct from the file-tool boundary of the agents it
+// spawns (which have the same lexical posture, so this grants no new reach).
+//
+// LIMITATION (by design, experimental): the check is NAME-based, not realpath —
+// `Filesystem.contains` is purely lexical and does NOT resolve symlinks. A
+// pre-existing symlink INSIDE the workspace that points OUTSIDE it (e.g. a pnpm
+// store link under node_modules) is therefore NOT caught: a path through it
+// resolves to an in-root lexical string, passes this check, and the underlying
+// fs op follows the link out of the jail. Hardening to a true boundary means
+// realpath-ing the resolved path (and, for writeFile, the leaf's parent) before
+// the contains check — deferred until the feature graduates off the flag.
+export function resolveInWorkspace(root: string, rel: string): string {
+  const abs = path.resolve(root, rel)
+  if (abs !== root && !Filesystem.contains(root, abs)) {
+    throw new Error(`workspace path escapes the workspace root: ${JSON.stringify(rel)}`)
+  }
+  return abs
+}
+
+// Build the workspace-jailed file host fns for a given root. readFile returns
+// null for a missing file (a branchable condition) but throws on a jail escape
+// (a bug). writeFile auto-creates parent dirs (Filesystem.write mkdir-on-ENOENT).
+export function makeFileHooks(root: string) {
+  return {
+    async readFile(rel: unknown): Promise<string | null> {
+      const abs = resolveInWorkspace(root, String(rel))
+      if (!(await Filesystem.exists(abs))) return null
+      return Filesystem.readText(abs)
+    },
+    async writeFile(rel: unknown, content: unknown): Promise<void> {
+      const abs = resolveInWorkspace(root, String(rel))
+      await Filesystem.write(abs, String(content))
+    },
+    async exists(rel: unknown): Promise<boolean> {
+      const abs = resolveInWorkspace(root, String(rel))
+      return Filesystem.exists(abs)
+    },
+    async glob(pattern: unknown): Promise<string[]> {
+      // Determinism: fan-out order derives from this list and the journal's
+      // occurrence index keys on call order, so the result MUST be stable —
+      // sort lexicographically. Returns paths relative to the workspace root
+      // (the guest never sees absolute host paths). include "all" → files + dirs
+      // (sub-project units like crates are dirs). dot:true matches existing callers.
+      const abs = await Glob.scan(String(pattern), {
+        cwd: root,
+        absolute: true,
+        include: "all",
+        dot: true,
+      })
+      // Jail: Glob.scan's `cwd` does NOT confine matches — a guest pattern with `..`
+      // or an absolute path escapes the workspace. The other file fns re-jail via
+      // resolveInWorkspace; glob must filter its RESULTS. A match outside root maps to
+      // a relative path starting with `..` (or an absolute path on some inputs), so
+      // drop those. Empty-string (the root itself) is also dropped. Then sort for
+      // deterministic fan-out order.
+      return abs
+        .map((p) => path.relative(root, p))
+        .filter((rel) => rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel))
+        .sort()
+    },
+  }
+}