@bevel-software/ael 0.0.0-stage → 0.1.0

package/src/temporal/payload-codec.ts

@@ -0,0 +1,84 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto';
+import type { DataConverter, Payload, PayloadCodec } from '@temporalio/common';
+
+/**
+ * What crosses Temporal is stored in its history: a container step's input
+ * carries the actor's vault values and the run key, and the server keeps
+ * every input for the namespace's retention. This codec encrypts every
+ * payload the platform and the executors exchange (AES-256-GCM, a key
+ * derived from `TEMPORAL_PAYLOAD_KEY`) before it leaves the process and
+ * decrypts it on arrival; the history holds ciphertext, the UI shows none of
+ * it. Both sides hold the same key; a side without it cannot read a step.
+ */
+export const ENCRYPTED_ENCODING = 'binary/encrypted';
+const ENCODING_KEY = 'encoding';
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+
+const utf8 = (s: string) => new TextEncoder().encode(s);
+
+export class EncryptingPayloadCodec implements PayloadCodec {
+  private readonly key: Buffer;
+
+  constructor(secret: string) {
+    if (!secret.trim()) throw new Error('the payload key is empty');
+    this.key = createHash('sha256').update(secret).digest();
+  }
+
+  async encode(payloads: Payload[]): Promise<Payload[]> {
+    return payloads.map((p) => this.encrypt(p));
+  }
+
+  async decode(payloads: Payload[]): Promise<Payload[]> {
+    return payloads.map((p) => (isEncrypted(p) ? this.decrypt(p) : p));
+  }
+
+  private encrypt(payload: Payload): Payload {
+    const plain = Buffer.from(JSON.stringify(serializable(payload)), 'utf8');
+    const iv = randomBytes(IV_BYTES);
+    const cipher = createCipheriv('aes-256-gcm', this.key, iv);
+    const body = Buffer.concat([cipher.update(plain), cipher.final()]);
+    return { metadata: { [ENCODING_KEY]: utf8(ENCRYPTED_ENCODING) }, data: Buffer.concat([iv, cipher.getAuthTag(), body]) };
+  }
+
+  private decrypt(payload: Payload): Payload {
+    const data = Buffer.from(payload.data ?? new Uint8Array());
+    if (data.length < IV_BYTES + TAG_BYTES) throw new Error('encrypted payload is too short');
+    const decipher = createDecipheriv('aes-256-gcm', this.key, data.subarray(0, IV_BYTES));
+    decipher.setAuthTag(data.subarray(IV_BYTES, IV_BYTES + TAG_BYTES));
+    let plain: Buffer;
+    try {
+      plain = Buffer.concat([decipher.update(data.subarray(IV_BYTES + TAG_BYTES)), decipher.final()]);
+    } catch {
+      throw new Error('encrypted payload could not be decrypted: the other side holds a different TEMPORAL_PAYLOAD_KEY');
+    }
+    return fromSerializable(JSON.parse(plain.toString('utf8')) as SerializablePayload);
+  }
+}
+
+/** The data converter both the platform and the executors run with when a key is set: every payload through the codec. */
+export function dataConverterFor(payloadKey: string | undefined): DataConverter | undefined {
+  return payloadKey?.trim() ? { payloadCodecs: [new EncryptingPayloadCodec(payloadKey)] } : undefined;
+}
+
+export function isEncrypted(payload: Payload): boolean {
+  const encoding = payload.metadata?.[ENCODING_KEY];
+  return encoding !== undefined && encoding !== null && Buffer.from(encoding).toString('utf8') === ENCRYPTED_ENCODING;
+}
+
+interface SerializablePayload {
+  metadata: Record<string, string>;
+  data: string | null;
+}
+
+function serializable(payload: Payload): SerializablePayload {
+  const metadata: Record<string, string> = {};
+  for (const [k, v] of Object.entries(payload.metadata ?? {})) if (v) metadata[k] = Buffer.from(v).toString('base64');
+  return { metadata, data: payload.data ? Buffer.from(payload.data).toString('base64') : null };
+}
+
+function fromSerializable(s: SerializablePayload): Payload {
+  const metadata: Record<string, Uint8Array> = {};
+  for (const [k, v] of Object.entries(s.metadata)) metadata[k] = Buffer.from(v, 'base64');
+  return { metadata, data: s.data === null ? null : Buffer.from(s.data, 'base64') };
+}

package/src/transcript/render.ts

@@ -0,0 +1,106 @@
+import type { RunEvent } from '../run/contract.js';
+
+/**
+ * Renders a run's events as a readable markdown transcript. Every access is
+ * defensive: the events were stored by an earlier version of this library or
+ * redacted on the way in, so an unexpected shape is skipped, never thrown on.
+ */
+
+const TOOL_INPUT_CAP = 4_000;
+const TOOL_RESULT_CAP = 20_000;
+
+export interface TranscriptMeta {
+  /** The run's title: a work item's path, a workflow name, a step. */
+  title: string;
+  step?: string;
+  attempt?: number;
+  startedAt?: string;
+}
+
+function capped(text: string, max: number): string {
+  if (text.length <= max) return text;
+  return `${text.slice(0, max)}\n…truncated (${text.length} chars total)`;
+}
+
+function safeJson(v: unknown): string {
+  try {
+    return JSON.stringify(v, null, 2) ?? String(v);
+  } catch {
+    return String(v);
+  }
+}
+
+/** The text of a tool output: a string, MCP-style content blocks, or anything else as JSON. */
+function outputText(output: unknown): string {
+  if (typeof output === 'string') return output;
+  if (output && typeof output === 'object' && Array.isArray((output as { content?: unknown }).content)) {
+    const blocks = (output as { content: unknown[] }).content;
+    const texts = blocks
+      .map((b) => (b && typeof b === 'object' && (b as { type?: unknown }).type === 'text' ? String((b as { text?: unknown }).text ?? '') : ''))
+      .filter(Boolean);
+    if (texts.length > 0) return texts.join('\n');
+  }
+  return output == null ? '' : safeJson(output);
+}
+
+export function renderTranscript(events: readonly RunEvent[], meta: TranscriptMeta): string {
+  const heading = meta.step ? `${meta.step}${meta.attempt ? ` (attempt ${meta.attempt})` : ''}` : meta.title;
+  const lines: string[] = [`# Transcript — ${heading}`, ''];
+
+  const started = events.find((e) => e.type === 'session_started');
+  const headerBits = [`Run: \`${meta.title}\``];
+  if (started && started.type === 'session_started') {
+    headerBits.push(`Harness: \`${started.harness}\``);
+    if (started.model) headerBits.push(`Model: \`${started.model}\``);
+    if (started.sessionId) headerBits.push(`Session: \`${started.sessionId}\``);
+  }
+  if (meta.startedAt) headerBits.push(`Started: ${meta.startedAt}`);
+  lines.push(headerBits.join(' · '), '');
+
+  for (const ev of events) {
+    try {
+      switch (ev.type) {
+        case 'user':
+          lines.push(`**User:** ${ev.text}`, '');
+          break;
+        case 'assistant':
+          if (ev.text.trim()) lines.push(ev.text, '');
+          break;
+        case 'reasoning':
+          if (ev.text.trim()) lines.push(...ev.text.split('\n').map((l) => `> ${l}`), '');
+          break;
+        case 'tool_call':
+          lines.push(`**→ ${ev.name}**`, '```json', capped(safeJson(ev.input), TOOL_INPUT_CAP), '```', '');
+          break;
+        case 'tool_result':
+          lines.push(ev.isError ? '```text (error)' : '```', capped(outputText(ev.output), TOOL_RESULT_CAP), '```', '');
+          break;
+          break;
+        case 'verdict':
+          lines.push(`**Verdict:** ${ev.verdict}`, '');
+          break;
+        case 'outputs':
+          lines.push('**Outputs:**', '```json', capped(safeJson(ev.values), TOOL_INPUT_CAP), '```', '');
+          break;
+        case 'error':
+          lines.push(`**Error:** ${ev.message}`, '');
+          break;
+        case 'session_ended': {
+          lines.push('---', '');
+          const bits: string[] = [ev.ok ? 'ended ok' : 'ended with failure'];
+          if (ev.usage && (ev.usage.input !== undefined || ev.usage.output !== undefined)) {
+            bits.push(`tokens ${ev.usage.input ?? '?'} in / ${ev.usage.output ?? '?'} out`);
+          }
+          lines.push(bits.join(' · '), '');
+          break;
+        }
+        default:
+          break;
+      }
+    } catch {
+      continue;
+    }
+  }
+
+  return lines.join('\n').trimEnd() + '\n';
+}

package/src/workflow/definition.ts

@@ -0,0 +1,196 @@
+/**
+ * The parsed shape of a `.workflow` and the pure helpers over it. This file
+ * has NO imports: it is loaded inside Temporal's workflow sandbox by the
+ * interpreter, where `node:*` and third-party modules are not available. The
+ * parser that produces these values lives in `workflow-file.ts`.
+ */
+
+/** How a step executes. `tool_chain` runs a tool chain as the actor, without a model. */
+export type StepKind = 'agent' | 'tool_chain' | 'wait' | 'choice';
+
+/** Terminal routing targets, reserved and unavailable as step names. */
+export const TERMINAL_TARGETS = ['done', 'failed', 'blocked'] as const;
+export type TerminalTarget = (typeof TERMINAL_TARGETS)[number];
+
+/** The error vocabulary: a closed set the file can match on, plus `ALL` as the wildcard matched last. */
+export const ERROR_NAMES = ['Fail', 'Blocked', 'Timeout', 'HarnessError', 'NoVerdict', 'ProbeError', 'ALL'] as const;
+export type ErrorName = (typeof ERROR_NAMES)[number];
+
+/**
+ * Where a run executes, one string in the file: `none` (in the platform
+ * process), an image reference, or the path of a Dockerfile in the knowledge
+ * base (built on the executor).
+ */
+export type Environment = { kind: 'none' } | { kind: 'image'; ref: string } | { kind: 'dockerfile'; path: string };
+
+/** Retriers re-run a step IN PLACE. Matched before any catcher. */
+export interface RetryRule {
+  errors: ErrorName[];
+  max: number;
+  backoff?: number;
+}
+
+/** Catchers ROUTE somewhere else. Matched only once retries are exhausted. */
+export interface CatchRule {
+  errors: ErrorName[];
+  then: string;
+  max?: number;
+  onExhausted?: string;
+}
+
+export interface SystemPromptSpec {
+  skill?: string;
+  extend?: string;
+}
+
+export interface Comparator {
+  op: 'stringEquals' | 'numericEquals' | 'numericGreaterThan' | 'numericLessThan' | 'isPresent';
+  state: string;
+  value?: unknown;
+}
+
+export interface ChoiceRule {
+  when: Comparator;
+  then: string;
+}
+
+export interface EntryBudget {
+  max: number;
+  then: string;
+}
+
+export interface StepDef {
+  name: string;
+  /** 1-based position in file order. */
+  index: number;
+  /** Entered only via another step's routing; has no implicit successor. */
+  offPath: boolean;
+  kind: StepKind;
+  /** agent steps: repo-relative path of the `.agent` to run as; absent means the deployment's default configuration. */
+  agent?: string;
+  systemPrompt?: SystemPromptSpec;
+  /** agent and wait steps: the prompt; tool_chain steps: the chain's source. */
+  instructions: string;
+  verdict?: string;
+  /** agent and tool_chain steps: `continue`, a terminal target, or an outcome→target map. */
+  then?: string | Record<string, string>;
+  /** agent steps: the STATE keys this step is expected to write in OUTPUTS. */
+  outputs?: string[];
+  /** wait steps: the probe's legal outcomes → routing target. */
+  outcomes?: Record<string, string>;
+  /** wait steps: a tool chain that answers one of `outcomes` or `wait`; absent means the gate waits for a signal. */
+  probe?: string;
+  choices?: ChoiceRule[];
+  default?: string;
+  retry?: RetryRule[];
+  catch?: CatchRule[];
+  entries?: EntryBudget;
+}
+
+export type ParamSource = { kind: 'ticket'; field: string } | { kind: 'follow'; link: string; field: string };
+
+export interface RequiredParam {
+  name: string;
+  from?: { link: string; field: string };
+}
+
+export interface ParametersDef {
+  sources: ParamSource[];
+  require: RequiredParam[];
+  optional: string[];
+}
+
+/**
+ * A personal executor's name, as a run's start or its trigger names it: a
+ * person runs it on their own machine (behind their VPN, say) and only
+ * their own runs reach it.
+ */
+export const PERSONAL_EXECUTOR_NAME = /^[a-z0-9][a-z0-9-]{0,39}$/;
+
+export interface WorkflowDefinition {
+  id: string;
+  name: string;
+  description?: string;
+  environment: Environment;
+  /** True when the file was the short form (`prompt:`); the one step is then named `Run`. */
+  shortForm: boolean;
+  parameters: ParametersDef;
+  /** STATE keys the interpreter owns; a step's outputs may never write them. */
+  reservedStateKeys: string[];
+  defaults: { retry: RetryRule[]; catch: CatchRule[] };
+  steps: StepDef[];
+  /** Step names in execution order, off-path steps excluded. */
+  happyPath: string[];
+  /**
+   * Content hash of the steps and their routing. A run records it at start; a
+   * mismatch at the next step blocks rather than silently restarting.
+   */
+  version: string;
+}
+
+export function stepByName(def: WorkflowDefinition, name: string): StepDef | undefined {
+  return def.steps.find((s) => s.name === name);
+}
+
+/** Next happy-path step after `name`; null when `name` is the last one. */
+export function nextAfter(def: WorkflowDefinition, name: string): string | null {
+  const i = def.happyPath.indexOf(name);
+  if (i === -1) throw new Error(`nextAfter: "${name}" is not on the happy path`);
+  return def.happyPath[i + 1] ?? null;
+}
+
+export function isTerminalTarget(target: string): target is TerminalTarget {
+  return (TERMINAL_TARGETS as readonly string[]).includes(target);
+}
+
+/** Step name → slug, used for statuses and transcript names. */
+export function stepSlug(name: string): string {
+  return name.toLowerCase().trim().replace(/[^a-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+}
+
+/** One comparison of a `choice` step against the run's STATE. */
+export function evaluate(cmp: Comparator, state: Record<string, unknown>): boolean {
+  const value = state[cmp.state];
+  switch (cmp.op) {
+    case 'isPresent':
+      return value !== undefined && value !== null && value !== '';
+    case 'stringEquals':
+      return String(value) === String(cmp.value);
+    case 'numericEquals':
+      return Number(value) === Number(cmp.value);
+    case 'numericGreaterThan':
+      return Number(value) > Number(cmp.value);
+    case 'numericLessThan':
+      return Number(value) < Number(cmp.value);
+  }
+}
+
+/**
+ * A step's OUTPUTS with the interpreter's own keys removed. A step cannot move
+ * its run, reset its budget or drop its claim by writing `step` or `attempts`
+ * into its outputs, by accident or otherwise.
+ */
+export function stripReservedKeys(
+  outputs: Record<string, unknown>,
+  reserved: readonly string[],
+  onDropped?: (key: string) => void,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(outputs)) {
+    if (reserved.includes(key)) onDropped?.(key);
+    else out[key] = value;
+  }
+  return out;
+}
+
+/**
+ * Substitute `${name}` references in step text with resolved parameter and
+ * state values. An unresolved reference is LEFT AS WRITTEN: a session reading
+ * `${featurePrUrl}` can say the value is missing, an empty string cannot.
+ */
+export function interpolate(text: string, values: Record<string, unknown>): string {
+  return text.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (whole, name: string) => {
+    const value = values[name];
+    return value === undefined || value === null || value === '' ? whole : String(value);
+  });
+}

package/src/workflow/failure-policy.ts

@@ -0,0 +1,100 @@
+import type { CatchRule, ErrorName, RetryRule, StepDef, WorkflowDefinition } from './workflow-file.js';
+import type { Verdict } from '../run/contract.js';
+
+/**
+ * Typed failure handling, on Amazon States Language's model.
+ *
+ * 1. **Retriers run IN PLACE, catchers ROUTE.** Retriers are matched first, in
+ *    array order, first match wins; only when they are exhausted (or none
+ *    matched) do catchers run, also in order.
+ * 2. **Counters count per CATCHER TARGET, per work item.** "This item has been
+ *    sent back to Coding N times" is the question worth capping.
+ *
+ * Per-step rules override the workflow defaults entirely rather than merging:
+ * a step that declares its own policy means the default did not fit.
+ */
+
+/** STATE key holding the per-target loop counters. */
+export const ATTEMPTS_KEY = 'attempts';
+/** STATE key holding the in-place retry count for the current step. */
+export const RETRIES_KEY = 'retries';
+/** STATE key holding how many times the item has entered each budgeted step. */
+export const ENTRIES_KEY = 'entries';
+
+export interface FailureContext {
+  step: StepDef;
+  error: ErrorName;
+  /** Per-target loop counters from STATE. */
+  attempts: Record<string, number>;
+  /** In-place retry counts, keyed by step AND retrier (see `retryKey`). */
+  retries: Record<string, number>;
+}
+
+/** The counter a retrier spends, one per step per retrier, named after the errors the rule lists. */
+export function retryKey(stepName: string, rule: RetryRule): string {
+  return `${stepName} · ${rule.errors.join('+')}`;
+}
+
+/** Every retry counter that belongs to `stepName`, under either spelling. */
+export function isRetryKeyOf(stepName: string, key: string): boolean {
+  return key === stepName || key.startsWith(`${stepName} · `);
+}
+
+export type FailureDecision =
+  /** Re-run the same step. `delayMs` is 0 when the rule declares no backoff. */
+  | { action: 'retry'; delayMs: number; attempt: number; max: number; counterKey: string }
+  /** Route to another step or a terminal target. */
+  | { action: 'route'; target: string; counterKey?: string; count?: number; max?: number }
+  /** Nothing matched — the workflow declared no handling for this error. */
+  | { action: 'unhandled' };
+
+function matches(errors: ErrorName[], error: ErrorName): boolean {
+  return errors.includes(error) || errors.includes('ALL');
+}
+
+/** A step's own policy replaces the defaults when the step writes one — an empty one included: `retry: []` means no retries, not the defaults'. */
+function rulesFor(def: WorkflowDefinition, step: StepDef): { retry: RetryRule[]; catch: CatchRule[] } {
+  return {
+    retry: step.retry ?? def.defaults.retry,
+    catch: step.catch ?? def.defaults.catch,
+  };
+}
+
+export function decide(def: WorkflowDefinition, ctx: FailureContext): FailureDecision {
+  const rules = rulesFor(def, ctx.step);
+
+  for (const rule of rules.retry) {
+    if (!matches(rule.errors, ctx.error)) continue;
+    const counterKey = retryKey(ctx.step.name, rule);
+    const used = ctx.retries[counterKey] ?? 0;
+    if (used < rule.max) {
+      const delayMs = rule.backoff ? Math.round(1000 * Math.pow(rule.backoff, used)) : 0;
+      return { action: 'retry', delayMs, attempt: used + 1, max: rule.max, counterKey };
+    }
+    // First match wins, and it is spent: fall through to the catchers.
+    break;
+  }
+
+  for (const rule of rules.catch) {
+    if (!matches(rule.errors, ctx.error)) continue;
+    if (rule.max === undefined) return { action: 'route', target: rule.then };
+    const count = (ctx.attempts[rule.then] ?? 0) + 1;
+    if (count > rule.max) {
+      return { action: 'route', target: rule.onExhausted ?? 'failed', counterKey: rule.then, count, max: rule.max };
+    }
+    return { action: 'route', target: rule.then, counterKey: rule.then, count, max: rule.max };
+  }
+
+  return { action: 'unhandled' };
+}
+
+/**
+ * Classify a session outcome into an error name. `BLOCKED` is the one an agent
+ * declares about itself: the cause is external, re-running cannot fix it, and
+ * no attempt is charged.
+ */
+export function errorForVerdict(verdict: Verdict | undefined): ErrorName {
+  if (verdict === 'BLOCKED') return 'Blocked';
+  if (verdict === 'FAIL') return 'Fail';
+  return 'NoVerdict';
+}

package/src/workflow/parameters.ts

@@ -0,0 +1,175 @@
+import type { ParametersDef, ParamSource } from './workflow-file.js';
+
+/**
+ * Resolves a run's parameters from the graph, using only the four primitives
+ * the interpreter is allowed to know:
+ *
+ *   1. read a field of the work item,
+ *   2. follow a markdown link in one of its fields,
+ *   3. read a field of the node that lands on,
+ *   4. parse a field as a key/value list.
+ *
+ * Every NAME involved — `Project`, `Delivery Parameters`, `repoUrl` — comes
+ * from the `.workflow` file. Nothing here requires a node type, a field name
+ * or a graph shape.
+ */
+
+export interface ResolvedParameters {
+  values: Record<string, string>;
+  /** Required parameters that nothing supplied. */
+  missing: string[];
+}
+
+export class ParameterResolutionError extends Error {}
+
+/**
+ * The body of a `# Heading` section of a knowledge-base node: the work item
+ * reader's own, so a parameter read and a work item write agree on what a
+ * heading is (`# Project (link parent)` answers `Project`).
+ */
+import { getSection } from '../workitem/node.js';
+
+export { getSection };
+
+/**
+ * Parse a field body as a key/value list: markdown bullets, `key: value` or
+ * `key = value`, backticks around either side, several pairs separated by `·`
+ * on one line. A line without a separator is prose and is skipped. The FIRST
+ * occurrence of a key wins.
+ */
+export function parseKeyValueField(body: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const rawLine of body.split(/\r?\n/)) {
+    const line = rawLine.replace(/^\s*[-*+]\s*/, '').trim();
+    if (!line) continue;
+    for (const part of line.split('·')) {
+      const m = /^\s*`?([A-Za-z_][A-Za-z0-9_]*)`?\s*[:=]\s*(.+?)\s*$/.exec(part);
+      if (!m) continue;
+      const key = m[1];
+      const value = stripDecoration(m[2]);
+      if (value && !(key in out)) out[key] = value;
+    }
+  }
+  return out;
+}
+
+function stripDecoration(raw: string): string {
+  const v = raw.trim();
+  const fenced = /^`([^`]*)`/.exec(v);
+  if (fenced) return fenced[1].trim();
+  return v.replace(/^["']|["']$/g, '').trim();
+}
+
+/** The first markdown link target in a field body, or null. */
+export function firstLinkTarget(body: string): string | null {
+  const m = /\[[^\]]*\]\(([^)]+)\)/.exec(body);
+  return m ? m[1].trim() : null;
+}
+
+/** The first URL in a field body — how a `Repository` field is read. */
+export function firstUrl(body: string): string | null {
+  const m = /https?:\/\/\S+/.exec(body);
+  return m ? m[0].replace(/[.,;)]+$/, '') : null;
+}
+
+/** What the resolver needs to reach the graph. Narrow on purpose — easy to fake. */
+export interface ParameterGraph {
+  itemField(field: string): string | null;
+  linkedField(link: string, field: string): Promise<string | null>;
+}
+
+/**
+ * The two reads the resolver makes of the knowledge base. The platform
+ * implements them over its own services. `readFile` answers null for a file
+ * that is not there or not readable; any other failure is the platform's
+ * and propagates, never read as "no such node".
+ */
+export interface GraphReader {
+  readFile(path: string): Promise<string | null>;
+  /** Paths and line numbers of lines matching a regular expression. */
+  grep(pattern: string): Promise<Array<{ path: string; line: number }>>;
+}
+
+/**
+ * Build a graph reader for one work item. Link targets are resolved relative
+ * to the item's own path when they look like a path, and treated as node ids
+ * otherwise — both spellings appear in real items.
+ */
+export function graphFor(kb: GraphReader, itemPath: string, itemBody: string): ParameterGraph {
+  const cache = new Map<string, string | null>();
+
+  const readLinked = async (link: string): Promise<string | null> => {
+    if (cache.has(link)) return cache.get(link) ?? null;
+    const body = getSection(itemBody, link);
+    const target = body ? firstLinkTarget(body) : null;
+    let content: string | null = null;
+    if (target) {
+      const resolved = target.includes('/') || target.endsWith('.md') ? resolvePath(itemPath, target) : null;
+      if (resolved) {
+        content = await kb.readFile(resolved);
+      } else {
+        const matches = await kb.grep(`^id:\\s*${escapeRe(target)}\\s*$`);
+        const hit = matches.find((m) => m.line <= 6);
+        content = hit ? await kb.readFile(hit.path) : null;
+      }
+    }
+    cache.set(link, content);
+    return content;
+  };
+
+  return {
+    itemField: (field) => getSection(itemBody, field),
+    async linkedField(link, field) {
+      const content = await readLinked(link);
+      return content ? getSection(content, field) : null;
+    },
+  };
+}
+
+function escapeRe(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/** Resolve `target` relative to the directory of `fromPath`, normalising `..`. */
+function resolvePath(fromPath: string, target: string): string {
+  if (!target.startsWith('.')) return target;
+  const segments = fromPath.split('/').slice(0, -1);
+  for (const part of target.split('/')) {
+    if (part === '.' || part === '') continue;
+    if (part === '..') segments.pop();
+    else segments.push(part);
+  }
+  return segments.join('/');
+}
+
+async function pairsFrom(graph: ParameterGraph, source: ParamSource): Promise<Record<string, string>> {
+  const body = source.kind === 'ticket' ? graph.itemField(source.field) : await graph.linkedField(source.link, source.field);
+  return body ? parseKeyValueField(body) : {};
+}
+
+/**
+ * Resolve the workflow's declared parameters for one work item. Sources are
+ * tried in order and the FIRST hit wins; a required parameter nothing supplies
+ * is reported by name rather than defaulted.
+ */
+export async function resolveParameters(def: ParametersDef, graph: ParameterGraph): Promise<ResolvedParameters> {
+  const values: Record<string, string> = {};
+  for (const source of def.sources) {
+    for (const [key, value] of Object.entries(await pairsFrom(graph, source))) {
+      if (!(key in values)) values[key] = value;
+    }
+  }
+  for (const param of def.require) {
+    if (param.name in values || !param.from) continue;
+    const body = await graph.linkedField(param.from.link, param.from.field);
+    if (!body) continue;
+    const value = firstUrl(body) ?? body.split(/\r?\n/).map((l) => l.trim()).find(Boolean);
+    if (value) values[param.name] = value;
+  }
+  const missing = def.require.map((p) => p.name).filter((name) => !values[name]);
+  return { values, missing };
+}
+
+// `interpolate` lives in definition.ts (the sandbox-safe module); re-exported
+// here because it belongs to the parameters story for a reader.
+export { interpolate } from './definition.js';