Build a Local Web App

// The real Agent SDK call. One function, one `query()`.
//
// Role: turn an agent request into a stream of SDK messages. This is the only
// file in the server that imports `query`.
//
// Invariants:
// - Options set here are the ones version 0 has a decision record for: cwd,
//   systemPrompt, maxTurns, permissionMode, abortController. Anything else is
//   the SDK's default and stays that way until a module needs it.
// - The abort path is the caller's AbortSignal, forwarded into the SDK's own
//   `abortController`. Verified against @anthropic-ai/claude-agent-sdk 0.3.251:
//   `Options.abortController` is the documented cancellation input, and
//   `Query.interrupt()` is described as a control request "only supported when
//   streaming input/output is used", which version 0 does not use.

import { query } from "@anthropic-ai/claude-agent-sdk";

/** @typedef {import("./agent.js").AgentRequest} AgentRequest */
/** @typedef {import("./agent.js").MessageStream} MessageStream */

/**
* Start one real session and return its stream of messages.
*
* @type {MessageStream}
*/
export const sdkStream = (request) => {
// An AbortController is the pair to an AbortSignal: the controller has the
// button, `abort()`, and the signal is what everyone else watches. The SDK
// takes a controller, and the session layer owns one already, so this one is
// a relay: abort in, abort out.
const controller = new AbortController();
if (request.signal.aborted) controller.abort();
else
  request.signal.addEventListener("abort", () => controller.abort(), {
    once: true,
  });

return query({
  prompt: request.prompt,
  options: {
    // The agent works in the workspace directory, never in the repository
    // that holds this server. See docs/decisions/0014.
    cwd: request.cwd,
    // The full Claude Code system prompt. Omitting systemPrompt would give the
    // SDK's minimal default, which covers tool calling only. See 0015.
    systemPrompt: { type: "preset", preset: "claude_code" },
    maxTurns: request.maxTurns,
    permissionMode: request.permissionMode,
    abortController: controller,
  },
});
};

// The Agent SDK message loop, in one place.
//
// Role: run one agent session and reduce the stream of SDK messages to the two
// things version 0 reports, the session identity and the final result. The
// switch below is the loop from the module 14 lab, kept visible on purpose:
// modules 16 (streaming), 16 (approvals) and 17 (sessions) each add a case or a
// handler here rather than replacing the file.
//
// Invariants:
// - This module never touches a WebSocket and never formats a protocol frame.
//   It reports through a handlers object and returns a result object.
// - The message stream is injected. `sdkStream` calls the real SDK,
//   `createFakeStream` replays a canned sequence; the loop cannot tell them
//   apart.
// - Exactly one of these happens per call: a return with a result, or a throw.
//   A stream that ends without a `result` message is a throw, not a silent
//   empty answer.
//
// The shapes this file passes around are written below as JSDoc `@typedef`
// comments. A typedef is a comment that names a shape so a later comment, and
// an editor, can refer to it. Nothing in it runs; the code is plain JavaScript.

/**
* One request to run the agent.
*
* @typedef {object} AgentRequest
* @property {string} prompt The user's prompt, verbatim.
* @property {string} cwd Absolute directory the agent runs in.
* @property {number} maxTurns Ceiling on agentic turns.
* @property {string} permissionMode One of the modes listed in config.js.
* @property {AbortSignal} signal Aborted when the client cancels or the socket
*   closes. An AbortSignal is a small object with a flag on it, `aborted`, that
*   flips from false to true once and never back. Code that is waiting can also
*   ask to be told the moment it flips.
*/

/**
* Who the session belongs to, as the SDK reports it.
*
* @typedef {object} SessionInfo
* @property {string} sessionId
* @property {string} model
*/

/**
* Callbacks the loop reports through while a session runs.
*
* @typedef {object} AgentHandlers
* @property {(info: SessionInfo) => void} onSession Called once, when the SDK
*   emits its system/init message.
*/

/**
* What one finished session produced.
*
* @typedef {object} AgentResult
* @property {string} subtype "success", or one of the SDK's error subtypes such
*   as "error_max_turns".
* @property {string} text The answer. Empty string when `subtype` is not
*   "success".
* @property {number} turns
* @property {number} costUsd
*/

/**
* A source of SDK messages for one request.
*
* It is a function that takes an AgentRequest and returns something the `for
* await` loop below can walk through, one message at a time, waiting for each.
*
* @typedef {(request: AgentRequest) => AsyncIterable<any>} MessageStream
*/

/** Thrown when the session stopped without producing a result. */
export class AgentError extends Error {
constructor(message) {
  super(message);
  this.name = "AgentError";
}
}

/** Thrown when the run was cancelled through the request's AbortSignal. */
export class AgentCancelled extends Error {
constructor() {
  super("cancelled");
  this.name = "AgentCancelled";
}
}

/**
* Run one session to completion.
*
* `createStream` is the seam that fake mode swaps. Everything downstream of
* this function sees the same shapes either way.
*
* @param {AgentRequest} request
* @param {AgentHandlers} handlers
* @param {MessageStream} createStream
* @returns {Promise<AgentResult>}
*/
export async function runAgent(request, handlers, createStream) {
let result;
// Assistant text is collected but not sent in version 0. The result message
// already carries the final answer; this is here because module 16 streams
// these blocks as `delta` frames and the collection point is the same.
const assistantText = [];

try {
  // `for await` is an ordinary loop with one difference: each trip round it
  // waits for the next item to arrive before running the body. That is what
  // reading a live stream of messages needs, because the next message has not
  // been written yet when the loop asks for it.
  for await (const message of createStream(request)) {
    switch (message.type) {
      case "system":
        // The first message of every session. Only the init subtype carries
        // the session id and model; other system subtypes exist and are not
        // interesting to version 0.
        if (message.subtype === "init") {
          handlers.onSession({
            sessionId: message.session_id,
            model: message.model,
          });
        }
        break;

      case "assistant":
        for (const block of message.message.content) {
          if (block.type === "text") assistantText.push(block.text);
        }
        break;

      case "user":
        // Tool results come back to the model as user messages. The bundled
        // Claude Code process ran the tool, not this code.
        break;

      case "result": {
        // The envelope that closes the session. Only the success variant has
        // a `result` string, so the answer is read by checking that the
        // property is there rather than assuming it.
        const text =
          message.subtype === "success" && typeof message.result === "string"
            ? message.result
            : "";
        result = {
          subtype: message.subtype,
          text,
          turns: message.num_turns,
          costUsd: message.total_cost_usd,
        };
        break;
      }

      default:
        // The SDK adds message types over time. Version 0 ignores what it
        // does not know rather than failing the prompt over it.
        break;
    }
  }
} catch (cause) {
  // An abort surfaces here as a rejection. Which error class the SDK throws
  // on abort is not part of its documented contract, so the signal is the
  // thing checked, not the error name.
  if (request.signal.aborted) throw new AgentCancelled();
  throw cause;
}

if (request.signal.aborted) throw new AgentCancelled();

if (result === undefined) {
  throw new AgentError("the agent session ended without a result message");
}

return result;
}

# Run the workbench in a container.
#
# Role: the one command a reader runs to see the app without installing Node.
#   docker compose build
#   WORKBENCH_FAKE_SDK=1 docker compose up
#
# Invariants:
#   - No secret is written in this file. ANTHROPIC_API_KEY is passed through
#     from the host environment with the "VAR" short form, which forwards the
#     host's value and sets nothing if it is unset.
#   - ./workspace on the host is the agent's working directory. It is a bind
#     mount, not a volume, because the point of the workbench is to look at the
#     files the agent changed with your own editor. See docs/decisions/0066.
#   - Port 3000 on the host maps to 3000 in the container, which is the server's
#     default PORT and what README.md and client/README.md both quote.

services:
workbench:
  build:
    context: .
    dockerfile: Dockerfile
  image: claude-workbench:0.15.0
  ports:
    # Host:container. Bound to all host interfaces, matching the plain
    # "localhost:3000" the docs quote; change the left side to
    # "127.0.0.1:3000" if the machine is on a network you do not trust.
    - "3000:3000"
  environment:
    # Short form: forward the host's value, or leave it unset if the host has
    # none. The long form "KEY: ${KEY}" would set it to the empty string
    # instead, and an empty API key reads as a configured key that fails.
    - ANTHROPIC_API_KEY
    - WORKBENCH_FAKE_SDK
    # Optional server settings, forwarded the same way so a reader can try one
    # without editing this file.
    - WORKBENCH_MAX_TURNS
    - WORKBENCH_PERMISSION_MODE
    # Not forwarded, set here: inside the container these two are not the
    # host's business, and the paths below are where the image puts them.
    - HOST=0.0.0.0
    - PORT=3000
    - WORKBENCH_DIR=/app/workspace
    # Where the browser files are. The client has no build step, so this is
    # client/public copied in as it stands. The Dockerfile sets the same
    # value; it is repeated here because this is the file a reader opens
    # first. See docs/decisions/0069.
    - WORKBENCH_CLIENT_DIR=/app/client/public
  volumes:
    # The agent reads and writes here. Everything it does is visible on the
    # host at ./workspace immediately, and nothing it does can reach the rest
    # of the repository, because nothing else is mounted.
    - ./workspace:/app/workspace
  # Compose's default is to leave stdin closed and no tty, which is what a
  # server wants. Named explicitly so nobody adds them by habit.
  stdin_open: false
  tty: false
  restart: "no"