@cogitator-ai/studio 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Cogitator Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,74 @@
+# @cogitator-ai/studio
+
+Cogitator Studio: a local debugger for Cogitator agent projects. Chat with every agent of a project, approve the tool calls that need it, read the trace and the cost of each run, run workflows and rerun them from a node, and fork a run from any step to see what a different input or tool result changes.
+
+Guide: [cogitator.app/docs/getting-started/studio](https://cogitator.app/docs/getting-started/studio)
+
+## Start it
+
+In a project created by `create-cogitator-app` or `cogitator init`:
+
+```bash
+pnpm dev:studio          # the script every generated project has
+npx cogitator dev        # the same, from @cogitator-ai/cli
+```
+
+It opens http://localhost:4321 (the next free port when it is taken). The studio finds the agents, workflows and swarms in `src/cogitator.ts`, the registry generated projects have: export the runtime as `cogitator` and the rest as `agents`, `workflows` and `swarms`.
+
+## What it does
+
+- **Overview**: the project at a glance, with its runs, success rate, spend in tokens and dollars, p50 and p95 latency, activity over the last two weeks, and every agent and workflow with the model it runs on and how often it ran.
+- **Chat** with any agent: streamed answers rendered as Markdown with highlighted code and LaTeX math (`\(...\)`, `\[...\]` and `$$...$$`, a single `$` stays a dollar), reasoning, tool calls as one line each that opens to its arguments and result, errors, stop, and threads grouped by day. A project without memory gets one from the studio, so threads keep their conversation, also after a restart.
+- **Approvals**: a tool call with `requiresApproval` waits in the chat with its arguments until you approve it, or reject it with a reason the model sees.
+- **Traces**: every run as a waterfall of model calls, tool calls and the runs agent tools start, nested under the call that started them, with the time, the tokens and the cost of each model call (priced from the model registry, `unpriced` for unknown models) and the total, counted live while the run goes. Click a span for its details: cached and reasoning tokens, the finish reason, the arguments and the result of a tool call.
+- **Workflows**: run one with an input state, watch the status and time of each node on its graph, read what each node returned (text an agent wrote is rendered as Markdown, the raw JSON is a click away), and rerun from a node, keeping what the nodes before it produced.
+- **Time-travel forks**: pick a step of a finished run (before each tool call), change the input, add context or replace a tool result, and run on from there. The original and the fork are shown side by side, with the tool calls that differ highlighted.
+- **History**: runs and threads are kept in `.cogitator/studio/` as JSON files, searchable by input, output and error and filtered by agent, workflow or kind. Runs a stopped studio left behind are marked failed.
+- **Keyboard**: `⌘K` (`Ctrl+K`) opens a command palette over agents, workflows, the whole run history and actions, `/` searches the page, `G O` and `G R` go to the overview and the runs, `J` and `K` walk the run list and the trace, `N` starts a thread, and `?` lists every shortcut.
+- **Themes**: light and dark, following the system until you pick one, which the browser remembers.
+
+## How it works
+
+```
+browser  ──HTTP, SSE──▶  studio server (cogitator dev)  ──IPC──▶  runtime host (child process)
+  React UI                 run store in .cogitator/studio           your project, loaded with tsx
+                           file watcher                             cogitator.observe(), TimeTravel,
+                                                                    WorkflowManager
+```
+
+- The **runtime host** is a child process that loads `.env` and `src/cogitator.ts` with tsx and runs the project with its own runtime, memory and tools. It watches every run through `cogitator.observe()`, so runs that agent tools start on the same runtime are seen too, and links them to the request that started them with `AsyncLocalStorage`. Forks use the project's `TimeTravel` with checkpoints kept on disk; workflows run on a `WorkflowManager` with file checkpoints, which is what reruns from a node start from.
+- The **server** keeps the runs and threads, prices model calls, puts nested runs under the tool call whose span was open when they started, and pushes every change to the browser over server-sent events.
+- When a file under `src/`, `cogitator.yml`, `.env`, `package.json` or `tsconfig.json` changes, the host is started again with the new code: the server and the browser stay, runs that were going are marked failed with the reason.
+
+## Security
+
+The server listens on `127.0.0.1` and answers only requests for `localhost`, so another site cannot reach it through DNS rebinding, and refuses cross-site posts. `--host 0.0.0.0` (or any other address) opens it to the network and requires the random token printed in its URL; the token is kept in an `HttpOnly`, `SameSite=Strict` cookie after the first visit.
+
+## API
+
+```ts
+import { startStudio } from '@cogitator-ai/studio';
+
+const studio = await startStudio({ projectDir: process.cwd(), port: 4321 });
+console.log(studio.url);
+await studio.ready();
+// ...
+await studio.close();
+```
+
+| Option       | Default                | What it does                                          |
+| ------------ | ---------------------- | ----------------------------------------------------- |
+| `projectDir` | required               | The project to run                                    |
+| `host`       | `127.0.0.1`            | Interface to listen on; anything else needs the token |
+| `port`       | `4321`                 | Port, the next free one unless `strictPort`           |
+| `token`      | random beyond loopback | Token requests must carry                             |
+| `watch`      | `true`                 | Reload the project when its files change              |
+| `studioDir`  | `.cogitator/studio`    | Where the history lives                               |
+| `log`        |                        | Receives the project's output                         |
+| `price`      | model registry         | Prices a model call from its model and tokens         |
+
+The HTTP API the UI uses is open to scripts as well: `GET /api/state`, `GET /api/runs?target=&kind=&q=`, `GET /api/runs/:id`, `GET /api/threads/:id`, `POST /api/chat`, `POST /api/runs/:id/stop`, `POST /api/approvals/:id`, `POST /api/runs/:id/fork`, `POST /api/workflows/:key/run`, `POST /api/runs/:id/rerun`, `GET /api/stats` for the totals of the overview, and `GET /api/events` for the event stream. The shapes are the types exported from the package (`RunRecord`, `ThreadRecord`, `StudioStats`, `StudioEvent` and the rest).
+
+## License
+
+MIT

package/dist/host/checkpoints.d.ts

@@ -0,0 +1,11 @@
+import type { InMemoryCheckpointStore } from '@cogitator-ai/core';
+type CheckpointStoreClass = typeof InMemoryCheckpointStore;
+/**
+ * A time-travel checkpoint store that keeps every checkpoint as a JSON file in
+ * `directory`, so the runs of earlier studio sessions can still be forked.
+ * It extends the in-memory store of the project's @cogitator-ai/core, which
+ * keeps the indexes and the queries.
+ */
+export declare function openCheckpointStore(Base: CheckpointStoreClass, directory: string): Promise<InMemoryCheckpointStore>;
+export {};
+//# sourceMappingURL=checkpoints.d.ts.map

package/dist/host/checkpoints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoints.d.ts","sourceRoot":"","sources":["../../src/host/checkpoints.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAGlE,KAAK,oBAAoB,GAAG,OAAO,uBAAuB,CAAC;AAO3D;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,oBAAoB,EAC1B,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,uBAAuB,CAAC,CA+BlC"}

package/dist/host/checkpoints.js

@@ -0,0 +1,43 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+function revive(raw) {
+    const parsed = JSON.parse(raw);
+    return { ...parsed, createdAt: new Date(parsed.createdAt) };
+}
+/**
+ * A time-travel checkpoint store that keeps every checkpoint as a JSON file in
+ * `directory`, so the runs of earlier studio sessions can still be forked.
+ * It extends the in-memory store of the project's @cogitator-ai/core, which
+ * keeps the indexes and the queries.
+ */
+export async function openCheckpointStore(Base, directory) {
+    mkdirSync(directory, { recursive: true });
+    const fileOf = (id) => join(directory, `${id.replace(/[^\w-]/g, '_')}.json`);
+    class FileTimeTravelStore extends Base {
+        async save(checkpoint) {
+            await super.save(checkpoint);
+            writeFileSync(fileOf(checkpoint.id), JSON.stringify(checkpoint));
+        }
+        async delete(id) {
+            const deleted = await super.delete(id);
+            rmSync(fileOf(id), { force: true });
+            return deleted;
+        }
+        async restore(checkpoint) {
+            await super.save(checkpoint);
+        }
+    }
+    const store = new FileTimeTravelStore();
+    for (const name of existsSync(directory) ? readdirSync(directory) : []) {
+        if (!name.endsWith('.json'))
+            continue;
+        try {
+            await store.restore(revive(readFileSync(join(directory, name), 'utf-8')));
+        }
+        catch {
+            rmSync(join(directory, name), { force: true });
+        }
+    }
+    return store;
+}
+//# sourceMappingURL=checkpoints.js.map

package/dist/host/checkpoints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoints.js","sourceRoot":"","sources":["../../src/host/checkpoints.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAClG,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAMjC,SAAS,MAAM,CAAC,GAAW;IACzB,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAgD,CAAC;IAC9E,OAAO,EAAE,GAAG,MAAM,EAAE,SAAS,EAAE,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;AAC9D,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,IAA0B,EAC1B,SAAiB;IAEjB,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1C,MAAM,MAAM,GAAG,CAAC,EAAU,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;IAErF,MAAM,mBAAoB,SAAQ,IAAI;QAC3B,KAAK,CAAC,IAAI,CAAC,UAA+B;YACjD,MAAM,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;YAC7B,aAAa,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC,CAAC;QACnE,CAAC;QAEQ,KAAK,CAAC,MAAM,CAAC,EAAU;YAC9B,MAAM,OAAO,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YACvC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YACpC,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,KAAK,CAAC,OAAO,CAAC,UAA+B;YAC3C,MAAM,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;QAC/B,CAAC;KACF;IAED,MAAM,KAAK,GAAG,IAAI,mBAAmB,EAAE,CAAC;IACxC,KAAK,MAAM,IAAI,IAAI,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;QACvE,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;YAAE,SAAS;QACtC,IAAI,CAAC;YACH,MAAM,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;QAC5E,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/host/main.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=main.d.ts.map

package/dist/host/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../src/host/main.ts"],"names":[],"mappings":""}

package/dist/host/main.js

@@ -0,0 +1,49 @@
+import { StudioHost } from './runner.js';
+/**
+ * The runtime host: a child process of `cogitator dev` that loads the project
+ * with tsx and runs it for the studio. It is started again whenever the
+ * project changes, so the studio always runs the current code.
+ */
+const [projectDir, studioDir] = process.argv.slice(2);
+function send(message) {
+    return new Promise((resolve) => {
+        if (!process.send)
+            return resolve();
+        process.send(message, () => resolve());
+    });
+}
+process.on('unhandledRejection', (reason) => {
+    console.error('[studio host] unhandled rejection:', reason);
+});
+process.on('disconnect', () => process.exit(0));
+if (!projectDir || !studioDir) {
+    console.error('usage: host <projectDir> <studioDir>');
+    process.exit(2);
+}
+try {
+    const host = await StudioHost.create(projectDir, studioDir, (event) => {
+        void send({ type: 'event', event });
+    });
+    process.on('message', (request) => {
+        host.handle(request).then((data) => send({ type: 'response', requestId: request.requestId, ok: true, data }), (error) => send({
+            type: 'response',
+            requestId: request.requestId,
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+        }));
+    });
+    process.once('SIGTERM', () => {
+        void host.close().finally(() => process.exit(0));
+    });
+    await send({ type: 'ready', registry: host.registry(), memory: host.memory });
+}
+catch (error) {
+    const detail = error instanceof Error ? (error.stack ?? error.message) : String(error);
+    console.error(detail);
+    await send({
+        type: 'load-failed',
+        error: error instanceof Error ? error.message : String(error),
+    });
+    process.exit(1);
+}
+//# sourceMappingURL=main.js.map

package/dist/host/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../src/host/main.ts"],"names":[],"mappings":"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"}

package/dist/host/project.d.ts

@@ -0,0 +1,22 @@
+import type { Agent, Cogitator } from '@cogitator-ai/core';
+import type { Workflow } from '@cogitator-ai/types';
+/**
+ * A package as the project resolves it, so the studio uses the very classes
+ * the project's runtime was built with; the studio's own copy when the
+ * project does not have it.
+ */
+export declare function importFromProject<T>(projectDir: string, name: string): Promise<T>;
+/** Whether the project can resolve `name`. */
+export declare function projectHas(projectDir: string, name: string): boolean;
+export interface LoadedProject {
+    cogitator: Cogitator;
+    agents: Map<string, Agent>;
+    workflows: Map<string, Workflow>;
+    module: Record<string, unknown>;
+}
+/**
+ * Loads `.env` and the registry of the project: the runtime it exports as
+ * `cogitator`, and its agents and workflows by key.
+ */
+export declare function loadProject(projectDir: string): Promise<LoadedProject>;
+//# sourceMappingURL=project.d.ts.map

package/dist/host/project.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.d.ts","sourceRoot":"","sources":["../../src/host/project.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAGpD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAQvF;AAED,8CAA8C;AAC9C,wBAAgB,UAAU,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAOpE;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,SAAS,CAAC;IACrB,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC3B,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AA2CD;;;GAGG;AACH,wBAAsB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAsB5E"}

package/dist/host/project.js

@@ -0,0 +1,88 @@
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { REGISTRY_PATH } from '../registry.js';
+/**
+ * A package as the project resolves it, so the studio uses the very classes
+ * the project's runtime was built with; the studio's own copy when the
+ * project does not have it.
+ */
+export async function importFromProject(projectDir, name) {
+    let entry;
+    try {
+        entry = createRequire(join(projectDir, 'package.json')).resolve(name);
+    }
+    catch {
+        entry = undefined;
+    }
+    return (await import(entry ? pathToFileURL(entry).href : name));
+}
+/** Whether the project can resolve `name`. */
+export function projectHas(projectDir, name) {
+    try {
+        createRequire(join(projectDir, 'package.json')).resolve(name);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isAgent(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'config' in value &&
+        typeof value.config === 'object' &&
+        value.config !== null &&
+        'instructions' in value.config &&
+        typeof value.config.instructions === 'string');
+}
+function isWorkflow(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'nodes' in value &&
+        value.nodes instanceof Map &&
+        'entryPoint' in value &&
+        typeof value.entryPoint === 'string');
+}
+function isCogitator(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'run' in value &&
+        typeof value.run === 'function' &&
+        'observe' in value &&
+        typeof value.observe === 'function');
+}
+function entries(group, guard) {
+    const found = new Map();
+    if (typeof group !== 'object' || group === null)
+        return found;
+    for (const [key, value] of Object.entries(group))
+        if (guard(value))
+            found.set(key, value);
+    return found;
+}
+/**
+ * Loads `.env` and the registry of the project: the runtime it exports as
+ * `cogitator`, and its agents and workflows by key.
+ */
+export async function loadProject(projectDir) {
+    const envFile = join(projectDir, '.env');
+    if (existsSync(envFile))
+        process.loadEnvFile(envFile);
+    const registryPath = join(projectDir, REGISTRY_PATH);
+    if (!existsSync(registryPath)) {
+        throw new Error(`${REGISTRY_PATH} not found: Cogitator Studio finds agents, workflows and swarms in the registry projects from create-cogitator-app have. Export your runtime as \`cogitator\` and your agents as \`agents\` from ${REGISTRY_PATH}.`);
+    }
+    const module = (await import(pathToFileURL(registryPath).href));
+    if (!isCogitator(module.cogitator)) {
+        throw new Error(`${REGISTRY_PATH} does not export the runtime as \`cogitator\` (a Cogitator from @cogitator-ai/core 0.34 or newer)`);
+    }
+    return {
+        cogitator: module.cogitator,
+        agents: entries(module.agents, isAgent),
+        workflows: entries(module.workflows, isWorkflow),
+        module,
+    };
+}
+//# sourceMappingURL=project.js.map

package/dist/host/project.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project.js","sourceRoot":"","sources":["../../src/host/project.ts"],"names":[],"mappings":"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"}

package/dist/host/runner.d.ts

@@ -0,0 +1,58 @@
+import type { HostEvent, HostRequest, RegistryInfo } from '../protocol.js';
+/**
+ * Runs the project for the studio: chats with its agents, asks the studio
+ * to approve tool calls, forks runs from their steps and runs its workflows.
+ * Everything that happens is reported through `emit`, from the runtime's own
+ * observer, so runs agent tools start show up too.
+ */
+export declare class StudioHost {
+    private readonly project;
+    private readonly core;
+    private readonly options;
+    private readonly als;
+    private readonly controllers;
+    private readonly approvals;
+    private readonly seeded;
+    private readonly workflowRunIds;
+    private timeTravel?;
+    private manager?;
+    private constructor();
+    static create(projectDir: string, studioDir: string, emit: (event: HostEvent) => void): Promise<StudioHost>;
+    get memory(): 'project' | 'studio';
+    registry(): RegistryInfo;
+    close(): Promise<void>;
+    handle(request: HostRequest): Promise<unknown>;
+    private emit;
+    /** Reports every run started for a studio request, nested ones included. */
+    private observer;
+    private agent;
+    private workflow;
+    /**
+     * Starts `start` under a new studio request and resolves with the id of
+     * the run it started, or rejects when it failed before starting one.
+     */
+    private begin;
+    /** Replays a thread's earlier messages into the studio's own memory, once per host. */
+    private seed;
+    private chat;
+    /**
+     * Reports how a run the studio started ended, with its fork steps. A run
+     * with a controller can be stopped from the studio.
+     */
+    private finish;
+    /** Holds a tool call until the studio approves or rejects it. */
+    private ask;
+    private decide;
+    private stop;
+    private travel;
+    /** The steps a run can be forked from: one before each tool call, or its start. */
+    private steps;
+    private fork;
+    private workflowManager;
+    private nodeCallbacks;
+    /** Runs a workflow under a studio id the run is known by from its first event. */
+    private startWorkflow;
+    private runWorkflow;
+    private rerunWorkflow;
+}
+//# sourceMappingURL=runner.d.ts.map

package/dist/host/runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/host/runner.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAGV,SAAS,EACT,WAAW,EAEX,YAAY,EAIb,MAAM,gBAAgB,CAAC;AAyFxB;;;;;GAKG;AACH,qBAAa,UAAU;IAUnB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAX1B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAuC;IAC3D,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAsC;IAClE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsC;IAChE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA6B;IAC5D,OAAO,CAAC,UAAU,CAAC,CAAsB;IACzC,OAAO,CAAC,OAAO,CAAC,CAAkD;IAElE,OAAO;WAWM,MAAM,CACjB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,GAC/B,OAAO,CAAC,UAAU,CAAC;IAetB,IAAI,MAAM,IAAI,SAAS,GAAG,QAAQ,CAEjC;IAED,QAAQ,IAAI,YAAY;IAIlB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAK5B,MAAM,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IAiB9C,OAAO,CAAC,IAAI;IAIZ,4EAA4E;IAC5E,OAAO,CAAC,QAAQ;IAsDhB,OAAO,CAAC,KAAK;IAMb,OAAO,CAAC,QAAQ;IAMhB;;;OAGG;YACW,KAAK;IAYnB,uFAAuF;YACzE,IAAI;YAqBJ,IAAI;IAwClB;;;OAGG;IACH,OAAO,CAAC,MAAM;IA6Cd,iEAAiE;IACjE,OAAO,CAAC,GAAG;IAgBX,OAAO,CAAC,MAAM;IAed,OAAO,CAAC,IAAI;IAUZ,OAAO,CAAC,MAAM;IAcd,mFAAmF;YACrE,KAAK;YAkBL,IAAI;IAmClB,OAAO,CAAC,eAAe;IAuBvB,OAAO,CAAC,aAAa;IA4BrB,kFAAkF;IAClF,OAAO,CAAC,aAAa;YAiDP,WAAW;YAUX,aAAa;CAmB5B"}