@xemahq/agent-session-runtime 0.1.1

package/src/lib/skill-bundle-template-resolver.ts

@@ -0,0 +1,147 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── Skill-bundle-backed TemplateResolver ──
+//
+// Phase 10 (workspace-manifests-api retirement). Seed-file templates used to
+// live in `workspace-manifests-api` (the `workspace_manifest_templates` table)
+// and were fetched by name. They are now SKILL-BUNDLE RESOURCES served by
+// `skill-registry-api` (`GET /skills/bundle`): a biome that ships templates
+// packages them inside a skill bundle under `assets/templates/<name>.hbs`.
+//
+// This factory builds a `TemplateResolver` that:
+//   1. Walks the resolved composition's skill set.
+//   2. Fetches each skill bundle through the injected `fetchBundle` function.
+//   3. Locates the requested template by mapping the bare template name
+//      (`demo-seeded-canvas-index.html`) to the resource relPath
+//      (`assets/templates/demo-seeded-canvas-index.html.hbs`).
+//   4. Compiles the raw template via the injected `compileTemplate` function
+//      and renders it with the seed-file `vars`.
+//
+// Both the bundle-fetch and the Handlebars compile are INJECTED so this
+// Kernel package stays free of an HTTP client and a templating dependency —
+// `agent-session-api` (and, after Step 4, `workflow-runtime-worker`) supply
+// the concrete implementations and share this one resolution algorithm.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import type { TemplateResolver } from './types';
+
+/** The `assets/templates/` directory prefix every template resource sits under. */
+const TEMPLATE_RESOURCE_PREFIX = 'assets/templates/';
+/** The file extension a Handlebars template resource carries inside the bundle. */
+const TEMPLATE_RESOURCE_SUFFIX = '.hbs';
+
+/**
+ * One resource inside a skill bundle. Mirrors `SkillBundleResourceDto` from
+ * the skill-registry-api client without importing it (Kernel stays
+ * client-dep-free).
+ */
+export interface SkillBundleResource {
+  /** Forward-slash path relative to the skill directory. */
+  readonly relPath: string;
+  /** File bytes, base64-encoded. */
+  readonly content: string;
+}
+
+/**
+ * The slice of a skill bundle this resolver needs. Mirrors
+ * `SkillBundleResponseDto` (subset).
+ */
+export interface SkillBundle {
+  readonly slug: string;
+  readonly resources: readonly SkillBundleResource[];
+}
+
+/**
+ * Fetches one skill bundle by slug. Implemented by the consumer with its
+ * `skill-registry-api` Orval client. Must reject (not return null) on a
+ * missing bundle — a template referencing a skill that does not resolve is
+ * a fail-fast condition.
+ */
+export type SkillBundleFetcher = (slug: string) => Promise<SkillBundle>;
+
+/**
+ * Compiles a raw template string and renders it with `vars`. Injected so
+ * the Kernel package does not depend on a concrete templating library.
+ */
+export type TemplateCompiler = (
+  source: string,
+  vars: Readonly<Record<string, unknown>>,
+) => string;
+
+/** Raised when a referenced seed-file template cannot be resolved. */
+export class SkillBundleTemplateNotFoundError extends Error {
+  constructor(
+    public readonly templateName: string,
+    public readonly skillSlugs: readonly string[],
+  ) {
+    super(
+      `Seed-file template "${templateName}" was not found as ` +
+        `"${TEMPLATE_RESOURCE_PREFIX}${templateName}${TEMPLATE_RESOURCE_SUFFIX}" ` +
+        `in any of the composition's skill bundles ` +
+        `[${skillSlugs.join(', ') || '<none>'}]. The biome that owns the ` +
+        `template must ship it inside a skill bundle the composition references.`,
+    );
+    this.name = 'SkillBundleTemplateNotFoundError';
+  }
+}
+
+/**
+ * Map a bare seed-file template name to its skill-bundle resource relPath.
+ * `demo-seeded-canvas-index.html` → `assets/templates/demo-seeded-canvas-index.html.hbs`.
+ */
+export function templateResourceRelPath(templateName: string): string {
+  return `${TEMPLATE_RESOURCE_PREFIX}${templateName}${TEMPLATE_RESOURCE_SUFFIX}`;
+}
+
+/**
+ * Build a `TemplateResolver` backed by the resolved composition's skill
+ * bundles.
+ *
+ * `skillSlugs` is the set of skill slugs attached to the resolved
+ * composition (root node + descendants). Bundles are fetched lazily and
+ * memoised for the lifetime of the returned resolver, so a session whose
+ * manifest references three templates from one skill fetches that bundle
+ * exactly once.
+ *
+ * Fail-fast: a `fetchBundle` rejection propagates; a template name that
+ * matches no resource in any bundle throws `SkillBundleTemplateNotFoundError`.
+ */
+export function buildSkillBundleTemplateResolver(params: {
+  readonly skillSlugs: readonly string[];
+  readonly fetchBundle: SkillBundleFetcher;
+  readonly compileTemplate: TemplateCompiler;
+}): TemplateResolver {
+  const { skillSlugs, fetchBundle, compileTemplate } = params;
+  // De-duplicate so the same skill referenced at multiple nodes is fetched once.
+  const uniqueSlugs = [...new Set(skillSlugs)];
+  const bundleCache = new Map<string, Promise<SkillBundle>>();
+
+  const loadBundle = (slug: string): Promise<SkillBundle> => {
+    const cached = bundleCache.get(slug);
+    if (cached) {
+      return cached;
+    }
+    const pending = fetchBundle(slug);
+    bundleCache.set(slug, pending);
+    return pending;
+  };
+
+  return {
+    async resolve(
+      name: string,
+      vars: Readonly<Record<string, unknown>>,
+    ): Promise<string> {
+      const relPath = templateResourceRelPath(name);
+      for (const slug of uniqueSlugs) {
+        const bundle = await loadBundle(slug);
+        const resource = bundle.resources.find((r) => r.relPath === relPath);
+        if (resource) {
+          const source = Buffer.from(resource.content, 'base64').toString(
+            'utf8',
+          );
+          return compileTemplate(source, vars);
+        }
+      }
+      throw new SkillBundleTemplateNotFoundError(name, uniqueSlugs);
+    },
+  };
+}

package/src/lib/types.ts

@@ -0,0 +1,443 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// ── @xemahq/agent-session-runtime — public types ──
+//
+// The shared abstract substrate beneath two entry points (workflow
+// agent.activity, agent-session bootstrap). Each entry point
+// keeps its own orchestration concerns (Temporal heartbeat /
+// cancellation, MinIO snapshot / resume) but delegates the substrate
+// operations to interfaces declared here:
+//
+//   1. ComposeWorkspaceImage    — manifest + bind context → mount plan
+//   2. ApplyWorkspaceImage      — push the mount plan to a runtime
+//   3. AgentSessionDriver       — drive a single agent turn to completion
+//   4. HarvestDeliverables      — read the workspace's emitted manifest
+//
+// All interfaces are runtime-dep-free (no NestJS, no Temporal, no
+// agent-runtime stack details). The concrete HTTP implementations live
+// in `@xemahq/agent-runtime-bridge`; consumers wire them with
+// the right HTTP clients.
+// ═══════════════════════════════════════════════════════════════════════════
+
+import type { WorkspaceMountPlan } from '@xemahq/kernel-contracts/agent-workspace';
+import type { CompiledWorkspaceManifest } from '@xemahq/dsl/workspace-manifest';
+import type { AgentRunRole, Briefcase } from '@xemahq/kernel-contracts/workflow';
+
+/**
+ * Worker allocation handle returned by opencode-pool. Carries the
+ * proxy URL + per-allocation password used for `/workspace/*` calls.
+ * Passed to every substrate operation.
+ */
+export interface WorkerAllocation {
+  readonly proxyUrl: string;
+  readonly password: string;
+  /** Pool allocation id; threaded into request headers for audit. */
+  readonly allocationId: string;
+}
+
+/**
+ * Inputs for `WorkspaceImageComposer.compose()`. Carries everything
+ * needed to turn a compiled manifest into a `WorkspaceMountPlan`.
+ *
+ * Exactly one of `workflowRun` / `interactive` MUST be supplied — the
+ * composer uses it to derive the lease key's scope id and to populate
+ * the rendered context.json's invocation identity.
+ */
+export interface ComposeWorkspaceImageRequest {
+  readonly orgId: string;
+  readonly projectId: string;
+  readonly manifest: CompiledWorkspaceManifest;
+  /** Free-form runtime context the composer threads to mount-source extractors. */
+  readonly agentContext: Readonly<Record<string, unknown>>;
+  readonly workflowRun?: { readonly runId: string; readonly jobRunId: string };
+  readonly interactive?: { readonly sessionId: string; readonly turnGen?: number };
+  /**
+   * Optional overrides for the agent block — used when the workflow
+   * action's `with:` block supplies a different role / spec ref than
+   * the manifest's defaults (the workflow's short-form sugar).
+   */
+  readonly agentOverrides?: {
+    readonly role?: AgentRunRole;
+    readonly deliverableSpecRef?: string;
+  };
+  /**
+   * Resolver for `seedFiles[].source.kind === 'template'` entries. The
+   * caller supplies one because templates are skill-bundle resources
+   * fetched from skill-registry-api, not content of this kernel-adjacent
+   * package. Returns the rendered string (the composer base64-encodes
+   * it). Must throw on a missing template — fail-fast, no silent skip.
+   */
+  readonly templateResolver?: TemplateResolver;
+  /**
+   * Kernel-shipped System-scope skill slugs to PREPEND to the composer's
+   * mounted skill set. Per `.claude/rules/skills-and-composition.md`,
+   * skills owned by `SkillSpace.System` are auto-injected into every
+   * agent's mounted bundle — they ship from `@xemahq/system-skills`
+   * via the System-tier seeder in `skill-registry-api`. The caller
+   * (workflow agent.activity, agent-session bootstrap) fetches the
+   * list once per session/turn from `skill-registry-api` and forwards
+   * it here. The composer prepends these slugs to whatever skills
+   * `agentContext.skills` already names, so every agent's mounted
+   * skill list starts with System skills then agent-declared ones.
+   *
+   * Empty / omitted = no System layer is mounted for this call (e.g.
+   * unit tests that don't wire skill-registry-api). The composer does
+   * NOT fetch them itself — kernel packages do not make HTTP calls.
+   */
+  readonly systemSkillSlugs?: readonly string[];
+  /**
+   * Run-scoped Briefcase carried verbatim from `ActionBaseInput.briefcase`.
+   * The composer emits MountSource entries for `briefcase.uploads[]` and
+   * `briefcase.references[]` (replacing the legacy ad-hoc
+   * `agentContext.uploads` / `agentContext.references` plumbing).
+   * `briefcase.mcpTools[]` is unioned into the manifest's tool selection
+   * by the environment resolver before this composer is called, so the
+   * composer itself does not look at that field.
+   */
+  readonly briefcase?: Briefcase;
+}
+
+/**
+ * Resolves a named manifest template (a skill-bundle resource under
+ * `assets/templates/<name>.hbs`) and renders it with `vars`.
+ * Implementations:
+ *   - `workflow-runtime-worker` agent.activity: skill-bundle fetch +
+ *     Handlebars render.
+ *   - `agent-session-api` bootstrap: same shape as agent.activity.
+ * See `skill-bundle-template-resolver.ts` for the shared algorithm.
+ */
+export interface TemplateResolver {
+  resolve(
+    name: string,
+    vars: Readonly<Record<string, unknown>>,
+  ): Promise<string>;
+}
+
+/**
+ * Inputs for `AgentSessionDriver.driveToCompletion()`.
+ *
+ * The concrete driver implementation is responsible for translating
+ * these into the runtime's wire protocol, parsing the response stream,
+ * emitting `SessionFrame` events, and resolving to a `DriveResult`
+ * when the agent's turn completes (or rejects on abort/error).
+ */
+export interface DrivePromptParams {
+  readonly prompt: string;
+  readonly agentSlug: string;
+  /**
+   * Logical platform session id. Required. workspace-proxy uses this as
+   * the key into `OpencodeSessionBindings`; passing the SAME id across
+   * multiple drives (e.g. self-correction loops) re-attaches to the
+   * same opencode session so the agent sees prior conversation. Pass a
+   * fresh id (e.g. per pool allocation, per chat session) to start
+   * cleanly. Never optional — workspace-proxy returns 400 if missing.
+   */
+  readonly sessionId: string;
+  /**
+   * Optional output-format hint forwarded verbatim to the agent
+   * runtime. When set with `type: 'json_schema'`, the runtime is
+   * expected to validate the assistant's final answer against the
+   * schema and surface it on the `done` frame's `structuredOutput`
+   * field. When unset, the session runs in plain-text mode and
+   * file-based deliverables rely on tool-call writes.
+   */
+  readonly outputFormat?: AgentOutputFormat;
+  /**
+   * Optional per-message routing override. When set, the bridge
+   * forwards `{ modelID, providerID }` to the runtime's
+   * `POST /session/prompt` body so OpenCode routes this prompt to the
+   * named virtual provider. Used by interactive sessions to switch
+   * model/provider mid-conversation and by workflow steps that pin a
+   * model via DSL `with.model`.
+   *
+   * The Kernel stays runtime-dep-free, so we model the override as the
+   * minimum routing record the wire actually needs — the upstream
+   * resolver (llm-registry-api) returns the canonical
+   * `(modelId, providerSlug, opencodeProviderId)` triple and the caller
+   * projects it onto this shape.
+   */
+  readonly modelOverride?: PromptModelOverride;
+}
+
+/**
+ * Concrete per-message routing override sent on the
+ * `POST /session/prompt` body. workspace-proxy resolves
+ * `opencodeProviderId` against the worker's materialized virtual
+ * provider map; if no match exists the proxy returns 400.
+ *
+ * Temperature is intentionally NOT carried per-prompt — it is a
+ * SESSION-level setting materialised onto the worker by the control
+ * plane (`/control/setup` writes `agent.temperature` into the rendered
+ * opencode.jsonc / agent .md), so a per-prompt override would be
+ * silently dropped by opencode's `POST /session/:id/message`.
+ */
+export interface PromptModelOverride {
+  readonly modelId: string;
+  readonly providerSlug?: string;
+  readonly opencodeProviderId?: string;
+}
+
+/**
+ * Output-format envelope. Discriminated union so the Kernel stays
+ * runtime-dep-free; the concrete bridge implementation projects this
+ * onto the runtime's wire shape.
+ */
+export type AgentOutputFormat =
+  | { readonly type: 'text' }
+  | {
+      readonly type: 'json_schema';
+      readonly schema: Readonly<Record<string, unknown>>;
+      /** Inclusive retries the structured-output validator performs before failing. */
+      readonly retryCount?: number;
+    };
+
+/**
+ * One frame from the agent runtime's session-event stream. Closed
+ * discriminator lets entry-point orchestrators react to specific
+ * events (heartbeat, UI pump, tool-pause routing).
+ */
+export type SessionFrame =
+  | { readonly kind: 'token'; readonly text: string }
+  | {
+      readonly kind: 'tool-call';
+      readonly tool: string;
+      readonly args: unknown;
+      /**
+       * Lifecycle status of the tool invocation. The agent runtime emits a
+       * `started` frame the moment the tool part is registered (args may
+       * still be empty / partially streamed), then a follow-up
+       * `completed` (or `error`) frame for the same `toolCallId` once the
+       * model finishes streaming arguments and the tool has run. Consumers
+       * that want a single line per tool collapse on `toolCallId`; UIs
+       * that animate a tool's lifecycle render the transitions directly.
+       */
+      readonly status: 'started' | 'completed' | 'error';
+      /**
+       * Stable correlation id for the tool call across `started`/`completed`
+       * frames AND any subsequent `tool-result` frame. Sourced from the
+       * runtime's tool-invocation part id (e.g. OpenCode's `part.id`).
+       * Optional because some adapters may not expose a stable id; when
+       * absent, consumers fall back to keying on `(tool, ordinal)`.
+       */
+      readonly toolCallId?: string;
+      /**
+       * Short human-readable hint produced by the runtime (e.g. truncated
+       * stderr/stdout for `error`, a one-liner for `completed`). Empty
+       * for `started` frames where no output exists yet.
+       */
+      readonly summary?: string;
+    }
+  | {
+      readonly kind: 'tool-result';
+      readonly tool: string;
+      /**
+       * Full structured tool output as emitted by the runtime. Kept for
+       * display + debugging; expensive consumers should clamp before
+       * persisting.
+       */
+      readonly result: unknown;
+      /** Same id as the matching `tool-call` frame. */
+      readonly toolCallId?: string;
+      /**
+       * Populated when the tool's `state.error` is non-empty. Mutually
+       * exclusive with a meaningful `result`.
+       */
+      readonly errorMessage?: string;
+    }
+  | { readonly kind: 'progress'; readonly stepIndex: number; readonly stepCount: number | undefined }
+  | { readonly kind: 'error'; readonly message: string }
+  | {
+      /**
+       * Generic "agent tool pause" frame. An active agent session has
+       * signalled that one of its tools needs external input before the
+       * turn can continue. The activity routes this through the
+       * AgentToolInquiryChannel, which materializes an Inquiry, awaits a
+       * recipient's reply, and posts the reply back to the runtime so
+       * the session resumes.
+       *
+       * `toolName` is free-form — the Platform bridge's frame-decoder
+       * registry is the single source of truth for which raw events
+       * map to this frame, and which reply route resumes which tool.
+       */
+      readonly kind: 'tool_pause';
+      /** Tool name (e.g. the runtime's "question" tool). Free-form; not enumerated. */
+      readonly toolName: string;
+      /**
+       * Runtime-supplied request id, opaque to the driver. The platform
+       * adapter uses it to route the reply back to the right tool
+       * invocation.
+       */
+      readonly toolRequestId: string;
+      /** Joined prompt text shown to the recipient. */
+      readonly promptText: string;
+      /**
+       * Optional structured choices presented by the agent (multiple
+       * choice question). `null` when the agent asked an open-ended
+       * question.
+       */
+      readonly choices: readonly string[] | null;
+    }
+  | {
+      readonly kind: 'done';
+      readonly turnId: string;
+      /**
+       * Concatenated final assistant text. Null only when the
+       * upstream stream was aborted before completion.
+       */
+      readonly finalText: string | null;
+      /**
+       * Validated structured payload, populated only when the prompt
+       * was sent with `outputFormat.type === 'json_schema'`. Null
+       * otherwise.
+       */
+      readonly structuredOutput: unknown;
+    };
+
+export interface DriveResult {
+  readonly turnId: string;
+  /** Steps completed within the turn (tool calls + token-emit batches). */
+  readonly stepCount: number;
+  /** True when the runtime completed the turn cleanly; false on abort. */
+  readonly completed: boolean;
+  /**
+   * Final assistant message text. Null when the run was aborted or the
+   * upstream stream ended without a `done` frame.
+   */
+  readonly finalText: string | null;
+  /**
+   * Validated structured payload. Populated only when the caller
+   * passed `DrivePromptParams.outputFormat = { type: 'json_schema', ... }`.
+   * Null when no schema was requested or the structured output was
+   * not produced.
+   */
+  readonly structuredOutput: unknown;
+}
+
+/**
+ * Result of `WorkspaceImageApplier.apply()`. Pass-through of the
+ * runtime's apply response (wire shape mirrors
+ * `MountApplyEntryResult` from `@xemahq/kernel-contracts/agent-workspace`).
+ *
+ * Fields exposed let the worker log per-entry status/bytes/error and
+ * surface failed entries even when the apply outcome is `applied` (a
+ * single failed entry can still mean the agent runs without its
+ * bundle).
+ */
+export interface ApplyWorkspaceImageResult {
+  readonly applyId: string;
+  readonly outcome: 'applied' | 'idempotent';
+  readonly leaseKey: string;
+  readonly entries: ReadonlyArray<{
+    readonly mountKey: string;
+    readonly slot: string;
+    readonly relPath: string;
+    readonly status: 'resolved' | 'applied' | 'failed';
+    readonly bytesWritten: number;
+    readonly errorCode?: string;
+    readonly errorMessage?: string;
+  }>;
+}
+
+/**
+ * High-level interface a session-driving caller can use to chain the
+ * substrate operations. Concrete implementations live in the entry-
+ * point service (workflow agent.activity / agent-session
+ * bootstrap) because lifecycle concerns differ.
+ */
+export interface AgentSessionRuntime {
+  readonly composer: WorkspaceImageComposer;
+  readonly applier: WorkspaceImageApplier;
+  readonly driver: AgentSessionDriver;
+}
+
+export interface WorkspaceImageComposer {
+  compose(req: ComposeWorkspaceImageRequest): Promise<WorkspaceMountPlan>;
+}
+
+export interface WorkspaceImageApplier {
+  apply(
+    allocation: WorkerAllocation,
+    plan: WorkspaceMountPlan,
+    abortSignal?: AbortSignal,
+  ): Promise<ApplyWorkspaceImageResult>;
+}
+
+/**
+ * Async hook called by `driveToCompletion` when the SSE stream emits a
+ * `kind: 'tool_pause'` frame. Resolves to the recipient's reply (opaque
+ * payload — the platform adapter that delivered the pause frame knows
+ * how to map the payload back to the runtime's tool-resume call). The
+ * driver forwards the reply to the runtime and the SSE stream resumes.
+ *
+ * Returning `null` aborts the turn (e.g. operator cancelled the run
+ * while the tool was paused). The driver propagates that as an abort
+ * to the caller.
+ */
+export type OnAgentToolPauseHook = (frame: {
+  readonly toolName: string;
+  readonly toolRequestId: string;
+  readonly promptText: string;
+  readonly choices: readonly string[] | null;
+}) => Promise<{ readonly replyPayload: unknown } | null>;
+
+/**
+ * Optional behavior overrides for `driveToCompletion`. Each field is
+ * additive — leaving them undefined preserves the previous fail-fast
+ * semantics, so existing callers are unaffected.
+ */
+export interface DriveToCompletionOptions {
+  /**
+   * Routes `kind: 'tool_pause'` frames into a recipient (typically the
+   * agent.activity's AgentToolInquiryChannel call which materializes an
+   * Inquiry, awaits a reply, and returns it here). The driver POSTs the
+   * reply back to the runtime so the session resumes its turn.
+   *
+   * If a `tool_pause` frame arrives without this hook configured, the
+   * driver throws `MissingAgentToolInquiryHookError` (typed; from
+   * `@xemahq/agent-tool-inquiry-channel`).
+   */
+  readonly onAgentToolPause?: OnAgentToolPauseHook;
+  /**
+   * Called once per yielded frame (every kind, including `done`). Lets
+   * callers surface in-flight progress to a UI without forking the
+   * driveToCompletion control flow. Errors thrown by the hook are
+   * swallowed at the call site — a misbehaving observer never aborts
+   * the session drive.
+   */
+  readonly onFrame?: (frame: SessionFrame) => void;
+  /**
+   * Called when the underlying runtime reports per-step LLM token
+   * usage (e.g. OpenCode's `step_finished` event). Fires once per
+   * step. `totalTokens` is the sum of input + output + reasoning
+   * (cache reads/writes are NOT included — they are not billable
+   * generation tokens). The driver routes runtime-specific token
+   * usage shapes through this single normalized hook so the kernel
+   * stays runtime-agnostic.
+   *
+   * Used by the agent.activity to decrement the composition's
+   * `tokenBudget` counter and trip a hard abort on breach. Errors
+   * thrown by the hook are NOT swallowed: a breach throw MUST
+   * propagate so the driver tears down the stream and stops burning
+   * tokens. Other thrown errors also surface so they are not
+   * silently lost.
+   */
+  readonly onTokenUsage?: (usage: {
+    readonly totalTokens: number;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly reasoningTokens: number;
+  }) => void;
+}
+
+export interface AgentSessionDriver {
+  drive(
+    allocation: WorkerAllocation,
+    params: DrivePromptParams,
+    abortSignal: AbortSignal,
+  ): AsyncIterable<SessionFrame>;
+  driveToCompletion(
+    allocation: WorkerAllocation,
+    params: DrivePromptParams,
+    abortSignal: AbortSignal,
+    options?: DriveToCompletionOptions,
+  ): Promise<DriveResult>;
+}