@ahpd/agent-claude 0.1.0

package/src/claude.ts

@@ -0,0 +1,353 @@
+import { probe } from './probe.js';
+import { serversFor } from './mcp.js';
+import { createSession, EFFORT_LABELS, EFFORTS } from './session.js';
+import { turnsOf } from './transcript.js';
+import { catalogue } from './catalog.js';
+import { within } from '@ahpd/server';
+import type { Agent, Bag, Start } from '@ahpd/server';
+
+/**
+ * The resource a token for this backend is for.
+ *
+ * Named once, because it is the identifier a client must send back verbatim:
+ * the protocol says `authenticate`'s `resource` MUST match one the server
+ * advertised, so this string appearing twice with a typo between them is a
+ * token nothing will accept.
+ */
+const ANTHROPIC = 'https://api.anthropic.com';
+
+/**
+ * Claude Code, as an agent backend.
+ *
+ * Everything the host would otherwise have to know about one particular
+ * harness: which settings it takes, where its past sessions are kept, and how
+ * to start one. The host asks through `Agent` and imports none of this.
+ */
+
+/** How to build the Claude backend. */
+export interface ClaudeOptions {
+  /**
+   * The directories it will work in, and the ones it lists.
+   *
+   * The first is where a session goes when the client names none. A client
+   * may name any of the others and nothing else: a host that ran the agent
+   * wherever it was told is one anybody who can reach the port can point at
+   * any directory on the machine.
+   *
+   * This is also the catalogue's scope, so a directory left out is one whose
+   * sessions are neither listed nor openable.
+   */
+  paths: string[];
+  /** The id clients name. `claude` unless something else already is. */
+  provider?: string;
+}
+
+/** Claude Code on one or more directories, ready to be handed to `createHost`. */
+export function claude(options: ClaudeOptions): Agent {
+  const dirs = options.paths;
+  const dir = dirs[0];
+  if (dir === undefined)
+    throw new Error('claude() needs at least one directory to work in.');
+
+  /**
+   * Which directory a session goes in.
+   *
+   * Named, or the first. Anything else is refused rather than quietly
+   * replaced - a directory accepted and then ignored is a session running
+   * somewhere nobody asked for, with nothing on screen to say so.
+   */
+  const workingDirectory = (asked?: string): string => {
+    if (asked === undefined)
+      return dir;
+    /*
+     * Under a served directory, not equal to one.
+     *
+     * This compared for equality, so a host told to serve `/home/you` served
+     * that one directory and refused every project inside it - which is the
+     * only kind of directory anybody opens. An editor asks for its workspace
+     * folder, and that is never the path somebody passed to `--path`.
+     */
+    if (!dirs.some((served) => within(served, asked))) {
+      throw new Error(
+        `This host does not serve ${asked}. It serves ${dirs.join(', ')}.`,
+      );
+    }
+    // What was asked for, not the root it sits under: the session runs where
+    // the client said.
+    return asked;
+  };
+
+  /*
+   * What the probe learned about output styles.
+   *
+   * The schema is otherwise fixed, but this one property's choices belong to
+   * the harness rather than to the protocol - a person's own styles live in
+   * their settings - so it is learned once at startup, the way models are,
+   * and the control is simply absent until it is known.
+   */
+  let styles: string[] = [];
+
+  /**
+   * Whether the models this harness offers carry effort controls of their own.
+   *
+   * A model's `configSchema` and the session-wide `effortLevel` reach the same
+   * setting, and a client draws both - so a person is shown two effort
+   * controls, on two different values, for one thing. The model's is the
+   * truthful one: it lists what that model actually supports, where the
+   * session-wide key lists all five whatever is chosen. So this backend offers
+   * the session key only while there is nothing better.
+   */
+  let perModelEffort = false;
+  let style: string | undefined;
+
+  /**
+   * What a session can be told to do differently.
+   *
+   * One schema, used by `resolveSessionConfig` (before a session exists) and
+   * by every session's own state (after one does). Two copies would drift, and
+   * the composer would offer one set of controls on the new-session screen and
+   * a different set the moment a session opened.
+   *
+   * `sessionMutable` is what each row turns on: the permission mode, the model
+   * and the effort level are things the CLI takes on a *running* session.
+   * `thinking` is fixed when the query is built, so offering it live would be
+   * a switch that flips back.
+   */
+  const schema = (): Bag => ({
+    // A JSON Schema object, and it has to say so: `type` is required, and a
+    // schema without it matches nothing a client validates.
+    type: 'object',
+    properties: {
+      /*
+       * One axis, and the CLI's own five values.
+       *
+       * The protocol's config schema is generic and a backend advertises what
+       * it has - VS Code's own hosts advertise different properties for
+       * Copilot and for Claude, and a client draws whatever it is given. Its
+       * Claude host says why in as many words: it collapses the platform's
+       * `autoApprove` x `mode` two-axis surface onto one `permissionMode`
+       * matching the SDK's enum, and *omits* `autoApprove`, `mode`,
+       * `isolation` and `branch` deliberately, because the pickers key off
+       * property names and omitting them suppresses a mode and branch UI that
+       * would not mean anything here.
+       *
+       * The wording is that host's too, so one session reads the same however
+       * it is opened. `auto` was missing here and is a real mode the CLI
+       * takes: the agent deciding, per call, whether it needs to ask.
+       */
+      permissionMode: {
+        scope: 'session',
+        type: 'string',
+        title: 'Approvals',
+        description: 'How the agent handles tool approvals.',
+        enum: ['default', 'acceptEdits', 'plan', 'auto', 'bypassPermissions'],
+        enumLabels: [
+          'Ask Before Edits',
+          'Edit Automatically',
+          'Plan Mode',
+          'Auto Mode',
+          'Bypass Permissions',
+        ],
+        enumDescriptions: [
+          'Asks before editing files.',
+          'Edits files without asking, and asks before using other tools.',
+          'Creates a plan before making changes.',
+          'Decides whether to ask for each tool operation.',
+          'Runs all tools without asking.',
+        ],
+        default: 'default',
+        sessionMutable: true,
+      },
+      /*
+       * The model is not a config property.
+       *
+       * A session has no model; each message has one. The choices are carried
+       * on the agent (`RootState.agents[].models`) and the choice on the turn.
+       * `session/configChanged` with a `model` key is still honoured, but the
+       * model is not advertised here as a control of its own.
+       */
+      ...(perModelEffort ? {} : {
+        effortLevel: {
+          scope: 'chat',
+          type: 'string',
+          title: 'Effort',
+          description: 'How hard it thinks before answering.',
+          enum: [...EFFORTS],
+          enumLabels: EFFORTS.map((one) => EFFORT_LABELS[one]),
+          default: 'high',
+          sessionMutable: true,
+        },
+      }),
+      // Learned, so absent until the probe has answered and absent for good
+      // on a harness that has no styles.
+      ...(styles.length > 0
+        ? {
+            outputStyle: {
+        scope: 'session',
+              type: 'string',
+              title: 'Output style',
+              description: 'The voice it answers in.',
+              enum: styles,
+              enumLabels: styles.map((name) => name.charAt(0).toUpperCase() + name.slice(1)),
+              ...(style !== undefined ? { default: style } : {}),
+              sessionMutable: true,
+            },
+          }
+        : {}),
+      thinking: {
+        type: 'string',
+        title: 'Thinking',
+        description: 'Fixed when the session is created.',
+        enum: ['adaptive', 'disabled'],
+        enumLabels: ['Adaptive', 'Off'],
+        enumDescriptions: ['The agent decides when to think', 'No extended thinking'],
+        default: 'adaptive',
+        sessionMutable: false,
+      },
+      /*
+       * Per-tool allow and deny, which is the slope the mode above is a cliff.
+       *
+       * A platform key rather than one of this backend's invention: it is what
+       * the reference client's permission picker writes when somebody approves
+       * a tool "in this session", and its own Claude host advertises it
+       * unchanged because the SDK takes `allowedTools` / `disallowedTools`
+       * natively. Without it the only way to stop being asked about the one
+       * command you trust is `bypassPermissions`, which stops asking about
+       * everything.
+       *
+       * An object, and the first config value here that is not a string. The
+       * protocol declares the bag `Record<string, unknown>`; this host used to
+       * declare it `Record<string, string>`, which is why nothing of this
+       * shape could be carried at all.
+       */
+      permissions: {
+        scope: 'session',
+        type: 'object',
+        title: 'Permissions',
+        description: 'Per-tool session permissions. Updated when a tool is approved for this session.',
+        properties: {
+          allow: { type: 'array', title: 'Allowed tools', items: { type: 'string', title: 'Tool name' } },
+          deny: { type: 'array', title: 'Denied tools', items: { type: 'string', title: 'Tool name' } },
+        },
+        default: { allow: [], deny: [] },
+        // Unlike `thinking`, this one really can move on a running session:
+        // the SDK takes the lists when the query is built, and `canUseTool`
+        // is where this host already sits between the agent and the person.
+        sessionMutable: true,
+      },
+    },
+  });
+
+  const defaults = (): Record<string, unknown> => ({
+    permissionMode: 'default',
+    // Beside its schema or not at all: a value with no property to draw it is
+    // a control a client cannot show and cannot change.
+    ...(perModelEffort ? {} : { effortLevel: 'high' }),
+    thinking: 'adaptive',
+    permissions: { allow: [], deny: [] },
+    ...(style !== undefined ? { outputStyle: style } : {}),
+  });
+
+  return {
+    provider: options.provider ?? 'claude',
+    displayName: 'Claude Code',
+    // Both, because the SDK resumes at a named prompt: `resumeSessionAt` with
+    // `forkSession` continues from a turn under a new id, and a side chat is
+    // an unresumed session handed what that turn said.
+    chats: { fork: true, sideChat: true },
+    // The SDK takes `additionalDirectories` at startup, so a session works in
+    // as many as it was given; the first is the process root and is fixed.
+    multipleDirectories: true,
+    description: `The Claude Agent SDK, on ${dirs.join(', ')}`,
+    schema,
+    defaults,
+
+    directories: () => [...dirs],
+
+    // The styles are kept as well as handed on: `schema()` is asked before any
+    // session exists, and it can only offer what has already been learned.
+    probe: async () => {
+      const offered = await probe(dir);
+      styles = offered.outputStyles ?? [];
+      style = offered.outputStyle;
+      perModelEffort = offered.models.some((model) => model.configSchema !== undefined);
+      return offered;
+    },
+
+    // Every directory it serves, as one list. A session is listed by the
+    // catalogue of the directory it ran in, and a host serving several has
+    // one catalogue.
+    list: async () => (await Promise.all(dirs.map((served) => catalogue(served)))).flat(),
+
+    // Whichever directory holds it. The transcript reader wants the one the
+    // session ran in, and only its own catalogue knows which that was.
+    transcript: async (id) => {
+      for (const served of dirs) {
+        const rows = await catalogue(served).catch(() => []);
+        if (rows.some((row) => row.id === id))
+          return turnsOf(id, served);
+      }
+      return undefined;
+    },
+
+    /*
+     * The one resource this backend can be given a token for.
+     *
+     * `required: false`, and that is the honest declaration rather than the
+     * lenient one: this daemon runs as whoever started it and inherits their
+     * `claude login` or `ANTHROPIC_API_KEY`, so it works with nothing pushed
+     * at all. Saying `required: true` would refuse clients that would
+     * otherwise be perfectly able to open a session.
+     */
+    protectedResources: [{
+      resource: ANTHROPIC,
+      resource_name: 'Anthropic API',
+      authorization_servers: ['https://console.anthropic.com'],
+      required: false,
+    }],
+
+    create: (start: Start) => createSession({
+      uri: start.uri,
+      chatUri: start.chatUri,
+      cwd: workingDirectory(start.workingDirectory),
+      /*
+       * The MCP servers, declared by this host rather than found by the CLI.
+       *
+       * The same files the CLI reads - `.mcp.json` beside the project and
+       * `mcpServers` in `~/.claude.json` - handed to the SDK so they are
+       * *its* servers. That is what makes a token a client signed in with
+       * applicable: `setMcpServers` re-declares only what the SDK was given.
+       */
+      mcpServers: serversFor([workingDirectory(start.workingDirectory), ...(start.additional ?? [])]),
+      // Each one checked the way the first is: a directory this host does not
+      // serve is not one an agent may be pointed at, however it arrived.
+      ...(start.additional && start.additional.length > 0
+        ? { additional: start.additional.map((one) => workingDirectory(one)) }
+        : {}),
+      // The host's own tools, offered to the model beside this backend's.
+      ...(start.tools && start.tools.length > 0 ? { tools: start.tools } : {}),
+      settings: start.settings,
+      schema: start.schema,
+      emit: start.emit,
+      ...(start.seedCustomizations ? { seedCustomizations: start.seedCustomizations } : {}),
+      ...(start.resume !== undefined ? { resume: start.resume } : {}),
+      ...(start.forkAt !== undefined ? { forkAt: start.forkAt } : {}),
+      ...(start.rewindAt !== undefined ? { rewindAt: start.rewindAt } : {}),
+      ...(start.context !== undefined ? { context: start.context } : {}),
+      ...(start.seed ? { seed: start.seed } : {}),
+      ...(start.onFileEdit ? { onFileEdit: start.onFileEdit } : {}),
+      ...(start.onHandshake ? { onHandshake: start.onHandshake } : {}),
+      /*
+       * A pushed token, as the variable the CLI reads.
+       *
+       * Which variable that is, is this file's business and not the host's:
+       * the host knows a token belongs to `https://api.anthropic.com` and
+       * stops there, which is what keeps `createHost` the protocol and
+       * nothing else.
+       */
+      ...(start.credentials?.[ANTHROPIC]
+        ? { env: { ANTHROPIC_API_KEY: start.credentials[ANTHROPIC] } }
+        : {}),
+    }),
+  };
+}

package/src/index.ts

@@ -0,0 +1,21 @@
+/**
+ * The Claude backend, as an `Agent` this host can be handed.
+ *
+ * One implementation of the contract `@ahpd/server` declares, and the only
+ * thing in either package that knows what the Claude harness is: it starts the
+ * agent SDK, translates its message stream into the state actions the protocol
+ * describes, and reads a transcript somebody else's session left on disk.
+ *
+ * A host that wants a different harness registers a different `Agent` and
+ * never loads this. A host that wants both registers both - `createHost` takes
+ * a list, and cannot tell one from another.
+ */
+
+export { catalogue } from './catalog.js';
+export { claude } from './claude.js';
+export type { ClaudeOptions } from './claude.js';
+export { createSession, EFFORTS, EFFORT_LABELS } from './session.js';
+export type { Published } from './session.js';
+export { probe } from './probe.js';
+export { turnsOf } from './transcript.js';
+export { protectedResource, urlOf } from './mcp.js';

package/src/mcp.ts

@@ -0,0 +1,75 @@
+/** The MCP servers a session runs with, read from the files the CLI reads. */
+
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import type { Bag } from '@ahpd/server';
+
+/**
+ * Every MCP server configured for a directory, by name.
+ *
+ * The CLI finds these itself and this host normally leaves it to. It reads
+ * them here for one reason: a server the *SDK* was given is one
+ * `setMcpServers` can re-declare, and a server that came from a settings file
+ * is not - so a token a client signs in with has nowhere to go unless this
+ * host owns the declaration. The files are the CLI's own: `.mcp.json` beside
+ * the project, and `mcpServers` in `~/.claude.json`.
+ *
+ * A file that is missing, unreadable or not JSON contributes nothing. This is
+ * a best effort by design: the CLI still reads the same files, and a server
+ * this misses is a server that works exactly as it did before.
+ */
+export function serversFor(directories: string[]): Record<string, Bag> {
+  const found: Record<string, Bag> = {};
+  const files = [
+    join(homedir(), '.claude.json'),
+    ...directories.map((dir) => join(dir, '.mcp.json')),
+  ];
+  for (const file of files) {
+    let held: unknown;
+    // Synchronous on purpose: these are two small files read once when a
+    // session is created, and a backend's `create` answers with a session
+    // rather than a promise of one.
+    try { held = JSON.parse(readFileSync(file, 'utf8')) as unknown; }
+    catch { continue; }
+    const bag = typeof held === 'object' && held !== null ? held as Bag : {};
+    const servers = typeof bag.mcpServers === 'object' && bag.mcpServers !== null ? bag.mcpServers as Bag : {};
+    for (const [name, config] of Object.entries(servers)) {
+      // Later wins: a project's own `.mcp.json` is nearer than the home file,
+      // which is the order the CLI resolves them in.
+      if (typeof config === 'object' && config !== null) found[name] = config as Bag;
+    }
+  }
+  return found;
+}
+
+/** The URL an http or sse server lives at, or nothing for a stdio one. */
+export const urlOf = (config: unknown): string | undefined => {
+  const bag = typeof config === 'object' && config !== null ? config as Bag : {};
+  const url = typeof bag.url === 'string' ? bag.url : undefined;
+  if (url === undefined) return undefined;
+  const kind = typeof bag.type === 'string' ? bag.type : 'http';
+  return kind === 'http' || kind === 'sse' ? url : undefined;
+};
+
+/**
+ * What an MCP server says about signing into it, per RFC 9728.
+ *
+ * `<url>/.well-known/oauth-protected-resource`, which is where an OAuth
+ * protected resource publishes its metadata and where a client looks to find
+ * the authorization server. Answers the discovered document, or a bare one
+ * naming the server itself: the URL *is* the canonical resource identifier,
+ * so an incomplete answer is still a true one - what a client loses is the
+ * one-click sign-in, not the knowledge that it needs to sign in.
+ */
+export async function protectedResource(url: string, name: string, ms = 15_000): Promise<Bag> {
+  const bare: Bag = { resource: url, resource_name: name };
+  const found = new URL(url);
+  const at = `${found.origin}/.well-known/oauth-protected-resource${found.pathname.replace(/\/+$/, '')}`;
+  const said = await fetch(at, { signal: AbortSignal.timeout(ms) })
+    .then((answer) => (answer.ok ? answer.json() as Promise<unknown> : undefined))
+    .catch(() => undefined);
+  if (typeof said !== 'object' || said === null) return bare;
+  const metadata = said as Bag;
+  return typeof metadata.resource === 'string' ? metadata : bare;
+}

package/src/probe.ts

@@ -0,0 +1,104 @@
+import { query } from '@anthropic-ai/claude-agent-sdk';
+import { customizationsOf, EFFORT_LABELS, EFFORTS } from './session.js';
+import type { Bag, Offered } from '@ahpd/server';
+
+/**
+ * Reads what the agent backend offers, once, without creating a session.
+ *
+ * Clients ask `resolveSessionConfig` before creating anything, so the models
+ * and commands have to be known before any session exists. This starts one
+ * short-lived agent process at startup, asks it over the control protocol,
+ * and closes it. No prompt is sent and no transcript is written.
+ */
+
+const bag = (value: unknown): Bag => (typeof value === 'object' && value !== null ? value as Bag : {});
+const list = (value: unknown): unknown[] => (Array.isArray(value) ? value : []);
+const str = (value: unknown): string | undefined => (typeof value === 'string' ? value : undefined);
+
+/**
+ * How hard *this* model can be told to think, as its own config schema.
+ *
+ * Per model and not per session, which is the whole point: the CLI reports a
+ * different `supportedEffortLevels` for each - some take all five, some take
+ * one, and some take none - so a single session-wide effort control offers
+ * levels the chosen model may not have, and accepts one it will then ignore.
+ * A model that supports none gets no schema and a client draws no control,
+ * which is the honest form of "this one does not think harder on request".
+ *
+ * `thinkingLevel` is the key, because that is the one the reference client's
+ * picker writes into `ModelSelection.config` for both of its providers.
+ */
+const thinkingFor = (efforts: string[]): { configSchema?: Record<string, unknown> } => {
+  if (efforts.length === 0) return {};
+  return {
+    configSchema: {
+      type: 'object',
+      properties: {
+        thinkingLevel: {
+          type: 'string',
+          title: 'Thinking Level',
+          description: 'Controls how much reasoning effort Claude uses.',
+          enum: [...efforts],
+          enumLabels: efforts.map((one) => EFFORT_LABELS[one as typeof EFFORTS[number]] ?? one),
+          ...(efforts.includes('high') ? { default: 'high' } : {}),
+        },
+      },
+    },
+  };
+};
+
+export async function probe(cwd: string): Promise<Offered> {
+  // A prompt that never yields. The query needs one to exist; it does not need
+  // one to answer what it can do.
+  async function* silence(): AsyncGenerator<never> {
+    await new Promise<void>(() => {});
+    // eslint-disable-next-line no-unreachable
+    return;
+  }
+
+  const handle = query({ prompt: silence(), options: { cwd } } as Parameters<typeof query>[0]);
+  try {
+    const [init, mcp, skills] = await Promise.all([
+      handle.initializationResult().then((answer) => bag(answer as unknown)),
+      // Best effort beside the one that matters: a harness with no MCP servers
+      // and one that will not say are the same empty list here, and neither is
+      // worth failing the probe over.
+      handle.mcpServerStatus().then((answer) => (Array.isArray(answer) ? answer : [])).catch(() => [] as unknown[]),
+      handle.reloadSkills().then((answer) => list(bag(answer as unknown).skills)).catch(() => [] as unknown[]),
+    ]);
+    const styles = list(init.available_output_styles).filter((s): s is string => typeof s === 'string');
+    return {
+      customizations: customizationsOf(init, mcp, skills),
+      // Only when the harness has them. An empty list would draw a picker
+      // with nothing in it, which is worse than no control.
+      ...(styles.length > 0 ? { outputStyles: styles } : {}),
+      ...(str(init.output_style) ? { outputStyle: str(init.output_style) as string } : {}),
+      models: list(init.models)
+        // `value`, not `id`.
+        .map((raw) => {
+          const model = bag(raw);
+          return {
+            id: str(model.value) ?? '',
+            name: str(model.displayName) ?? str(model.value) ?? '',
+            ...thinkingFor(list(model.supportedEffortLevels).filter((one): one is string => typeof one === 'string')),
+          };
+        })
+        .filter((model) => model.id !== ''),
+      commands: list(init.commands)
+        .map((raw) => {
+          const command = bag(raw);
+          return {
+            name: str(command.name) ?? '',
+            ...(str(command.description) ? { description: str(command.description) as string } : {}),
+            ...(str(command.argumentHint) ? { argumentHint: str(command.argumentHint) as string } : {}),
+          };
+        })
+        .filter((command) => command.name !== ''),
+    };
+  } catch {
+    // A harness that will not answer offers nothing, which is a real answer.
+    return { models: [], commands: [], customizations: [] };
+  } finally {
+    handle.close();
+  }
+}