@skaile/workspaces 0.8.5

package/dist/runner/src/serve.d.ts

@@ -0,0 +1,154 @@
+/**
+ * serve.ts — WebSocket agent server.
+ *
+ * Exposes the agent runtime over a pluggable transport. Accepts AgentCommand
+ * messages and streams AgentEvent responses. Uses WebSocketServerTransport for
+ * the default transport (pass opts.transport to override for testing/stdio).
+ *
+ * Usage:
+ *   skaile serve --project-dir /project --port 8080
+ *
+ * The platform's session manager connects via AgentClient + WebSocketClientTransport
+ * to drive agent execution inside a local subprocess or Docker container.
+ *
+ * ─── Session Startup Pattern ───────────────────────────────────────────────────
+ *
+ * All three runner modes (REPL, flow, serve) follow the same 5-step setup:
+ *   1. resolveSettings()          → driver, model, provider, API key
+ *   2. loadAgentManifest()         → manifest (model/maxTurns/tools); optionally systemPrompt
+ *   3. buildAgentResources()      → ConnectorManager, resourcePromptSection, mcpServers
+ *   4. createDriver()             → AgentDriver with assembled systemPrompt
+ *   5. driver.start()             → subprocess spawn / SDK import
+ *
+ * Differences between modes:
+ *   REPL    — identity native (agentDir/agentName); systemPrompt = resource docs only; eager start
+ *   Flow    — identity injected (full SOUL+RULES+knowledge); no transport; single orchestrator prompt
+ *   Serve   — identity injected + external (SKAILE_SYSTEM_PROMPT_FILE); lazy start (first prompt cmd);
+ *             adds EventNormalizer, resource watch callbacks, lifecycle command handling
+ *
+ * The shared `createAgentSession(opts)` helper in session-builder.ts extracts the
+ * common setup sequence. serve.ts retains: EventNormalizer, lazy start (driverStarted flag),
+ * transport setup, and lifecycle command handling.
+ */
+import type { AgentEvent, ServerTransport } from "@skaile/workspaces/types";
+import { CLAUDE_CODE_CREDENTIALS_KEY, writeClaudeCodeCredentialsFile } from "./serve-credentials.js";
+import { type AgentSession } from "./session-builder.js";
+/**
+ * Emit a `system_prompt_composed` event carrying the labeled section
+ * breakdown from the freshly-built {@link AgentSession}. Called from every
+ * `createAgentSession` consumer in serve.ts (initial bootstrap, configure
+ * re-runs, add_resource flow-connector path, aiResources skill changes,
+ * session_init provisioned path) so the platform's debug panel always sees
+ * the prompt the agent is actually receiving.
+ *
+ * Keeping the emission centralised in serve.ts (rather than inside
+ * session-builder.ts) preserves the builder's transport-agnostic contract —
+ * forge apps and the CLI consume the same builder without a transport.
+ *
+ * Spec: `docs/superpowers/specs/2026-05-13-platform-agent-prompt-design.md`
+ * § 3.3.2 Re-emission requirement.
+ * @since 2026-05
+ */
+export declare function emitSystemPromptComposed(agentSession: AgentSession, sendEvent: (e: AgentEvent) => void): void;
+/**
+ * Phase 4.8 — Claude Code subscription credentials provisioning.
+ *
+ * The constant + the atomic rewrite helper now live in `./serve-credentials.ts`
+ * so the AI 401 mediation helper can reuse them without importing from this
+ * (large) module. Re-exported here for back-compat with existing test
+ * imports of `serve.js`.
+ *
+ * @docLink packages/runner/dev-guide#environment-variables
+ */
+export { CLAUDE_CODE_CREDENTIALS_KEY, writeClaudeCodeCredentialsFile };
+/**
+ * Idempotently ensure `~/.gitconfig` includes the runner-managed gitconfig
+ * via `[include] path = <managedGitconfigPath>`. Fallback path for shells
+ * that strip `GIT_CONFIG_GLOBAL`. The function is idempotent — running it
+ * twice produces the same file content.
+ *
+ * Exported for unit tests.
+ * @docLink packages/runner/capabilities#ensure-git-config-include
+ */
+export declare function ensureGitConfigInclude(managedGitconfigPath: string): void;
+/**
+ * Configuration for {@link startAgentServer}.
+ * @docLink packages/runner/dev-guide#flow-execution-turn-based-model
+ */
+export interface ServeOptions {
+    /**
+     * WebSocket server port. Defaults to `8080`.
+     * Ignored when a custom {@link transport} is provided.
+     */
+    port?: number;
+    /** Absolute path to the project working directory. */
+    projectDir: string;
+    /**
+     * GitAgent definition directory (`agent.yaml`, `SOUL.md`, `RULES.md`,
+     * `knowledge/`). When omitted, resolved from `skaile.yaml` via
+     * `resolveAgentDir`. If unresolvable, no agent definition is loaded and the
+     * agent starts without an identity prompt.
+     */
+    agentDir?: string;
+    /** Agent driver backend override (e.g. `"omp"`, `"claude-sdk"`). */
+    driver?: string;
+    /** LLM model name override. */
+    model?: string;
+    /** LLM provider override (e.g. `"anthropic"`, `"openrouter"`). */
+    provider?: string;
+    /** Directory of deployed prompt/command files appended to the system prompt. */
+    promptsDir?: string;
+    /** Stable session ID for conversation continuity across agent turns. */
+    sessionId?: string;
+    /**
+     * OMP driver session ID to resume. When set, OMP is spawned with
+     * `--session <id>` to restore its native conversation context without
+     * needing `<conversation_history>` injection. For OMP driver only.
+     */
+    resumeSessionId?: string;
+    /** Called for each diagnostic log line. Defaults to `console.log`. */
+    onLog?: (line: string) => void;
+    /**
+     * Pre-built transport to use instead of the default
+     * `WebSocketServerTransport`. Useful for testing (in-process transport,
+     * stdio transport) or embedding the server in another process.
+     */
+    transport?: ServerTransport;
+}
+/**
+ * Start a WebSocket agent server that the Skaile platform connects to for
+ * host-driven agent execution inside a local subprocess or Docker container.
+ *
+ * The server accepts {@link AgentCommand} messages over a
+ * {@link ServerTransport} (default: `WebSocketServerTransport` on `opts.port`)
+ * and streams {@link AgentEvent} responses back to the connected client.
+ *
+ * Handled commands:
+ * - `provision_secrets` — injects API keys and Claude Code credentials; in
+ *   `provisioned` secrets mode, triggers deferred session creation.
+ * - `configure` — registers shared state stores and applies mid-session skill
+ *   catalog changes. Phase 4 of the flow-connector extraction (Protocol 2.2)
+ *   removed the implicit `activeFlows` rehydration; hosts now issue an
+ *   explicit `connector_mutate { id: "flow", op: "hydrate" }` per flow.
+ * - `prompt` — routes free-chat messages through the SessionStimulusBus when
+ *   a flow is active, otherwise forwards directly to the driver; **driver is
+ *   lazily started on the first `prompt` command**.
+ * - `connector_mutate` / `connector_query` — generic connector dispatch.
+ *   Replaces the 6 typed flow commands removed in Protocol 2.2 (`start_flow`,
+ *   `approve_flow_node`, `provide_flow_input`, `cancel_flow`,
+ *   `set_flow_autonomous_mode`, `retry_flow_node`); see
+ *   `MIGRATION-flow-connector.md` for the per-op mapping table.
+ * - `add_resource` / `remove_resource` — mount/unmount mounts or
+ *   connect/disconnect connectors mid-session. When the added connector's
+ *   driver is `flow`, the runner injects the per-session stimulus bus into
+ *   the connect options.
+ *
+ * The function resolves after the transport starts listening. It does not
+ * resolve until the process exits — shutdown is driven by SIGINT/SIGTERM or
+ * a `shutdown` command from the connected client.
+ *
+ * @param opts - Server configuration.
+ * @docLink packages/runner/dev-guide#flow-execution-turn-based-model
+ */
+export declare function startAgentServer(opts: ServeOptions): Promise<void>;
+//# sourceMappingURL=serve.d.ts.map

package/dist/runner/src/serve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../../../runner/src/serve.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AA+BH,OAAO,KAAK,EAEV,UAAU,EAEV,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAWlC,OAAO,EACL,2BAA2B,EAE3B,8BAA8B,EAC/B,MAAM,wBAAwB,CAAC;AAehC,OAAO,EACL,KAAK,YAAY,EAGlB,MAAM,sBAAsB,CAAC;AAuB9B;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,wBAAwB,CACtC,YAAY,EAAE,YAAY,EAC1B,SAAS,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,GACjC,IAAI,CAMN;AA8ID;;;;;;;;;GASG;AACH,OAAO,EAAE,2BAA2B,EAAE,8BAA8B,EAAE,CAAC;AAEvE;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAoCzE;AAWD;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sEAAsE;IACtE,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B;;;;OAIG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;CAC7B;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAu+DxE"}

package/dist/runner/src/session-builder.d.ts

@@ -0,0 +1,213 @@
+/**
+ * session-builder.ts
+ *
+ * Shared `createAgentSession()` factory — extracts the common agent
+ * initialisation sequence from agent.ts (REPL), run-flow.ts (flow), and
+ * serve.ts (WebSocket server) into a single reusable module.
+ *
+ * The shared setup pipeline:
+ *   1. resolveSettings → driverType, provider, model, apiKey
+ *   2. loadAgentManifest → manifest (model, maxTurns, tools, name)
+ *   3. buildAgentResources → resourceManager, resourcePromptSection, mcpServers, dispose
+ *   4. Load workspace config, build contextSection + environmentSection, load prompt-extensions
+ *   5. assembleSystemPrompt (context + env + resources + extensions + additional sections)
+ *   6. Resolve maxTurns (config override wins over manifest)
+ *   7. createDriver (NOT started — caller calls driver.start() when ready)
+ *
+ * Agent identity (SOUL.md, RULES.md, knowledge/) is never assembled here.
+ * It is rendered at install time by the renderers in asset-manager and read
+ * natively by each backend driver at runtime.
+ */
+import type { AgentDriver, BridgeCapabilityHooks } from "@skaile/workspaces/bridge";
+import type { AgentManifest, RuntimeAssetsResult, SkWorkspaceConfig } from "@skaile/workspaces/core";
+import type { TelemetryProvider, Trace } from "@skaile/workspaces/telemetry";
+import type { SystemPromptSection } from "@skaile/workspaces/types";
+import { type ResolvedComposition } from "./composition/bootstrap.js";
+import { type ResourceWatchCallbacks } from "./resources.js";
+export type { ResourceWatchCallbacks };
+/**
+ * Configuration for creating an agent session.
+ *
+ * Controls the driver backend, LLM provider and model, agent identity,
+ * workspace layout, resource lifecycle, and protocol v2 capability hooks.
+ *
+ * @docLink packages/runner/dev-guide#flow-execution-turn-based-model
+ */
+export interface AgentSessionConfig {
+    projectDir: string;
+    /**
+     * Agent working directory — where the agent reads/writes files.
+     * Defaults to `projectDir` when omitted. Use this to separate the config
+     * root (`projectDir` with `skaile.yaml`) from the actual working directory
+     * (e.g. when the user is in a subdirectory or has no `skaile.yaml` in their CWD).
+     */
+    cwd?: string;
+    agentDir?: string;
+    driver?: string;
+    model?: string;
+    provider?: string;
+    promptsDir?: string;
+    projectClaudeMd?: string;
+    sessionId?: string;
+    resumeSessionId?: string;
+    /**
+     * Path to a file whose contents are prepended to the system prompt.
+     * @deprecated Use `agent.prompt-extensions` in skaile.yaml instead. The runner
+     * no longer injects this file's contents.
+     */
+    externalPromptFile?: string;
+    /**
+     * Pre-resolved workspace config. Avoids re-reading skaile.yaml when the caller
+     * already has it. Optional — falls back to `resolveSkWorkspaceConfig(projectDir)`.
+     */
+    wsConfig?: SkWorkspaceConfig;
+    /**
+     * Platform-level maxTurns override. Takes precedence over manifest.runtime.max_turns.
+     * Flow/REPL modes omit this field — they use the manifest value only.
+     */
+    maxTurns?: number;
+    /** Thinking mode override. */
+    thinking?: "adaptive" | "enabled" | "disabled";
+    /** Reasoning effort level override. */
+    effort?: "low" | "medium" | "high" | "max";
+    /** Watch callbacks for filesystem/sync events (serve mode only). */
+    watch?: ResourceWatchCallbacks;
+    /** Secret provider for connector credential resolution. */
+    secretProvider?: unknown;
+    /**
+     * Pre-resolved API key for the active provider. When supplied, it takes
+     * precedence over the env-var lookup performed inside `resolveApiKey()`.
+     * Used by `serve.ts` to feed the value from `provision_secrets` straight
+     * into `AgentConfig.apiKeys` without writing it to `process.env`.
+     */
+    apiKey?: string;
+    /**
+     * Optional callback used by `auth: backend` git mounts to request
+     * short-lived access tokens from the platform's credential mediator.
+     * Threaded into the `MountManager` constructor so all git mounts in this
+     * session share the same mediator.
+     */
+    tokenMediator?: import("@skaile/workspaces/connectors").TokenMediator;
+    /**
+     * Pre-minted credential provider populated from the v3 `session_init`
+     * envelope's `credentials` map. Threaded into MountManager so that
+     * mounts with `auth: backend` find their token in-process instead of
+     * paying a `request_access_token` round-trip at mount time.
+     *
+     * @since 3.0.0
+     */
+    preMintedSecrets?: import("@skaile/workspaces/connectors").PreMintedSecretProvider;
+    /**
+     * Platform `AIProviderConfig.id` for the AI credential provisioned into
+     * this session. Threaded into `AgentConfig.aiProviderConfigId` so that
+     * driver recreates (tier-1 native SDK resume, subagents, etc.) preserve
+     * the link to the platform mediator. The driver itself does not consume
+     * this field; only the runner's 401-mediation handler reads it.
+     */
+    aiProviderConfigId?: string;
+    /**
+     * Optional auth-refresh callback threaded into the bridge driver. Invoked
+     * by the driver when the underlying agent surfaces an
+     * `authentication_error`; in v3 the runner mediates a fresh credential
+     * via the `host.refresh_credential` capability and returns a typed
+     * {@link CredentialMint}. The driver branches on the discriminator:
+     * `ok: true` triggers a one-shot retry of the in-flight prompt;
+     * `ok: false` surfaces the original auth error to the caller.
+     *
+     * Centralising auth-retry inside the driver removes the need to wrap
+     * every `driver.prompt(...)` call site (compaction, flow turns, serve
+     * handler) with a runner-side retry helper. Standalone CLI / forge
+     * sessions leave it undefined.
+     *
+     * Spec: `_devlog/specs/2026-05-10-deterministic-session-bootstrap.md`
+     * § "Refresh-on-401 routes through host.refresh_credential".
+     */
+    onAuthError?: (args: {
+        configId: string;
+    }) => Promise<import("@skaile/workspaces/types").CredentialMint>;
+    /**
+     * Additional sections to append to the assembled system prompt.
+     * Used by serve mode to inject the component catalog (AVAILABLE_COMPONENTS)
+     * without modifying the session builder's core assembly logic.
+     */
+    additionalPromptSections?: string[];
+    onLog?: (line: string) => void;
+    /** Telemetry provider for observability. Optional — omit to disable tracing. */
+    telemetry?: TelemetryProvider;
+    /** Active trace to attach to this session's driver. */
+    trace?: Trace;
+    /**
+     * Protocol v2 capability dispatch hooks built from the runner's
+     * CapabilityRegistry. When present, the driver routes registered tool
+     * calls through `hooks.invoke()` instead of the legacy in-driver dispatch.
+     *
+     * @since 2.0.0
+     */
+    capabilities?: BridgeCapabilityHooks;
+}
+/**
+ * A configured agent session returned by {@link createAgentSession}.
+ *
+ * Carries a driver instance (not yet started), connected resource and
+ * mount managers, resolved runtime assets, and the parsed agent manifest.
+ *
+ * @docLink packages/runner/dev-guide#flow-execution-turn-based-model
+ */
+export interface AgentSession {
+    /** Driver configured but NOT started. Caller must call driver.start(). */
+    driver: AgentDriver;
+    /** Connected ConnectorManager — null if no connectors declared. any intentional (optional dep). */
+    resourceManager: any | null;
+    /** Mounted MountManager — null if no mounts declared. any intentional (optional dep). */
+    mountManager: any | null;
+    /**
+     * Resolved runtime assets — catalog entries, implicit refs, npm deps,
+     * warnings, plus refresh() / findEntry() helpers. Live-update paths
+     * (add_resource, configure) hold this reference and call refresh() when
+     * a new repository is cloned or driver installed mid-session.
+     */
+    runtimeAssets: RuntimeAssetsResult | null;
+    /**
+     * Resolved composition — inline blocks (already injected into systemPrompt)
+     * and discoverable entries (caller registers these with CapabilityRegistry).
+     * Null when the agent has no `composes:` field.
+     */
+    composition: ResolvedComposition | null;
+    /** Parsed agent.yaml manifest — model, maxTurns, tools, name. */
+    manifest: AgentManifest | undefined;
+    /** Active driver type string ('omp' | 'claude-sdk'). */
+    driverType: string;
+    provider: string | undefined;
+    model: string | undefined;
+    /** Disconnect all connectors, unmount all mounts, and stop watchers. */
+    dispose: () => Promise<void>;
+    /** Start filesystem and connector watchers. Call after transport is listening. */
+    startWatching: () => void;
+    /** Telemetry provider for this session (noop if not configured). */
+    telemetry?: TelemetryProvider;
+    /**
+     * Labeled per-section breakdown of the system prompt, in the same
+     * order assembleSystemPrompt consumed them. Multi-entry sections
+     * (prompt-extensions, composition, additional) appear as repeated
+     * entries with `source` set.
+     *
+     * Consumed by serve.ts's emitSystemPromptComposed helper to emit
+     * `system_prompt_composed` events to the platform.
+     * @since 2026-05
+     */
+    systemPromptSections: SystemPromptSection[];
+}
+/**
+ * Create an agent session by resolving settings, loading the agent
+ * manifest, building resources (connectors, mounts, MCP servers),
+ * and creating the driver.
+ *
+ * The returned driver is NOT started — the caller must call
+ * `driver.start()` after optionally attaching event handlers.
+ *
+ * @param config - Session configuration
+ * @returns A fully configured AgentSession ready for start()
+ * @docLink packages/runner/dev-guide#flow-execution-turn-based-model
+ */
+export declare function createAgentSession(config: AgentSessionConfig): Promise<AgentSession>;
+//# sourceMappingURL=session-builder.d.ts.map

package/dist/runner/src/session-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-builder.d.ts","sourceRoot":"","sources":["../../../runner/src/session-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAOH,OAAO,KAAK,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AACpF,OAAO,KAAK,EACV,aAAa,EACb,mBAAmB,EACnB,iBAAiB,EAClB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,iBAAiB,EAAE,KAAK,EAAE,MAAM,8BAA8B,CAAC;AAC7E,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAEpE,OAAO,EAA2B,KAAK,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AAI/F,OAAO,EAAuB,KAAK,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAElF,YAAY,EAAE,sBAAsB,EAAE,CAAC;AAMvC;;;;;;;GAOG;AACH,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,QAAQ,CAAC,EAAE,UAAU,GAAG,SAAS,GAAG,UAAU,CAAC;IAC/C,uCAAuC;IACvC,MAAM,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,CAAC;IAC3C,oEAAoE;IACpE,KAAK,CAAC,EAAE,sBAAsB,CAAC;IAC/B,2DAA2D;IAC3D,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,+BAA+B,EAAE,aAAa,CAAC;IACtE;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,OAAO,+BAA+B,EAAE,uBAAuB,CAAC;IACnF;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;;;;;;;;OAgBG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE;QACnB,QAAQ,EAAE,MAAM,CAAC;KAClB,KAAK,OAAO,CAAC,OAAO,0BAA0B,EAAE,cAAc,CAAC,CAAC;IACjE;;;;OAIG;IACH,wBAAwB,CAAC,EAAE,MAAM,EAAE,CAAC;IACpC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,gFAAgF;IAChF,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B,uDAAuD;IACvD,KAAK,CAAC,EAAE,KAAK,CAAC;IACd;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,qBAAqB,CAAC;CACtC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,MAAM,EAAE,WAAW,CAAC;IACpB,mGAAmG;IAEnG,eAAe,EAAE,GAAG,GAAG,IAAI,CAAC;IAC5B,yFAAyF;IAEzF,YAAY,EAAE,GAAG,GAAG,IAAI,CAAC;IACzB;;;;;OAKG;IACH,aAAa,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAC1C;;;;OAIG;IACH,WAAW,EAAE,mBAAmB,GAAG,IAAI,CAAC;IACxC,iEAAiE;IACjE,QAAQ,EAAE,aAAa,GAAG,SAAS,CAAC;IACpC,wDAAwD;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,wEAAwE;IACxE,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,kFAAkF;IAClF,aAAa,EAAE,MAAM,IAAI,CAAC;IAC1B,oEAAoE;IACpE,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B;;;;;;;;;OASG;IACH,oBAAoB,EAAE,mBAAmB,EAAE,CAAC;CAC7C;AAMD;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,CAAC,CAkO1F"}

package/dist/runner/src/session-stimulus.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Session stimulus bus — generic trailing-edge coalescing turn driver.
+ *
+ * Connectors that observe state changes (FlowAdapter, future alert/inbox/
+ * file-watch connectors) call `bus.signal(connectorId, { promptFragment, meta })`
+ * to request that the agent be woken with a fresh turn. Multiple signals from
+ * the same connector arriving within `coalesceMs` are folded into one turn,
+ * with their `promptFragment`s concatenated by `\n\n` and their `meta` objects
+ * collected into an array.
+ *
+ * Per-`connectorId` queues — concurrent connectors NEVER coalesce together;
+ * each runs its own pending timer and turn pipeline.
+ *
+ * If `signal()` is called for a connector whose driveTurn is already in flight,
+ * the new signal queues for the next cycle (a fresh timer starts only after
+ * the in-flight turn settles).
+ *
+ * Distinct from `refresh-flag-dispatcher.ts`'s leading-edge debounce: that one
+ * fires immediately and drops within a 2 s window. The stimulus bus is trailing-
+ * edge collapse with a returned promise, so callers can `await` completion of
+ * the turn that drained their signal.
+ *
+ * @docLink runner#session-stimulus-bus
+ * @since 2.2.0
+ */
+import type { Logger } from "@skaile/workspaces/types";
+/**
+ * One stimulus from a connector. The bus collapses contiguous signals from the
+ * same connector into a single turn whose prompt is built by joining the
+ * `promptFragment`s with `\n\n`.
+ */
+export interface StimulusSignal {
+    /** Fragment the connector wants prepended to the next turn prompt. */
+    promptFragment: string;
+    /** Optional event metadata for tracing. Connector-defined. */
+    meta?: Record<string, unknown>;
+    /**
+     * Trailing-edge coalesce window — multiple signals from the same connector
+     * arriving within this many ms are folded into one turn with their
+     * fragments concatenated. Default: 50 ms (a tick to let near-simultaneous
+     * signals settle without perceptible delay).
+     */
+    coalesceMs?: number;
+}
+/**
+ * Public surface returned by `createSessionStimulusBus`. Connectors hold a
+ * reference to this and call `signal(...)` whenever they want to wake the
+ * agent.
+ */
+export interface SessionStimulusBus {
+    /**
+     * Request a turn kick for `connectorId`. Resolves once the resulting turn
+     * has drained (the supplied `driveTurn` resolved). Multiple parallel calls
+     * within `coalesceMs` collapse into one turn and share a single resolution.
+     */
+    signal(connectorId: string, sig: StimulusSignal): Promise<void>;
+}
+/**
+ * Drives one agent turn given a concatenated prompt fragment. The runner
+ * supplies this when constructing the bus — typically wraps `driver.prompt`
+ * + waits for `agent_end`. The bus calls it with all coalesced fragments
+ * joined by newline.
+ */
+export type TurnDriver = (promptFragment: string, batchedMeta: Array<Record<string, unknown>>) => Promise<void>;
+export interface CreateStimulusBusOptions {
+    driveTurn: TurnDriver;
+    /** Default coalesce window when a signal omits its own. */
+    defaultCoalesceMs?: number;
+    log?: Logger;
+}
+/** Default coalesce window — kept consistent with the spec's stated default. */
+export declare const DEFAULT_COALESCE_MS = 50;
+/**
+ * Construct a fresh stimulus bus. The caller (typically `serve.ts` or
+ * `run-flow.ts`) provides `driveTurn`, which kicks one agent turn given a
+ * joined prompt + batched meta, and resolves once the turn drains.
+ */
+export declare function createSessionStimulusBus(opts: CreateStimulusBusOptions): SessionStimulusBus;
+//# sourceMappingURL=session-stimulus.d.ts.map

package/dist/runner/src/session-stimulus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-stimulus.d.ts","sourceRoot":"","sources":["../../../runner/src/session-stimulus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAEvD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,sEAAsE;IACtE,cAAc,EAAE,MAAM,CAAC;IACvB,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjE;AAED;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,CACvB,cAAc,EAAE,MAAM,EACtB,WAAW,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,KACxC,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnB,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,UAAU,CAAC;IACtB,2DAA2D;IAC3D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,gFAAgF;AAChF,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAqBtC;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,wBAAwB,GAAG,kBAAkB,CAoF3F"}

package/dist/runner/src/session.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Runner session metadata.
+ *
+ * Holds only what the runner needs to resume the agent driver across
+ * process restarts — notably `driverSessionId` for SDK session resume.
+ *
+ * Flow execution state (per-node status, approvals, outputs) moved out
+ * of the session file in Phase 2 of the flow-execution plan. It now
+ * lives in the FlowAdapter's in-memory snapshot and, for hosts that
+ * persist it, in whatever durable store they provide (the Skaile
+ * platform uses the `FlowExecution` Prisma table). The runner does
+ * not read or write flow state from disk.
+ * @docLink packages/runner/session#session-state
+ */
+export interface SessionState {
+    /** Unique identifier for this session run (UUID). */
+    runId: string;
+    /** ID of the flow definition being executed. */
+    flowId: string;
+    /** Absolute path to the project directory. */
+    projectDir: string;
+    /**
+     * Absolute path to the agent definition directory (`agent.yaml`,
+     * `SOUL.md`, `RULES.md`, `knowledge/`). Resolved from `skaile.yaml`
+     * via `resolveAgentDir` when absent at session creation time.
+     */
+    agentDir?: string;
+    /** Agent driver backend used for this session (e.g. `"omp"`, `"claude-sdk"`). */
+    driver: string;
+    /** LLM provider (if set), e.g. `"anthropic"` or `"openrouter"`. */
+    provider?: string;
+    /** Model name (if set), e.g. `"claude-opus-4-5"`. */
+    model?: string;
+    /** Provider-native session/thread identifier for resume support. */
+    driverSessionId?: string;
+    /** ISO 8601 timestamp when the session was created. */
+    startedAt: string;
+    /** ISO 8601 timestamp of the last state change. */
+    updatedAt: string;
+    /** Optional human-readable label for the session */
+    label?: string;
+    /** Session lifecycle status. */
+    status?: "running" | "complete" | "failed" | "paused";
+}
+/**
+ * Load the current (most recently active) session for a project.
+ *
+ * Reads the `<projectDir>/.skaile/current` pointer file and loads the
+ * corresponding session. Auto-migrates the legacy flat `session.json`
+ * format to the per-run `sessions/<runId>.json` layout on first call.
+ *
+ * @param projectDir - Absolute path to the project directory.
+ * @returns The current session or `null` if no session exists.
+ * @docLink packages/runner/session#load-session
+ */
+export declare function loadSession(projectDir: string): Promise<SessionState | null>;
+/**
+ * Load a specific session by its run ID.
+ *
+ * @param projectDir - Absolute path to the project directory.
+ * @param runId - The UUID of the session to load.
+ * @returns The session state or `null` if not found.
+ * @docLink packages/runner/session#load-session-by-id
+ */
+export declare function loadSessionById(projectDir: string, runId: string): Promise<SessionState | null>;
+/**
+ * List all sessions for a project.
+ *
+ * Auto-migrates the legacy flat `session.json` format on first call.
+ * Corrupt or unreadable session files are silently skipped.
+ *
+ * @param projectDir - Absolute path to the project directory.
+ * @returns All sessions sorted by `updatedAt` descending (newest first).
+ * @docLink packages/runner/session#list-sessions
+ */
+export declare function listSessions(projectDir: string): Promise<SessionState[]>;
+/**
+ * Persist a session to `<projectDir>/.skaile/sessions/<runId>.json`.
+ *
+ * @param projectDir - Absolute path to the project directory.
+ * @param state - Session state to write.
+ * @param setCurrent - When `true` (default), updates the `current` pointer
+ *   file so subsequent {@link loadSession} calls return this session.
+ * @docLink packages/runner/session#save-session
+ */
+export declare function saveSession(projectDir: string, state: SessionState, setCurrent?: boolean): Promise<void>;
+/**
+ * Set the current session pointer to an existing session.
+ *
+ * @param projectDir - Absolute path to the project directory.
+ * @param runId - The UUID of the session to make current.
+ * @throws {Error} When no session with the given `runId` exists.
+ * @docLink packages/runner/session#set-current-session
+ */
+export declare function setCurrentSession(projectDir: string, runId: string): Promise<void>;
+/**
+ * Delete a session file by run ID.
+ *
+ * If the deleted session was the current session, the `current` pointer
+ * file is also removed. Missing session files are silently ignored.
+ *
+ * @param projectDir - Absolute path to the project directory.
+ * @param runId - The UUID of the session to delete.
+ * @docLink packages/runner/session#delete-session
+ */
+export declare function deleteSession(projectDir: string, runId: string): Promise<void>;
+/**
+ * Unset the current session pointer without deleting the session file.
+ *
+ * After calling this, {@link loadSession} returns `null` until a new
+ * session is saved or {@link setCurrentSession} is called.
+ *
+ * @param projectDir - Absolute path to the project directory.
+ * @docLink packages/runner/session#clear-session
+ */
+export declare function clearSession(projectDir: string): Promise<void>;
+/**
+ * Create a new {@link SessionState} with a fresh UUID and current timestamps.
+ *
+ * The returned session has `status: "running"` and both `startedAt` and
+ * `updatedAt` set to the current ISO 8601 time. Caller is responsible for
+ * persisting it via {@link saveSession}.
+ *
+ * @param opts - All session fields except `runId`, `startedAt`, `updatedAt`,
+ *   and `status` (which are generated automatically).
+ * @returns A fully initialized session state ready to be saved.
+ * @docLink packages/runner/session#new-session
+ */
+export declare function newSession(opts: Omit<SessionState, "runId" | "startedAt" | "updatedAt" | "status">): SessionState;
+/**
+ * Update a session's `updatedAt` timestamp without changing any other field.
+ * Used by callers that persist a session mid-run to refresh the staleness clock.
+ *
+ * @param state - Current session state
+ * @returns New session state with updated timestamp
+ * @docLink packages/runner/session#touch-session
+ */
+export declare function touchSession(state: SessionState): SessionState;
+//# sourceMappingURL=session.d.ts.map

package/dist/runner/src/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../runner/src/session.ts"],"names":[],"mappings":"AASA;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,YAAY;IAC3B,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iFAAiF;IACjF,MAAM,EAAE,MAAM,CAAC;IACf,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,MAAM,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAC;CACvD;AAuDD;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CASlF;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACnC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAO9B;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAmB9E;AAED;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAC/B,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,YAAY,EACnB,UAAU,UAAO,GAChB,OAAO,CAAC,IAAI,CAAC,CAUf;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAKxF;AAED;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAepF;AAED;;;;;;;;GAQG;AACH,wBAAsB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMpE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,IAAI,CAAC,YAAY,EAAE,OAAO,GAAG,WAAW,GAAG,WAAW,GAAG,QAAQ,CAAC,GACvE,YAAY,CAGd;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,YAAY,CAE9D"}

package/dist/runner/src/workspace-migration.d.ts

@@ -0,0 +1,54 @@
+/**
+ * workspace-migration.ts — Phase 3: workspace replacement for empty projects.
+ *
+ * When a user attaches a real backend (git, sharepoint, etc.) to a project
+ * that previously used a local temp workspace, we need to:
+ *   1. Mount the new mount to a staging path
+ *   2. Detect whether the target is blank (no user files)
+ *   3. Copy workspace files to the right destination
+ *   4. Commit if git-backed
+ *   5. Swap mounts: unmount old workspace + staging, mount new mount as workspace
+ *   6. Emit resource_status: active
+ *
+ * On failure at any step, rollback: unmount staging, delete staging dir, emit error.
+ */
+import type { MountManager } from "@skaile/workspaces/connectors";
+import type { ResourceDeclaration, ResourceMigration } from "@skaile/workspaces/types";
+type ReplaceWorkspaceMigration = Extract<ResourceMigration, {
+    strategy: "replace-workspace";
+}>;
+/**
+ * Replace the current workspace mount with a new mount backend.
+ *
+ * Steps:
+ *   1. Mount new mount to ../.staging (relative to workspace)
+ *   2. Check if staging is blank (no non-hidden files)
+ *   3. Copy workspace files — to root if blank, into named subfolder if non-blank
+ *   4. Git add+commit if driver is 'git'
+ *   5. Unmount old workspace and staging
+ *   6. Mount new mount as workspace
+ *   7. Emit resource_status: active
+ *
+ * On any error: rollback (unmount staging, clean up staging dir, emit error status).
+ * @docLink packages/runner/dev-guide#flow-execution-turn-based-model
+ */
+export declare function handleWorkspaceReplacement(resource: ResourceDeclaration, migration: ReplaceWorkspaceMigration, mountManager: MountManager, sendEvent: (event: Record<string, unknown>) => void, workspaceDir: string): Promise<void>;
+/**
+ * Returns true if the directory has no non-hidden files or directories.
+ * Hidden entries (starting with '.') are ignored — e.g. .git, .DS_Store.
+ * @docLink packages/runner/dev-guide#flow-execution-turn-based-model
+ */
+export declare function isEffectivelyEmpty(dir: string): boolean;
+/**
+ * Recursively copy src into dest, skipping hidden entries (starting with '.').
+ * @docLink packages/runner/dev-guide#flow-execution-turn-based-model
+ */
+export declare function copyDirectory(src: string, dest: string): void;
+/**
+ * Run `git add -A` and `git commit` in repoDir. Skips the commit if nothing
+ * is staged (i.e. the workspace was already empty or all files were hidden).
+ * @docLink packages/runner/dev-guide#flow-execution-turn-based-model
+ */
+export declare function gitAddAndCommit(repoDir: string, message: string): void;
+export {};
+//# sourceMappingURL=workspace-migration.d.ts.map

package/dist/runner/src/workspace-migration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace-migration.d.ts","sourceRoot":"","sources":["../../../runner/src/workspace-migration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,KAAK,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAEvF,KAAK,yBAAyB,GAAG,OAAO,CAAC,iBAAiB,EAAE;IAAE,QAAQ,EAAE,mBAAmB,CAAA;CAAE,CAAC,CAAC;AAE/F;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,0BAA0B,CAC9C,QAAQ,EAAE,mBAAmB,EAC7B,SAAS,EAAE,yBAAyB,EACpC,YAAY,EAAE,YAAY,EAC1B,SAAS,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,EACnD,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,IAAI,CAAC,CAuFf;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAY7D;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAUtE"}