@skaile/forge-agent-runtime 1.0.0 → 1.1.0

package/dist/shared/forge-agent-runtime.DlNAoPjs.d.ts

@@ -0,0 +1,122 @@
+import { AIProviderRegistryView } from '@skaile/forge-settings/server';
+
+/**
+ * AgentAdapter — canonical interface for forge agent harnesses.
+ *
+ * Every harness (omp, claude-sdk, codex, …) runs behind an adapter that
+ * implements this interface. Apps depend only on this contract, not the
+ * concrete adapter type.
+ *
+ * Lifecycle:
+ *   1. Call `connect(config)` — spawns the subprocess or initialises the SDK client.
+ *   2. Call `sendCommand(cmd)` to dispatch prompts and control commands.
+ *   3. Call `listen()` to consume the async event stream.
+ *   4. Call `abort()` to cancel an in-flight turn.
+ *   5. Call `disconnect()` to tear down cleanly.
+ *
+ * Adapters are STATEFUL: one instance per active agent session.
+ */
+
+/** Input to the agent: a natural-language prompt or a control message. */
+interface AgentCommand {
+    type: string;
+    [key: string]: unknown;
+}
+/** Output from the agent: any typed event from the skaile protocol. */
+interface AgentEvent {
+    type: string;
+    [key: string]: unknown;
+}
+/** Observable lifecycle state of an adapter instance. */
+type AgentStatus = "idle" | "running" | "error" | "disconnected";
+/**
+ * Configuration passed to `AgentAdapter.connect()`.
+ *
+ * All fields mirror `AgentProcessConfig` from `agent-process.ts`
+ * so the ProcessManagerAdapter can pass them through unchanged.
+ */
+interface AgentAdapterConfig {
+    /** Working directory for the agent (--project-dir) */
+    projectDir: string;
+    /** Bridge harness type (omp, claude-sdk). Defaults to 'omp'. */
+    harness?: string;
+    /**
+     * The AI provider registry the session runs against. The adapter resolves
+     * each enabled entry's credential reference and delivers it through the
+     * child environment.
+     */
+    registry?: AIProviderRegistryView;
+    /**
+     * Registry entry ids the session is restricted to (`--providers a,b`).
+     * Absent or empty: the session sees the whole registry. `registry` should
+     * already be narrowed to the same ids so only their credentials are delivered.
+     */
+    providers?: string[];
+    /**
+     * The layered environment `env:` references resolve against and the child
+     * env is based on; defaults to `process.env`.
+     */
+    credentialEnv?: Record<string, string | undefined>;
+    /** Model selection as `"<providerId>/<modelId>"`, a bare model id, or `@role` */
+    model?: string;
+    /** Environment variables injected into the subprocess */
+    env?: Record<string, string>;
+    /** System prompt written to .skaile/system-prompt.md before spawn */
+    systemPrompt?: string;
+    /** Max agentic turns */
+    maxTurns?: number;
+    /** GitAgent definition directory */
+    agentDir?: string;
+    /** OMP harness session ID for native resume */
+    harnessSessionId?: string;
+    /** Address the subprocess binds and the client dials. Absent: runtime default bind, dial `127.0.0.1`. */
+    host?: string;
+    /** Bearer token the subprocess WebSocket requires and the client presents. Absent: no authentication. */
+    wsAuthToken?: string;
+}
+/**
+ * Canonical interface for all forge agent harnesses.
+ *
+ * Implementations wrap the `AgentProcessManager` pattern used by the existing
+ * forge apps, exposing a minimal async API that higher-level managers consume.
+ */
+interface AgentAdapter {
+    /**
+     * Connect to the agent harness and prepare it for commands.
+     * Must be called once before `sendCommand` or `listen`.
+     */
+    connect(config: AgentAdapterConfig): Promise<void>;
+    /**
+     * Send a command to the connected agent.
+     * Throws if `connect()` has not been called or the session has disconnected.
+     */
+    sendCommand(command: AgentCommand): Promise<void>;
+    /**
+     * Return an async iterable of agent events.
+     * The iterable completes when the adapter disconnects.
+     *
+     * Callers can use `for await (const event of adapter.listen()) { ... }` or
+     * subscribe via an EventEmitter bridge (see BaseAgentManager).
+     */
+    listen(): AsyncIterable<AgentEvent>;
+    /**
+     * Cancel the current in-flight agent turn.
+     * No-op if the agent is idle.
+     */
+    abort(): Promise<void>;
+    /**
+     * Whether the adapter is connected and the agent is ready to receive commands.
+     */
+    isConnected(): boolean;
+    /**
+     * Observable lifecycle state.
+     */
+    getStatus(): AgentStatus;
+    /**
+     * Tear down the adapter: disconnect, stop subprocess if applicable, release resources.
+     * Safe to call multiple times.
+     */
+    disconnect(): Promise<void>;
+}
+
+export type { AgentEvent as A, AgentAdapter as a, AgentAdapterConfig as b, AgentCommand as c, AgentStatus as d };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skaile/forge-agent-runtime",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Agent process lifecycle for Skaile forge apps: spawns `skaile serve`, connects over WebSocket, and exposes the AgentAdapter, harness registry and session manager. Node-only.",
   "type": "module",
   "packageManager": "bun@1.3.9",
@@ -10,6 +10,10 @@
     ".": {
       "types": "./dist/index.d.mts",
       "import": "./dist/index.mjs"
+    },
+    "./app-runner-host": {
+      "types": "./dist/app-runner-host/index.d.mts",
+      "import": "./dist/app-runner-host/index.mjs"
     }
   },
   "files": [
@@ -39,7 +43,7 @@
   },
   "dependencies": {
     "@skaile/forge-settings": "^1.0.0",
-    "@skaile/workspaces": "^6.0.0",
+    "@skaile/workspaces": "^6.11.0",
     "consola": "^3.4.2",
     "picocolors": "^1.1.1"
   },