@skaile/forge-agent-runtime 0.0.0-stage → 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,593 @@
+import { EventEmitter } from 'node:events';
+import { AgentClient } from '@skaile/workspaces/sdk/client';
+import { AgentCommand as AgentCommand$1, AgentEvent as AgentEvent$1, MessageV2 } from '@skaile/workspaces/sdk/types';
+import { AIProviderRegistryView } from '@skaile/forge-settings/server';
+import { SubscriberTransport, SessionDispatcher, MessageStore } from '@skaile/workspaces/sdk/session';
+
+/**
+ * AgentProcessManager — spawns `skaile serve` subprocesses and connects via WebSocket.
+ *
+ * Replaces direct `createHarness()` calls in forge apps. Each session gets an isolated
+ * subprocess running the full agent runtime (harness, connectors, skills) and communicates
+ * via the AgentCommand/AgentEvent WebSocket protocol.
+ *
+ * Uses `WebSocketClientTransport` from `@skaile/agent-transport` for typed protocol
+ * handling, reconnection with exponential backoff, and heartbeat keepalive.
+ *
+ * Usage:
+ *   const manager = new AgentProcessManager()
+ *   await manager.create('my-session', { projectDir: '/path', ... })
+ *   manager.on('event:my-session', (event) => { ... })
+ *   await manager.prompt('my-session', 'Hello')
+ *   await manager.shutdown('my-session')
+ */
+
+interface AgentProcessConfig {
+    /** Working directory for the agent (--project-dir) */
+    projectDir: string;
+    /** Bridge harness type (omp, pi, claude-sdk) */
+    harness?: string;
+    /**
+     * Model selection passed through as `--model`: `"<providerId>/<modelId>"`,
+     * where `providerId` is a registry entry id. A bare model id and an `@role`
+     * alias also resolve — the runtime does that against its own registry.
+     */
+    model?: string;
+    /**
+     * The AI provider registry this session runs against. Every enabled entry's
+     * credential is resolved at spawn and delivered through the child
+     * environment as `SKAILE_AIP_<ID>_KEY`, which is the *name* the harness
+     * adapters write into the config they render. No secret is ever passed as an
+     * argument or written to a file by forge.
+     */
+    registry?: AIProviderRegistryView;
+    /**
+     * Registry entry ids the session is restricted to, passed as
+     * `--providers a,b`. Narrowing `registry` to the same ids is the caller's
+     * job — it decides which credentials are delivered; this decides which
+     * entries the spawned runtime keeps. Empty or absent: no restriction.
+     */
+    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>;
+    /** Environment variables — merged over the base environment and the resolved credentials */
+    env?: Record<string, string>;
+    /** System prompt — sent via configure message after connect */
+    systemPrompt?: string;
+    /** Max agentic turns */
+    maxTurns?: number;
+    /** GitAgent definition directory (--agent-dir) */
+    agentDir?: string;
+    /** Prompts directory for command injection */
+    promptsDir?: string;
+    /** SSH key path for git operations */
+    sshKeyPath?: string;
+    /**
+     * OMP harness session ID from a prior run. When set, injected as
+     * `SKAILE_RESUME_SESSION_ID` into the subprocess environment so the
+     * `skaile serve` subprocess passes it to OMP via `--session <id>`,
+     * restoring OMP's native conversation context without history injection.
+     */
+    harnessSessionId?: string;
+    /**
+     * Address `skaile serve` binds (`--host`) and this manager dials. Absent: the
+     * runtime's default bind (all interfaces) and a client dial on `127.0.0.1`.
+     * A host that must keep the child private passes `127.0.0.1`.
+     */
+    host?: string;
+    /**
+     * Bearer token the child's WebSocket requires. Delivered to the child as
+     * `SKAILE_WS_AUTH_TOKEN` (the runtime removes it from its own environment at
+     * startup, so agent processes never see it) and presented by the client
+     * transport. Absent: the socket stays unauthenticated, as before.
+     */
+    wsAuthToken?: string;
+}
+declare class AgentProcessManager extends EventEmitter {
+    private processes;
+    constructor();
+    /**
+     * Spawn a `skaile serve` subprocess and connect via WebSocket transport.
+     * Resolves when the subprocess is ready and transport is connected.
+     */
+    create(id: string, config: AgentProcessConfig): Promise<void>;
+    /**
+     * Send a prompt to the agent subprocess.
+     */
+    prompt(id: string, message: string): Promise<void>;
+    /**
+     * Cancel the current agent operation.
+     */
+    cancel(id: string): Promise<void>;
+    /**
+     * Gracefully shut down a subprocess.
+     */
+    shutdown(id: string): Promise<void>;
+    /**
+     * Check if a subprocess is connected and ready.
+     */
+    isConnected(id: string): boolean;
+    /**
+     * Check if a session exists (regardless of connection state).
+     */
+    has(id: string): boolean;
+    /**
+     * Send any AgentCommand to the managed process.
+     * Used internally by ProcessManagerClientTransport.
+     */
+    sendCommand(id: string, command: AgentCommand$1): void;
+    /**
+     * Create an AgentClient for a managed session.
+     * Uses ProcessManagerClientTransport so there is no second subscription
+     * on the underlying WebSocket transport. Disposing the client will
+     * gracefully shut down the subprocess via manager.shutdown().
+     *
+     * Throws if the session does not exist. The session must be connected
+     * (isConnected() === true) before any commands can be sent.
+     */
+    createAgentClient(id: string): AgentClient;
+    private shutdownSync;
+    private waitForReady;
+}
+
+/**
+ * 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>;
+}
+
+/**
+ * ProcessManagerAdapter — AgentAdapter implementation backed by AgentProcessManager.
+ *
+ * Wraps the existing `AgentProcessManager` (spawns `skaile serve` subprocess,
+ * connects via WebSocket) so apps can use it through the canonical AgentAdapter
+ * interface without coupling to the process manager directly.
+ *
+ * One instance per active session.
+ */
+declare class ProcessManagerAdapter implements AgentAdapter {
+    private readonly processManager;
+    private readonly emitter;
+    private processKey;
+    private status;
+    constructor();
+    connect(config: AgentAdapterConfig): Promise<void>;
+    sendCommand(command: AgentCommand): Promise<void>;
+    listen(): AsyncIterable<AgentEvent>;
+    abort(): Promise<void>;
+    isConnected(): boolean;
+    getStatus(): AgentStatus;
+    disconnect(): Promise<void>;
+    /**
+     * Internal: push an event into the async iterable queue.
+     * Exposed with underscore prefix for test injection.
+     */
+    _pushEvent(event: AgentEvent): void;
+    /**
+     * Set a custom process key (used by apps that namespace keys as 'userId:slug:mode').
+     * Must be called before `connect()`.
+     */
+    setProcessKey(key: string): void;
+    /**
+     * Access the underlying AgentProcessManager for advanced use cases
+     * (e.g. createAgentClient() needed by SessionDispatcher construction).
+     */
+    getProcessManager(): AgentProcessManager;
+}
+
+type AdapterFactory = () => AgentAdapter;
+/**
+ * Create an adapter instance for the given harness name.
+ *
+ * Falls back to 'omp' if the harness is not registered.
+ * The caller must still call `adapter.connect(config)` with the harness name
+ * in `config.harness` so the subprocess receives the correct --harness flag.
+ */
+declare function createAdapterForHarness(harness: string): AgentAdapter;
+/**
+ * Register a custom adapter factory.
+ *
+ * Use this in tests or for experimental harnesses without touching the built-in list.
+ */
+declare function registerHarness(name: string, factory: AdapterFactory): void;
+/**
+ * Return all registered harness names.
+ */
+declare function listRegisteredHarnesses(): string[];
+
+/**
+ * EventEmitter-backed `SubscriberTransport` for forge SSE endpoints.
+ *
+ * One instance is created per session. SSE connections register via the
+ * concrete `listen()` method (not part of the `SubscriberTransport` interface)
+ * and receive an unsubscribe function for cleanup on connection close.
+ *
+ * @example
+ * ```ts
+ * const transport = new EventEmitterSubscriberTransport()
+ *
+ * // In an SSE endpoint handler:
+ * const stop = transport.listen('conn-123', (event) => {
+ *   res.write(`data: ${JSON.stringify(event)}\n\n`)
+ * })
+ * // On connection close:
+ * stop()
+ * ```
+ */
+declare class EventEmitterSubscriberTransport implements SubscriberTransport {
+    private readonly emitter;
+    /**
+     * Push an event to all listeners registered for this subscriber ID.
+     *
+     * Part of the `SubscriberTransport` interface — called by `SessionDispatcher`
+     * when the agent emits an event.
+     *
+     * @param subscriberId - ID of the subscriber connection to notify.
+     * @param event - Agent event to broadcast.
+     */
+    send(subscriberId: string, event: AgentEvent$1): void;
+    /**
+     * Remove all listeners for a subscriber ID.
+     *
+     * Part of the `SubscriberTransport` interface — called by `SessionDispatcher`
+     * when a subscriber disconnects or the session ends.
+     *
+     * @param subscriberId - ID of the subscriber whose listeners should be cleared.
+     */
+    remove(subscriberId: string): void;
+    /**
+     * Register a per-connection event handler and return an unsubscribe function.
+     *
+     * Not part of the `SubscriberTransport` interface — used directly by SSE route handlers.
+     *
+     * @param subscriberId - Unique identifier for this SSE connection.
+     * @param handler - Called for each agent event broadcast to this subscriber.
+     * @returns Cleanup function — call when the SSE connection closes.
+     */
+    listen(subscriberId: string, handler: (event: AgentEvent$1) => void): () => void;
+}
+
+/**
+ * The in-memory session record maintained by BaseAgentManager.
+ *
+ * Mirrors the `AgentSession` / `ManagedSession` interfaces in each app's
+ * agent-manager.ts but without app-specific fields (mode, processKey, etc.)
+ * Those remain in the app-level subclass.
+ */
+interface ManagedSession {
+    sessionId: string;
+    dispatcher: SessionDispatcher;
+    subscriberTransport: EventEmitterSubscriberTransport;
+    isStreaming: boolean;
+    error: string | null;
+    /** Call to unregister the event handler from processManager. */
+    removeEventHandler?: () => void;
+}
+/**
+ * BaseAgentManager — shared session lifecycle for forge agent-manager singletons.
+ *
+ * Handles the boilerplate that is identical across forge-workspace,
+ * forge-assistant, and forge-project:
+ *   - AgentProcessManager ownership
+ *   - JsonlMessageStore + EventEmitterSubscriberTransport + SessionDispatcher creation
+ *   - Event handler wiring: streaming-state tracking, error tracking, SSE fan-out
+ *   - Session teardown (removeEventHandler + dispatcher.disconnect)
+ *
+ * Subclasses implement:
+ *   - `buildProcessKey(sessionId)` — e.g. 'work', 'assistant:uuid', 'userId:slug:mode'
+ *   - `buildAdapterConfig(sessionId)` — reads settings, resolves the provider
+ *     registry, the model selector and the env
+ *   - `getMessagesDir(sessionId)` — where JSONL files are stored for this session
+ *   - `onSessionCreated(session)` — app-specific post-creation hook (capabilities,
+ *     memory context, transformPrompt setup, session timer, etc.)
+ */
+declare abstract class BaseAgentManager extends EventEmitter {
+    protected readonly processManager: AgentProcessManager;
+    constructor();
+    /** Derive the AgentProcessManager key for a session. */
+    protected abstract buildProcessKey(sessionId: string): string;
+    /** Build the config to pass to AgentProcessManager.create(). */
+    protected abstract buildAdapterConfig(sessionId: string): Promise<AgentAdapterConfig>;
+    /** Return the directory where JSONL message files are stored. */
+    protected abstract getMessagesDir(sessionId: string): string;
+    /**
+     * Hook called after the dispatcher is initialised but before the session
+     * is returned. Override for capability registration, transformPrompt setup,
+     * memory context injection, idle timer creation, etc.
+     */
+    protected abstract onSessionCreated(session: ManagedSession): Promise<void>;
+    /**
+     * Create a new ManagedSession: spawn subprocess, wire dispatcher, register event handler.
+     *
+     * This is the canonical "extract" from the `_createSession` methods in each app.
+     * The event handler below is the common core — apps extend via `onEvent()`.
+     *
+     * @param sessionId - The UUID for this session (resolved by the app).
+     */
+    protected createManagedSession(sessionId: string): Promise<ManagedSession>;
+    /**
+     * App-specific event hook. Called for every agent event after common
+     * streaming/error tracking but before SSE fan-out.
+     *
+     * Return `true` to suppress the default `this.emit('event', event)` call.
+     * Default implementation: no-op, returns false.
+     *
+     * @example Override in forge-workspace to handle `capability_invoked`
+     * @example Override in forge-assistant to trigger consolidation on `finished`
+     */
+    protected onEvent(_event: AgentEvent, _session: ManagedSession, _processKey: string): Promise<boolean>;
+    /**
+     * Tear down a session: unregister event handler, disconnect dispatcher.
+     */
+    protected teardownSession(session: ManagedSession): void;
+    /**
+     * Whether the given session is currently streaming.
+     * Returns false if the session does not exist.
+     * Override in subclasses that cache their session.
+     */
+    isSessionStreaming(_sessionId: string): boolean;
+    /**
+     * Last error for the given session, or null.
+     * Override in subclasses that cache their session.
+     */
+    getSessionError(_sessionId: string): string | null;
+}
+
+/**
+ * JSONL-backed MessageStore. One file per session at `{dir}/{sessionId}.jsonl`.
+ * Each line is a JSON-serialized MessageV2. Append-only; writes are serialised per
+ * store instance (see `append()`), and `BaseAgentManager.createManagedSession`
+ * constructs one instance per session — so a session's file keeps its call order even
+ * when the event dispatcher has several appends in flight at once.
+ * Reads the full file on every getMessages()/getLatestSeq() call — acceptable
+ * for forge's short-lived single-user sessions.
+ *
+ * `limit` returns the most recent N messages (tail semantics).
+ *
+ * Generic over `TMetaExtensions` so platforms can attach typed metadata under
+ * `meta` without forking. Forge apps use the bare default (`Record<string, never>`).
+ */
+declare class JsonlMessageStore<TMetaExtensions extends object = Record<string, never>> implements MessageStore<MessageV2<TMetaExtensions>> {
+    private readonly dir;
+    /** Tail of this instance's serialised append chain; never rejects. */
+    private tail;
+    /**
+     * @param dir - Directory where per-session `.jsonl` files are stored.
+     *   The directory is created on first write if it does not exist.
+     */
+    constructor(dir: string);
+    private filePath;
+    /**
+     * Append a message to the session's JSONL file.
+     *
+     * Creates the file (and parent directory) if absent.
+     *
+     * Appends are chained on a per-instance tail promise, so overlapping calls are
+     * written in the order they were issued rather than racing each other's
+     * open/write/close. A failed write is neutralised for the chain but still
+     * rejected to its own caller, so one bad append does not poison the ones after it.
+     *
+     * @param message - Message to persist. `message.sessionId` determines the target file.
+     */
+    append(message: MessageV2<TMetaExtensions>): Promise<void>;
+    /**
+     * Read messages for a session with optional pagination.
+     *
+     * Reads the full file on every call — acceptable for forge's short-lived sessions.
+     *
+     * @param sessionId - Session whose messages to retrieve.
+     * @param opts.before - Return only messages with `seq` less than this value.
+     * @param opts.limit - Return at most this many messages (tail semantics — most recent).
+     * @returns Ordered array of messages (oldest first within the result window).
+     */
+    getMessages(sessionId: string, opts?: {
+        before?: number;
+        limit?: number;
+    }): Promise<MessageV2<TMetaExtensions>[]>;
+    /**
+     * Return the sequence number of the most recent message in the session.
+     *
+     * Reads the whole JSONL file and takes its last non-empty line — see the
+     * class note on why re-reading is acceptable here.
+     *
+     * @param sessionId - Session to inspect.
+     * @returns `seq` of the last appended message, or `0` if the session has no
+     *   messages (or its last line is unreadable).
+     */
+    getLatestSeq(sessionId: string): Promise<number>;
+}
+
+/**
+ * Internal class — implements SubscriberTransport, fans out to all subscribers.
+ *
+ * SessionDispatcher calls `send(subscriberId, event)` for each event, but
+ * FanoutSubscriberTransport broadcasts to ALL connected subscribers by
+ * ignoring the subscriberId argument and emitting on a shared fanout channel.
+ */
+declare class FanoutSubscriberTransport implements SubscriberTransport {
+    private readonly emitter;
+    private readonly FANOUT_CHANNEL;
+    constructor(maxListeners?: number);
+    /**
+     * Called by SessionDispatcher. Broadcasts to ALL subscribers (ignores subscriberId).
+     */
+    send(_subscriberId: string, event: AgentEvent$1): void;
+    /**
+     * Called by SessionDispatcher on disconnect. No-op for fanout — subscribers
+     * manage their own cleanup via the unsubscribe function returned by subscribe().
+     */
+    remove(_subscriberId: string): void;
+    /**
+     * Internal: register a handler for all broadcasted events.
+     * Returns an unsubscribe function.
+     */
+    _listen(handler: (event: AgentEvent$1) => void): () => void;
+    /**
+     * Current count of listeners on the fanout channel.
+     */
+    get listenerCount(): number;
+}
+/**
+ * Multi-tab SSE fanout wrapper around EventEmitterSubscriberTransport.
+ *
+ * When two browser tabs subscribe with different subscriber IDs, each tab would
+ * normally only see events directed to it. FanoutTransport lets a single shared
+ * event source broadcast to every registered subscriber simultaneously.
+ *
+ * ## Usage in agent-manager.ts
+ *
+ * ```ts
+ * const fanout = new FanoutTransport()
+ *
+ * // Pass fanout.transport to SessionDispatcher instead of EventEmitterSubscriberTransport:
+ * new SessionDispatcher({ transport: fanout.transport, ... })
+ *
+ * // In the SSE endpoint (one call per browser connection):
+ * const connectionId = randomUUID()
+ * const unsub = fanout.subscribe(connectionId, (event) => res.write(...))
+ * req.on('close', unsub)
+ * ```
+ */
+declare class FanoutTransport {
+    /**
+     * The inner transport passed to SessionDispatcher.
+     * SessionDispatcher calls transport.send(subscriberId, event) for each
+     * registered subscriber. FanoutTransport overrides send() to broadcast
+     * to ALL connected subscribers, ignoring the subscriberId argument.
+     */
+    readonly transport: FanoutSubscriberTransport;
+    constructor();
+    /**
+     * Register a new SSE connection.
+     *
+     * @param connectionId - Unique identifier for this browser connection (e.g. randomUUID()).
+     *   Used only for diagnostics — the fanout ignores it for routing.
+     * @param handler - Called for each agent event broadcast to all subscribers.
+     * @returns Unsubscribe function — call when the SSE connection closes.
+     */
+    subscribe(_connectionId: string, handler: (event: AgentEvent$1) => void): () => void;
+    /**
+     * Returns the current count of active subscribers.
+     * Useful for diagnostics and health checks.
+     */
+    get subscriberCount(): number;
+}
+
+export { AgentProcessManager, BaseAgentManager, EventEmitterSubscriberTransport, FanoutTransport, JsonlMessageStore, ProcessManagerAdapter, createAdapterForHarness, listRegisteredHarnesses, registerHarness };
+export type { AgentAdapter, AgentAdapterConfig, AgentCommand, AgentEvent, AgentProcessConfig, AgentStatus, ManagedSession };