Agentic experiences

1  The domain       domain("orders") … .includes(contextDomain)   entities, events and actions: what exists and what can change
2  Exact context    events: { ids } · session.from(selection)     you pick what the model sees; the selection is recorded
3  The turn         orders.ask → Session → agent({ actions })     a business action runs the agent over the domain
4  The route        client.action("orders.ask")                   only calls the business action, as the person
5  Live state       useContext(db, options)                       events, reactions, send status, append, stop
6  The chat         <Conversation> … <Composer>                   registry components that render that state
7  Confirmations    requestShip → orders.decide                   the agent asks; the person decides through an action
8  Costs            usage on every model call                     measured in Context, per person and per model

import { domain, defineAction, i } from "@domainruntime/domain";
import { contextDomain, defineEvent } from "@domainruntime/context";
import { z } from "zod";

export default domain("orders")
  .includes(contextDomain)                                   // the harness: contexts, events, reactions
  .withSchema({
    entities: {
      orders_order: i.entity({ status: i.string().indexed(), total: i.number(), placedAt: i.date().indexed() }),
      orders_customer: i.entity({ name: i.string() }),
    },
    links: {
      orders_orderCustomer: {
        forward: { on: "orders_order", has: "one", label: "customer" },
        reverse: { on: "orders_customer", has: "many", label: "orders" },
      },
    },
    rooms: {},
  })
  .withEvents({
    /** The person wrote to the agent. */
    message: defineEvent({ payload: z.object({ text: z.string().min(1).max(8000) }) }),
  })
  .withActions({
    openOrders: defineAction({
      description: "List open orders with their customer. Use it when the question is about current or pending work.",
      input: z.object({ limit: z.number().int().max(100).default(20) }),
      output: z.object({ orders: z.array(z.object({ id: z.string(), total: z.number(), customer: z.string() })) }),
      async execute({ input, runtime }) {
        const db = await runtime.db();
        const { orders_order } = await db.query({
          orders_order: { $: { where: { status: "open" }, limit: input.limit }, customer: {} },
        });
        return { orders: orders_order.map((o) => ({ id: o.id, total: o.total, customer: o.customer?.name ?? "" })) };
      },
    }),
    ship: defineAction({
      description: "Mark an open order as shipped.",
      input: z.object({ orderId: z.string().uuid() }),
      output: z.object({ orderId: z.string() }),
      async execute({ input, runtime }) {
        const db = await runtime.db();
        await db.transact(db.tx.orders_order[input.orderId].update({ status: "shipped" }));
        return { orderId: input.orderId };
      },
    }),
  });

const context = await Context(runtime).open(`orders:thread:${threadId}`);
const events = await context.events;

// the person's messages and the agent's answers, last 24; tool traffic of earlier turns left out
const selection = events.filter(isConversational).slice(-24);

import { Context, Session } from "@domainruntime/context";
import { ai } from "@domainruntime/context/reactor";

ask: defineAction({
  description: "The person asks the orders assistant a question in a thread.",
  input: z.object({ threadId: z.string().uuid(), text: z.string().min(1).max(8000) }),
  output: z.object({ reply: z.string(), suggestions: z.array(z.string()) }),
  async execute({ input, runtime }) {
    const context = await Context(runtime).open(`orders:thread:${input.threadId}`);
    const message = await context.append(orders.events.message({ text: input.text }));

    const selection = [...(await context.events).filter(isConversational).slice(-24)];
    if (!selection.some((e) => e.id === message.id)) selection.push(message);

    await using session = await Session.open(runtime, context, {
      scope,
      engines: { agent: ai({ model: "anthropic/claude-sonnet-5", maxRounds: 24 }) },
      events: { ids: selection.map((e) => e.id) },             // the exact context of this turn
    });
    const answer = await session.from(selection).agent({
      instruction: "You work on the person's orders. Read before you answer; ask before you change anything.",
      output: reply,                                            // a Zod schema: { reply, suggestions }
      actions: [orders.actions.openOrders, orders.actions.requestShip],
    });
    await session.complete();
    return answer;
  },
}),

export async function POST(request: Request) {
  const client = await clientFor(request);                      // a domain client with the person's token
  const { contextId, messages } = await request.json();         // the shape useContext sends
  const text = messages.at(-1).parts.map((p) => p.text ?? "").join("");

  const result = await client.action("orders.ask")({ threadId: contextId, text });
  return Response.json({ contextId, result });
}

"use client";
import { useContext } from "@domainruntime/context/react";
import { db } from "@/lib/db";                                  // the environment's browser client

export function useChat(threadId: string) {
  return useContext(db, { apiUrl: "/api/agent", contextKey: `orders:thread:${threadId}` });
}

npx shadcn@latest add @domainruntime/conversation

import {
  Conversation, ConversationContent, ConversationEmpty, Message, MessageContent,
  MessageSteps, MessageStep, Suggestions, Suggestion, Composer,
} from "@/components/domainruntime/conversation";

export function Chat({ threadId }: { threadId: string }) {
  const chat = useChat(threadId);
  const send = (text: string) => chat.append({ parts: [{ type: "text", text }] });
  const busy = chat.contextStatus === "running" || chat.sendStatus === "submitting";

  return (
    <Conversation>
      <ConversationContent>
        {chat.events.length === 0 && <ConversationEmpty>Ask about your orders.</ConversationEmpty>}
        {chat.reactions.map((reaction) => (
          <Turn key={reaction.id} reaction={reaction} onSuggest={send} />
        ))}
      </ConversationContent>
      <Composer onSubmit={send} busy={busy} onStop={chat.stop} placeholder="Ask about your orders" />
    </Conversation>
  );
}

function Turn({ reaction, onSuggest }) {
  const asked = textOf(reaction.causes);                         // the person's message
  const steps = reaction.effects.filter(isActionCall);           // the actions the agent ran
  const answer = replyOf(reaction.effects);                      // { reply, suggestions } from `output`

  return (
    <>
      {asked && <Message from="person"><MessageContent>{asked}</MessageContent></Message>}
      <Message from="agent">
        {steps.length > 0 && (
          <MessageSteps>
            {steps.map((s) => <MessageStep key={s.id} state={stateOf(s)}>{labelOf(s)}</MessageStep>)}
          </MessageSteps>
        )}
        {answer && <MessageContent>{answer.reply}</MessageContent>}
        {answer?.suggestions.length ? (
          <Suggestions>{answer.suggestions.map((q) => <Suggestion key={q} onClick={() => onSuggest(q)}>{q}</Suggestion>)}</Suggestions>
        ) : null}
      </Message>
    </>
  );
}

requestShip: defineAction({
  description: "Ask the person to confirm shipping an order. Use it instead of shipping directly.",
  input: z.object({ orderId: z.string().uuid(), title: z.string().max(140) }),
  output: z.object({ status: z.literal("awaiting_confirmation"), approvalId: z.string() }),
  async execute({ input, runtime }) {
    const approvalId = crypto.randomUUID();
    const db = await runtime.db();
    await db.transact(db.tx.orders_approval[approvalId]
      .update({ title: input.title, action: "ship", input: { orderId: input.orderId }, status: "pending" })
      .link({ owner: runtime.auth.user!.id }));
    return { status: "awaiting_confirmation", approvalId };
  },
}),

decide: defineAction({
  description: "The person approves or declines a change the assistant asked for.",
  input: z.object({ threadId: z.string().uuid(), approvalId: z.string().uuid(), decision: z.enum(["approved", "declined"]) }),
  output: z.object({ outcome: z.enum(["executed", "failed", "declined"]) }),
  async execute({ input, runtime }) {
    // 1. claim the decision (status "running") so a second click can't run it twice
    // 2. if approved, run the requested action (orders.ship) as the person, with the approval id as its request id
    // 3. append { approvalId, decision, outcome } to the thread's Context and run the next turn, as in orders.ask
  },
}),