@unoverse-platform/studio 0.1.90 → 0.1.91

package/vendor/base/src/manifests/runtime/loops/poll.ts

@@ -0,0 +1,169 @@
+/**
+ * POLLING. One call in the manifest, a job on the wire.
+ *
+ * The third loop, after `paginate` and `chunk`, and the same trade as both: vendors
+ * disagree about the mechanism and agree about the shape. Start work, get a handle, ask
+ * "done yet?" until it is. What differs is description (where the handle lives, which
+ * field says finished, what the status URL looks like); the waiting is computation, so it
+ * belongs here and every long-running node inherits it (DECLARATIVE_NODES.md §2).
+ *
+ * Without this a manifest cannot express a job at all. `run` is an ordered list of
+ * DIFFERENT calls, so a manifest can say "start, then check once" but never "check until".
+ * Every crawler, render farm, transcription and batch-import API in the world works this
+ * way, so the alternative is that all of them stay TypeScript.
+ *
+ * A polled call's reply is the FINAL status payload, not the start payload. The start
+ * reply is a receipt — a job id and nothing else — and handing that back would give the
+ * events table a handle where it expected the answer.
+ */
+import type { ComposedNode } from "../../compose.js";
+import type { RunContext } from "../context.js";
+import { evaluate } from "../templating.js";
+import { sendRequest } from "../http/request.js";
+import { readSettled, assertOk } from "../http/response.js";
+
+/**
+ * A hard ceiling on polls, independent of anything the manifest says.
+ *
+ * Same reasoning as pagination's page cap: `maxAttempts` is the author's bound, and this
+ * is the platform's, because the author's can be wrong. A vendor stuck on "running"
+ * forever would otherwise hold a workflow slot until the process died.
+ */
+const HARD_POLL_CAP = 300;
+
+/** Longest a single poll may wait between attempts. Guards a typo'd intervalMs. */
+const MAX_INTERVAL_MS = 60_000;
+
+export async function fetchPolled(
+  node: ComposedNode,
+  call: any,
+  ctx: RunContext,
+  label: string,
+): Promise<any> {
+  const p = call.poll;
+  const scope = (payload: unknown) => ({ ...ctx, response: payload }) as unknown as Record<string, unknown>;
+
+  /**
+   * Terminal? Asked of the START reply as well as of every poll.
+   *
+   * This is not defensiveness, it is the documented behaviour of at least one vendor we
+   * migrate: Hyperbrowser's unified /web/fetch may finish INLINE and return the completed
+   * result on the POST, with no job id to poll. A manifest that assumed a handle always
+   * came back would try to build a status URL out of `undefined` and fail on exactly the
+   * fast path it was hoping for.
+   */
+  const settled = async (payload: any, where: string): Promise<boolean> => {
+    if (p.failed && (await evaluate(p.failed, scope(payload)))) {
+      const why = p.message ? await evaluate(p.message, scope(payload)) : "no reason given";
+      throw new Error(`${label}: the job failed upstream (${where}) — ${why}`);
+    }
+    return !!(await evaluate(p.until, scope(payload)));
+  };
+
+  // ── Start the job ────────────────────────────────────────────────────────────────
+  const startRes = await sendRequest(node, call, ctx, `${label} (start)`);
+  const start = await readSettled(startRes, call.transport, call.encoding);
+  await assertOk(node, call, start, `${label} (start)`);
+
+  if (await settled(start, "on the start reply")) return start;
+
+  // ── Where to ask ─────────────────────────────────────────────────────────────────
+  // Resolved ONCE, against the start reply, because that is the only place the job id
+  // exists. Re-resolving per attempt against the latest status would work for vendors
+  // that echo the id back and break for the ones that do not.
+  const url = String((await evaluate(p.url, scope(start))) ?? "");
+
+  /**
+   * A MISSING HANDLE IS NOT AN EMPTY STRING, and checking for empty alone misses it.
+   *
+   * A status URL is nearly always built by concatenation, so a job id the vendor did not
+   * send produces ".../jobs/undefined" — a perfectly non-empty URL that 404s on every one
+   * of the next ninety polls and then reports a timeout. The same trap as an auth header
+   * going out as the literal "undefined": the string form of nothing looks like a value.
+   *
+   * So the check is for a path segment that is the WORD undefined or null, which no real
+   * job id ever is.
+   */
+  if (!url.trim() || /\/(undefined|null)(\/|\?|$)/.test(url))
+    throw new Error(
+      `${label}: the job did not finish on the start reply, and poll.url did not resolve to a real URL ` +
+        `(got ${url.trim() ? `"${url}"` : "nothing"}). The start reply was ${JSON.stringify(start).slice(0, 200)}.`,
+    );
+
+  /**
+   * The STATUS CHECK. Auth, headers, retry, transport and error carry over from the call — a status
+   * check is the same conversation with the same vendor — but the start request's method, body and
+   * query do NOT: they described starting work.
+   *
+   * A GET by default, because most vendors put the job id in the path. AWS does not: Textract's
+   * `GetDocumentAnalysis` is a POST carrying `{ JobId }`, signed like any other, and every AWS batch
+   * job is shaped the same way. Hardcoding GET is what kept that whole family in TypeScript.
+   *
+   * `poll.body` is an EXPRESSION over the start reply, exactly like `poll.url`, and resolved here
+   * ONCE for the same reason: the job id exists only in that first response. Resolving it per
+   * attempt against the latest status would work for vendors that echo the id back and quietly
+   * break for the ones that do not — the identical trap the url comment above describes.
+   */
+  const statusBody = p.body ? await evaluate(p.body, scope(start)) : undefined;
+  const statusCall = {
+    ...call,
+    poll: undefined,
+    method: p.method ?? "GET",
+    url,
+    body: statusBody,
+    query: undefined,
+  };
+
+  // RESOLVED, not read: how long to wait is often a dial a person sets, so both may be an
+  // expression over config rather than a constant the manifest bakes in. Same treatment as
+  // toolExchange's turn budget, and for the same reason.
+  const dial = async (v: unknown, fallback: number): Promise<number> => {
+    if (v === undefined || v === null) return fallback;
+    const n = typeof v === "string" ? Number(await evaluate(v, ctx as unknown as Record<string, unknown>)) : Number(v);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+  };
+
+  const interval = Math.min(await dial(p.intervalMs, 2000), MAX_INTERVAL_MS);
+  const attempts = Math.min(await dial(p.maxAttempts, 90), HARD_POLL_CAP);
+
+  /**
+   * THE WAIT NARRATES ITSELF — by STATUS CHANGE, with a heartbeat, never per request.
+   * A job is minutes of silence in the engine log otherwise, and silence gets read as a
+   * hang. Per-attempt logging is the other failure: 300 lines of "still RUNNING" bury the
+   * one line that mattered. The query is cut from the url for the same reason it is cut in
+   * sendRequest: signatures and filters live there.
+   */
+  const startedAt = Date.now();
+  const elapsed = () => Math.round((Date.now() - startedAt) / 1000);
+  const heartbeat = Math.max(1, Math.round(30_000 / interval));
+  let lastStatus: string | undefined;
+  console.log(
+    `[manifests] ${label}: job started — polling ${url.split("?")[0]} every ${Math.round(interval / 1000)}s (up to ${attempts} attempts)`,
+  );
+
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    await new Promise((r) => setTimeout(r, interval));
+
+    const res = await sendRequest(node, statusCall, ctx, `${label} (poll ${attempt}/${attempts})`);
+    const payload = await readSettled(res, call.transport, call.encoding);
+    await assertOk(node, call, payload, `${label} (poll ${attempt}/${attempts})`);
+
+    const status = typeof payload?.status === "string" ? payload.status : undefined;
+    if (status !== lastStatus || attempt % heartbeat === 0)
+      console.log(`[manifests] ${label}: poll ${attempt}/${attempts} — ${status ?? "(no status field)"} after ${elapsed()}s`);
+    lastStatus = status;
+
+    if (await settled(payload, `poll ${attempt}`)) {
+      console.log(`[manifests] ${label}: job finished after ${attempt} polls (${elapsed()}s)`);
+      return payload;
+    }
+  }
+
+  // Timing out is a real outcome, and the message says how long we actually waited rather
+  // than just "timed out": the fix is nearly always a bigger maxAttempts, and a reader
+  // cannot judge that without knowing what the current bound bought them.
+  throw new Error(
+    `${label}: the job was still unfinished after ${attempts} polls ` +
+      `(~${Math.round((attempts * interval) / 1000)}s). Raise poll.maxAttempts if this job is legitimately slow.`,
+  );
+}

package/vendor/base/src/manifests/runtime/narrate.ts

@@ -0,0 +1,53 @@
+/**
+ * THE NARRATOR — the running commentary a node gives while it works.
+ *
+ * Its own module, and NOT part of the tool loop, because narration is a property of the NODE
+ * rather than of having tools. It used to live inside the loop, which meant a node with no MCP
+ * provider wired silently never narrated at all.
+ *
+ * The manifest describes the whole of it — endpoint, model, instructions, copy. The only part
+ * that cannot be data is the timing, which is why there is any code here:
+ *
+ *   a local line at 0ms, because the round trip has a ~1s floor and the first token beats it
+ *   never awaited, so narration cannot delay the work it describes
+ *   fall back on any failure, so a missing narrator never fails a turn
+ *   drop late lines, since one arriving after the answer reads as still working
+ */
+import type { ComposedNode } from "../compose.js";
+import type { RunContext } from "./context.js";
+import { evaluate, render } from "./templating.js";
+import { sendRequest } from "./http/request.js";
+import type { Emitter } from "./events.js";
+
+/** Bound for one run. `fire` on each thing worth narrating, `settle` when the answer lands. */
+export function makeNarrator(node: ComposedNode, ctx: RunContext, emitter: Emitter) {
+  const n = node.api?.narrate;
+  let settled = false;
+  let firstLine = false;
+
+  // Through the table like everything else: the narrator does not know which connector
+  // it lands on, only that it produced a line. `from: narrator` in api/events.yaml says.
+  const say = (line: unknown) => {
+    if (line && !settled) void emitter.narrator(String(line));
+  };
+
+  const fire = (event: Record<string, unknown>) => {
+    if (!n) return;
+    if (!firstLine && n.instant?.length) {
+      firstLine = true;
+      say(n.instant[Math.floor(Math.random() * n.instant.length)]);
+    }
+    void (async () => {
+      try {
+        const res = await sendRequest(node, n.request, { ...ctx, event } as any, `${node.type} narrator`);
+        say(await evaluate(n.response.line, { response: await res.json() }));
+      } catch {
+        say(render(n.fallback, ctx));
+      }
+    })();
+  };
+
+  return { fire, settle: () => { settled = true; } };
+}
+
+export type Narrator = ReturnType<typeof makeNarrator>;

package/vendor/base/src/manifests/runtime/state.ts

@@ -0,0 +1,171 @@
+/**
+ * PLATFORM STATE. The capability that lets a manifest keep something between runs.
+ *
+ * Every other capability here reaches a vendor over HTTP. This one reaches Redis, through
+ * the same `api.getRedisClient()` handle the plugin library already gives a code node, so
+ * nothing new is introduced: a manifest simply NAMES an operation the platform already
+ * performs (DECLARATIVE_NODES.md §2).
+ *
+ * Four operations, which is what the retired CRM and Code nodes needed and no more:
+ *
+ *   read    the value at a key, or {} when cold
+ *   merge   shallow-merge a patch into it, stamped with updatedAt
+ *   drain   pop up to `max` items off a list, oldest first
+ *   save    put this node's value into the RUN's saved-context hash, so a later template
+ *           reaches it as saved.<nodeId>
+ *
+ * `save` NAMES NO KEY, and that is the whole reason it is a separate operation rather than a
+ * `merge` the manifest addresses itself. Its key belongs to the ENGINE — NodeExecutionContext
+ * reads `saved:<executionId>` when it builds the template scope, and workflowActions deletes it
+ * when the run ends — so a manifest writing that key by hand would be guessing at another
+ * component's private layout, and would also get the namespace exactly wrong (see below).
+ *
+ * THE NAMESPACE IS APPLIED HERE, never by the manifest. `REDIS_NAMESPACE` is a deployment
+ * fact, and the memory server prefixes its own keys with it. A manifest that had to
+ * remember the prefix would eventually forget, both sides would write happily to different
+ * keys, and nothing would error: the sync would just silently stop working. So a manifest
+ * writes the logical key and cannot get this wrong.
+ */
+
+import { makeLoopOps, type LoopOps } from "./loops/loop.js";
+
+/** What the executor needs from Redis. Injected, so this file touches no platform global. */
+export interface StateStore {
+  read(key: string): Promise<Record<string, unknown>>;
+  merge(key: string, patch: Record<string, unknown>): Promise<Record<string, unknown>>;
+  drain(key: string, max: number): Promise<unknown[]>;
+  /** The run's saved-context hash. Takes ids, not a key: the layout is the engine's, not ours. */
+  save(executionId: string, nodeId: string, value: unknown): Promise<unknown>;
+  /**
+   * ITERATION BOOKKEEPING, implemented in loops/loop.ts and carried here.
+   *
+   * It hangs off this interface rather than being a seventh argument threaded through
+   * performApi, runCalls and runFinal because it needs exactly the same thing this store
+   * needs — the Redis handle — and every one of those call sites already has the store. A
+   * parallel parameter would be four signature changes to deliver one dependency twice.
+   */
+  loop?: LoopOps;
+  /**
+   * THE LIVE CLIENT ITSELF, for the one capability the four named operations cannot express:
+   * the docstore's WATCH/MULTI transaction (read-check-write as one unit, retried on
+   * conflict). Carried here for the same reason `loop` is — every call site that needs it
+   * already has the store. Capabilities take it from here; a manifest never sees it.
+   */
+  raw?: any;
+}
+
+/** Bound to a live client. `null` when the platform has no Redis, which is not an error. */
+export function makeStateStore(redis: any, namespace: string | undefined): StateStore | undefined {
+  if (!redis) return undefined;
+  const ns = namespace ? `${namespace}:` : "";
+  const full = (key: string) => `${ns}${key}`;
+
+  const parse = (raw: string | null): Record<string, unknown> => {
+    if (!raw) return {};
+    try {
+      const v = JSON.parse(raw);
+      return v && typeof v === "object" && !Array.isArray(v) ? v : {};
+    } catch {
+      return {}; // a corrupt value reads as cold, which is recoverable; throwing is not
+    }
+  };
+
+  return {
+    // Same client, same namespace. See loops/loop.ts for why a loop is one capability rather
+    // than the seven raw Redis commands the retired nodes reached for.
+    loop: makeLoopOps(redis, namespace),
+
+    // The handle itself, for the docstore's WATCH/MULTI transaction (see the interface).
+    raw: redis,
+
+    async read(key) {
+      return parse(await redis.get(full(key)));
+    },
+
+    async merge(key, patch) {
+      // Read-modify-write, shallow. The snapshot is written by more than one node and by
+      // the memory server, so replacing it wholesale would drop whatever the others put
+      // there. No TTL: CRM context stays until something explicitly refreshes it.
+      const next = { ...parse(await redis.get(full(key))), ...patch, updatedAt: new Date().toISOString() };
+      await redis.set(full(key), JSON.stringify(next));
+      return next;
+    },
+
+    /**
+     * `saved:<executionId>`, one hash field per node — the ENGINE's layout, matched exactly.
+     *
+     * NOT namespaced, deliberately, and it is the one key here that must not be. Every other key
+     * in this file is ours and is shared with the memory server, which prefixes. This one is read
+     * by `NodeExecutionContext` and deleted by `workflowActions` with a bare `saved:${executionId}`,
+     * so prefixing it would put the value somewhere nothing looks. That failure is invisible: the
+     * write succeeds, the toggle appears to work, and `{{ saved.x }}` is quietly empty forever.
+     * Hence `full()` is not applied and this comment sits where someone would think to add it.
+     *
+     * TTL matches the retired node's hour, which is also the loop state's. It is a within-run
+     * cache, and the engine deletes the key at the end of a run anyway — the expiry is only there
+     * so a run that dies without cleaning up does not leak the key.
+     */
+    async save(executionId, nodeId, value) {
+      const key = `saved:${executionId}`;
+      await redis.hset(key, nodeId, JSON.stringify(value ?? null));
+      await redis.expire(key, 3600);
+      // `?? null` so `calls.<name>` always HAS a key once this ran. Returning undefined would be
+      // indistinguishable from the call being skipped, and that distinction is exactly what the
+      // `__saveToContext` flag is derived from.
+      return value ?? null;
+    },
+
+    async drain(key, max) {
+      // LPOP one at a time so dedup is inherent: an item taken is gone, and a crash
+      // mid-drain loses at most the one in flight rather than the whole queue.
+      const out: unknown[] = [];
+      for (let i = 0; i < Math.max(1, max); i++) {
+        const raw = await redis.lpop(full(key));
+        if (!raw) break;
+        try {
+          out.push(JSON.parse(raw));
+        } catch {
+          // A malformed item is skipped rather than retried forever. It is already popped.
+        }
+      }
+      return out;
+    },
+  };
+}
+
+/**
+ * Perform one declared state operation and return what the call's `name` will hold.
+ *
+ * With no store this returns empty rather than throwing. A universe with no Redis should
+ * degrade to "the cache was cold", which every caller already handles, instead of failing
+ * a workflow over a cache.
+ */
+export async function performState(
+  op: string,
+  key: string,
+  value: unknown,
+  max: number | undefined,
+  store: StateStore | undefined,
+  /** Only `save` reads this: its key is the run's, not the manifest's. */
+  scope: { executionId?: string; nodeId?: string } = {},
+): Promise<unknown> {
+  if (!store) return op === "drain" ? [] : op === "save" ? (value ?? null) : {};
+
+  switch (op) {
+    case "read":
+      return store.read(key);
+    case "merge":
+      return store.merge(key, (value as Record<string, unknown>) ?? {});
+    case "drain":
+      return store.drain(key, max ?? 25);
+    case "save":
+      // Both ids or nothing. A save keyed by "undefined" would write a hash no run ever reads,
+      // and would look identical to a working one from the manifest's side. The retired node
+      // defaulted the node id instead, which silently merged two nodes into one field.
+      if (!scope.executionId || !scope.nodeId)
+        throw new Error(`state "save" needs the run's executionId and nodeId, and this run supplied neither`);
+      return store.save(scope.executionId, scope.nodeId, value);
+    default:
+      throw new Error(`state operation "${op}" is declared in the schema but not implemented in the executor`);
+  }
+}

package/vendor/base/src/manifests/runtime/templating.ts

@@ -0,0 +1,110 @@
+/**
+ * Templates and expressions, both borrowed from the platform rather than rebuilt.
+ *
+ * Part of the manifest runtime (DECLARATIVE_NODES.md §2): the manifest DESCRIBES the
+ * service, this half COMPUTES it. Split by concern so each piece stays readable.
+ */
+import type { RunContext } from "./context.js";
+
+/**
+ * ORDINARY IMPORTS, at last.
+ *
+ * These two were reached by SOURCE URL, five directories up into the engine tree, because
+ * they lived there and this package could not name them. Such a path is a STRING, so
+ * TypeScript could not check either one: moving a folder broke both and every node failed
+ * at run time while the build stayed green. Only a test asserting the paths still resolved
+ * caught it.
+ *
+ * They live in this package now (`../../template/`), so they are checked like anything else,
+ * and nothing here has to be lazily loaded to work around a path.
+ *
+ * Neither is a copy, and neither may become one. `SafeExpression` is the sandbox every
+ * `return ...` in every manifest runs inside — security by ABSENCE, with no
+ * process/require/fetch/eval/new/constructor for an expression to reach. And the Handlebars
+ * resolver memoizes compilation, sets noEscape (a prompt with backticks must not arrive
+ * HTML-escaped) and registers the helpers a manifest may use (eq, toJSON, filter, contains);
+ * calling Handlebars directly here would silently lack all four while the linter went on
+ * checking manifests against them.
+ */
+import { evaluateSafeExpression } from "../../template/SafeExpression.js";
+import { resolveStringTemplate } from "../../template/StringTemplateResolver.js";
+import { currentHelpers } from "./helpers.js";
+
+/**
+ * Kept as a no-op rather than deleted. It existed to await a dynamic import, and there is
+ * nothing left to await — but every caller and test in the tree awaits it, and removing it
+ * would be a wide, purely mechanical change for no behaviour.
+ */
+export async function primeTemplating(): Promise<void> {}
+
+/**
+ * A string that is EXACTLY one plain reference, e.g. "{{ config.maxTokens }}".
+ *
+ * Handlebars always produces a string, so rendering this through it sends "2048"
+ * where the vendor demands 2048 and rejects the request. When a template IS the whole
+ * value rather than part of a sentence, the value keeps its type.
+ *
+ * Deliberately only a dotted path: anything with a helper or a block is genuinely
+ * text assembly and belongs in Handlebars.
+ */
+const WHOLE_VALUE = /^\s*\{\{\s*([a-zA-Z_$][\w$]*(?:\.[\w$]+)*)\s*\}\}\s*$/;
+
+function lookup(path: string, ctx: RunContext): unknown {
+  return path.split(".").reduce<any>((a, k) => (a == null ? a : a[k]), ctx as any);
+}
+
+/** Resolve every {{ }} in a value, recursively. Non-strings pass through. */
+export function render(value: any, ctx: RunContext): any {
+  if (typeof value === "string") {
+    if (!value.includes("{{")) return value;
+    const whole = value.match(WHOLE_VALUE);
+    if (whole) return lookup(whole[1], ctx);
+    return resolveStringTemplate(value, ctx, console);
+  }
+  if (Array.isArray(value)) return value.map((v) => render(v, ctx));
+  if (value && typeof value === "object") {
+    const out: Record<string, any> = {};
+    for (const [k, v] of Object.entries(value)) {
+      const r = render(v, ctx);
+      // A key whose template resolved to nothing is OMITTED rather than sent as an
+      // empty string: vendors reject "" where they accept absence.
+      if (r !== undefined && r !== "") out[k] = r;
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Evaluate a `return ...` expression from a manifest against a scope.
+ *
+ * Still async, for the same reason primeTemplating still exists: every call site awaits it,
+ * and the evaluation itself is synchronous now that the sandbox is imported rather than
+ * fetched.
+ */
+export async function evaluate(expr: unknown, scope: Record<string, unknown>): Promise<unknown> {
+  /**
+   * A LITERAL IS ITSELF. Only a string is code; anything else is data the author wrote out.
+   *
+   * `getSchema` is what forced this. A method that hands back a constant document had only
+   * one way to say so — a `return { ... }` expression — which meant a large object encoded
+   * inside a YAML string, with every inner quote escaped and no editor able to check it.
+   * Authors write YAML everywhere else in this format; making them write JavaScript-in-a-
+   * string to express a constant was the format's problem, not theirs.
+   *
+   * Nothing is evaluated here, so a literal cannot fail, cannot reference scope, and cannot
+   * be a smuggling route: it is returned exactly as parsed.
+   */
+  if (typeof expr !== "string") return expr;
+  /**
+   * The package's named helpers, added HERE rather than at each of the fifty-odd call sites
+   * that build a scope. A helper that worked in `returns` but not in an events row would be
+   * the sort of inconsistency nobody can predict from reading the manifest.
+   *
+   * A scope that already carries `helpers` wins, so a caller can still pass its own — and so
+   * this cannot silently shadow something a future scope defines.
+   */
+  const helpers = currentHelpers();
+  const withBag = helpers && !("helpers" in scope) ? { ...scope, helpers } : scope;
+  return evaluateSafeExpression(expr.replace(/^return\s+/, ""), withBag);
+}

package/vendor/base/src/manifests/runtime/tools/regionSkills.ts

@@ -0,0 +1,125 @@
+/**
+ * THE SKILLS IN FORCE, held the same way whichever door the conversation came through.
+ *
+ * A region-attached skill reaches an Agent by POSITION rather than by the model choosing to
+ * read one, and two runtimes drive that: `runToolLoop` for a request/response vendor, and
+ * `duplex/session` for a socket. Both absorb the same `regionSkills` from the same search
+ * result, and both then have to answer the same three questions — what changed, what does
+ * the model get told, and what goes on the timeline.
+ *
+ * ONE COPY, because the answers are properties of the FEATURE and not of the transport. The
+ * loop had all of this inline and the socket had none of it, which is exactly how voice came
+ * to absorb region skills correctly and then throw them away: nothing shared meant nothing
+ * obliged the second runtime to do anything with them.
+ *
+ * What genuinely differs between the two stays with them: the loop rebuilds its prompt every
+ * turn and so needs no notification, while a socket sent its instructions once at the
+ * handshake and must re-send them when this reports a change.
+ */
+import type { RunContext } from "../context.js";
+// `recordToolTrace` lives in toolloop.ts and both runtimes already import it from there, so
+// this takes it from the same place rather than moving a working export and touching every
+// caller. The cycle is function-level and resolves at call time.
+import { recordToolTrace } from "./toolloop.js";
+
+/** One skill in force. Shape as it arrives from the engine's `regionSkills`. */
+export interface InForceSkill {
+  name: string;
+  title?: string;
+  instructions?: string;
+  regionId?: string;
+  regionName?: string | null;
+  /** How long the engine spent resolving it, for the timeline bar. */
+  ms?: number;
+}
+
+/**
+ * What the model gets told, appended to whatever the manifest calls a system prompt.
+ *
+ * Empty until something is in force, so a node that never loads one sends exactly what it
+ * always did.
+ *
+ * GENERAL FIRST, SPECIFIC LAST — the engine returns them parent region before child, and
+ * insertion order is preserved, so the more specific instructions come last.
+ *
+ * THEY ADD TO THE ROLE, THEY DO NOT REPLACE IT. A skill is know-how for a situation, not a
+ * new identity: an Agent that reaches this part of the map is still the same Agent, doing
+ * the same job, now with guidance for where it is standing. Wording this as an override
+ * invites the model to drop its role prompt the moment a skill loads, which is the opposite
+ * of what an attachment is for.
+ */
+export function renderSkillsText(skills: Map<string, InForceSkill>): string {
+  if (!skills.size) return "";
+  const bodies = [...skills.values()].map((s) => `## ${s.title || s.name}\n\n${s.instructions}`);
+  return (
+    "\n\n---\n\nThe following skills apply to this part of the conversation. They ADD to " +
+    "your role and instructions above rather than replacing them: keep doing your job, " +
+    "and let these guide how you do it here. Where two skills overlap, the later one is " +
+    "the more specific.\n\n" +
+    bodies.join("\n\n")
+  );
+}
+
+/**
+ * Fold a search's `regionSkills` into the held set, and say whether anything moved.
+ *
+ * WHAT IS IN FORCE IS WHERE YOU ARE. The resolved list REPLACES the held one rather than
+ * adding to it, because a skill is attached to a region and a conversation that has moved on
+ * is no longer in that region. Accumulating would leave someone being coached on
+ * qualifications long after they had wandered into complaints.
+ *
+ * `null` means the reply said nothing about position: leave it alone. `[]` means it was
+ * placed and nothing applies there, which includes unassigned ground, and that CLEARS.
+ *
+ * A skill already held is not reloaded: it stays in the map, keeps its place in the order,
+ * and raises no event. Only what actually changed is news.
+ */
+export function applyInForce(
+  held: Map<string, InForceSkill>,
+  inForce: InForceSkill[] | null | undefined,
+  node: { type: string },
+  ctx: RunContext,
+): { changed: boolean; added: InForceSkill[]; dropped: string[] } {
+  if (!inForce) return { changed: false, added: [], dropped: [] };
+
+  const before = new Set(held.keys());
+  const next = new Map<string, InForceSkill>();
+  for (const s of inForce) next.set(s.name, held.get(s.name) ?? s);
+  const added = inForce.filter((s) => !before.has(s.name));
+  const dropped = [...before].filter((n) => !next.has(n));
+  if (!added.length && !dropped.length) return { changed: false, added: [], dropped: [] };
+
+  held.clear();
+  for (const [k, v] of next) held.set(k, v);
+
+  for (const s of added) {
+    console.log(
+      `[manifests] ${node.type}: skill in force "${s.name}" from region ${s.regionName ?? s.regionId ?? "?"}`,
+    );
+    /**
+     * ON THE TIMELINE, through the SAME publisher every tool call uses.
+     *
+     * A skill coming into force changes what the model is working to, so it belongs on the
+     * execution timeline beside the search that caused it. Its OWN KIND, not a name with a
+     * prefix on it: the trace lands as node_type `skill_load` and the viewer draws it as a
+     * skill because it was told so.
+     *
+     * THE DURATION COMES FROM THE ENGINE (`ms`), not from here. A runtime only learns a
+     * skill exists once the search returns, so timing it locally would measure the gap
+     * between hearing and recording — zero — and draw every skill as an instantaneous step.
+     */
+    recordToolTrace(
+      node as any,
+      ctx,
+      s.name,
+      { region: s.regionName ?? s.regionId ?? null },
+      { title: s.title ?? s.name, instructions: s.instructions ?? "" },
+      Date.now() - (Number(s.ms) || 0),
+      true,
+      "skill",
+    );
+  }
+  for (const n of dropped) console.log(`[manifests] ${node.type}: skill cleared "${n}" (left its region)`);
+
+  return { changed: true, added, dropped };
+}