Skip to main content

Authoring helpers

Inside an ilmek node you shape the conversation with a handful of helpers. They're the entire authoring surface — everything a turn can produce on the wire comes from one of them. Each takes ilmek's context (no ambient storage; ilmek already threads it through every node) and emits a custom event the mapper turns into a frame.

import { mekik } from "@mekik/core";

// one node of a compiled ilmek graph
.node("desk", async (state, ctx) => {
const id = state.input as string;
const order = await mekik.tool(ctx, "get_order", { id }, () => Orders.get(id)); // journaled tool
mekik.text(ctx, "Looking that up… "); // streamed prose
mekik.ui(ctx, "order-card", { id: order.id, total: order.total }); // mount a component
const ok = await mekik.approve<{ approved: boolean }>( // pause for a human
ctx,
{ title: `Refund ${order.total}?` },
{ ui: { component: "approval-form", props: { orderId: order.id } } },
);
return { reply: ok.approved ? "done" : "cancelled" };
})

The one name, two ways​

In TypeScript the single mekik export is both the app factory and the helpers — index.ts folds the helper functions onto the callable factory, so both read naturally. In .NET they split: the app is MekikApp, and the helpers live on a static Shuttle class (a static class named Mekik would clash with the namespace — see Parity).

import { mekik } from "@mekik/core";

const app = mekik({ graph }); // app factory — called once, at the top level
mekik.ui(ctx, "card", {}); // helper — called inside a node

// helpers are also available as named imports:
import { ui, tool, approve } from "@mekik/core";

The helpers​

TypeScript.NETEmitsAwaits?Guide
mekik.text(ctx, content)Shuttle.Text(ctx, content)a genui text chunknoGenerative UI
mekik.streamText(ctx, deltas, select?)Shuttle.StreamText(ctx, deltas, …)one genui text chunk per deltayes — returns the joined textGenerative UI
mekik.ui(ctx, component, props?)Shuttle.Ui(ctx, component, props?)a genui ui chunknoGenerative UI
mekik.event(ctx, name, payload?)Shuttle.Event(ctx, name, payload?)a genui event chunknoGenerative UI
mekik.mount(ctx, component, props?)Shuttle.Mount(ctx, component, props?)a genui ui chunk + an update handlenoTyped components
mekik.message(ctx, type, data)Shuttle.Message(ctx, type, data)a persistent rich message framenoRich messages
mekik.tool(ctx, name, params, fn)Shuttle.Tool(ctx, name, params, fn)a tool_call trace + runs fn onceyes — returns the resultTools
mekik.approve(ctx, payload, opts?)Shuttle.Approve(ctx, payload, …)an interrupt frame; the run pausesyes — returns the answerHuman-in-the-loop
mekik.choose(ctx, payload, options)Shuttle.Choose<T>(ctx, payload, options)an interrupt frame whose actions are the optionsyes — returns the pickHITL → Buttons
mekik.action(label, value?)Shuttle.Action(label, value?)nothing — builds one chip (MessageAction) for choose / approvenoHITL → Buttons
mekik.onEvent(ctx, eventType, opts?)Shuttle.OnEvent<T>(ctx, eventType, …)an interrupt frame carrying data.event; the run pauses until a mounted component fires that eventyes — returns the event's payloadGenerative UI → component-event
mekik.clientTools(ctx, filter?)Shuttle.ClientTools(ctx, tags?, mode?)nothing — reads the turn's client tool snapshotno — returns the definitionsClient tools
mekik.callClientTool(ctx, name, params?)Shuttle.CallClientToolAsync<T>(ctx, name, params?)a tool_call trace + an interrupt (or a notify chunk)yes — returns the client's resultClient tools
mekik.skills(ctx, filter?) / mekik.skillsPrompt(ctx, filter?)Shuttle.Skills(ctx, tags?, source?) / Shuttle.SkillsPrompt(…)nothing — reads the turn's skill catalog (level 1)noSkills
mekik.skillTools(ctx, filter?)Shuttle.SkillTools<TTool>(ctx, tags?, source?)nothing — the tools each visible server skill owns (SkillEntry.tools), keyed by skill namenoSkills
mekik.loadSkill(ctx, name)Shuttle.LoadSkill(ctx, name)a skill trace; returns the instructions (level 2)noSkills
mekik.skillResource(ctx, name, path)Shuttle.SkillResourceAsync(ctx, name, path)nothing — reads one bundled file (level 3)yes — returns the file textSkills
mekik.authClaims(ctx) / mekik.claimStrings(claims, key)Shuttle.AuthClaims(ctx) / Shuttle.ClaimStrings(claims, key)nothing — reads the turn's verified auth claims ({} when anonymous)noReading per-conversation context

mekik.skillResourcesAvailable(ctx) / Shuttle.SkillResourcesAvailable(ctx) reports whether the turn's skill source can serve level-3 files at all.

text, ui, event and message are fire-and-forget: they emit and return. streamText is the token-by-token convenience — it drives an async delta source through text and returns the joined string (while streaming, the streamed bubble is the durable message — don't also return it as the reply; see Generative UI). tool, approve, choose, onEvent and callClientTool await because they wrap ilmek machinery (ctx.step / ctx.StepAsync for tool, ctx.interrupt / ctx.InterruptAsync for the others).

On top of these sit the typed catalogs, which bind a component or message name once so the payload is compiler-checked: mekik.component / mekik.genui for components, mekik.messageKind / mekik.messages for messages, and mekik.action for chips. They add nothing to the wire — same frames, fewer hand-written object literals.

Each message type also has a describe form — messages.card.spec(data) / Messages.CardSpec(…) — returning the message as a value instead of emitting it, for the places that send one without a ctx. That's how the greeting carries a card or buttons rather than only a paragraph.

text / ui / event​

Stream a chunk of generative UI. text streams prose deltas; ui mounts or updates a registered component by name; event dispatches a named event to a mounted component:

mekik.text(ctx, "Analyzing your order… ");
mekik.ui(ctx, "data-table", { rows, columns });
mekik.event(ctx, "highlight", { rowId: 3 });

All three carry the same AIChunk shape chativa renders. Chunks under one turn share a streamId; the mapper assigns each chunk an id (consecutive text deltas share one, so they grow a single bubble) and closes the stream when the run finishes. Details and the component contract: Generative UI.

tool​

Run a side effect exactly once and surface it as a tool_call trace:

const order = await mekik.tool(ctx, "get_order", { id }, () => Orders.get(id));

It emits tool_call{running}, runs fn inside ilmek's ctx.step (which journals the result), then emits tool_call{completed, result} — or tool_call{error} if fn throws, and rethrows the error, so the node fails unless you catch it. (Inside an agent loop — runAgent / Agent.RunAsync — a throwing tool becomes an Error from <tool>: … observation the model reads instead.) An interrupt thrown by fn is rethrown untouched: a pause is not a failure. The journaling is the point: on a resume pass the node re-runs, but fn returns its recorded value instead of executing again. This is what stops a refund from charging twice. Full story: Tools.

approve​

Pause the run for a human and resume with their answer:

const ok = await mekik.approve<{ approved: boolean }>(
ctx,
{ title: "Deploy to production?" },
{
ui: { component: "approval-form", props: { env: "prod" } }, // a rich form…
actions: [ // …or chip fallback
{ label: "Approve", value: { approved: true } },
{ label: "Cancel", value: { approved: false } },
],
},
);
if (ok.approved) await deploy();

The node suspends at that await on the first pass — it never returns. The engine emits an interrupt frame and ends the run interrupted. When the client answers, the graph re-runs the node from the top and the await returns the answer. The authoring contract — and why anything before the await must be journaled — is Human-in-the-loop.

The presentation/journaling options — a form via ui, chips via actions, a key when a node pauses more than once — read like this (omit both ui and actions for default Approve/Cancel chips):

interface ApproveOptions {
ui?: UiRef; // mount a form instead of relying on chips
actions?: MessageAction[]; // chips; omit both for default Approve/Cancel
key?: string; // journal key, when a node pauses more than once
}

Low-level trace primitives​

For integrations that execute tools themselves (a LangChain or Semantic Kernel agent calling its own functions), mekik exports the primitives behind tool so the same trace can be produced without re-deriving the reserved payload shape:

import { nextToolCallId, toolTrace } from "@mekik/core";

const id = nextToolCallId(ctx);
toolTrace(ctx, { id, name: "search", status: "running", params });
const result = await runTheToolYourself(params);
toolTrace(ctx, { id, name: "search", status: "completed", result });

mekik.toolTrace / Shuttle.ToolTrace emits one tool_call frame (upsert by id); mekik.nextToolCallId / Shuttle.NextToolCallId mints a replay-stable id (both are named exports too). mekik.skillTrace / Shuttle.SkillTrace is the same primitive for the skill frame behind loadSkill. You rarely call these directly — the agent integrations use them internally. Reach for them only when wrapping a tool runner mekik doesn't already integrate.

Reading per-conversation context​

Helpers emit; to read per-conversation data (a user id, a locale, auth claims), use ilmek's context metadata, which mekik populates:

.node("desk", async (state, ctx) => {
const locale = (ctx.meta.mekik as { locale?: string })?.locale ?? "en";
const claims = ctx.meta.auth; // verified auth claims, if an Authenticator ran
return { reply: greet(locale) };
})

meta.mekik is your context selector's output; meta.client is the client meta your acceptClientMeta allowlist kept — the connection's hello.meta with the turn frame's own meta laid over it per key; meta.auth is the auth verdict's claims (read them with mekik.authClaims(ctx) / Shuttle.AuthClaims(ctx)). meta.clientTools and meta.skills are there only when those features are on — read them through the client tool and skill helpers. See Concepts → Graph context.

Where to go next​

  • Generative UI — the chunk model and the component contract.
  • Typed components — bind a component name once; every chativa built-in, worked through.
  • Rich messages — standalone transcript entries: images, cards, carousels, files.
  • Tools — exactly-once, redaction, and the trace lifecycle.
  • Human-in-the-loop — the durable-pause authoring rules.