@ggui-ai/agent-runtime 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a
+      fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Loqu, Inc. (Guuey)
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied. See the License for the specific language governing
+   permissions and limitations under the License.

package/README.md

@@ -0,0 +1,24 @@
+# @ggui-ai/agent-runtime
+
+Pluggable adapter seam for "the thing that runs an agent."
+
+Part of the **ggui protocol** toolchain, this package defines a small contract —
+`AgentRuntimeAdapter` — for supervising whatever actually executes an agent: the
+Claude Agent SDK, OpenAI Agents, the Vercel AI SDK, a plain subprocess, or anything
+else. A host consumes this seam so no agent framework is hardcoded into its dev loop;
+swapping runtimes never touches host code.
+
+This package exposes the contract types plus an in-memory stub adapter
+(`createStubAgentRuntime`) for tests and local development. Framework-specific
+adapters live in their own packages so consumers opt into the dependency weight.
+
+## Exports
+
+| Import                           | Contents                                                   |
+| -------------------------------- | ---------------------------------------------------------- |
+| `@ggui-ai/agent-runtime`         | The `AgentRuntimeAdapter` contract and the in-memory stub. |
+| `@ggui-ai/agent-runtime/process` | A subprocess-backed adapter.                               |
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `@ggui-ai/agent-runtime` — pluggable adapter seam for "the thing
+ * that runs an agent," consumed by the open dev engine
+ * (`@ggui-ai/dev-stack`) and any future non-dev host (bench
+ * runners, remote supervisors).
+ *
+ * This barrel exposes the contract + an in-memory stub adapter.
+ * Framework-specific adapters (Claude Agent SDK, OpenAI Agents,
+ * Vercel AI SDK, a plain subprocess) live in their own packages so
+ * consumers opt into the dependency weight.
+ *
+ * Design rule: the agent framework is NEVER hardcoded into the dev
+ * engine. This adapter seam carries every framework, so a host can
+ * swap runtimes without touching engine code.
+ */
+export type { AgentRuntimeAdapter, AgentRuntimeCapabilities, AgentRuntimeEvent, AgentRuntimeHandle, AgentRuntimeListener, AgentRuntimeProjectIdentity, AgentRuntimeStartInput, AgentRuntimeStatus, } from './types.js';
+export { createStubAgentRuntime, type StubAgentRuntimeController, type StubAgentRuntimeOptions, } from './stub.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,YAAY,EACV,mBAAmB,EACnB,wBAAwB,EACxB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,2BAA2B,EAC3B,sBAAsB,EACtB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,sBAAsB,EACtB,KAAK,0BAA0B,EAC/B,KAAK,uBAAuB,GAC7B,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1 @@
+export { createStubAgentRuntime, } from './stub.js';

package/dist/process.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Node subprocess reference adapter — the first real
+ * implementation of {@link AgentRuntimeAdapter}.
+ *
+ * Supervises a local agent that runs as a child process: spawns
+ * with an explicit `command` + `args`, streams stdout/stderr into
+ * the event channel, and maps process lifecycle signals onto the
+ * adapter's status machine (`starting` → `ready` → `stopped` |
+ * `crashed`).
+ *
+ * Reference only — deliberately NOT the architecture:
+ *
+ *   - `command` + `args` are REQUIRED. The factory does not assume
+ *     `npx tsx watch src/index.ts` (the `ggui dev` default) or
+ *     any framework-specific entrypoint. A CLI wanting `.ts` input
+ *     wraps its own `node --import=tsx` shape and passes it
+ *     through; the adapter itself knows only how to spawn.
+ *   - No framework detection. Claude / OpenAI / Vercel AI / LangGraph
+ *     adapters live in their own packages and translate their own
+ *     idioms onto this same seam.
+ *   - No service-discovery assumptions. Optional `readyCheck` lets
+ *     callers promote `starting → ready` on an HTTP probe; if
+ *     omitted the adapter considers the child "ready" as soon as
+ *     the spawn completes.
+ *
+ * Lives under `@ggui-ai/agent-runtime/process` so consumers that
+ * don't spawn subprocesses (browser-side hubs, future test
+ * runners) never pull the `node:child_process` dep by loading the
+ * root barrel.
+ */
+import { type ChildProcess } from 'node:child_process';
+import type { AgentRuntimeAdapter } from './types.js';
+/**
+ * Optional HTTP-probe readiness gate. The adapter polls
+ * `http://127.0.0.1:<port>/<path>` and emits `status: 'ready'` on
+ * the first successful response. Before that the handle stays in
+ * `starting`.
+ *
+ * Kept narrow — no redirect following, no body inspection, no
+ * non-HTTP probes. Hosts wanting richer semantics (gRPC health,
+ * stdout-match) fork the adapter or post a specific probe layer
+ * on top. Keeps the reference impl honest.
+ */
+export interface HttpReadyCheck {
+    readonly type: 'http';
+    /** Port to probe on 127.0.0.1. Required — we don't scan. */
+    readonly port: number;
+    /** Path to probe. Defaults to `'/'`. */
+    readonly path?: string;
+    /** Milliseconds between polls. Defaults to 250. */
+    readonly intervalMs?: number;
+    /** Overall timeout budget. Defaults to 30s. */
+    readonly timeoutMs?: number;
+}
+export type ReadyCheck = HttpReadyCheck;
+export interface NodeProcessAgentRuntimeOptions {
+    /**
+     * Adapter name surfaced via `adapter.name`. Defaults to
+     * `'node-process'`. Override for clearer logs when multiple
+     * adapters coexist.
+     */
+    readonly name?: string;
+    /**
+     * Executable to run. Required — the factory takes NO default to
+     * avoid pinning a framework. The CLI or host decides whether
+     * this is `'node'`, `process.execPath`, or something else.
+     */
+    readonly command: string;
+    /** Args forwarded to the child. Required; pass `[]` for no args. */
+    readonly args: readonly string[];
+    /**
+     * Working directory for the child process. When omitted the
+     * adapter uses {@link AgentRuntimeStartInput.projectRoot} (or the
+     * parent's cwd as a last resort). Absolute paths only.
+     */
+    readonly cwd?: string;
+    /**
+     * Extra env vars forwarded into the child. MERGED with
+     * `startInput.env` (startInput wins on collision) and then with
+     * `process.env` (child inherits the rest of the parent env).
+     * Adapter never leaks env keys the caller didn't opt into by
+     * either source.
+     */
+    readonly env?: Readonly<Record<string, string>>;
+    /**
+     * Optional readiness probe. When omitted the adapter emits
+     * `status: 'ready'` immediately after spawn succeeds.
+     */
+    readonly readyCheck?: ReadyCheck;
+    /**
+     * Signal to send on `stop()`. Defaults to `'SIGTERM'`. After
+     * {@link shutdownTimeoutMs} the adapter escalates to `SIGKILL`.
+     */
+    readonly shutdownSignal?: NodeJS.Signals;
+    /** Grace period before SIGKILL. Defaults to {@link DEFAULT_SHUTDOWN_TIMEOUT_MS}. */
+    readonly shutdownTimeoutMs?: number;
+    /**
+     * Maximum bytes to buffer from a single log line before truncation.
+     * Useful for runaway stack traces — defaults to 16 KiB.
+     */
+    readonly maxLineBytes?: number;
+    /**
+     * Test seam — inject a spawner to exercise the adapter without
+     * touching the filesystem. Production code leaves this unset.
+     */
+    readonly spawner?: Spawner;
+}
+/**
+ * Minimal spawner contract — `spawn()` from `node:child_process`
+ * satisfies this. Broken out so tests can substitute a fake that
+ * emits crafted stdout / stderr / exit events.
+ */
+export type Spawner = (command: string, args: readonly string[], options: {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}) => ChildProcess;
+/**
+ * Construct a framework-neutral subprocess adapter. The returned
+ * adapter carries no framework-specific behaviour; callers pin the
+ * framework by choosing `command` + `args`.
+ */
+export declare function createNodeProcessAgentRuntime(options: NodeProcessAgentRuntimeOptions): AgentRuntimeAdapter;
+//# sourceMappingURL=process.d.ts.map

package/dist/process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.d.ts","sourceRoot":"","sources":["../src/process.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EACV,mBAAmB,EAMpB,MAAM,YAAY,CAAC;AASpB;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,4DAA4D;IAC5D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wCAAwC;IACxC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,mDAAmD;IACnD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,MAAM,UAAU,GAAG,cAAc,CAAC;AAExC,MAAM,WAAW,8BAA8B;IAC7C;;;;OAIG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAChD;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAC;IACjC;;;OAGG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC,OAAO,CAAC;IACzC,oFAAoF;IACpF,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,MAAM,OAAO,GAAG,CACpB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CAAE,KAC/C,YAAY,CAAC;AAElB;;;;GAIG;AACH,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,8BAA8B,GACtC,mBAAmB,CAoDrB"}

package/dist/process.js

@@ -0,0 +1,349 @@
+/**
+ * Node subprocess reference adapter — the first real
+ * implementation of {@link AgentRuntimeAdapter}.
+ *
+ * Supervises a local agent that runs as a child process: spawns
+ * with an explicit `command` + `args`, streams stdout/stderr into
+ * the event channel, and maps process lifecycle signals onto the
+ * adapter's status machine (`starting` → `ready` → `stopped` |
+ * `crashed`).
+ *
+ * Reference only — deliberately NOT the architecture:
+ *
+ *   - `command` + `args` are REQUIRED. The factory does not assume
+ *     `npx tsx watch src/index.ts` (the `ggui dev` default) or
+ *     any framework-specific entrypoint. A CLI wanting `.ts` input
+ *     wraps its own `node --import=tsx` shape and passes it
+ *     through; the adapter itself knows only how to spawn.
+ *   - No framework detection. Claude / OpenAI / Vercel AI / LangGraph
+ *     adapters live in their own packages and translate their own
+ *     idioms onto this same seam.
+ *   - No service-discovery assumptions. Optional `readyCheck` lets
+ *     callers promote `starting → ready` on an HTTP probe; if
+ *     omitted the adapter considers the child "ready" as soon as
+ *     the spawn completes.
+ *
+ * Lives under `@ggui-ai/agent-runtime/process` so consumers that
+ * don't spawn subprocesses (browser-side hubs, future test
+ * runners) never pull the `node:child_process` dep by loading the
+ * root barrel.
+ */
+import { spawn } from 'node:child_process';
+/** Default graceful-shutdown window before escalating to SIGKILL. */
+const DEFAULT_SHUTDOWN_TIMEOUT_MS = 5_000;
+/** Default readyCheck polling cadence. */
+const DEFAULT_READY_INTERVAL_MS = 250;
+/** Default readyCheck overall budget. */
+const DEFAULT_READY_TIMEOUT_MS = 30_000;
+/**
+ * Construct a framework-neutral subprocess adapter. The returned
+ * adapter carries no framework-specific behaviour; callers pin the
+ * framework by choosing `command` + `args`.
+ */
+export function createNodeProcessAgentRuntime(options) {
+    if (!options.command || options.command.length === 0) {
+        throw new TypeError('createNodeProcessAgentRuntime: `command` is required');
+    }
+    const name = options.name ?? 'node-process';
+    const spawnImpl = options.spawner ??
+        ((cmd, args, opts) => spawn(cmd, args, { ...opts, stdio: ['ignore', 'pipe', 'pipe'] }));
+    return {
+        name,
+        capabilities: {
+            observable: true,
+            restartable: false,
+        },
+        async start(input) {
+            const cwd = options.cwd ?? input.projectRoot;
+            const env = {
+                ...process.env,
+                ...options.env,
+                ...input.env,
+            };
+            const child = spawnImpl(options.command, options.args, { cwd, env });
+            const handle = new NodeProcessHandle({
+                child,
+                runId: `node-process-${child.pid ?? 'nopid'}-${Date.now()}`,
+                shutdownSignal: options.shutdownSignal ?? 'SIGTERM',
+                shutdownTimeoutMs: options.shutdownTimeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS,
+                maxLineBytes: options.maxLineBytes ?? 16_384,
+            });
+            if (input.signal) {
+                const onAbort = () => {
+                    void handle.stop();
+                };
+                if (input.signal.aborted) {
+                    queueMicrotask(onAbort);
+                }
+                else {
+                    input.signal.addEventListener('abort', onAbort, { once: true });
+                }
+            }
+            if (options.readyCheck) {
+                handle.runReadyCheck(options.readyCheck);
+            }
+            else {
+                handle.markReadyOnNextTick();
+            }
+            return handle;
+        },
+    };
+}
+/**
+ * Concrete handle wrapping a `ChildProcess`. Owns the lifecycle
+ * transitions and the stdout/stderr line fanout.
+ */
+class NodeProcessHandle {
+    runId;
+    _status = 'starting';
+    listeners = new Set();
+    child;
+    shutdownSignal;
+    shutdownTimeoutMs;
+    maxLineBytes;
+    stopping = false;
+    readyAbort = null;
+    stdoutBuffer = '';
+    stderrBuffer = '';
+    constructor(options) {
+        this.runId = options.runId;
+        this.child = options.child;
+        this.shutdownSignal = options.shutdownSignal;
+        this.shutdownTimeoutMs = options.shutdownTimeoutMs;
+        this.maxLineBytes = options.maxLineBytes;
+        this.child.stdout?.setEncoding('utf-8');
+        this.child.stderr?.setEncoding('utf-8');
+        this.child.stdout?.on('data', (chunk) => this.onChunk('stdout', chunk));
+        this.child.stderr?.on('data', (chunk) => this.onChunk('stderr', chunk));
+        this.child.on('error', (err) => {
+            this.emit({
+                type: 'error',
+                message: err instanceof Error ? err.message : String(err),
+                timestamp: Date.now(),
+            });
+        });
+        this.child.on('exit', (code, signal) => this.onExit(code, signal));
+    }
+    get status() {
+        return this._status;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    async stop() {
+        if (this._status === 'stopped' || this._status === 'crashed')
+            return;
+        if (this.stopping)
+            return;
+        this.stopping = true;
+        this.cancelReadyCheck();
+        if (this.child.exitCode !== null || this.child.signalCode !== null) {
+            // Already gone.
+            this.transitionTo('stopped');
+            return;
+        }
+        // Graceful request first.
+        this.child.kill(this.shutdownSignal);
+        // Escalate to SIGKILL if the child doesn't exit in time. We
+        // only escalate — the `exit` handler owns the final status
+        // transition once the kernel reports the process gone.
+        await new Promise((resolve) => {
+            const killTimer = setTimeout(() => {
+                try {
+                    this.child.kill('SIGKILL');
+                }
+                catch {
+                    // Already exited between checks.
+                }
+            }, this.shutdownTimeoutMs).unref?.();
+            this.child.once('exit', () => {
+                if (killTimer !== undefined)
+                    clearTimeout(killTimer);
+                resolve();
+            });
+        });
+    }
+    /**
+     * Schedule a ready transition on a macrotask. Called when
+     * there's no readyCheck configured — the adapter considers the
+     * child "ready" as soon as it exists. A `setTimeout(…, 0)`
+     * macrotask is deliberate: subscribers attached synchronously
+     * after `await adapter.start()` must land BEFORE the emit fires
+     * (microtasks would race with the `async` resolution). Guarded
+     * so an immediate stop() or crash doesn't raise `ready` over a
+     * terminal state.
+     */
+    markReadyOnNextTick() {
+        const timer = setTimeout(() => {
+            if (this._status === 'starting') {
+                this.transitionTo('ready');
+            }
+        }, 0);
+        timer.unref?.();
+    }
+    runReadyCheck(check) {
+        const abort = new AbortController();
+        this.readyAbort = abort;
+        void runHttpReadyCheck(check, abort.signal).then((result) => {
+            if (abort.signal.aborted)
+                return;
+            if (this._status !== 'starting')
+                return;
+            if (result.ok) {
+                this.transitionTo('ready');
+            }
+            else {
+                this.emit({
+                    type: 'error',
+                    message: `readyCheck failed: ${result.reason}`,
+                    timestamp: Date.now(),
+                });
+            }
+        }, (err) => {
+            if (abort.signal.aborted)
+                return;
+            const message = err instanceof Error ? err.message : String(err);
+            this.emit({ type: 'error', message, timestamp: Date.now() });
+        });
+    }
+    cancelReadyCheck() {
+        this.readyAbort?.abort();
+        this.readyAbort = null;
+    }
+    onChunk(stream, chunk) {
+        const buffer = stream === 'stdout' ? 'stdoutBuffer' : 'stderrBuffer';
+        let remaining = (this[buffer] + chunk);
+        let lineEnd = remaining.indexOf('\n');
+        while (lineEnd !== -1) {
+            const raw = remaining.slice(0, lineEnd).replace(/\r$/, '');
+            const line = raw.length > this.maxLineBytes ? `${raw.slice(0, this.maxLineBytes)}…` : raw;
+            this.emit({
+                type: 'log',
+                stream,
+                line,
+                timestamp: Date.now(),
+            });
+            remaining = remaining.slice(lineEnd + 1);
+            lineEnd = remaining.indexOf('\n');
+        }
+        this[buffer] = remaining;
+    }
+    onExit(code, signal) {
+        // Flush any tail-buffered output as a final line each.
+        for (const stream of ['stdout', 'stderr']) {
+            const key = stream === 'stdout' ? 'stdoutBuffer' : 'stderrBuffer';
+            const tail = this[key];
+            if (tail.length > 0) {
+                this.emit({
+                    type: 'log',
+                    stream,
+                    line: tail.replace(/\r$/, ''),
+                    timestamp: Date.now(),
+                });
+                this[key] = '';
+            }
+        }
+        this.cancelReadyCheck();
+        // Crashed vs stopped:
+        //   - `stop()` was called → stopping=true, we requested the exit.
+        //   - external signal we asked for (`shutdownSignal`) → stopped.
+        //   - non-zero exit code WITHOUT our request → crashed.
+        //   - zero exit code WITHOUT our request → stopped (graceful self-exit).
+        if (this.stopping) {
+            this.transitionTo('stopped');
+            return;
+        }
+        if (signal !== null) {
+            // Unexpected signal the dev-stack didn't send → crashed.
+            this.emit({
+                type: 'error',
+                message: `process terminated by signal ${signal}`,
+                timestamp: Date.now(),
+            });
+            this.transitionTo('crashed');
+            return;
+        }
+        if (code === 0) {
+            this.transitionTo('stopped');
+        }
+        else {
+            this.emit({
+                type: 'error',
+                message: `process exited with code ${code ?? 'null'}`,
+                timestamp: Date.now(),
+            });
+            this.transitionTo('crashed');
+        }
+    }
+    transitionTo(status) {
+        if (this._status === status)
+            return;
+        this.emit({ type: 'status', status, timestamp: Date.now() });
+    }
+    emit(event) {
+        if (event.type === 'status') {
+            this._status = event.status;
+        }
+        const snapshot = Array.from(this.listeners);
+        for (const listener of snapshot) {
+            try {
+                listener(event);
+            }
+            catch {
+                // A bad listener MUST NOT break fanout. Adapter-level
+                // errors surface through `error` events; a listener that
+                // throws is a consumer bug.
+            }
+        }
+    }
+}
+/**
+ * HTTP readiness probe. Polls `http://127.0.0.1:port<path>` at the
+ * configured interval until it gets a 2xx, the caller aborts, or
+ * the overall budget expires.
+ *
+ * Uses the built-in `fetch` with its own `AbortController` per
+ * request so a slow connect doesn't block the poll cadence. The
+ * outer `signal` cancels the whole loop on caller abort (handle
+ * shutdown).
+ */
+async function runHttpReadyCheck(check, signal) {
+    const interval = check.intervalMs ?? DEFAULT_READY_INTERVAL_MS;
+    const budget = check.timeoutMs ?? DEFAULT_READY_TIMEOUT_MS;
+    const path = check.path ?? '/';
+    const url = `http://127.0.0.1:${check.port}${path.startsWith('/') ? path : `/${path}`}`;
+    const start = Date.now();
+    while (!signal.aborted) {
+        if (Date.now() - start > budget) {
+            return { ok: false, reason: `timeout after ${budget}ms probing ${url}` };
+        }
+        const perRequest = AbortSignal.timeout
+            ? AbortSignal.timeout(Math.max(interval, 100))
+            : undefined;
+        try {
+            const res = await fetch(url, { signal: perRequest });
+            if (res.ok)
+                return { ok: true };
+        }
+        catch {
+            // Not reachable yet — fall through to the sleep.
+        }
+        if (signal.aborted)
+            return { ok: false, reason: 'aborted' };
+        await sleep(interval, signal);
+    }
+    return { ok: false, reason: 'aborted' };
+}
+function sleep(ms, signal) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref?.();
+        signal.addEventListener('abort', () => {
+            clearTimeout(timer);
+            resolve();
+        }, { once: true });
+    });
+}

package/dist/stub.d.ts

@@ -0,0 +1,70 @@
+/**
+ * In-memory stub adapter — a reference implementation that
+ * `@ggui-ai/dev-stack` tests, the hub's dev fixtures, and contract
+ * tests in this package use to exercise the seam without spawning
+ * real processes.
+ *
+ * The stub's behaviour is deterministic and fully controlled by
+ * the caller:
+ *
+ *   - `start()` immediately transitions `starting → ready` via a
+ *     status event, unless `manualReady` is set (in which case the
+ *     caller drives the transition through the returned controller).
+ *   - `stop()` transitions whatever-the-current-state is →
+ *     `stopped` and resolves after all pending listeners have seen
+ *     the event.
+ *   - The returned controller lets tests emit arbitrary log / error
+ *     events, flip status programmatically, and assert against
+ *     whatever timing shape they care about.
+ *
+ * The stub is the shape new adapter implementations should imitate
+ * for their own event-loop plumbing: fanout set, single `status`
+ * field, idempotent stop, no global state.
+ */
+import type { AgentRuntimeAdapter, AgentRuntimeHandle, AgentRuntimeStartInput, AgentRuntimeStatus } from './types.js';
+export interface StubAgentRuntimeOptions {
+    /** Identifier surfaced via `adapter.name`. Defaults to `'stub'`. */
+    readonly name?: string;
+    /**
+     * When `true`, `start()` returns a handle in `starting` without
+     * emitting `ready`. Tests drive the transition via
+     * {@link StubAgentRuntimeController.emitStatus}.
+     */
+    readonly manualReady?: boolean;
+}
+/**
+ * Side-channel controller returned from
+ * {@link createStubAgentRuntime}. Production code should never hold
+ * one of these; they exist so tests can simulate arbitrary adapter
+ * behaviour.
+ */
+export interface StubAgentRuntimeController {
+    /** Inputs the last `start()` call received. `null` before start. */
+    lastInput(): AgentRuntimeStartInput | null;
+    /** All handles ever produced (one per `start()`). */
+    handles(): readonly AgentRuntimeHandle[];
+    /**
+     * Inject a status event on the latest handle. Updates the handle's
+     * declarative `status` too.
+     */
+    emitStatus(status: AgentRuntimeStatus): void;
+    /** Inject a log event on the latest handle. */
+    emitLog(stream: 'stdout' | 'stderr', line: string): void;
+    /** Inject an error event on the latest handle. */
+    emitError(message: string): void;
+    /** Fail the next `start()` call with the given error. */
+    failNextStart(error: Error): void;
+}
+/**
+ * Construct a stub adapter + controller pair.
+ *
+ *     const { adapter, controller } = createStubAgentRuntime();
+ *     const handle = await adapter.start({ … });
+ *     controller.emitLog('stderr', 'boot fail');
+ *     await handle.stop();
+ */
+export declare function createStubAgentRuntime(options?: StubAgentRuntimeOptions): {
+    adapter: AgentRuntimeAdapter;
+    controller: StubAgentRuntimeController;
+};
+//# sourceMappingURL=stub.d.ts.map

package/dist/stub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stub.d.ts","sourceRoot":"","sources":["../src/stub.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EACV,mBAAmB,EAEnB,kBAAkB,EAElB,sBAAsB,EACtB,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,uBAAuB;IACtC,oEAAoE;IACpE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEvB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,0BAA0B;IACzC,oEAAoE;IACpE,SAAS,IAAI,sBAAsB,GAAG,IAAI,CAAC;IAC3C,qDAAqD;IACrD,OAAO,IAAI,SAAS,kBAAkB,EAAE,CAAC;IACzC;;;OAGG;IACH,UAAU,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC7C,+CAA+C;IAC/C,OAAO,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzD,kDAAkD;IAClD,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,yDAAyD;IACzD,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACnC;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,GAAE,uBAA4B,GACpC;IACD,OAAO,EAAE,mBAAmB,CAAC;IAC7B,UAAU,EAAE,0BAA0B,CAAC;CACxC,CA8EA"}

package/dist/stub.js

@@ -0,0 +1,160 @@
+/**
+ * Construct a stub adapter + controller pair.
+ *
+ *     const { adapter, controller } = createStubAgentRuntime();
+ *     const handle = await adapter.start({ … });
+ *     controller.emitLog('stderr', 'boot fail');
+ *     await handle.stop();
+ */
+export function createStubAgentRuntime(options = {}) {
+    const name = options.name ?? 'stub';
+    const manualReady = options.manualReady ?? false;
+    const handles = [];
+    let lastInput = null;
+    let nextStartError = null;
+    const adapter = {
+        name,
+        capabilities: {
+            observable: true,
+            restartable: false,
+        },
+        async start(input) {
+            lastInput = input;
+            if (nextStartError) {
+                const err = nextStartError;
+                nextStartError = null;
+                throw err;
+            }
+            const handle = new StubHandle(`stub-run-${handles.length + 1}`, {
+                signal: input.signal,
+            });
+            handles.push(handle);
+            // Emit ready asynchronously unless the caller wants to drive it.
+            // A `setTimeout(…, 0)` macrotask guarantees the emit lands AFTER
+            // the caller's sync code post-`await adapter.start()` has run —
+            // so `handle.subscribe(…)` attached right after the await still
+            // catches the ready event. `queueMicrotask` would fire before the
+            // subscriber was registered because `async` resolution is also a
+            // microtask.
+            if (!manualReady) {
+                const timer = setTimeout(() => {
+                    handle.emitIfStarting({
+                        type: 'status',
+                        status: 'ready',
+                        timestamp: Date.now(),
+                    });
+                }, 0);
+                timer.unref?.();
+            }
+            return handle;
+        },
+    };
+    const controller = {
+        lastInput: () => lastInput,
+        handles: () => handles,
+        emitStatus(status) {
+            currentHandle(handles).emit({
+                type: 'status',
+                status,
+                timestamp: Date.now(),
+            });
+        },
+        emitLog(stream, line) {
+            currentHandle(handles).emit({
+                type: 'log',
+                stream,
+                line,
+                timestamp: Date.now(),
+            });
+        },
+        emitError(message) {
+            currentHandle(handles).emit({
+                type: 'error',
+                message,
+                timestamp: Date.now(),
+            });
+        },
+        failNextStart(error) {
+            nextStartError = error;
+        },
+    };
+    return { adapter, controller };
+}
+function currentHandle(handles) {
+    const latest = handles.at(-1);
+    if (!latest) {
+        throw new Error('stub adapter has no active handle — call start() first');
+    }
+    return latest;
+}
+/**
+ * Concrete handle implementation. Extracted so the stub adapter +
+ * future in-package adapters can share the same event fanout
+ * plumbing without depending on Node internals.
+ */
+class StubHandle {
+    runId;
+    _status = 'starting';
+    listeners = new Set();
+    stopped = false;
+    constructor(runId, options = {}) {
+        this.runId = runId;
+        if (options.signal) {
+            const onAbort = () => {
+                void this.stop();
+            };
+            if (options.signal.aborted) {
+                queueMicrotask(onAbort);
+            }
+            else {
+                options.signal.addEventListener('abort', onAbort, { once: true });
+            }
+        }
+    }
+    get status() {
+        return this._status;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    emit(event) {
+        if (event.type === 'status') {
+            this._status = event.status;
+        }
+        // Snapshot first so a listener that unsubscribes mid-fanout
+        // doesn't skip another listener in the same tick.
+        const snapshot = Array.from(this.listeners);
+        for (const listener of snapshot) {
+            try {
+                listener(event);
+            }
+            catch {
+                // A bad listener MUST NOT break fanout to its peers.
+                // Adapter-level errors surface through `error` events; a
+                // listener that throws is a consumer bug.
+            }
+        }
+    }
+    /**
+     * Emit iff the handle is still in `starting`. Used by the
+     * deferred auto-ready path so an aborted / explicitly-stopped
+     * handle doesn't reawaken as `ready` when the timer fires.
+     */
+    emitIfStarting(event) {
+        if (this._status !== 'starting')
+            return;
+        this.emit(event);
+    }
+    async stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        this.emit({ type: 'status', status: 'stopped', timestamp: Date.now() });
+        // A real adapter awaits subprocess exit here. The stub has
+        // nothing to wait on — but the microtask-synchronous emit
+        // keeps timing predictable for tests.
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Agent runtime adapter seam — the one public contract for
+ * "something that runs an agent and can be supervised by
+ * `@ggui-ai/dev-stack` or any other host."
+ *
+ * Design rules (locked 2026-04-18):
+ *
+ * 1. **Framework-neutral.** No Claude / OpenAI / Vercel-AI / LangGraph
+ *    assumption leaks into this interface. Adapter authors translate
+ *    their framework's idioms into this shape, not the other way
+ *    around. `tsx watch src/index.ts` is a reference adapter — not
+ *    the architecture.
+ *
+ * 2. **Node-free.** These types MUST NOT import from `node:*`. A
+ *    browser-side host (the local dev hub, a cloud control plane,
+ *    a test runner) needs to consume the adapter's events without
+ *    pulling subprocess / fs APIs in. Reference adapters that DO
+ *    spawn subprocesses live behind secondary subpaths (`./process`,
+ *    `./stub`) so consumers opt in.
+ *
+ * 3. **Events are the runtime truth.** A handle exposes a declarative
+ *    `status` for one-shot queries, but the authoritative state lives
+ *    in the event stream (`status` → `log` → `error`). Consumers that
+ *    care about liveness subscribe; those that only need a
+ *    point-in-time probe read `status`.
+ *
+ * 4. **Capabilities are data, not duck typing.** Hosts inspect
+ *    `capabilities.restartable` / `.observable` before calling
+ *    methods that might not exist. Keeps the seam declarative even
+ *    when adapters grow feature flags.
+ *
+ * 5. **Dependency direction.** `dev-stack` → `agent-runtime` only.
+ *    Never the reverse. This lets future non-dev hosts (bench
+ *    runners, remote supervisors) consume the same adapters without
+ *    pulling the dev server in.
+ */
+/**
+ * Point-in-time status of a running adapter.
+ *
+ * - `starting` — `start()` has been called; the adapter is
+ *   bootstrapping. The handle is already returned; status events
+ *   will surface progress.
+ * - `ready` — the underlying agent process / worker / service is
+ *   healthy and accepting work.
+ * - `stopped` — `stop()` was called and completed, or the adapter
+ *   shut itself down cleanly (graceful exit).
+ * - `crashed` — the adapter terminated without a request. Hosts
+ *   decide whether to restart; adapters MAY self-restart only when
+ *   `capabilities.restartable === true`.
+ */
+export type AgentRuntimeStatus = 'starting' | 'ready' | 'stopped' | 'crashed';
+/**
+ * Event the adapter emits through the handle's subscription.
+ *
+ * Delivery is at-least-once — consumers dedupe where it matters.
+ * Ordering is preserved per-adapter; cross-adapter ordering is not.
+ */
+export type AgentRuntimeEvent = {
+    type: 'status';
+    status: AgentRuntimeStatus;
+    timestamp: number;
+} | {
+    type: 'log';
+    stream: 'stdout' | 'stderr';
+    line: string;
+    timestamp: number;
+} | {
+    type: 'error';
+    message: string;
+    timestamp: number;
+};
+/** Listener shape — hosts register one of these via `handle.subscribe`. */
+export type AgentRuntimeListener = (event: AgentRuntimeEvent) => void;
+/**
+ * Capability probe. Callers branch the UI / supervision policy on
+ * these instead of poking at optional methods at runtime.
+ */
+export interface AgentRuntimeCapabilities {
+    /**
+     * `true` if the adapter emits a non-empty event stream during its
+     * run (at minimum, a `status: 'ready'` event after boot). `false`
+     * for adapters that only support start/stop/status polling.
+     */
+    readonly observable: boolean;
+    /**
+     * `true` if the adapter's `restart()` is safe to call on an active
+     * handle. Adapters that need a full stop-then-start cycle leave
+     * this `false` and hosts compose their own restart.
+     */
+    readonly restartable: boolean;
+}
+/**
+ * Minimal identity of the ggui project the adapter is being asked
+ * to run. The adapter MAY use `slug` / `name` in logs or in the
+ * process title; it MUST NOT assume anything beyond these fields
+ * are present.
+ *
+ * `protocol` carries the ggui protocol version (e.g. `'1.1'`) so
+ * adapters that generate boilerplate / pass protocol headers to
+ * their framework can stay in lockstep with the manifest.
+ */
+export interface AgentRuntimeProjectIdentity {
+    readonly slug: string;
+    readonly name: string;
+    readonly protocol: string;
+}
+/**
+ * Input passed to {@link AgentRuntimeAdapter.start}. Intentionally
+ * narrow — adapters accept extra configuration through their own
+ * factory functions; this shape is the common subset every adapter
+ * MUST handle.
+ */
+export interface AgentRuntimeStartInput {
+    /**
+     * Absolute project root (directory that contains `ggui.json`).
+     * Adapters resolve entry files / env files relative to this.
+     */
+    readonly projectRoot: string;
+    /** The loaded project identity (see above). */
+    readonly project: AgentRuntimeProjectIdentity;
+    /**
+     * Optional entry hint. Adapter-specific interpretation — a
+     * subprocess adapter might treat this as the script path; a worker
+     * adapter might treat it as a module name. `undefined` lets the
+     * adapter fall back to its own default.
+     */
+    readonly entry?: string;
+    /**
+     * Environment variables to forward into the runtime. Adapter MUST
+     * NOT leak `process.env` keys that aren't in this record — hosts
+     * explicitly opt into what crosses the boundary.
+     */
+    readonly env?: Readonly<Record<string, string>>;
+    /**
+     * Port hint. Adapters that bind a socket SHOULD honour it when
+     * available, or pick the next free port and surface the chosen
+     * value via a status event.
+     */
+    readonly portHint?: number;
+    /**
+     * Abort signal. Aborting is equivalent to calling
+     * {@link AgentRuntimeHandle.stop} on the returned handle — hosts
+     * that want fire-and-forget cleanup pass a signal instead of
+     * holding the handle.
+     */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Running-instance handle returned from {@link AgentRuntimeAdapter.start}.
+ *
+ * Every method is idempotent when called on an already-terminal
+ * state: `stop()` on a stopped handle is a no-op; a second
+ * `subscribe()` after `stop()` is allowed (returns an unsubscribe
+ * that does nothing) but MAY be rejected with a clear error by the
+ * adapter if desired.
+ */
+export interface AgentRuntimeHandle {
+    /** Opaque id unique per run. Adapter decides the format. */
+    readonly runId: string;
+    /**
+     * Declarative snapshot. Reflects the last status event the adapter
+     * emitted; consumers that need real-time progress should
+     * `subscribe` instead.
+     */
+    readonly status: AgentRuntimeStatus;
+    /**
+     * Subscribe to events. Returns an unsubscribe function.
+     * At-least-once delivery; listeners MUST be idempotent.
+     */
+    subscribe(listener: AgentRuntimeListener): () => void;
+    /**
+     * Stop the runtime. Resolves after the adapter has completed its
+     * teardown (process exit, worker termination, server close —
+     * adapter-specific).
+     */
+    stop(): Promise<void>;
+}
+/**
+ * The adapter interface. Implementations translate a specific agent
+ * framework / process model into the seam's shape.
+ *
+ * Minimal reference adapters live in this package under secondary
+ * subpaths (`./stub` for tests, `./process` for subprocess-based
+ * runtimes). Framework-specific adapters (Claude Agent SDK, OpenAI
+ * Agents, Vercel AI SDK) belong in their own packages so pulling
+ * the seam in doesn't drag an SDK's dependency graph along.
+ */
+export interface AgentRuntimeAdapter {
+    /** Human-readable identifier — used in logs and the hub UI. */
+    readonly name: string;
+    /** Capability probe — see {@link AgentRuntimeCapabilities}. */
+    readonly capabilities: AgentRuntimeCapabilities;
+    /**
+     * Boot the runtime. Resolves once the handle is safe to return —
+     * the agent may still be `starting`; `status: 'ready'` surfaces
+     * via the event stream.
+     *
+     * Throws only on permanent start-time errors (missing entry,
+     * malformed config). Runtime crashes after boot travel through
+     * the event stream + `handle.status === 'crashed'`.
+     */
+    start(input: AgentRuntimeStartInput): Promise<AgentRuntimeHandle>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,kBAAkB,GAAG,UAAU,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAC;AAE9E;;;;;GAKG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,kBAAkB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACjE;IACE,IAAI,EAAE,KAAK,CAAC;IACZ,MAAM,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB,GACD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D,2EAA2E;AAC3E,MAAM,MAAM,oBAAoB,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAC;AAEtE;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAE7B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;GAKG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,EAAE,2BAA2B,CAAC;IAE9C;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB;;;;OAIG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAEhD;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAE3B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IACjC,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAEvB;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IAEpC;;;OAGG;IACH,SAAS,CAAC,QAAQ,EAAE,oBAAoB,GAAG,MAAM,IAAI,CAAC;IAEtD;;;;OAIG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACvB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,+DAA+D;IAC/D,QAAQ,CAAC,YAAY,EAAE,wBAAwB,CAAC;IAEhD;;;;;;;;OAQG;IACH,KAAK,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACnE"}

package/dist/types.js

@@ -0,0 +1,37 @@
+/**
+ * Agent runtime adapter seam — the one public contract for
+ * "something that runs an agent and can be supervised by
+ * `@ggui-ai/dev-stack` or any other host."
+ *
+ * Design rules (locked 2026-04-18):
+ *
+ * 1. **Framework-neutral.** No Claude / OpenAI / Vercel-AI / LangGraph
+ *    assumption leaks into this interface. Adapter authors translate
+ *    their framework's idioms into this shape, not the other way
+ *    around. `tsx watch src/index.ts` is a reference adapter — not
+ *    the architecture.
+ *
+ * 2. **Node-free.** These types MUST NOT import from `node:*`. A
+ *    browser-side host (the local dev hub, a cloud control plane,
+ *    a test runner) needs to consume the adapter's events without
+ *    pulling subprocess / fs APIs in. Reference adapters that DO
+ *    spawn subprocesses live behind secondary subpaths (`./process`,
+ *    `./stub`) so consumers opt in.
+ *
+ * 3. **Events are the runtime truth.** A handle exposes a declarative
+ *    `status` for one-shot queries, but the authoritative state lives
+ *    in the event stream (`status` → `log` → `error`). Consumers that
+ *    care about liveness subscribe; those that only need a
+ *    point-in-time probe read `status`.
+ *
+ * 4. **Capabilities are data, not duck typing.** Hosts inspect
+ *    `capabilities.restartable` / `.observable` before calling
+ *    methods that might not exist. Keeps the seam declarative even
+ *    when adapters grow feature flags.
+ *
+ * 5. **Dependency direction.** `dev-stack` → `agent-runtime` only.
+ *    Never the reverse. This lets future non-dev hosts (bench
+ *    runners, remote supervisors) consume the same adapters without
+ *    pulling the dev server in.
+ */
+export {};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@ggui-ai/agent-runtime",
+  "version": "0.1.0-rc.1",
+  "description": "Pluggable adapter seam for supervising whatever actually runs an agent — the Claude Agent SDK, OpenAI Agents, the Vercel AI SDK, a plain subprocess, and more. Lets a host swap agent runtimes without hardcoding any framework into its dev loop.",
+  "keywords": [
+    "ggui",
+    "agent",
+    "agent-runtime",
+    "adapter",
+    "claude-agent-sdk"
+  ],
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./process": {
+      "types": "./dist/process.d.ts",
+      "import": "./dist/process.js",
+      "default": "./dist/process.js"
+    }
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ggui-ai/ggui.git",
+    "directory": "packages/agent-runtime"
+  },
+  "homepage": "https://github.com/ggui-ai/ggui/tree/main/packages/agent-runtime",
+  "bugs": {
+    "url": "https://github.com/ggui-ai/ggui/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "author": "ggui contributors <hello@ggui.ai>",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}