@bevel-software/ael 0.0.0-stage → 0.2.0

package/src/interpreter/scheduled.workflow.ts

@@ -0,0 +1,28 @@
+import { ParentClosePolicy, executeChild, proxyActivities, uuid4 } from '@temporalio/workflow';
+import { PLATFORM_TASK_QUEUE, type InterpreterActivities } from './contract.js';
+import { interpret } from './interpret.workflow.js';
+
+const platform = proxyActivities<Pick<InterpreterActivities, 'startTriggeredRun'>>({
+  taskQueue: PLATFORM_TASK_QUEUE,
+  startToCloseTimeout: '5 minutes',
+  retry: { maximumAttempts: 3, initialInterval: '5 seconds' },
+});
+
+/**
+ * What a Temporal schedule starts: one workflow per firing that asks the
+ * platform to prepare the run (thread, work item) and then runs the
+ * interpreter as its child, waiting for it. The wait is the point: the
+ * schedule's overlap policy is buffer-one, and it judges overlap by THIS
+ * workflow — a firing that lands while the run is still going is kept and
+ * starts right after it, a second one is dropped. Were this workflow to end
+ * once the run had merely started, every firing would overlap a run in
+ * flight. Abandoned on close, so a schedule deleted mid-run (the trigger
+ * paused) leaves the run to finish. The run's id is chosen here, replay-safe,
+ * so the preparing activity's retries make one run, not one per attempt.
+ */
+export async function startScheduledRun(input: { triggerId: string }): Promise<{ runId: string | null }> {
+  const { run } = await platform.startTriggeredRun({ triggerId: input.triggerId, firedAt: new Date().toISOString(), runId: uuid4() });
+  if (!run) return { runId: null };
+  await executeChild(interpret, { workflowId: `run-${run.runId}`, args: [run], taskQueue: PLATFORM_TASK_QUEUE, parentClosePolicy: ParentClosePolicy.ABANDON });
+  return { runId: run.runId };
+}

package/src/interpreter/workflows.ts

@@ -0,0 +1,8 @@
+/**
+ * The workflows a Temporal worker registers: point `workflowsPath` at this
+ * file. Everything it imports is sandbox-safe (no `node:*`, no third-party
+ * modules besides `@temporalio/workflow`).
+ */
+export { cancelRunSignal, gateOutcomeSignal, interpret } from './interpret.workflow.js';
+export { dispatch, dispatcherRunsQuery, dispatcherStateQuery, enqueueSignal, settingsSignal, stopDispatcherSignal, type DispatchInput, type DispatchSettings, type DispatcherState, type Enqueued } from './dispatcher.workflow.js';
+export { startScheduledRun } from './scheduled.workflow.js';

package/src/run/contract.ts

@@ -0,0 +1,150 @@
+import type { AgentDefinition } from '../agent/agent-file.js';
+
+/**
+ * The run contract: what the platform hands a harness to run one step, and
+ * what every harness answers in the same shape. Nothing downstream — the
+ * interpreter's failure policy, the thread store, the live view — knows which
+ * harness ran.
+ */
+
+export type Verdict = 'PASS' | 'FAIL' | 'BLOCKED';
+
+/** What a run is given: the trigger's input, or a step's instructions. */
+export interface RunInput {
+  /** The trigger's words: a webhook body, Run now text, the kb node, the `ask` prompt. Not a place for a secret — nothing redacts it; a configuration's `env:` is where secrets go. */
+  text: string;
+  images?: Array<{ mediaType: string; dataBase64: string }>;
+}
+
+/**
+ * The run key: a connection key minted for the actor and scoped to the step's
+ * configuration. The only credential a run holds. The harness uses it for the
+ * platform's MCP endpoint and, in-process, for the model gateway.
+ */
+export interface ActorKey {
+  token: string;
+  /** The key's id, for the audit log and for revocation at run end. */
+  keyId?: string;
+}
+
+/** Where the platform is, from the session's point of view. */
+export interface PlatformEndpoints {
+  /** The platform's MCP endpoint (streamable HTTP). Tools are called as the actor through it. */
+  mcpUrl: string;
+  /** The platform's OpenAI-compatible model gateway, authenticated with the run key. */
+  gatewayUrl: string;
+  /** The gateway model a configuration without `model` runs on. */
+  gatewayModel: string;
+  /** The thinking level such a session runs with (off | minimal | low | medium | high); off when absent. A configuration's `model: …:<level>` overrides it. */
+  gatewayThinking?: string;
+  /** The context window of the gateway model, in tokens, as the platform's model configuration reports it; 200k when absent. The output budget is cut to what fits, so a window smaller than the model's starves it. */
+  gatewayContextWindow?: number;
+  /**
+   * In a run container: the local Hexis MCP server the session reaches its
+   * tools through instead of `mcpUrl`, as the execution layer always ran it.
+   * It serves the platform's tools (still executed on the platform, so the
+   * vault never moves) and materializes and runs the LOCAL ones in the
+   * container — `git` among them, its credential resolved where it runs and
+   * never in the session's environment. Absent in the platform process,
+   * where a session has no shell to run a local tool in.
+   */
+  localMcp?: LocalMcpServer;
+}
+
+/** A stdio MCP server: the command, and its environment (the key travels here, never in argv). */
+export interface LocalMcpServer {
+  command: string;
+  args: string[];
+  env: Record<string, string>;
+}
+
+/** The name sessions see the knowledge base's MCP server under; tool ids are `mcp__knowledge-base__<tool>`, as in the execution layer. */
+export const MCP_SERVER_NAME = 'knowledge-base';
+
+/**
+ * The harness's own session state, opaque to everyone but the harness that
+ * wrote it. Stored on the thread after every turn; a crashed or moved step is
+ * restored from it, anywhere.
+ */
+export interface SessionState {
+  harness: string;
+  version: number;
+  data: unknown;
+}
+
+/**
+ * The event vocabulary the thread store keeps. Every harness translates its
+ * own stream into this one; the transcript renderer and the live view read
+ * nothing else. `at` is an ISO timestamp.
+ */
+export type RunEvent =
+  | { type: 'session_started'; at: string; harness: string; model?: string; sessionId?: string; resumed: boolean; /** The tools the session may call, built-in and platform, once the harness has activated them. */ tools?: string[] }
+  | { type: 'user'; at: string; text: string }
+  | { type: 'assistant'; at: string; text: string }
+  /**
+   * What the model weighed before one of its messages, as its provider summarised it (when the gateway asked for a
+   * summary): kept with the run so a reply can be read against its reasons afterwards. Never part of the reply.
+   */
+  | { type: 'reasoning'; at: string; text: string }
+  | { type: 'tool_call'; at: string; id: string; name: string; input: unknown }
+  | { type: 'tool_result'; at: string; id: string; name: string; output: unknown; isError: boolean }
+  | { type: 'verdict'; at: string; verdict: Verdict }
+  | { type: 'outputs'; at: string; values: Record<string, unknown> }
+  | { type: 'error'; at: string; message: string }
+  | { type: 'session_ended'; at: string; ok: boolean; finalText: string; usage?: { input?: number; output?: number } }
+  /** The run moved: on the RUN's own thread, one per transition the interpreter records — the step entered, a step's verdict, a gate parked on, the end. */
+  | { type: 'transition'; at: string; log: string; status: string; step: string | null; waiting: boolean };
+
+export interface SessionStartParams {
+  input: RunInput;
+  systemPrompt: string;
+  /** The configuration the session runs as. The harness reads its own concerns from it. */
+  agent: AgentDefinition;
+  actorKey: ActorKey;
+  platform: PlatformEndpoints;
+  /** The configuration's `env:` block, resolved. Visible to the agent by construction; the caller redacts it. */
+  env?: Record<string, string>;
+  /** A working directory, for harnesses that have one. In-process sessions have none. */
+  cwd?: string;
+  /** The key the caller follows the session by (the run's id, not a step thread's id): a message handed to a running session finds it by this. */
+  runKey?: string;
+  /** The state to resume from, when the thread holds one. */
+  state?: SessionState;
+  timeoutMs?: number;
+  /** Fires when the run is cancelled: the session is aborted where it is. */
+  signal?: AbortSignal;
+  /** Ask once for a `RESULT:` line when the session ends cleanly without one. */
+  expectVerdict?: boolean;
+  /** Every event as it happens, in order. The caller stores it on the thread. */
+  onEvent?: (event: RunEvent) => void;
+  /** The state after every turn, for the thread. The caller stores it; the harness never persists it. */
+  onState?: (state: SessionState) => void;
+}
+
+export interface SessionResult {
+  ok: boolean;
+  /** The session exceeded its budget — a `Timeout`, not a failed step. */
+  timedOut?: boolean;
+  finalText: string;
+  verdict?: Verdict;
+  outputs?: Record<string, unknown>;
+  /**
+   * The provider refused the ACCOUNT, not this step: a subscription or rate
+   * limit. Never a step failure; the executor pauses until `resetAt` and the
+   * work item is left as it was.
+   */
+  accountLimit?: { kind: 'session-limit' | 'not-logged-in'; resetAt?: number; text: string };
+  /** The harness produced no event at all: the step did not run, nothing here is evidence about the item. */
+  sessionNotStarted?: boolean;
+  /** The state to store, so the next turn or a resumed step continues from here. */
+  state?: SessionState;
+  events: RunEvent[];
+}
+
+/** Something that can run one step as a session. One per harness. */
+export interface Harness {
+  readonly name: string;
+  run(params: SessionStartParams): Promise<SessionResult>;
+  /** Hand a message to the session running under `runKey`: answered in that session's own reply. 'absent' when none runs here. */
+  followUp?(runKey: string, text: string): Promise<'queued' | 'absent'>;
+}

package/src/run/outcome.ts

@@ -0,0 +1,63 @@
+import type { AgentStepOutcome } from '../interpreter/contract.js';
+import type { Redactor } from '../shared/redact.js';
+import type { SessionResult, Verdict } from './contract.js';
+
+/**
+ * A session's result as the interpreter reads it. One rule for every place a
+ * step runs — the platform's own worker, a container on an executor — so a
+ * step's fate never depends on where it ran.
+ */
+export function outcomeFromResult(result: SessionResult, opts: { threadId: string; expectVerdict: boolean; redactor: Redactor }): AgentStepOutcome {
+  const { threadId, redactor } = opts;
+  if (result.accountLimit) {
+    return { kind: 'account-limit', threadId, resetAt: result.accountLimit.resetAt ?? null, text: redactor.text(result.accountLimit.text) };
+  }
+  if (result.sessionNotStarted) {
+    return { kind: 'harness-error', threadId, reason: 'the session produced no event' };
+  }
+  if (result.timedOut) {
+    return { kind: 'timeout', threadId, reason: 'the step exceeded its budget' };
+  }
+  if (!result.ok) {
+    const error = result.events.find((e) => e.type === 'error');
+    return { kind: 'harness-error', threadId, reason: redactor.text(error && error.type === 'error' ? error.message : 'the session ended with an error') };
+  }
+  // A step with no verdict line declared (the short form) passes when its
+  // session ends cleanly; one that declared a verdict must give it.
+  const verdict: Verdict | undefined = result.verdict ?? (opts.expectVerdict ? undefined : 'PASS');
+  if (!verdict) {
+    return { kind: 'no-verdict', threadId, reason: 'the session ended without a RESULT line' };
+  }
+  return {
+    kind: 'verdict',
+    verdict,
+    threadId,
+    outputs: result.outputs ? redactor.json(result.outputs) : null,
+    reason:
+      verdict === 'PASS'
+        ? null
+        : redactor.text(
+            result.finalText
+              .split(/RESULT:\s*(?:FAIL|BLOCKED)/i)
+              .pop()
+              ?.replace(/^\s*[—-]\s*/, '')
+              .trim() || `verdict ${verdict}`,
+          ),
+  };
+}
+
+/** The thread status an outcome leaves a step thread in. */
+export function threadStatusOf(outcome: AgentStepOutcome): 'running' | 'waiting' | 'done' | 'failed' | 'blocked' {
+  switch (outcome.kind) {
+    case 'verdict':
+      return outcome.verdict === 'PASS' ? 'done' : outcome.verdict === 'BLOCKED' ? 'blocked' : 'failed';
+    case 'blocked':
+      return 'blocked';
+    case 'account-limit':
+      return 'waiting';
+    case 'no-verdict':
+    case 'timeout':
+    case 'harness-error':
+      return 'failed';
+  }
+}

package/src/run/reporter.ts

@@ -0,0 +1,127 @@
+import type { RunEvent, SessionState } from './contract.js';
+
+/**
+ * How a session outside the platform process reports to it: every event and
+ * every turn's state go to the platform's run API with the run key, so the
+ * thread store is the record wherever the step ran, and a moved or restarted
+ * step restores from there.
+ *
+ * Events are sent in order, one request after the other, so the store's
+ * sequence is the session's; the state is sent after the events that led to
+ * it. A request that fails is retried a few times; a request that keeps
+ * failing, or that the platform refuses for good, is logged and dropped
+ * rather than stalling the session — and remembered: the thread is the
+ * record, and `flush` says when the record is incomplete, so the step is
+ * not reported finished with its answer or its saved context gone.
+ */
+/** The HTTP call the reporter makes: `fetch`, narrowed to what the reporter uses of it. */
+export type FetchLike = (url: string, init: { method: string; headers: Record<string, string>; body: string }) => Promise<{ ok: boolean; status: number }>;
+
+export interface RunReporterOptions {
+  /** The platform's API root, e.g. `https://kb.example.com/api`. */
+  apiUrl: string;
+  /** The step thread the events and the state belong to. */
+  threadId: string;
+  /** The run key. */
+  token: string;
+  fetch?: FetchLike;
+  log?: (line: string) => void;
+  /** Attempts per request before it is dropped. */
+  attempts?: number;
+  /** Backoff base in milliseconds. */
+  backoffMs?: number;
+}
+
+export class PlatformRunReporter {
+  private queue: Promise<void> = Promise.resolve();
+  private pending: RunEvent[] = [];
+  private flushing = false;
+  /** The first report that did not land, kept for `flush` to tell. */
+  private lost: string | null = null;
+  private readonly fetchImpl: FetchLike;
+  private readonly log: (line: string) => void;
+  private readonly attempts: number;
+  private readonly backoffMs: number;
+  private readonly sleep: (ms: number) => Promise<void>;
+
+  constructor(
+    private readonly options: RunReporterOptions,
+    sleep: (ms: number) => Promise<void> = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  ) {
+    this.fetchImpl = options.fetch ?? fetch;
+    this.log = options.log ?? (() => undefined);
+    this.attempts = options.attempts ?? 4;
+    this.backoffMs = options.backoffMs ?? 500;
+    this.sleep = sleep;
+  }
+
+  /** Queue an event; events are batched into one request per flush, in order. */
+  onEvent(event: RunEvent): void {
+    this.pending.push(event);
+    if (!this.flushing) this.enqueue(() => this.flushEvents());
+  }
+
+  /** Send the state after everything queued before it. */
+  onState(state: SessionState): void {
+    this.enqueue(async () => {
+      await this.flushEvents();
+      await this.send('PUT', `/agents/runs/${encodeURIComponent(this.options.threadId)}/state`, state);
+    });
+  }
+
+  /**
+   * Wait until everything reported so far has been sent or dropped; throws
+   * when any report was dropped, naming the first, since a thread missing
+   * events or state is not the step's record.
+   */
+  async flush(): Promise<void> {
+    this.enqueue(() => this.flushEvents());
+    await this.queue;
+    if (this.lost) throw new Error(`a report did not reach the platform (${this.lost})`);
+  }
+
+  private enqueue(task: () => Promise<void>): void {
+    this.queue = this.queue.then(task, task);
+  }
+
+  private async flushEvents(): Promise<void> {
+    if (this.pending.length === 0) return;
+    this.flushing = true;
+    try {
+      while (this.pending.length > 0) {
+        const batch = this.pending;
+        this.pending = [];
+        await this.send('POST', `/agents/runs/${encodeURIComponent(this.options.threadId)}/events`, { events: batch });
+      }
+    } finally {
+      this.flushing = false;
+    }
+  }
+
+  private async send(method: 'POST' | 'PUT', path: string, body: unknown): Promise<void> {
+    const url = `${this.options.apiUrl.replace(/\/$/, '')}${path}`;
+    for (let attempt = 1; attempt <= this.attempts; attempt++) {
+      try {
+        const res = await this.fetchImpl(url, {
+          method,
+          headers: { 'content-type': 'application/json', authorization: `Bearer ${this.options.token}` },
+          body: JSON.stringify(body),
+        });
+        if (res.ok) return;
+        // The platform refused this report for good (the key is gone, the
+        // thread is not ours): retrying would not change the answer.
+        if (res.status >= 400 && res.status < 500 && res.status !== 429) {
+          this.log(`${method} ${path}: ${res.status} — dropped`);
+          this.lost ??= `${method} ${path}: ${res.status}`;
+          return;
+        }
+        this.log(`${method} ${path}: ${res.status} (attempt ${attempt})`);
+      } catch (err) {
+        this.log(`${method} ${path}: ${err instanceof Error ? err.message : String(err)} (attempt ${attempt})`);
+      }
+      if (attempt < this.attempts) await this.sleep(this.backoffMs * 2 ** (attempt - 1));
+    }
+    this.log(`${method} ${path}: gave up after ${this.attempts} attempts`);
+    this.lost ??= `${method} ${path}: gave up after ${this.attempts} attempts`;
+  }
+}

package/src/run/system-prompt.ts

@@ -0,0 +1,35 @@
+import type { SystemPromptSpec } from '../workflow/definition.js';
+
+/**
+ * A step's system prompt, composed the one way wherever the step runs: the
+ * configuration's `systemPrompt` (a skill, an extension, or both), then the
+ * step's own, each skill read from the knowledge base — as the actor on the
+ * platform, from the checkout in a local run. A skill that cannot be read
+ * is a refusal, not an omission: running without it would be a different
+ * step from the one the file describes.
+ */
+export class SkillNotReadable extends Error {
+  constructor(readonly skill: string) {
+    super(`skill ${skill} is not there, or not readable`);
+  }
+}
+
+export async function composeSystemPrompt(
+  agent: { name: string; description: string; systemPrompt?: SystemPromptSpec },
+  step: { systemPrompt?: SystemPromptSpec | null },
+  /** A repo-relative file's text, or null when it is not there or not readable by whoever asks. */
+  readRepoFile: (repoPath: string) => Promise<string | null>,
+): Promise<string> {
+  const parts: string[] = [];
+  for (const spec of [agent.systemPrompt, step.systemPrompt]) {
+    if (!spec) continue;
+    if (spec.skill) {
+      const skill = (await readRepoFile(`${spec.skill.replace(/\/$/, '')}/SKILL.md`)) ?? (await readRepoFile(spec.skill));
+      if (skill === null) throw new SkillNotReadable(spec.skill);
+      parts.push(skill.replace(/^---[\s\S]*?\n---\n/, '').trim());
+    }
+    if (spec.extend) parts.push(spec.extend);
+  }
+  if (parts.length === 0) parts.push(`You are ${agent.name}. ${agent.description}`.trim());
+  return parts.join('\n\n');
+}

package/src/run/verdict.ts

@@ -0,0 +1,46 @@
+import type { Verdict } from './contract.js';
+
+/**
+ * What a session that finished without a verdict is asked. It names the three
+ * legal lines and forbids further work: the session has done its step, and
+ * the only thing missing is the sentence the interpreter routes on.
+ */
+export const VERDICT_NUDGE =
+  'Your last message did not end with the verdict line this step requires, so the runner cannot tell how it went. ' +
+  'Do no further work and call no tools. Judge the work you just finished and reply with exactly one line: ' +
+  '`RESULT: PASS`, `RESULT: FAIL — <reason>` or `RESULT: BLOCKED — <reason>`.';
+
+/** Extract the last `RESULT: PASS|FAIL|BLOCKED` line the agent emitted. */
+export function parseVerdict(text: string): Verdict | undefined {
+  const matches = [...text.matchAll(/RESULT:\s*(PASS|FAIL|BLOCKED)/gi)];
+  if (matches.length === 0) return undefined;
+  return matches[matches.length - 1][1].toUpperCase() as Verdict;
+}
+
+/**
+ * The step's `OUTPUTS`: a fenced JSON object after the word `OUTPUTS`, the
+ * last one in the text when there are several. Null when there is none or it
+ * does not parse as an object; a step that wanted to record something and got
+ * the fence wrong is logged by the caller, not failed.
+ */
+export function parseOutputs(text: string): Record<string, unknown> | null {
+  const matches = [...text.matchAll(/OUTPUTS[^\n]*\n```(?:json)?\s*\n([\s\S]*?)\n```/gi)];
+  if (matches.length === 0) return null;
+  try {
+    const parsed: unknown = JSON.parse(matches[matches.length - 1][1]);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+export function tail(text: string, max = 2000): string {
+  const t = text.trim();
+  return t.length > max ? t.slice(-max) : t || '(no output)';
+}
+
+/** The START of what a session that never ran had to say: the cause of an early exit is its first complaint. */
+export function head(text: string, max = 2000): string {
+  const t = text.trim();
+  return t.length > max ? t.slice(0, max) : t;
+}

package/src/shared/front-matter.ts

@@ -0,0 +1,27 @@
+import { parse as parseYaml } from 'yaml';
+
+/**
+ * The document shape every file this library reads shares — `.agent` and
+ * `.workflow` alike (and `.tool`, which the platform reads): one `---` fenced
+ * YAML block, prose after the fence. A file without a fence is read as YAML
+ * whole. The one place the fence is spelled, so the two parsers cannot drift
+ * on what counts as a document.
+ */
+const FENCE = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
+
+/** The YAML document of a fenced file (or of the whole text when there is no fence). Throws the YAML parser's own error. */
+export function yamlDocumentOf(content: string): unknown {
+  const m = FENCE.exec(content);
+  return parseYaml(m ? m[1] : content);
+}
+
+/** A non-empty string value, trimmed; `undefined` for anything else. */
+export function optionalStr(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+/** A plain object, or the parser's own error (`fail`) for anything else. */
+export function plainObject(value: unknown, what: string, fail: (message: string) => Error): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw fail(`${what} must be an object`);
+  return value as Record<string, unknown>;
+}

package/src/shared/redact.ts

@@ -0,0 +1,78 @@
+/**
+ * Scrubs injected secret values out of anything that gets persisted.
+ *
+ * Load-bearing, not tidy. A run's events are stored and shown, and an `.agent`
+ * may have injected vault values into the session's environment — values the
+ * agent can read by construction. A value that reaches a stored event can
+ * only be remediated by rotating it.
+ *
+ * Exact substring replacement, deliberately: a pattern-matching redactor misses
+ * every credential shaped differently from the patterns someone thought of,
+ * and this one knows exactly which strings it injected.
+ */
+
+/**
+ * Values shorter than this are not redacted. A three-character password would
+ * turn every event into confetti and hide the context needed to debug a run;
+ * the fix for a short secret is a longer secret.
+ */
+export const MIN_REDACTABLE_LENGTH = 8;
+
+export class Redactor {
+  private readonly values: string[];
+  /**
+   * The JSON spelling of each value whose spelling differs from the value
+   * (a quote, a backslash or a control character in it): what the value
+   * looks like inside serialised JSON, where `values` would not match it.
+   */
+  private readonly escaped: string[];
+
+  constructor(values: Iterable<string>) {
+    // Longest first: a value that contains another must be replaced before the
+    // shorter one eats part of it and leaves a recognisable tail behind.
+    this.values = [...new Set([...values].filter((v) => v && v.length >= MIN_REDACTABLE_LENGTH))].sort(
+      (a, b) => b.length - a.length,
+    );
+    this.escaped = this.values.map((v) => JSON.stringify(v).slice(1, -1)).filter((e, i) => e !== this.values[i]);
+  }
+
+  /** Replace every occurrence of every known value with a marker. */
+  text(input: string): string {
+    let out = input;
+    for (const value of this.values) out = out.split(value).join('[redacted]');
+    return out;
+  }
+
+  /**
+   * Redact through a JSON structure, keys and values alike: serialise, scrub
+   * (the values' JSON spellings first, then the values), parse back, so a
+   * secret anywhere in a tool input or output is caught. A structure JSON
+   * cannot carry as it is (a cycle, a BigInt) is serialised with those parts
+   * replaced, never returned as it came: unredacted is the one outcome this
+   * must not have.
+   */
+  json<T>(input: T): T {
+    if (this.values.length === 0 || input === undefined) return input;
+    let serialised = safeStringify(input);
+    for (const value of this.escaped) serialised = serialised.split(value).join('[redacted]');
+    return JSON.parse(this.text(serialised)) as T;
+  }
+}
+
+/** `JSON.stringify` that never throws: a cycle becomes a marker, a BigInt its digits. */
+function safeStringify(input: unknown): string {
+  const seen = new WeakSet<object>();
+  return (
+    JSON.stringify(input, (_key, value: unknown) => {
+      if (typeof value === 'bigint') return value.toString();
+      if (value && typeof value === 'object') {
+        if (seen.has(value)) return '[cycle]';
+        seen.add(value);
+      }
+      return value;
+    }) ?? 'null'
+  );
+}
+
+/** A redactor that knows nothing — used where no values were injected. */
+export const NO_REDACTION = new Redactor([]);

package/src/shared/schedule.ts

@@ -0,0 +1,93 @@
+/**
+ * The grammar of a schedule trigger's two keys — durations, cron lines and
+ * ISO date-times — in one place, read by the platform that validates a
+ * trigger and by the app that edits one, so neither mirrors the other.
+ * Browser-safe on purpose: `Intl` and regular expressions, nothing of Node.
+ */
+
+const DURATION = /^\s*(?:(\d+)\s*d)?\s*(?:(\d+)\s*h)?\s*(?:(\d+)\s*m)?\s*(?:(\d+)\s*s)?\s*$/i;
+const ISO_DATE_TIME = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?$/i;
+const CRON_SHORTHAND = /^@(yearly|annually|monthly|weekly|daily|hourly)$/i;
+
+/** `15m`, `1h`, `2h30m`, `1d`, `90s` → milliseconds; null for anything else. */
+export function durationMs(text: string): number | null {
+  const m = DURATION.exec(text);
+  if (!m || !m.slice(1).some(Boolean)) return null;
+  const [d, h, min, s] = m.slice(1).map((v) => Number(v ?? 0));
+  return (((d! * 24 + h!) * 60 + min!) * 60 + s!) * 1000;
+}
+
+/** Whether `text` is a duration: the one spelling of a start or a repeat that needs no time zone. */
+export function isDuration(text: string): boolean {
+  return durationMs(text) !== null;
+}
+
+/** Whether `text` is a cron line Temporal reads: five to seven fields, or one of the `@` words. */
+export function isCron(text: string): boolean {
+  const fields = text.trim().split(/\s+/).length;
+  return CRON_SHORTHAND.test(text.trim()) || (fields >= 5 && fields <= 7);
+}
+
+/** Whether `name` is a time zone this runtime knows (an IANA name such as `Europe/Berlin`, or `UTC`). */
+export function isTimeZone(name: string): boolean {
+  try {
+    new Intl.DateTimeFormat('en-US', { timeZone: name });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** A wall-clock date-time, as an ISO string spells it; `offset` is `Z` or `±HH:MM` when the text carries one, null when it is to be read in some zone. */
+export interface IsoDateTime {
+  year: number;
+  month: number;
+  day: number;
+  hour: number;
+  minute: number;
+  second: number;
+  offset: string | null;
+}
+
+/** `2026-11-20T09:00`, `2026-11-20T09:00:00.000+01:00` → its parts; null for anything else. */
+export function parseIsoDateTime(text: string): IsoDateTime | null {
+  const m = ISO_DATE_TIME.exec(text.trim());
+  if (!m) return null;
+  return { year: Number(m[1]), month: Number(m[2]), day: Number(m[3]), hour: Number(m[4]), minute: Number(m[5]), second: Number(m[6] ?? 0), offset: m[7] ?? null };
+}
+
+/**
+ * The instant a wall-clock time names in a zone — what `new Date()` cannot
+ * tell without a library: the zone's offset at that moment is found by
+ * formatting a first guess in the zone and correcting by the difference,
+ * twice, which settles across a DST change.
+ */
+export function wallClockToInstant(parts: Omit<IsoDateTime, 'offset'>, timeZone: string): Date {
+  const wanted = Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second);
+  let guess = wanted;
+  for (let i = 0; i < 2; i++) guess -= zonedUtcMs(guess, timeZone) - wanted;
+  return new Date(guess);
+}
+
+/** The wall clock in `timeZone` at `instantMs`, as if it were UTC — for the offset arithmetic above. */
+function zonedUtcMs(instantMs: number, timeZone: string): number {
+  const fields = new Intl.DateTimeFormat('en-US', { timeZone, hourCycle: 'h23', year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', second: '2-digit' }).formatToParts(new Date(instantMs));
+  const n = (type: string) => Number(fields.find((f) => f.type === type)?.value ?? 0);
+  return Date.UTC(n('year'), n('month') - 1, n('day'), n('hour') % 24, n('minute'), n('second'));
+}
+
+/**
+ * An ISO date-time's absolute instant: its own offset when it carries one,
+ * `timeZone` otherwise. Null when the text is not a date-time, or carries no
+ * offset and no zone was given.
+ */
+export function isoToInstant(text: string, timeZone: string | undefined): Date | null {
+  const parts = parseIsoDateTime(text);
+  if (!parts) return null;
+  if (parts.offset) {
+    const parsed = Date.parse(text.trim());
+    return Number.isNaN(parsed) ? null : new Date(parsed);
+  }
+  if (!timeZone) return null;
+  return wallClockToInstant(parts, timeZone);
+}