Runtime

A runtime runs agents. You create it with createRuntime, telling it what runs may do (permissions), who they act for (scope) and how far they may go (limits). Then you submit an agent with its input and get a handle to the run. One runtime can run many agents and many runs at once; usually you create one per process, or one per request when permissions or scope differ per user.

#Submit a run

import { createRuntime } from 'mayura';

const runtime = createRuntime({
  profile: 'ephemeral',
  permissions: { allow: ['model:openai.responses', 'tool:orders.lookup', 'effect:read'] },
  scope: { principalId: 'customer-42', projectId: 'shop' },
  limits: { maxCostMicros: 100_000, maxDurationMs: 30_000 },
});

try {
  const run = runtime.submit(supportAgent, { input: { message: 'Where is order A-1001?' } });

  for await (const event of run.observe()) {
    console.log(event.sequence, event.type, event.metadata);
  }

  const outcome = await run.result();
  if (outcome.status === 'succeeded') console.log(outcome.output);
  else console.error(outcome.status, outcome.error.code, outcome.error.message);

  console.log(runtime.inspect(run).budget); // { spentMicros, reservedMicros, calls }
} finally {
  await runtime.close();
}

#Options

ephemeral means the runtime keeps everything in memory. Runs, events and costs are lost when the process exits, and a run interrupted by a crash is not resumed. For work that must survive restarts, use durable workflows.

scope.principalId and scope.projectId must start with a letter or digit and may contain letters, digits, ., _, / and -, up to 128 characters. Use an internal user id, not an email address.

#Limits

Each submitted run gets its own counters and its own cost budget, checked against these limits. maxConcurrentRuns and maxConcurrentOperations also apply to the runtime as a whole. Child runs count against their parent's limits.

Every limit except maxCostMicros and maxToolCalls must be a positive integer. An unknown limit name throws INVALID_CONFIG.

maxCostMicros defaults to 0, so a paid model is refused until you set it. Only free models (for example the scripted test model, whose calls cost 0) work without it.

#The run handle

runtime.submit(agent, { input }) returns a RunHandle right away; the run starts on its own.

submit itself throws only when the run cannot start at all: the input is not plain JSON or is larger than maxInputBytes (INVALID_INPUT), maxConcurrentRuns runs are in progress (LIMIT_EXCEEDED), or the runtime is closed (CONFLICT). Everything after that, including invalid input for the agent's schema, arrives as the outcome.

#Events

Every event has runId, a sequence number that increases by one, a timestamp, a type and a small metadata object (ids, counts and statuses, never prompts or secrets).

Events are kept in a buffer of maxEventRetention entries. If you start observing late, or read slower than the run writes, the oldest events may be gone; you then get one events.gap event with the missing range instead of silence. Pass after: sequence to resume after an event you already saw, and signal to stop observing. Observing never changes the run, and stopping observation does not cancel it.

#Cancel a run

run.cancel() stops the run from starting new model calls, tool calls or child runs, and the outcome becomes cancelled. Work already in progress is told through its AbortSignal; a tool that already sent a request may still complete it. In that case the call is outcome_unknown, and so is the run. See Outcomes and errors.

When maxDurationMs passes, the run is stopped the same way and fails with TIMEOUT.

#Inspect a run

runtime.inspect(handle) returns a snapshot of a run and its children, while it runs or after:

• status: running or the final status.
• budget: spentMicros, reservedMicros (cost held for calls in progress or with unknown cost) and calls.
• runs: the run and every child run, with ids, agent ids and statuses.
• evidence: for each tool call, whether it ran (not_started, succeeded, failed or unknown) and whether its result was released to the model.

#Child runs and speculation

Two methods start runs under a running parent, sharing its budget and limits:

• runtime.spawn(parent, agent, { input, permissions, limits }) starts a child run. The child gets only the permissions you list that the parent also has, and its limits cannot exceed the parent's. The parent needs agent:delegate. Most apps use agentAsTool instead, so the model decides when to delegate.
• runtime.speculate(parent, { branches, verify }) runs 1 to 8 read-only branches at once and keeps at most one result, the first that your verify function accepts.

Both are covered in Child agents.

#Close the runtime

await runtime.close() stops accepting runs, cancels the runs in progress and waits until each has an outcome. Call it when your process shuts down, or in a finally block in scripts and tests.

#Good to know

• Limits are enforced between steps and at every call. Your own code in tools and hooks is not interrupted by force; it must respect context.signal.
• A runtime's permissions and scope are fixed when you create it. For per-user authority, create a runtime per user or request; it is cheap.
• For a runtime behind HTTP, with authentication and a client, see Server and client.

#Related

• Agents
• Outcomes and errors
• Permissions
• Costs and budgets
• Observability