nah-studio 0.0.1-beta.1

package/dist/launcher.d.ts

@@ -0,0 +1,67 @@
+import { spawn } from 'node:child_process';
+import { StudioStore } from './store.js';
+import { Agent } from './wire.js';
+export type Launcher = {
+    /** The thing being spawned: a `nah` binary, or this process's own node. */
+    command: string;
+    /** Arguments that always come first, e.g. the script path when running under node. */
+    prefixArgs: string[];
+    /** Human-readable form, for the UI. */
+    label: string;
+};
+export type LaunchRequest = {
+    store: StudioStore;
+    agentId: string;
+    cwd: string;
+    prompt: string;
+    model?: string;
+    permissions?: string;
+};
+/**
+ * Find the `nah` to launch.
+ *
+ * Checked in the order that produces the version you are debugging: the binary
+ * recorded by the `nah` that started this Studio, then a `nah` on PATH. The
+ * recorded one matters because a global `nah` from npm and a `nah` built from
+ * source send different trace shapes, and a dashboard that quietly launched the
+ * other one would show you runs you never made.
+ *
+ * A recorded path ending in `.js` is a script rather than a binary — which is what
+ * `argv[1]` is for a dev checkout or an `npx` run — so it is launched through this
+ * process's own node. Depending on the file's executable bit would work on a
+ * globally installed CLI and fail on every checkout, which is the opposite of the
+ * order that matters.
+ */
+export declare const resolveNahBinary: (recorded: string | undefined, options?: {
+    platform?: NodeJS.Platform;
+    execPath?: string;
+    which?: (command: string) => string | undefined;
+}) => Launcher | null;
+/**
+ * Argument list for one launched agent.
+ *
+ * `--mode json` because the output is a machine-readable event stream, not a
+ * terminal: this process has no TTY, so the pretty renderer would have nothing to
+ * render into and the agent's reasoning would be invisible in the log pane.
+ */
+export declare const launchArgs: (request: Pick<LaunchRequest, "prompt" | "model" | "permissions">) => string[];
+export type LaunchResult = {
+    started: boolean;
+    reason?: string;
+    pid?: number;
+};
+export declare const launchAgent: (launcher: Launcher, request: LaunchRequest, options?: {
+    spawnProcess?: typeof spawn;
+}) => Promise<LaunchResult>;
+export type StopResult = {
+    stopped: boolean;
+    reason?: string;
+};
+/**
+ * Ask a launched agent to stop.
+ *
+ * `SIGTERM` first, because a `nah` process restores the terminal on the way out
+ * and `SIGKILL` would leave an alternate screen behind. Only agents the Studio
+ * started are eligible, and the server checks the host before calling this.
+ */
+export declare const stopAgentProcess: (agent: Agent, store: StudioStore) => StopResult;

package/dist/run.d.ts

@@ -0,0 +1,29 @@
+import { StudioAgent } from 'nah/agent';
+import { StudioHandle } from './server.js';
+export type ServeOptions = {
+    cwd: string;
+    port?: number;
+    host?: string;
+    /** Studio database. Defaults to ~/.nah/studio/studio.sqlite. */
+    dbPath?: string;
+    model?: string;
+    /** Shared secret required on every request. Set it before binding 0.0.0.0. */
+    token?: string;
+    /** The `nah` to launch agents with. Resolved from PATH when absent. */
+    nahBin?: string;
+    /** Do not publish `~/.nah/studio.json`, so no agent finds this Studio. */
+    noPublish?: boolean;
+    out?: NodeJS.WriteStream;
+    /** Injected in tests. */
+    createAgent?: (options: {
+        cwd: string;
+        model?: string;
+    }) => Promise<StudioAgent>;
+};
+export type ServeRun = {
+    output: string;
+    toolsCalled: string[];
+    filesChanged: string[];
+    traceId?: string;
+};
+export declare const runServe: (options: ServeOptions) => Promise<StudioHandle>;

package/dist/sandbox-C5dJwMTq-Cv8w7UGu.js

@@ -0,0 +1,96 @@
+import { DEFAULT_CAPS as x } from "@astracollab/not-another-harness";
+import { posix as l } from "node:path";
+const u = (process.env.BL_WORKSPACE ?? process.env.BLAXEL_WORKSPACE ?? "").trim(), b = async (s = {}) => {
+  if (!(process.env.BL_API_KEY ?? process.env.BLAXEL_API_KEY ?? "").trim())
+    throw new Error(
+      "--sandbox needs a Blaxel API key: set BL_API_KEY (workspace is inferred from the key, or set BL_WORKSPACE)."
+    );
+  u && (process.env.BL_WORKSPACE = u);
+  let p;
+  try {
+    p = await import("@blaxel/core");
+  } catch {
+    throw new Error("--sandbox needs the optional dependency @blaxel/core installed.");
+  }
+  const c = s.sandboxName ?? `nah-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 7)}`, i = l.resolve(s.repoDir ?? "/workspace/repo"), f = s.sandboxName == null, o = s.sandboxName ? await p.SandboxInstance.get(c) : await p.SandboxInstance.create({
+    name: c,
+    image: s.image ?? "blaxel/ts-app:latest",
+    memory: 4096,
+    region: (process.env.BL_REGION ?? "us-pdx-1").trim()
+  }), m = async (e, r, a) => {
+    const t = await o.process.exec({
+      command: e,
+      ...r ? { workingDir: r } : {},
+      timeout: a ?? 120,
+      waitForCompletion: !0
+    });
+    return typeof t == "string" ? { stdout: t, stderr: "", exitCode: 0 } : {
+      stdout: typeof t.stdout == "string" ? t.stdout : "",
+      stderr: typeof t.stderr == "string" ? t.stderr : "",
+      exitCode: typeof t.exitCode == "number" ? t.exitCode : 0
+    };
+  };
+  await m(`mkdir -p ${d(i)}`, "/").catch(() => {
+  });
+  const w = (e, r) => m(e, i, r), n = (e) => {
+    const r = e.replace(/\\/g, "/");
+    if (r.startsWith("/") || /^[A-Za-z]:/.test(r))
+      throw new Error(`absolute paths are not allowed in the sandbox repo: ${e}`);
+    const a = l.normalize(r || ".");
+    if (a === ".." || a.startsWith("../"))
+      throw new Error(`path escapes sandbox repo: ${e}`);
+    const t = l.resolve(i, a);
+    if (t !== i && !t.startsWith(`${i}/`))
+      throw new Error(`path escapes sandbox repo: ${e}`);
+    return t;
+  };
+  return {
+    env: {
+      readFile: (e) => o.fs.read(n(e)),
+      writeFile: async (e, r) => {
+        await o.fs.write(n(e), r);
+      },
+      deleteFile: async (e) => {
+        const r = o.fs;
+        if (!r.rm) throw new Error("the configured sandbox SDK does not support file removal");
+        await r.rm(n(e));
+      },
+      exists: async (e) => {
+        try {
+          return await o.fs.read(n(e)), !0;
+        } catch {
+        }
+        try {
+          return await o.fs.ls(n(e)), !0;
+        } catch {
+          return !1;
+        }
+      },
+      readdir: async (e) => {
+        const r = await o.fs.ls(n(e)), a = (r.files ?? []).map((t) => ({
+          name: t.path.split("/").pop() ?? t.path,
+          type: "file"
+        }));
+        return [...(r.subdirectories ?? []).map((t) => ({
+          name: t.path.split("/").pop() ?? t.path,
+          type: "directory"
+        })), ...a];
+      },
+      grep: async ({ pattern: e, path: r, ignoreCase: a }) => {
+        const t = ["-rnI", "-m", String(x.grep.maxPerFile)];
+        a && t.push("-i"), t.push("-E", "--", e);
+        const h = r?.trim() ? n(r.trim()) : ".", y = `git grep -nI ${a ? "-i " : ""}-m ${x.grep.maxPerFile} -E -- ${d(e)} ${d(h)} 2>/dev/null || grep ${t.join(" ")} ${d(h)}`;
+        return (await w(y, 60)).stdout ?? "";
+      },
+      exec: (e, r) => w(e, r?.timeoutSeconds)
+    },
+    sandboxName: c,
+    destroy: async () => {
+      !f || process.env.NAH_KEEP_SANDBOX === "1" || await p.SandboxInstance.delete?.(c).catch(() => {
+      });
+    }
+  };
+}, d = (s) => `'${s.replace(/'/g, "'\\''")}'`;
+export {
+  b as createBlaxelEnvironment
+};

package/dist/server.d.ts

@@ -0,0 +1,63 @@
+import { Server } from 'node:http';
+import { StudioStore } from './store.js';
+import { StreamHub } from './stream.js';
+import { Launcher } from './launcher.js';
+import { Scorer } from './evals.js';
+export type StudioServerOptions = {
+    store: StudioStore;
+    /**
+     * Directory holding the built Studio (`index.html` plus hashed assets).
+     *
+     * The UI is built by the package's own second Vite pass into `dist/ui`, so the
+     * server serves bytes from beside its entry point rather than shipping a
+     * second copy of the source.
+     */
+    assetDir?: string;
+    port?: number;
+    host?: string;
+    /** Reuse an already-listening server in tests. */
+    server?: Server;
+    /**
+     * Runs one prompt through the real agent, used by the chat tab and by
+     * experiments. Supplied by `run.ts`, which owns model resolution.
+     */
+    execute?: (input: string) => Promise<{
+        output: string;
+        toolsCalled: string[];
+        filesChanged: string[];
+        traceId?: string;
+    }>;
+    /** Model the server is running, recorded on experiments. */
+    model?: string;
+    /**
+     * Shared secret for every request. Set when the server is not bound to
+     * loopback, because the store holds prompts, file paths and tool output.
+     */
+    token?: string;
+    /**
+     * Spawning agents. Absent in tests and whenever no `nah` binary can be found,
+     * in which case the launch route reports that instead of pretending.
+     */
+    launcher?: Launcher;
+    /** The live event stream. Supplied by `startStudioServer`, which owns its lifetime. */
+    stream?: StreamHub;
+    /** The directory the built-in agent works in, reported by `/api/info`. */
+    cwd?: string;
+};
+/**
+ * Scorers this process can actually run.
+ *
+ * A registry rather than instances in the database, because a scorer is code and
+ * a database row cannot be code. The row carries the name and the description;
+ * this map decides what runs.
+ */
+export declare const registeredScorers: Map<string, Scorer>;
+/** Register the scorers that need no model, so a fresh server has something to run. */
+export declare const registerBuiltinScorers: () => void;
+export declare const createStudioServer: (options: StudioServerOptions) => Server;
+export type StudioHandle = {
+    server: Server;
+    url: string;
+    close(): Promise<void>;
+};
+export declare const startStudioServer: (options: StudioServerOptions) => Promise<StudioHandle>;

package/dist/store.d.ts

@@ -0,0 +1,301 @@
+import { Agent, AgentLogLine, AgentStatus, AgentSummary, Span, Trace } from './wire.js';
+export type TraceRow = Trace;
+export type DatasetItem = {
+    id: string;
+    input: string;
+    expected?: string;
+    metadata: Record<string, unknown>;
+};
+export type ScoreRecord = {
+    scorerId: string;
+    score: number;
+    reason?: string;
+    /** Scorers may decline rather than guess; recorded so averages stay honest. */
+    skipped?: boolean;
+};
+export type ExperimentResult = {
+    id: string;
+    itemId: string;
+    input: string;
+    status: "passed" | "failed" | "error";
+    output?: string;
+    error?: string;
+    scores: ScoreRecord[];
+    traceId?: string;
+    durationMs: number;
+    /** Provider-level retries before this item ran (or gave up). */
+    attempts: number;
+};
+/**
+ * What changed, for whoever is watching.
+ *
+ * The store is synchronous and knows nothing about HTTP, so it announces facts
+ * and the server decides who to tell. That is what keeps the live dashboard from
+ * needing a second source of truth: there is no polling loop to drift from the
+ * writes that actually happened.
+ */
+export type StoreEvent = {
+    type: "trace";
+    trace: Trace;
+    agentId: string | null;
+} | {
+    type: "agent";
+    agentId: string;
+} | {
+    type: "log";
+    agentId: string;
+    line: AgentLogLine;
+};
+export declare class StudioStore {
+    private readonly db;
+    private readonly listeners;
+    constructor(options: {
+        path: string;
+    });
+    /**
+     * Bring an older file up to the current shape.
+     *
+     * `CREATE TABLE IF NOT EXISTS` only helps a store that does not exist yet, and
+     * everyone who ran the Studio last week has one. SQLite has no
+     * `ADD COLUMN IF NOT EXISTS`, so the columns are checked first: an `ALTER` on
+     * an existing column is an error, and a dashboard that refuses to start
+     * because it ran twice is worse than one that starts twice.
+     */
+    private migrate;
+    /** Watch for writes. Returns the unsubscribe, so a caller cannot leak a listener. */
+    on(listener: (event: StoreEvent) => void): () => void;
+    /**
+     * Tell the listeners, and never let one of them fail the write.
+     *
+     * A watcher is a viewer. A dashboard that has gone away mid-turn must not turn
+     * a completed run into an error for the agent that produced it.
+     */
+    private emit;
+    /** Persist a finished trace and all of its spans, as one unit. */
+    saveTrace(trace: Trace, spans: Span[], agentId?: string | null): void;
+    listTraces(filter?: {
+        limit?: number;
+        search?: string;
+        status?: string;
+        tag?: string;
+        since?: number;
+        until?: number;
+        /** One agent, or every agent. */
+        agentId?: string;
+        sort?: "startTime" | "name" | "costUsd";
+        order?: "asc" | "desc";
+    }): TraceRow[];
+    getTrace(id: string): {
+        trace: TraceRow;
+        spans: Span[];
+    } | null;
+    /**
+     * Bucketed history for the dashboard charts.
+     *
+     * Buckets rather than a raw series: a week of runs is thousands of points, and
+     * a sparkline cannot show that anyway. `NULLS`-free arithmetic keeps an empty
+     * hour at zero rather than absent, which is the difference between "no runs"
+     * and "the query lost them".
+     */
+    timeseries(buckets?: number, filter?: {
+        agentId?: string;
+    }): Array<{
+        t: number;
+        traces: number;
+        errors: number;
+        costUsd: number;
+        medianMs: number;
+    }>;
+    /**
+     * Per-tool aggregates across every trace.
+     *
+     * "Which tool is slow or failing" is a question about the whole history, not
+     * about one run, so it is answered in SQL rather than by loading spans.
+     */
+    toolStats(filter?: {
+        agentId?: string;
+    }): Array<{
+        tool: string;
+        calls: number;
+        errors: number;
+        errorRate: number;
+        p50Ms: number;
+        p95Ms: number;
+        totalMs: number;
+    }>;
+    /** Totals for the dashboard. One pass, so it stays cheap as the table grows. */
+    overview(filter?: {
+        agentId?: string;
+    }): {
+        traces: number;
+        errors: number;
+        costUsd: number;
+        inputTokens: number;
+        outputTokens: number;
+        medianDurationMs: number;
+    };
+    /**
+     * Register, or refresh, one agent.
+     *
+     * An id is the identity: a process asks with the same id every time it
+     * heartbeats, so a re-registration updates one row instead of filling the list
+     * with copies of the same agent. A caller with no id gets a new one, which is
+     * what a fresh `nah` session does.
+     */
+    registerAgent(registration: {
+        id?: string;
+        name?: string;
+        cwd: string;
+        host?: string;
+        pid?: number;
+        model?: string | null;
+        version?: string | null;
+        source?: "session" | "launch";
+        metadata?: Record<string, unknown>;
+        status?: AgentStatus;
+    }): Agent;
+    /**
+     * Move an agent to a new status and mark it seen.
+     *
+     * Separate from registration because a heartbeat must not be able to rewrite
+     * the fields it has no opinion about — a status change should not blank a model.
+     */
+    setAgentState(id: string, patch: {
+        status?: AgentStatus;
+        exitCode?: number | null;
+        metadata?: Record<string, unknown>;
+    }): Agent | null;
+    getAgent(id: string): Agent | null;
+    /**
+     * Agents, each with its own totals, newest activity first.
+     *
+     * `runningBefore` is what makes the online dot honest: a process that stopped
+     * reporting is offline even though nothing ever wrote "offline", because a
+     * machine that was unplugged cannot file that report.
+     */
+    listAgents(filter?: {
+        runningBefore?: number;
+        cwd?: string;
+    }): AgentSummary[];
+    /**
+     * One agent's summary.
+     *
+     * Separate from filtering the list because the live stream needs this per
+     * event, and re-aggregating every agent to describe the one that just moved is
+     * how a ten-agent dashboard spends its time on nine agents nobody is watching.
+     */
+    getAgentSummary(id: string, runningBefore?: number): AgentSummary | null;
+    private summarize;
+    deleteAgent(id: string): boolean;
+    /** Append one line of an agent's output, and hand it to whoever is watching. */
+    appendAgentLog(agentId: string, line: {
+        stream: "stdout" | "stderr" | "system";
+        text: string;
+    }): AgentLogLine;
+    listAgentLogs(agentId: string, limit?: number): AgentLogLine[];
+    /**
+     * Drop the rows nobody is looking at any more.
+     *
+     * Agents age out far faster than traces: a process from last month is not a
+     * thing to keep a row for, and the trace it produced is the part worth keeping.
+     */
+    pruneAgents(olderThanMs: number): number;
+    saveMessage(message: {
+        id: string;
+        traceId?: string;
+        agentId?: string;
+        role: string;
+        content: string;
+        metadata?: Record<string, unknown>;
+    }): void;
+    /**
+     * Messages newest first, with a monotonic sequence number.
+     *
+     * `created_at` is millisecond-resolution, and a short reply writes its user and
+     * assistant messages inside the same millisecond — so timestamp alone is not a
+     * total order and a thread rebuilt from it can come back reversed. `seq` is
+     * SQLite's insertion counter: it is monotonic, so sorting by it puts the thread
+     * back in the order it was actually said in. The sort order *within* equal
+     * timestamps is left unspecified on purpose rather than papered over.
+     */
+    listMessages(filter?: {
+        traceId?: string;
+        limit?: number;
+    }): Array<{
+        id: string;
+        traceId?: string;
+        role: string;
+        content: string;
+        createdAt: number;
+        seq: number;
+    }>;
+    /** Bounded retention. Traces are diagnostic; a year of them is a liability. */
+    prune(olderThanMs: number): number;
+    createDataset(input: {
+        id?: string;
+        name: string;
+        description?: string;
+    }): {
+        id: string;
+        version: number;
+    };
+    listDatasets(): Array<{
+        id: string;
+        name: string;
+        description: string;
+        version: number;
+        items: number;
+    }>;
+    addDatasetItems(datasetId: string, items: Array<{
+        id?: string;
+        input: string;
+        expected?: string;
+        metadata?: Record<string, unknown>;
+    }>): number;
+    listDatasetItems(datasetId: string): DatasetItem[];
+    deleteDataset(id: string): boolean;
+    saveScorer(scorer: {
+        id: string;
+        name: string;
+        description?: string;
+        kind: string;
+        config?: Record<string, unknown>;
+    }): void;
+    listScorers(): Array<{
+        id: string;
+        name: string;
+        description: string;
+        kind: string;
+        config: Record<string, unknown>;
+    }>;
+    startExperiment(input: {
+        id?: string;
+        datasetId: string;
+        model: string;
+    }): string;
+    saveExperimentResult(result: ExperimentResult & {
+        experimentId: string;
+    }): void;
+    finishExperiment(id: string, summary: Record<string, unknown>, error?: string): void;
+    getExperiment(id: string): {
+        id: string;
+        datasetId: string;
+        status: string;
+        model: string;
+        startedAt: number;
+        finishedAt: number | null;
+        summary: Record<string, unknown>;
+        error?: string;
+        results: ExperimentResult[];
+    } | null;
+    listExperiments(limit?: number): Array<{
+        id: string;
+        datasetId: string;
+        status: string;
+        model: string;
+        startedAt: number;
+        finishedAt: number | null;
+        summary: Record<string, unknown>;
+    }>;
+    close(): void;
+}

package/dist/stream.d.ts

@@ -0,0 +1,14 @@
+import { ServerResponse } from 'node:http';
+import { StudioStore } from './store.js';
+export type StreamHub = {
+    /** Take over a response and keep it open as an event stream. */
+    add: (response: ServerResponse) => void;
+    /** End every open stream. Called when the server closes. */
+    close: () => void;
+    /** Clients currently attached, for tests. */
+    readonly size: () => number;
+};
+export declare const createStreamHub: (store: StudioStore, options?: {
+    livenessMs?: number;
+    now?: () => number;
+}) => StreamHub;