Agentic workflows as state machines, off your laptop.

control flow in markdown

• hard to follow the graph is prose, spread across files
• hard to test nothing to run but the agent itself
• still non-deterministic MUST and NEVER are requests, not edges

/commandSKILL.mdmcp resource

## Workflow

1. Run the tests. If they fail, go to step 4.
2. IMPORTANT: ask the reviewer for a review.
3. If it asks for changes, go back to step 1.
   You MUST loop until it approves.
4. Fix the failures, then return to step 1.

NEVER commit before the review passes.
ALWAYS follow these steps in order.

different problems, different workflows

jr drew one of these. I did not want to create more bash loops.

a workflow you can read

reviewing: {
  invoke: { src: "reviewer", input: reviewerPrompt },
  on: {
    review_verdict: [
      { guard: approved, target: "closingTask" },
      { guard: "underReviewCap", target: "coding" },
      { target: "#body.escalated" },
    ],
    report_blocked: { target: "#body.escalated" },
  },
},

Claude wrote it. I review the graph, not the transcript.

a filesystem sandbox is not isolation

one host is one host

headless: every UI can be a client

jr2 is infrastructure. The UI is whatever calls it.

one pod, three containers

The Agent writes the code. It never holds a key.

your image, byte for byte

FROM node:24-slim

# the floor: glibc and git
RUN apt-get update \
  && apt-get install -y git ca-certificates

# your agents' toolchain: compilers, CLIs,
# language servers, dotfiles
RUN …

At pod start jr2 mounts its runtime at /opt/jr2: the Harness, built on the pi agent toolkit. It adds no layer to your image, and your tools win on PATH.

You own the toolchain. jr2 brings the Harness.

what a Machine is made of

const needsInfo = defineEvent({ 2
  name: "needs_info", audience: "agent",
  input: z.object({ question: z.string() }),
});
jr2Setup({
  events: [accept, needsInfo, reject, answer],
  actors: {
    triager: agent({ 3
      model: "local/qwen3.6-35b-a3b",
      workspace: "none",
      instructions: "You triage feature requests…",
    }),
  },
}).createMachine({
  input: z.object({ request: z.string() }), 1
  states: {
    triaging: { 4
      invoke: { src: "triager" },
      on: { accept: "accepted", needs_info: "clarify", reject: "rejected" },
    },
    clarify: { invoke: { src: "gate" }, on: { answer: "triaging" } },
    accepted: { type: "final" }, rejected: { type: "final" },
  },
});

Choose your own adventure: the Agent picks where it goes next, from defined states.

Machines compose

import { task } from "@jr2/machines";

export const machine = customize(task, {
  repos: {
    target: { url: "http://seed…/greet.git" },
  },
  agents: {
    coder: { model: "local/qwen3.6-35b-a3b" },
  },
});

const coding = customize(task, {
  repos, agents,
});

jr2Setup({ actors: { triager, coding } })
  .createMachine({
    states: {
      building: {
        invoke: {
          src: "coding",
          input: ({ context }) => ({
            prompt: context.summary,
            branch: `feat/${context.slug}`,
          }),
        },
      },
    },
  });

export const machine = customize(
  pool(task, {
    source: source({
      // the next ready ticket, or null
      next: fromPromise(({ input }) =>
        tracker.next(input.active)),
    }),
    itemId: (t) => t.id,
    cap: 3,
    itemInput: (t) => ({
      prompt: t.body,
      branch: `ticket/${t.id}`,
    }),
  }),
  { repos, agents },
);

Loop engineering? How about state machine engineering?

any model, chosen per Agent

harness: {
  // one OpenAI-compatible endpoint:
  // llama.cpp, vLLM, Ollama, …
  provider: {
    id: "local",
    api: "openai-completions",
    baseUrl: process.env.JR2_PROVIDER_URL,
  },
},
// keys for the built-in catalog, held
// by the Custodian: anthropic, openai, …
secrets: [{
  name: "ANTHROPIC_API_KEY",
  value: process.env.ANTHROPIC_API_KEY,
}],

The kit never picks a vendor. You pick the model.

a run outlives its Orchestrator

Kill the Orchestrator mid-Turn. The run picks up where it was.

the Custodian holds every key

Add external tools, and the Agent never holds a key.

memory, messaging, and more

Agents are good at one small thing. Let the Machine do the rest.

Agents that write runtime Machines

const plan = await agent("plan it");
for (const step of plan.steps) {
  const r = await agent(`do ${step}`);
  if (!r.ok) break;
}

planning: {
  invoke: { src: "planner" },
  on: { planned: "working" },
},
working: {
  invoke: { src: "coder" },
  on: { done: "review", blocked: "escalated" },
},

Agents are good at writing Machines. The types catch mistakes before the run.