agl 41.0.1 → 41.1.0

package/ts/functions.controllermanagementsurface.ts

@@ -0,0 +1,149 @@
+import * as plugins from './plugins.js';
+import {
+  controllerManagementMethods,
+  controllerManagementRequestMaximumBodyBytes,
+  controllerManagementTypedRequestPath,
+} from '../ts_interfaces/index.js';
+
+/** The direct peer addresses the management endpoint answers: this host's loopback, as Node reports it. */
+const loopbackPeerAddresses = new Set(['127.0.0.1', '::ffff:127.0.0.1', '::1']);
+
+/**
+ * Headers a forwarding proxy adds, and the transport secret a trusted TLS proxy injects. A request that carries one
+ * came through a proxy, even one on this host whose connection is loopback, so it is not a local caller's.
+ */
+const forwardingHeaders = [
+  'forwarded',
+  'x-forwarded-for',
+  'x-forwarded-host',
+  'x-forwarded-proto',
+  'x-real-ip',
+  'x-harness-controller-proxy-secret',
+] as const;
+
+const envelopeKeys = new Set(['method', 'request', 'response', 'correlation', 'requestInstanceId']);
+
+/**
+ * The connection a management request arrived on, granted to its handler as `localData.peer`: one per request, so
+ * the handlers' per-peer operation and preflight budgets count it as a connection of its own.
+ */
+export interface IControllerManagementPeer {
+  id: string;
+  context: {
+    headers: Headers;
+    state: Record<string, unknown>;
+  };
+}
+
+export const isLoopbackPeerAddress = (addressArg: string | undefined): boolean => (
+  addressArg !== undefined && loopbackPeerAddresses.has(addressArg)
+);
+
+/**
+ * Admits a request to the management endpoint before its body is read: from a loopback peer, a POST of
+ * `application/json` to the exact path, addressed to `127.0.0.1:<port>`, with no `Origin` (a browser always sends
+ * one with a POST) and no forwarding header. Anything else is refused; nothing about the request is logged.
+ */
+export const admitControllerManagementRequest = (
+  contextArg: plugins.smartserve.IRequestContext,
+  portArg: number,
+): true | Response => {
+  if (!isLoopbackPeerAddress(contextArg.connectionInfo?.remoteAddr)) {
+    return new Response('Forbidden', { status: 403 });
+  }
+  const url = contextArg.url;
+  if (
+    url.pathname !== controllerManagementTypedRequestPath
+    || url.search !== ''
+    || url.hash !== ''
+    || url.username !== ''
+    || url.password !== ''
+    || url.hostname !== '127.0.0.1'
+    || url.port !== String(portArg)
+    || contextArg.headers.get('host') !== `127.0.0.1:${portArg}`
+  ) {
+    return new Response('Not Found', { status: 404 });
+  }
+  if (
+    contextArg.headers.has('origin')
+    || forwardingHeaders.some((headerArg) => contextArg.headers.has(headerArg))
+  ) {
+    return new Response('Forbidden', { status: 403 });
+  }
+  if (contextArg.method !== 'POST') {
+    return new Response('Method Not Allowed', { status: 405, headers: { Allow: 'POST' } });
+  }
+  if (contextArg.headers.get('content-type') !== 'application/json') {
+    return new Response('Unsupported Media Type', { status: 415 });
+  }
+  return true;
+};
+
+/**
+ * Admits one envelope: exactly the keys a TypedRequest client sends, a management method, a request object and a
+ * request-phase correlation. It grants the request its own peer and nothing else: every upgrade method still
+ * authorises itself against the upgrade token it is handed, as it does over the controller socket.
+ */
+export const admitControllerManagementTypedRequest = (
+  requestArg: plugins.typedrequestInterfaces.ITypedRequest,
+  contextArg: plugins.smartserve.IRequestContext,
+): { trustedLocalData: { peer: IControllerManagementPeer } } | Response => {
+  const envelope: unknown = requestArg;
+  if (
+    typeof envelope !== 'object'
+    || envelope === null
+    || Array.isArray(envelope)
+    || !Object.keys(envelope).every((keyArg) => envelopeKeys.has(keyArg))
+  ) return new Response('Invalid request', { status: 400 });
+  const { method, request, correlation, requestInstanceId } = envelope as Record<string, unknown>;
+  if (
+    !controllerManagementMethods.some((methodArg) => methodArg === method)
+    || typeof request !== 'object'
+    || request === null
+    || Array.isArray(request)
+    || typeof correlation !== 'object'
+    || correlation === null
+    || (correlation as Record<string, unknown>).phase !== 'request'
+    || typeof (correlation as Record<string, unknown>).id !== 'string'
+    || typeof requestInstanceId !== 'string'
+    || requestInstanceId.length === 0
+  ) return new Response('Invalid request', { status: 400 });
+  return {
+    trustedLocalData: {
+      peer: {
+        id: `management:${plugins.crypto.randomUUID()}`,
+        context: { headers: contextArg.headers, state: {} },
+      },
+    },
+  };
+};
+
+/**
+ * The management endpoint as a surface of the controller's listener: it matches only the exact host and path, so
+ * every other request on the port keeps reaching the browser surface.
+ */
+export const createControllerManagementSurface = (optionsArg: {
+  port: number;
+  router: plugins.typedrequest.TypedRouter;
+}): plugins.typedserver.ITypedServerSurface => ({
+  name: 'controller-management',
+  match: { hostnames: ['127.0.0.1'], pathPrefixes: [controllerManagementTypedRequestPath] },
+  httpTypedRouter: optionsArg.router,
+  typedRequestPath: controllerManagementTypedRequestPath,
+  typedRequestMaxBodyBytes: controllerManagementRequestMaximumBodyBytes,
+  includeBuiltinTypedHandlers: false,
+  serveDir: null,
+  spaFallback: false,
+  healthzEndpoint: false,
+  cors: false,
+  noCache: true,
+  requestAdmission: (contextArg) => admitControllerManagementRequest(contextArg, optionsArg.port),
+  typedRequestAdmission: admitControllerManagementTypedRequest,
+  securityHeaders: {
+    xFrameOptions: 'DENY',
+    xContentTypeOptions: true,
+    referrerPolicy: 'no-referrer',
+    crossOriginOpenerPolicy: 'same-origin',
+    crossOriginResourcePolicy: 'same-origin',
+  },
+});

package/ts/functions.inferencecli.ts

@@ -19,12 +19,15 @@ type TAccountPlacementKey = 'lifecycle' | 'lapsesAt' | 'placementScore' | 'place
 
 /**
  * The status a running proxy answers with: one started from an AGL before 38.3.0 reports no accounts and no usage
- * observations, one before 38.4.0 no lifecycle, placement or placement journal, and one before confined runs neither
- * its confined listener nor its runs.
+ * observations, one before 38.4.0 no lifecycle, placement or placement journal, one before confined runs neither
+ * its confined listener nor its runs, and one before ChatGPT-pool confined runs no run's pool: its runs are all of the
+ * Claude pool.
  */
 export type TReportedProxyStatus = Omit<IAglProxyStatus, 'accounts' | 'usageObservations' | 'nextPlacement'
   | 'recentPlacements' | 'confinedSocketPath' | 'confinedRuns'>
-  & Partial<Pick<IAglProxyStatus, 'usageObservations' | 'nextPlacement' | 'recentPlacements' | 'confinedSocketPath' | 'confinedRuns'>>
+  & Partial<Pick<IAglProxyStatus, 'usageObservations' | 'nextPlacement' | 'recentPlacements' | 'confinedSocketPath'>>
+  & { confinedRuns?: Array<Omit<IAglProxyStatus['confinedRuns'][number], 'provider'>
+    & Partial<Pick<IAglProxyStatus['confinedRuns'][number], 'provider'>>> }
   & { accounts?: Array<Omit<IAglProxyStatus['accounts'][number], TAccountPlacementKey>
     & Partial<Pick<IAglProxyStatus['accounts'][number], TAccountPlacementKey>>> };
 
@@ -73,7 +76,8 @@ export const formatProxyStatus = (unitArg: string, statusArg: TReportedProxyStat
   if (statusArg.confinedSocketPath !== undefined) {
     lines.push(`Confined listener: ${statusArg.confinedSocketPath ?? 'none'}`);
     for (const run of statusArg.confinedRuns ?? []) {
-      lines.push(`Confined run ${run.id}: issued ${run.createdAt}`
+      // An older proxy names no run's pool: it issues Claude-pool runs alone.
+      lines.push(`Confined run ${run.id}: ${run.provider === 'openai' ? 'ChatGPT pool' : 'Claude pool'}, issued ${run.createdAt}`
         + `${run.held ? '' : ', waiting for its launcher to take it back after a proxy restart'}`
         + ` (end it with \`agl proxy confined end ${run.id}\`)`);
     }
@@ -213,13 +217,17 @@ const run = (optionsArg: IInferenceCliArguments): Promise<void> => withSignals(a
 const confinedRun = (optionsArg: IInferenceCliArguments): Promise<void> => withSignals(async (signalArg) => {
   await preflightAGLHomeMigration();
   const paths = resolveAGLHomePaths();
-  const run = await AglProxyConfinedHolder.take({ socketPath: paths.proxySocket }, AbortSignal.any([signalArg, AbortSignal.timeout(90_000)]));
+  const run = await AglProxyConfinedHolder.take({ socketPath: paths.proxySocket, provider: optionsArg.provider ?? 'anthropic' },
+    AbortSignal.any([signalArg, AbortSignal.timeout(90_000)]));
   let lost: AglProxyLeaseLostError | undefined;
   try {
     const launch = confinedDockerLaunch({ args: optionsArg.args, socketPath: run.confinedSocketPath, baseUrl: run.baseUrl,
-      token: run.token, environment: process.env });
+      token: run.token, environment: process.env,
+      pool: run.provider === 'anthropic' ? { provider: 'anthropic' } : { provider: 'openai', models: run.models } });
+    // A Claude-pool run says what it said before ChatGPT-pool runs; a ChatGPT-pool run says so.
     process.stderr.write(`AGL proxy confined run ${run.id}: ${plugins.path.dirname(run.confinedSocketPath)} is mounted read-only `
-      + `at ${aglProxyConfinedMountPoint}; end it at once with \`agl proxy confined end ${run.id}\`.\n`);
+      + `at ${aglProxyConfinedMountPoint}${run.provider === 'openai' ? ', served from the ChatGPT pool' : ''}; `
+      + `end it at once with \`agl proxy confined end ${run.id}\`.\n`);
     signalArg.throwIfAborted();
     const child = plugins.childProcess.spawn(launch.command, launch.args, { env: launch.environment, stdio: 'inherit', shell: false });
     let killTimer: ReturnType<typeof setTimeout> | undefined;

package/ts/functions.inferencecliarguments.ts

@@ -26,7 +26,7 @@ export const inferenceCliHelp = `Usage:
   agl proxy status [--json]
   agl proxy credential <client> [--provider openai|anthropic] [--delivery file|none] [--write <path>] [--rotate] | --version
   agl proxy run codex|claude|opencode [--provider openai|anthropic] [--account <id>] [--plan <name>] [--model <id>] -- [harness arguments]
-  agl proxy confined run -- docker run [docker options] <image> [command]
+  agl proxy confined run [--provider anthropic|openai] -- docker run [docker options] <image> [command]
   agl proxy confined end <run id>
 
 The proxy runs as the ${aglProxyUnitName} user unit (serve runs it in a terminal instead).
@@ -40,12 +40,15 @@ client starts on Claude accounts, every other client on ChatGPT accounts; --prov
 Run gives one child a private credential that ends when the child exits; run claude uses Claude accounts
 unless --provider openai asks for ChatGPT models behind Claude Code.
 confined run starts Claude Code's container on a credential of its own, accepted only on the proxy's confined
-listener: a Unix socket whose directory the run mounts read-only at ${aglProxyConfinedMountPoint}, served the Claude pool's
-three Claude Code endpoints alone. It adds the mount and Claude Code's settings (ANTHROPIC_UNIX_SOCKET, ANTHROPIC_BASE_URL,
-ANTHROPIC_AUTH_TOKEN) right after docker run, prints the run's id on standard error, and ends the credential when the
+listener: a Unix socket whose directory the run mounts read-only at ${aglProxyConfinedMountPoint}, served Claude Code's
+three endpoints of the run's pool alone: Claude accounts unless --provider openai asks for the ChatGPT pool, whose
+ChatGPT accounts answer it translated, as for run claude --provider openai. It adds the mount and Claude Code's settings
+(ANTHROPIC_UNIX_SOCKET, ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN, and on the ChatGPT pool the model variables run claude
+--provider openai sets) right after docker run, prints the run's id on standard error, and ends the credential when the
 container exits. The socket is the proxy user's (0600): run the container as that uid (--user), or as root under
 rootless Docker. Root of a rootful daemon connects as well while it keeps CAP_DAC_OVERRIDE (--cap-drop ALL takes it).
-confined end ends a run's credential at once, and its launcher stops the container; agl proxy status lists the runs.
+confined end ends a run's credential at once, and its launcher stops the container; agl proxy status lists the runs
+with their pools.
 Repeat --account or --plan to restrict automatic routing. Only accounts the account service holds are eligible.
 ChatGPT pools: /openai/v1/responses, /anthropic/v1/messages (translated), and each prefix's /models.
 Claude pools: /anthropic/v1/messages, /anthropic/v1/messages/count_tokens and /anthropic/v1/models, sent on as Claude Code sent them.
@@ -124,7 +127,14 @@ export const parseInferenceCliArguments = (argvArg: readonly string[]): IInferen
       result.confinedId = id;
       return result;
     }
-    if (action !== 'run' || argv.shift() !== '--' || !argv.length) throw new Error(inferenceCliHelp);
+    if (action !== 'run') throw new Error(inferenceCliHelp);
+    if (argv[0] === '--provider') {
+      argv.shift();
+      const value = argv.shift();
+      if (!inferenceProviders.includes(value as TInferenceProvider)) throw new Error('--provider is openai or anthropic.');
+      result.provider = value as TInferenceProvider;
+    }
+    if (argv.shift() !== '--' || !argv.length) throw new Error(inferenceCliHelp);
     result.confinedAction = 'run';
     result.args = argv;
     return result;

package/ts/functions.inferencelaunch.ts

@@ -37,10 +37,41 @@ const claudeNativeLaunch = (optionsArg: IInferenceLaunchOptions & { catalog: { p
 };
 
 /**
- * Claude Code on a ChatGPT pool: the proxy's Anthropic Messages endpoint answered by the pool's models, the default model
- * for every model alias, the context window the catalog states for it, and the pool's models as the whole `/model`
- * picker. Its configuration lives in its own directory, never the host's, so the host's `settings.json` cannot route it
- * elsewhere; it sends nothing beyond its model requests: no experimental betas, no nonessential traffic, no attribution.
+ * The variables that put Claude Code on a ChatGPT pool: the proxy's Anthropic Messages endpoint and credential, the
+ * pool's default model for every model alias, the context window the catalog states for it, and nothing beyond its model
+ * requests: no experimental betas, no nonessential traffic, no attribution. `agl proxy run claude --provider openai` and a
+ * ChatGPT-pool confined run give Claude Code these alike.
+ */
+export const claudeChatGptEnvironment = (inputArg: {
+  baseUrl: string;
+  token: string;
+  models: readonly TInferenceModel[];
+}): Record<string, string> => {
+  const model = inputArg.models.find((entryArg) => entryArg.isDefault) ?? inputArg.models[0];
+  if (!model) throw new Error('The ChatGPT pool offers no model Claude Code can run on.');
+  return {
+    ANTHROPIC_BASE_URL: inputArg.baseUrl,
+    ANTHROPIC_AUTH_TOKEN: inputArg.token,
+    ANTHROPIC_MODEL: model.modelId,
+    ANTHROPIC_DEFAULT_OPUS_MODEL: model.modelId,
+    ANTHROPIC_DEFAULT_SONNET_MODEL: model.modelId,
+    ANTHROPIC_DEFAULT_HAIKU_MODEL: model.modelId,
+    ...(model.contextWindow === undefined ? {} : { CLAUDE_CODE_MAX_CONTEXT_TOKENS: String(model.contextWindow) }),
+    CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: '1',
+    CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1',
+    CLAUDE_CODE_ATTRIBUTION_HEADER: '0',
+  };
+};
+
+/** Every variable `claudeChatGptEnvironment` may set, the context window's included. */
+const claudeChatGptVariables: readonly string[] = ['ANTHROPIC_BASE_URL', 'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_MODEL',
+  'ANTHROPIC_DEFAULT_OPUS_MODEL', 'ANTHROPIC_DEFAULT_SONNET_MODEL', 'ANTHROPIC_DEFAULT_HAIKU_MODEL',
+  'CLAUDE_CODE_MAX_CONTEXT_TOKENS', 'CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS', 'CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC',
+  'CLAUDE_CODE_ATTRIBUTION_HEADER'];
+
+/**
+ * Claude Code on a ChatGPT pool (`claudeChatGptEnvironment`), with the pool's models as the whole `/model` picker. Its
+ * configuration lives in its own directory, never the host's, so the host's `settings.json` cannot route it elsewhere.
  */
 export const claudeChatGptLaunch = (inputArg: {
   baseUrl: string;
@@ -48,21 +79,10 @@ export const claudeChatGptLaunch = (inputArg: {
   configDirectory: string;
   models: readonly TInferenceModel[];
 }): { environment: Record<string, string>; args: string[] } => {
-  const model = inputArg.models.find((entryArg) => entryArg.isDefault) ?? inputArg.models[0];
-  if (!model) throw new Error('The ChatGPT pool offers no model Claude Code can run on.');
   return {
     environment: {
       CLAUDE_CONFIG_DIR: inputArg.configDirectory,
-      ANTHROPIC_BASE_URL: inputArg.baseUrl,
-      ANTHROPIC_AUTH_TOKEN: inputArg.token,
-      ANTHROPIC_MODEL: model.modelId,
-      ANTHROPIC_DEFAULT_OPUS_MODEL: model.modelId,
-      ANTHROPIC_DEFAULT_SONNET_MODEL: model.modelId,
-      ANTHROPIC_DEFAULT_HAIKU_MODEL: model.modelId,
-      ...(model.contextWindow === undefined ? {} : { CLAUDE_CODE_MAX_CONTEXT_TOKENS: String(model.contextWindow) }),
-      CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: '1',
-      CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1',
-      CLAUDE_CODE_ATTRIBUTION_HEADER: '0',
+      ...claudeChatGptEnvironment(inputArg),
     },
     args: ['--settings', JSON.stringify({
       modelPicker: {
@@ -140,16 +160,23 @@ export const inferenceHarnessLaunch = (optionsArg: IInferenceLaunchOptions): { a
   return { environment, args: args[0] !== undefined && openCodeCommands.has(args[0]) ? args : [...selection, ...args] };
 };
 
+/** A confined run's pool, as its launcher configures Claude Code for it: a ChatGPT-pool run with the pool's models. */
+export type TConfinedLaunchPool = { provider: 'anthropic' } | { provider: 'openai'; models: readonly TInferenceModel[] };
+
 /**
  * A confined run's `docker run`: the given command, with the confined listener's directory mounted read-only at
  * `aglProxyConfinedMountPoint` and Claude Code's settings for it added right after `run`, before the launcher's own
  * options and image. Claude Code inside reaches the proxy through the socket alone (`ANTHROPIC_UNIX_SOCKET`, which
  * Claude Code sends its API requests through as plain HTTP to `ANTHROPIC_BASE_URL`'s path), on the run's credential
- * (`ANTHROPIC_AUTH_TOKEN`), reads the pool's models from the proxy and sends nothing beyond its model requests. The
- * container gets each variable by name from the docker command's environment, so the credential never appears on a
- * command line; that environment drops every variable that would give Claude Code another login or route, so `-e NAME`
- * of one of them passes nothing. The mount is the socket's own directory, which holds nothing else and survives a proxy
- * restart, unlike a mount of the socket file. Only `docker run` and `docker container run` are taken.
+ * (`ANTHROPIC_AUTH_TOKEN`), and sends nothing beyond its model requests. On the Claude pool it reads the pool's models
+ * from the proxy; on the ChatGPT pool it gets the variables `agl proxy run claude --provider openai` gives it
+ * (`claudeChatGptEnvironment`: the pool's default model for every alias, its context window), but neither that command's
+ * configuration directory, which lies in the AGL home, nor its `/model` picker, an option of the container's command
+ * that the launcher does not touch. The container gets each variable by name from the docker command's environment, so
+ * the credential never appears on a command line; that environment drops every variable that would give Claude Code
+ * another login or route, and on the ChatGPT pool every model variable it sets, so `-e NAME` of one of them passes
+ * nothing. The mount is the socket's own directory, which holds nothing else and survives a proxy restart, unlike a
+ * mount of the socket file. Only `docker run` and `docker container run` are taken.
  */
 export const confinedDockerLaunch = (optionsArg: {
   args: readonly string[];
@@ -159,6 +186,7 @@ export const confinedDockerLaunch = (optionsArg: {
   baseUrl: string;
   token: string;
   environment: NodeJS.ProcessEnv;
+  pool: TConfinedLaunchPool;
 }): { command: string; args: string[]; environment: NodeJS.ProcessEnv } => {
   const [command, ...args] = optionsArg.args;
   const runAt = args[0] === 'run' ? 1 : args[0] === 'container' && args[1] === 'run' ? 2 : 0;
@@ -168,13 +196,19 @@ export const confinedDockerLaunch = (optionsArg: {
   const directory = path.dirname(optionsArg.socketPath);
   // `--mount` separates its fields with commas and reads quotes; a directory naming either cannot be passed safely.
   if (/[,"'\n]/u.test(directory)) throw new Error(`The confined listener's directory ${directory} cannot be mounted: it holds a comma, quote or line break.`);
-  const variables: Record<string, string> = {
+  const socket = `${aglProxyConfinedMountPoint}/${path.basename(optionsArg.socketPath)}`;
+  const variables: Record<string, string> = optionsArg.pool.provider === 'anthropic' ? {
     ...claudeProxyEnvironment(optionsArg.baseUrl),
-    ANTHROPIC_UNIX_SOCKET: `${aglProxyConfinedMountPoint}/${path.basename(optionsArg.socketPath)}`,
+    ANTHROPIC_UNIX_SOCKET: socket,
     ANTHROPIC_AUTH_TOKEN: optionsArg.token,
+  } : {
+    ...claudeChatGptEnvironment({ baseUrl: `${optionsArg.baseUrl}/anthropic`, token: optionsArg.token,
+      models: optionsArg.pool.models }),
+    ANTHROPIC_UNIX_SOCKET: socket,
   };
   const environment = { ...optionsArg.environment };
   for (const name of claudeProxyReservedVariables) delete environment[name];
+  if (optionsArg.pool.provider === 'openai') for (const name of claudeChatGptVariables) delete environment[name];
   return {
     command,
     args: [...args.slice(0, runAt),

package/ts/interfaces.auth.ts

@@ -7,9 +7,10 @@ export type TControllerAuthLifecycleState = 'setupRequired' | 'ready';
 export type TWebAuthnCeremonyKind = 'setup' | 'authentication';
 export type TWebAuthnCeremonyState = 'pending' | 'consumed';
 /**
- * Single source of the audit event vocabulary: the persisted-document
+ * Single source of the audit types this release writes: the persisted-document
  * assertion consumes this list at runtime, so a type added here is
- * automatically storable — the two can no longer drift apart.
+ * automatically storable with its type-specific checks — the two can no longer
+ * drift apart. Other well-formed types are a later release's and still read.
  */
 export const controllerAuditEventTypes = [
   'controller.started',
@@ -249,11 +250,16 @@ export type TControllerAuditSessionId =
   | IControllerRuntimeId
   | plugins.browserRuntime.IBrowserClaudeSessionId;
 
+/**
+ * A stored audit event. The audit log is shared with later releases, so a stored `type` is any audit type, also one
+ * this release does not know (a later release's, read back after a rollback). This release writes only its own types
+ * (`IRecordAuditEventInput`).
+ */
 export interface IControllerAuditEvent {
   id: string;
   controllerId: string;
   timestamp: Date;
-  type: TControllerAuditEventType;
+  type: string;
   outcome: TControllerAuditOutcome;
   operationId?: string;
   peerId?: string;
@@ -263,6 +269,11 @@ export interface IControllerAuditEvent {
   /** The sender label an agent message declared (`session.message`). */
   senderLabel?: string;
   localCli?: IConfigurationLocalCliActor;
+  /**
+   * What a later release's type records beyond the envelope (bounded plain JSON). This release never writes or
+   * interprets it; it is declared so a rolled-back controller still reads and prunes such events.
+   */
+  details?: Record<string, unknown>;
 }
 
 export interface IControllerTempPasswordDocument {

package/ts_interfaces/index.ts

@@ -9,6 +9,7 @@ export * from './functions.browserpaintcopy.js';
 export * from './devtools.js';
 export * from './requests.js';
 export * from './mcprequests.js';
+export * from './management.js';
 export * from './codex.js';
 export * from './mcpworkspacerequests.js';
 export * from './mcpjobrequests.js';

package/ts_interfaces/interfaces.ts

@@ -325,6 +325,11 @@ export interface IControllerStatus {
   packageVersion: string;
   protocolVersion: typeof controllerProtocolVersion;
   upgradeManagementVersion: number;
+  /**
+   * The protocol of the controller's loopback management endpoint (`controllerManagementProtocolVersion`); absent
+   * from a controller older than the endpoint, which is reached over its socket.
+   */
+  managementProtocolVersion?: number;
   controllerPid: number;
   processGroupId: number;
   processFingerprint: string;

package/ts_interfaces/management.ts

@@ -0,0 +1,52 @@
+import type { IReq_ControllerStatus } from './requests.status.js';
+import type {
+  IReq_ControllerUpgradeFinalize,
+  IReq_ControllerUpgradeLaunch,
+  IReq_ControllerUpgradePrepareBegin,
+} from './requests.upgrade.js';
+
+/**
+ * The controller's loopback management endpoint, on the controller's own port: one TypedRequest envelope
+ * (`method`, `request`, `response`, `correlation`, `requestInstanceId`) per HTTP POST of `application/json`, with
+ * `Host: 127.0.0.1:<port>`. The local CLI and the upgrade worker read the status and drive an upgrade through it,
+ * so an upgrade worker of one release can finalize the controller of the next whatever transport the browser
+ * speaks. Every later release keeps this path, these methods, their request and response shapes and the envelope
+ * (`test/test.controllermanagementwire.node.ts` pins the bytes an AGL 41 client sends and what it accepts).
+ */
+export const controllerManagementTypedRequestPath = '/management/typedrequest' as const;
+
+/**
+ * The protocol of this loopback management endpoint: its path, methods, envelope and their request and response
+ * shapes. 1 is the endpoint as its first release ships it; only an incompatible change to that contract raises it.
+ * A release declares it twice: as `controllerManagementProtocolVersion` in its `package.json`, which a client reads
+ * before the release's controller runs, and as `managementProtocolVersion` in that controller's status. A client
+ * reaches a controller over this endpoint only when it declares 1 or more, and over the controller socket otherwise
+ * (an older release has no endpoint).
+ *
+ * It is not `controllerUpgradeManagementVersion` (2), the upgrade contract: every upgrade worker requires exactly
+ * that number in its target's `package.json` and status, and upgrade transactions record it, so it cannot move
+ * without breaking the online upgrade of every earlier release. This number says only how the management methods
+ * are reached.
+ */
+export const controllerManagementProtocolVersion = 1 as const;
+
+/** The methods the endpoint answers; every other method is refused before it is routed. */
+export const controllerManagementMethods = [
+  'controller.status',
+  'controller.upgrade.launch',
+  'controller.upgrade.prepare.begin',
+  'controller.upgrade.finalize',
+] as const;
+
+export type TControllerManagementMethod = typeof controllerManagementMethods[number];
+
+export type TControllerManagementTypedRequest =
+  | IReq_ControllerStatus
+  | IReq_ControllerUpgradeLaunch
+  | IReq_ControllerUpgradePrepareBegin
+  | IReq_ControllerUpgradeFinalize;
+
+/** A management request carries a token, a version and a mode at most. */
+export const controllerManagementRequestMaximumBodyBytes = 16 * 1024;
+/** The status document with every harness profile and upgrade blocker it may report. */
+export const controllerManagementResponseMaximumBytes = 1024 * 1024;

package/ts_web/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: 'agl',
-  version: '41.0.1',
+  version: '41.1.0',
   description: 'Agent Gateway Layer for OpenCode, FlexHarness, and Codex sessions'
 }