THE LOOP.

WHILE YOU SETTLE IN.

Three things to do while you find a seat. Do them now and you will not lose the first twenty minutes.

1. Connect your agent to Immersive Commons (once, about 60s)
   POST https://www.immersivecommons.com/api/agent/signup/start
   scopes: ["read:public", "membership:read", "keys:request"]
   Open the verify URL it prints, sign in, done.

2. File the request
   ic_request_workshop_key(
       event_id="https://luma.com/vcn-44-the-loop")
   -> request_id, status "pending"
   An IC operator approves it. That operator is in this room.

3. Pick it up, once, within ~15 min of approval
   ic_get_my_workshop_key(request_id)
   -> bundle.copy_paste, a paste-and-go setup block

YOU USE ONE EVERY DAY. YOU CANNOT SEE INSIDE IT.

You already trust a piece of software to edit your code. You have no idea how it decides what to do next.

Today we delete the magic.

PLAN, ACT, OBSERVE, REPEAT.

Ask the AI what to do. Do it. Show it what happened. Ask again. Stop when it says it is finished. That is the whole design.

The rest of this morning is filling those four verbs in with real code, one at a time, in the order you would actually write them.

A TURN IS REASON, THEN ACT, THEN SEE THE RESULT.

One round-trip. The AI thinks out loud, asks for one thing to be done, you do it, and you hand back what happened. That round-trip is the unit everything else is counted in.

Honest footnote, and say it out loud. ReAct is not magic either. In the original paper, on the HotpotQA question-answering benchmark, plain ReAct scored 27.4 and plain chain-of-thought scored 29.4. ReAct lost. What it won is the thing you care about here: it hallucinated 0 percent of the time versus 56 percent, and on long multi-step interactive tasks like ALFWorld it scored 71 versus 45. ReAct is a pattern for doing work in the world, not for answering trivia. That is exactly why it is the right shape for a coding agent. Yao et al., ICLR 2023, arXiv 2210.03629

FOUR MOVING PARTS. NOTHING ELSE.

A brain that decides, hands that touch things, a loop that connects them, and a rule for when to stop.

python smoke.py

reply:       LOOP OK
VCN44 SETUP READY

THE WHILE-LOOP HARNESS.

Write the loop before you write anything for it to do. Get the skeleton standing, then hang the muscles on it.

What you are about to do, and why it matters: you are going to write the dumbest possible version of the loop, the one that cannot use a single tool yet, because getting the shape right first means every later stage is a small addition instead of a rewrite.

import os
import sys

from anthropic import Anthropic

BASE_URL = os.environ.get("ANTHROPIC_BASE_URL",
                          os.environ.get("VCN_BASE_URL", "https://api.z.ai/api/anthropic"))
MODEL = os.environ.get("ANTHROPIC_MODEL", os.environ.get("VCN_MODEL", "glm-4.6"))

def client():
    global _CLIENT
    if _CLIENT is None:
        key = os.environ.get("ANTHROPIC_AUTH_TOKEN") or os.environ.get("ZAI_API_KEY")
        if not key:
            sys.exit(MISSING_KEY)
        # auth_token=, NOT api_key=. The SDK sends api_key as the X-Api-Key
        # header and auth_token as "Authorization: Bearer". The workshop
        # gateway reads only Authorization; z.ai accepts either. One word.
        _CLIENT = Anthropic(base_url=BASE_URL, auth_token=key)
    return _CLIENT

def agent(task: str) -> str:
    messages = [{"role": "user", "content": task}]

    while True:                                       # <- THE LOOP
        resp = client().messages.create(
            model=MODEL,
            max_tokens=2048,
            messages=messages,
        )
        messages.append({"role": "assistant", "content": resp.content})

        # No tools exist yet, so the model can never ask for one and this
        # always fires on turn 1. Stage 2 gives it something else to do.
        if resp.stop_reason != "tool_use":             # <- STOP CONDITION
            return text_of(resp)

def text_of(resp) -> str:
    return "\n".join(b.text for b in resp.content if b.type == "text").strip()

auth_token, not api_key. One word, whole morning. The SDK sends api_key= as the X-Api-Key header and auth_token= as Authorization: Bearer. Your workshop gateway reads only Authorization, so the wrong keyword returns "malformed token" on a perfectly valid key.

JARGON: stop_reason. Every response tells you why the model stopped talking, like a courier handing back a delivery slip. tool_use means "I stopped because I want you to run something". Anything else means "I stopped because I am done".

This file does not run yet. TOOLS and run_tools arrive in stages 1 and 2. Run it now and Python says NameError, which is the correct outcome. You are looking at the shape.

GIVE THE MODEL HANDS.

A tool is a job description plus an actual worker. The model only ever reads the job description. If the description lies, the model makes bad decisions and nothing crashes.

What you are about to do, and why it matters: you are going to discover that a tool is two separate things that must agree, because when they disagree the model goes blind and you never see an error message.

TOOLS = [
    {
        "name": "read_file",
        "description": "Read a UTF-8 text file inside the workspace and return its contents.",
        "input_schema": {
            "type": "object",
            "properties": {"path": {"type": "string"}},
            "required": ["path"],
        },
    },
    # write_file is the same shape: path + content, both required.
    {
        "name": "run_command",
        "description": (
            "Run a shell command in the workspace directory. Returns the exit code "
            "plus stdout and stderr. Destructive commands are blocked unless a human "
            "approves them."
        ),
        "input_schema": {
            "type": "object",
            "properties": {"cmd": {"type": "string"}},
            "required": ["cmd"],
        },
    },
]

def read_file(path: str) -> str:
    return safe_path(WORKSPACE, path).read_text(encoding="utf-8")[:8000]


def write_file(path: str, content: str) -> str:
    target = safe_path(WORKSPACE, path)
    target.parent.mkdir(parents=True, exist_ok=True)
    target.write_text(content, encoding="utf-8")
    return f"wrote {len(content)} chars to {path}"

def run_command(cmd: str) -> str:
    blocked = gate_command(cmd)
    if blocked:
        return blocked
    proc = subprocess.run(
        cmd, shell=True, capture_output=True, text=True, cwd=WORKSPACE, timeout=120
    )
    return (
        f"exit code: {proc.returncode}\n"
        f"--- stdout ---\n{proc.stdout}\n"
        f"--- stderr ---\n{proc.stderr}"
    )[-8000:]

JARGON: schema. A small piece of JSON saying what arguments a tool takes and which are required. It is the label on the socket that tells you which plug fits. The model reads only the schema, never your Python.

JARGON: stdout and stderr. Two separate output channels. Normal output goes to stdout. Crashes, warnings and tracebacks go to stderr. Your terminal blends them, so you have probably never noticed they are different. Python does not blend them.

Measured, not guessed. The obvious version of run_command returns .stdout only. On this fixture that hands the model an empty string for every single failure, and it will then confidently tell you the problem is fixed. That is worse than a crash, because a crash is honest.

JARGON: traceback. The multi-line error report Python prints when something breaks. It goes to stderr. It is the most useful thing you can hand a model, and it is exactly what the naive version throws away.

RUN THE CALL, FEED THE RESULT BACK.

The model asks for something. You do it. You hand back what happened, in a shape it can read. This one function is the entire bridge between thinking and the real world.

What you are about to do, and why it matters: this single function is both "act" and "observe", which is why it is the piece people get wrong.

def run_tools(resp, verbose: bool = True) -> list:
    """ACT and OBSERVE. Returns the single user message carrying every result."""
    results = []
    for block in resp.content:
        if block.type != "tool_use":
            continue
        if verbose:
            print(f"  [tool] {block.name}({block.input})")
        try:
            out = DISPATCH[block.name](**block.input)     # ACT
            is_error = False
        except Exception as exc:
            # Do NOT crash the loop on a bad call. The error text goes back to
            # the model, which usually self-corrects. Tool errors are signal.
            out = f"ERROR: {type(exc).__name__}: {exc}"
            is_error = True
        results.append({                                  # OBSERVE
            "type": "tool_result",
            "tool_use_id": block.id,
            "content": str(out),
            "is_error": is_error,
        })
    return [{"role": "user", "content": results}]          # ONE message, all results

def agent(task: str) -> str:
    messages = [{"role": "user", "content": task}]
    turn = 0
    while True:                                            # <- still no ceiling
        turn += 1
        print(f"[turn {turn}]")
        resp = client().messages.create(
            model=MODEL, max_tokens=2048, tools=TOOLS, messages=messages
        )
        messages.append({"role": "assistant", "content": resp.content})
        if resp.stop_reason != "tool_use":
            return text_of(resp)
        messages += run_tools(resp)                        # <- NEW: act + observe

KNOWING WHEN TO QUIT.

Left alone, this thing keeps going. You need a way it stops when finished, a way you stop it when it is not, and a way it can announce it is done on purpose.

What you are about to do, and why it matters: three independent stops, because a loop that knows only one way to stop is one bad response away from spending your whole budget while you are in the bathroom.

    {
        "name": "done",
        "description": (
            "Call this when the task is complete. Pass a one-line summary of what "
            "you did. Calling this ends the run."
        ),
        "input_schema": {
            "type": "object",
            "properties": {"summary": {"type": "string"}},
            "required": ["summary"],
        },
    },
]

def done(summary: str) -> str:
    return summary

def called_done(resp):
    """Return the summary if the model called the done tool this turn."""
    for block in resp.content:
        if block.type == "tool_use" and block.name == "done":
            return block.input.get("summary", "done")
    return None

def agent(task: str, max_turns: int = 25) -> str:
    global LAST_TRANSCRIPT
    messages = [{"role": "user", "content": task}]
    LAST_TRANSCRIPT = messages

    for turn in range(1, max_turns + 1):               # <- NEW: hard ceiling
        print(f"[turn {turn}/{max_turns}]")
        resp = client().messages.create(
            model=MODEL, max_tokens=2048, tools=TOOLS, messages=messages
        )
        messages.append({"role": "assistant", "content": resp.content})

        if resp.stop_reason != "tool_use":             # 1. natural stop
            return text_of(resp)

        summary = called_done(resp)
        if summary is not None:                        # 3. done tool
            return summary

        messages += run_tools(resp)

    # 2. safety stop. Say what happened and hand back something usable,
    # because "stopped" with no context gives you nothing to debug.
    return (
        f"stopped: hit max_turns ({max_turns}) without finishing. "
        f"{len(messages)} messages in the transcript. "
        f"Inspect stage3_stop.LAST_TRANSCRIPT, raise max_turns, or narrow the task."
    )

THE HARD PART NOBODY SHOWS YOU.

The model has no memory. Every turn you resend the whole conversation. Read three files and you have filled it up. Deciding what to throw away is your job, and it is the job nobody writes a tutorial about.

Picture a whiteboard of fixed size. Every turn you write more on it. You will never get a bigger whiteboard, so you get good at erasing: the task stays pinned in the corner, the last few lines stay because they are what you are working on, and the crowded middle becomes one line that says what happened there.

def est_tokens(messages, exact: int | None = None) -> int:
    if exact is not None:
        return exact
    return len(json.dumps(messages, default=str)) // 4

def maybe_compact(messages, budget: int = 60_000, exact: int | None = None) -> list:
    if est_tokens(messages, exact) < budget:
        return messages
    if len(messages) <= 7:                     # nothing meaningful in the middle
        return messages

    print(f"  [compact] transcript over {budget} tokens, folding the middle")
    head = messages[:1]                        # the task, pinned forever
    tail = messages[-6:]                       # recent turns, verbatim
    summary = summarize(messages[1:-6])        # one LLM call
    folded = [{"role": "user", "content": f"[earlier turns summary] {summary}"}]
    return head + folded + tail

    for turn in range(1, max_turns + 1):
        messages = maybe_compact(messages, budget, last_input_tokens)   # <- NEW, and actually called
        LAST_TRANSCRIPT = messages
        print(f"[turn {turn}/{max_turns}] ~{est_tokens(messages, last_input_tokens)} tokens")

        resp = client().messages.create(
            model=MODEL, max_tokens=2048, tools=TOOLS, messages=messages
        )
        last_input_tokens = resp.usage.input_tokens      # the exact count, free
        messages.append({"role": "assistant", "content": resp.content})

JARGON: token. Roughly three quarters of a word. The unit models count in and bill in. A 60,000-token budget is maybe 45,000 words. JARGON: compaction. Deliberately shrinking the conversation you resend, so you stay under the limit without losing the plot.

Two honest notes. Do not reach for tiktoken: that is OpenAI's tokenizer, it miscounts Claude-shaped models, and you will overflow while your own counter says you are fine. And summarize() is a second model call: it costs tokens, adds latency, and can fail mid-task. It shares your key and your model, so if your loop is rate limited, so is your compaction. Say that out loud rather than hiding it behind a helper name.

SAME SHAPE AS THE BIG TOOLS.

Point your loop at a broken test and watch it fix itself. Everything on screen is code you typed in the last hour.

python agent.py --demo

# --demo copies fixtures/ into .work/ first, so the
# start state is identical every single time you run it.
# That is not tidiness. It is what makes this task
# reusable as an eval at #45 on Wednesday.

# lab/fixtures/mathlib.py
def median(values):
    """Middle value. For an even-length list, the mean of the middle two."""
    ordered = sorted(values)
    return ordered[len(ordered) // 2]

# lab/fixtures/test_math.py
class TestMedian(unittest.TestCase):
    def test_median_odd_length(self):
        self.assertEqual(median([3, 1, 2]), 2)

    def test_median_even_length(self):
        # The middle two are 2 and 3, so the median is 2.5.
        self.assertEqual(median([1, 2, 3, 4]), 2.5)

    def test_median_unsorted_even(self):
        self.assertEqual(median([10, 2, 8, 4]), 6.0)

[turn 1/25]  read_file(test_math.py)
[turn 2/25]  read_file(mathlib.py)
[turn 3/25]  run_command(python test_math.py)
            exit code: 1
            FAILED (failures=2)
            AssertionError: 3 != 2.5
[turn 4/25]  write_file(mathlib.py)
            wrote 412 chars to mathlib.py
[turn 5/25]  run_command(python test_math.py)
            exit code: 0
            Ran 5 tests OK
[turn 6/25]  stop_reason end_turn
            fixed median() for even-length lists

Read, run, observe, edit, re-run, stop. That is exactly what Claude Code prints, and you just wrote the engine that prints it. There was never any magic. There was a while-loop, three tools, and a rule about when to stop. If the network is slow, the recorded trace is at /lab/trace.txt and python verify_loop.py drives the real loop with no key and no network at all.

SAME LOOP, DIFFERENT WIRE.

Point the agent you just built at a completely different provider. Six things change. The loop is not one of them.

What you are about to do, and why it matters: "just change the base URL" is true for an Anthropic-shaped endpoint and false for an OpenAI-shaped one. Doing the port yourself is how you learn which parts of your agent were real and which were just the vendor's spelling.

  [SWAP 1] SDK              anthropic  ->  openai
  [SWAP 2] tool schema      {name, description, input_schema}
                            ->  {type:"function", function:{name, description, parameters}}
  [SWAP 3] the call         max_tokens required, system= top level
                            ->  max_tokens optional, system is a message
  [SWAP 4] stop signal      resp.stop_reason == "tool_use"
                            ->  resp.choices[0].finish_reason == "tool_calls"
  [SWAP 5] arguments        block.input is a parsed DICT
                            ->  call.function.arguments is a JSON STRING (json.loads it)
  [SWAP 6] tool results     ONE user message holding all tool_result blocks
                            ->  ONE {"role":"tool"} message PER call
                            (note this INVERTS: batched becomes per-call)

    out_messages = []
    for call in message.tool_calls:
        args = json.loads(call.function.arguments)          # [SWAP 5] JSON STRING, not a dict
        if verbose:
            print(f"  [tool] {call.function.name}({call.function.arguments[:160]})")
        try:
            out = DISPATCH[call.function.name](**args)
        except Exception as exc:
            out = f"ERROR: {type(exc).__name__}: {exc}"
        out_messages.append({
            "role": "tool",                                 # [SWAP 6] one per call
            "tool_call_id": call.id,
            "name": call.function.name,
            "content": str(out),
        })
    return out_messages

def agent(task: str, max_turns: int = 25) -> str:
    """Identical shape to agent.py. Only the wire format moved."""
    messages = [{"role": "user", "content": task}]

    for turn in range(1, max_turns + 1):
        print(f"[turn {turn}/{max_turns}]")
        resp = client().chat.completions.create(            # [SWAP 3] no max_tokens required
            model=MODEL, tools=TOOLS, messages=messages)
        message = resp.choices[0].message
        messages.append(message)                            # append the object itself

        if resp.choices[0].finish_reason != "tool_calls":   # [SWAP 4] different field, different string
            return text_of(resp)

        messages += run_tools(message)

    return f"stopped: hit max_turns ({max_turns})."

SWAP 5 is the one that bites. Copy DISPATCH[name](**block.input) straight across and you get TypeError: argument after ** must be a mapping, not str. Over there the arguments arrive as a parsed dict. Over here they arrive as a JSON string.

Now count what did not change: the while-loop, the turn ceiling, the natural stop, the tools themselves, the safety gate, the compaction policy, and agent(task, max_turns) -> str. The loop is the invariant. The wire format is the accident. That is the whole reason this morning was worth two hours of your Saturday.

WHERE IT BREAKS, AND WHERE YOU STAY IN THE LOOP.

Plain language: four ways this bites people. You have already met three of them this morning, which is why they will stick.

# No human, or no answer, means no approval. Fail closed, always.
return (f"BLOCKED by the safety gate ({label}, not approved by a human). "
        f"Do not retry this command. Find a non-destructive route.")

Measured this morning against the fixture. The stdout only bug survives every rehearsal and detonates the first time you run your own script.

WHAT YOU NOW HAVE WORKING.

Plain language: here is the list of things that were opaque two hours ago and are not any more.

WHAT YOUR TICKET INCLUDES.

Plain language: the model access is provisioned for you. The code and the test are yours to keep.

WHERE THESE SHAPES CAME FROM.

Plain language: you did not invent these formats this morning. Here is who did, and why that is worth knowing.

Nobody sponsored this event. Nothing on this slide is an endorsement, and nothing on it is a logo.

KEEP BUILDING WITH VCN.

Plain language: two things happen next and both of them use the thing you just built.

def agent(task: str, max_turns: int = 25) -> str:

Off the Leash runs #41 to #50: local models, sandboxes, VMs, evals, self hosting your whole rig. The Loop is the core, the rest of the season wires the world around it. Teach a night. Twenty minutes, we have a projector, you do not need slides, and #46 Bake-Off on Aug 1 and #47 Fast Local on Aug 5 both have open speaker slots. Talk to Facilitator Rayyan Zahid before you leave, or find him in the Telegram.

STOP TREATING YOUR AGENT AS A BLACK BOX.

Plain language: you walked in using one of these. You walk out owning one.

You came in using a coding agent. You leave owning one. Same loop. Thirty four lines of it are yours, and you can read every one of them.

plan → act → observe → repeat

Hosted by Vibe Coding Nights: Rayyan Zahid (Immersive Commons), Michalis Vasileiadis (Hacker Bob), Eric Mockler (AI Geneticist), Devinder Sodhi (Learning Layer Labs). Facilitator: Rayyan Zahid.

YOU BUILT THE ENGINE. HERE IS THE CAR.

Plain language: this hour is not more theory. It is the eight loops you can actually run tonight, in the tool you already have open, ordered by how many people really use them.

lab/agent.py:226   for turn in range(1, max_turns + 1):        the loop
lab/agent.py:231   client().messages.create(..., tools=TOOLS)  PLAN, gather context
lab/agent.py:242   messages += run_tools(resp)                 ACT and OBSERVE
lab/agent.py:236   if resp.stop_reason != "tool_use": return   NATURAL STOP

This is a faithful teaching model, not a decompilation. We did not read Claude Code's source. What we have is the documented three phase loop and the public Messages API shape your agent.py already speaks. Same shape is true. Literally this code would be made up.

STEER THE LOOP YOU ARE ALREADY IN.

Plain language: you run this loop every day and you are probably steering it with one blunt instrument. Here are the other three.

/compact focus on the auth bug fix

GIVE THE LOOP A FINISH LINE IT CANNOT FAKE.

Plain language: every loop up to here stops when the model decides it is finished. That is fine while you are watching. It stops being fine the second you are not.

checks:
  - id: events-invariants
    cmd: ["C:/Users/jtole/Documents/2026/life/.venv/Scripts/python.exe",
          "check_events_invariants.py"]
    cwd: "."
    expect_rc: 0
    stdout_contains: "EVENTS-INVARIANTS: PASS"

$ python main.py verify probe events/oracle.yaml
  deterministic: True
  oracle: PASS

If your check can pass while the thing is broken, it is a proxy, not an oracle.

THEN PUT THE LOOP AROUND IT.

Plain language: generate, then check, then repeat until the checker says green. The generate step can be a headless Claude Code, or any command at all. The loop does not care.

generate:  ["claude", "-p", "<the task>", "--permission-mode", "acceptEdits"]
oracle:    "oracle.yaml"          # path relative to this config's dir
max_iters: 6
max_seconds: 1200
stall_limit: 2                    # stop if the SAME checks fail this many times running
on_green:  ["git", "commit", "-m", "<msg>", "--", "mathlib.py"]   # name the file

Four named stops, never silence. Its own docstring at line 18 says it: all logged, never silent. On any non green stop it reports residual_failing, so nothing is quietly dropped. A loop that exits on its safety cap without saying so is a lie.

MAKE THE LOOP REFUSE TO STOP.

Plain language: the session that built these slides kept trying to end this morning. It could not. Something on this laptop kept saying no, and that something is one small program that gets a vote on whether the session is allowed to end.

process.stdout.write(JSON.stringify({ decision: "block", reason }));

UNCOMMITTED CHANGES (${sourceLines.length} files). Commit atomically before ending.

Start a WIP commit to accumulate across turns (recommended for
multi-turn work):
  git commit -m "WIP: <short title of the logical unit>"

Or commit atomically now with a real message:
  git commit -m "<message>"

FIVE ANSWERS. ONE OF THEM DOES NOTHING.

Plain language: this is the slide that makes the rest of the rung buildable. All five styles are live in one folder on this laptop right now.

if (input.stop_hook_active) return;

} catch (e) {
  process.exit(0);
}

And the bit worth putting on a slide about trusting documentation. Ray's own global CLAUDE.md says seven hooks. We counted the file this morning: it is 18 hook commands across 6 events, and 6 of them are Stop hooks. Six separate programs get a vote on whether this session is allowed to end. The doc is stale. The file is the truth. One thing we could not answer, and we looked: how two parallel Stop hooks resolve when both block with different reasons.

EXACTLY TWO THINGS CAN WAKE A LOOP.

Plain language: a clock, or a doorbell. Almost every wasted dollar in agent automation comes from reaching for a clock when you were holding a doorbell.

/loop 5m /babysit-prs
/loop 30m check the deploy

Bash({ command: 'until grep -q "Ready in" dev.log; do sleep 0.5; done',
       run_in_background: true })

Do not poll for something you will be told about. A CI run that takes eight minutes deserves one 480 second check, not eight 60 second ones.

EVERYTHING SO FAR DIES WHEN YOU CLOSE THE TERMINAL.

Plain language: the fix is boring on purpose. One declarative file, applied by a command that previews before it commits.

python main.py cron bootstrap          # preview, this is the default
python main.py cron bootstrap --apply  # commit
python main.py cron                    # the dashboard

Crons: 27 active | 7 paused | 3 failing | 0 firing now

MANY LOOPS, AND THE SAME WAY TWICE.

Plain language: we are not talking through this one. Photograph it. Two rungs, one table, and the sentence the whole hour was built to land.

Every rung answered the same four questions. The ladder is really about the third one. Rung 1 observes with your eyes. Rung 2 observes with an exit code. Rung 3 makes that exit code something the model cannot talk its way past. Everything above Rung 2 is only worth building if Rung 2 is real. Write the check first.