agl 40.5.1 → 41.0.0

package/ts/classes.inferencegateway.ts

@@ -13,6 +13,13 @@ import { inferenceAnthropicCheckedBytes, inferenceAnthropicServerToolTypes, infe
   inferenceAnthropicUnpricedRequest, inferenceOpenAiCheckedBytes, inferenceOpenAiSpend,
   inferenceOpenAiUnpricedRequest } from './classes.inferencespend.js';
 import { usageSessionPattern, type IInferenceTokenCounts, type IInferenceUsageLedger } from './classes.inferenceusage.js';
+import { claimProxySocketPath } from './functions.proxysocket.js';
+
+/**
+ * Where a credential is accepted: the loopback listener, which every process on the host can reach, or the confined
+ * listener, a Unix socket only the containers it is mounted into have. Each credential is accepted on its own route alone.
+ */
+export type TInferenceGatewayRoute = 'loopback' | 'confined';
 
 /**
  * Requests in flight: per session, so one runaway conversation cannot starve the others; per client credential,
@@ -57,6 +64,13 @@ export interface IInferenceGatewayOptions {
    * and translated Messages answers alike. It holds no prompt, answer or credential.
    */
   usageLedger: IInferenceUsageLedger;
+  /**
+   * The confined listener's Unix socket, bound beside the loopback port and made this user's alone (0600, in a private
+   * directory that holds nothing else). It accepts confined credentials alone and serves them the Claude pool's three
+   * endpoints Claude Code uses (`confinedEndpoints`), exactly as the loopback listener serves them; unset, the gateway has
+   * no confined listener and admits no confined credential.
+   */
+  confinedSocketPath?: string;
 }
 
 /** A placement the journal could not record, as the proxy reports it: no session id, prompt or account id. */
@@ -144,6 +158,11 @@ export interface IInferenceGatewayClientOptions {
    * sessions are its name's. Sessions are kept per pool (see `inferenceSessionKey`).
    */
   sessionScope?: string;
+  /**
+   * Where the credential is accepted; `loopback` when unset. A confined credential is a lease of the Claude pool, accepted
+   * on the confined listener alone.
+   */
+  route?: TInferenceGatewayRoute;
 }
 
 /** A credential the gateway admits, known to it by its digest alone. */
@@ -166,6 +185,8 @@ export interface IInferenceGatewayRestoredLease {
   digest: string;
   /** The lease's `sessionScope`; see `IInferenceGatewayClientOptions`. */
   sessionScope?: string;
+  /** The lease's `route`; see `IInferenceGatewayClientOptions`. */
+  route?: TInferenceGatewayRoute;
 }
 
 interface IClient {
@@ -176,6 +197,8 @@ interface IClient {
   name?: string;
   /** Whose sessions the client's session ids name; see `inferenceSessionKey`. */
   sessionScope: string;
+  /** The one listener the credential is accepted on. */
+  route: TInferenceGatewayRoute;
   lastUsedAt?: number;
   /** The Codex version this client last read its catalog for; its responses then report the current catalog tag. */
   codexClientVersion?: string;
@@ -209,6 +232,12 @@ const isCodexResponseHeader = (nameArg: string): boolean => nameArg.startsWith('
 const maximumErrorBodyBytes = 64 * 1024;
 const catalogTag = (modelsArg: unknown): string =>
   `"${plugins.crypto.createHash('sha256').update(JSON.stringify(modelsArg)).digest('base64url')}"`;
+/**
+ * What the confined listener serves, by method and path: the Claude pool's endpoints Claude Code uses. Every other
+ * method, path and pool is refused there before anything is read or routed.
+ */
+const confinedEndpoints: ReadonlySet<string> = new Set(['GET /anthropic/v1/models', 'POST /anthropic/v1/messages',
+  'POST /anthropic/v1/messages/count_tokens']);
 const turnStateLimit = 4096;
 const turnStateLifetimeMs = 60 * 60 * 1000;
 const clientVersionPattern = /^\d{1,6}\.\d{1,6}\.\d{1,6}(?:[-+][0-9A-Za-z.-]{1,32})?$/;
@@ -447,7 +476,19 @@ export const assertInferenceRoutingPolicy = (policyArg: IInferenceRoutingPolicy)
   }
 };
 
-/** Authenticated, loopback-only Responses and Messages endpoints with bounded, cancelable streaming. */
+/** A confined credential is a lease of the Claude pool, admitted only by a gateway with a confined listener. */
+const assertConfinedClient = (policyArg: IInferenceRoutingPolicy, nameArg: string | undefined,
+  socketPathArg: string | undefined): void => {
+  if (socketPathArg === undefined) throw new Error('The gateway has no confined listener.');
+  if (nameArg !== undefined || policyArg.provider !== 'anthropic') {
+    throw new Error('A confined credential is a lease of the Claude pool.');
+  }
+};
+
+/**
+ * Authenticated Responses and Messages endpoints with bounded, cancelable streaming, on a loopback listener and, for
+ * confined credentials, a Unix socket that serves the Claude pool alone.
+ */
 export class InferenceGateway {
   private readonly clients = new Set<IClient>();
   private readonly abort = new AbortController();
@@ -461,6 +502,7 @@ export class InferenceGateway {
   private inFlight = 0;
   private readonly limits: IInferenceGatewayLimits;
   private server?: plugins.http.Server;
+  private confinedServer?: plugins.http.Server;
   private host = '';
   private startTask?: Promise<void>;
   private stopTask?: Promise<void>;
@@ -507,7 +549,8 @@ export class InferenceGateway {
     }
     const token = clientArg.token ?? plugins.crypto.randomBytes(32).toString('base64url');
     if (Buffer.byteLength(token) < 32 || Buffer.byteLength(token) > 512) throw new Error('The gateway credential must have 32 to 512 bytes.');
-    const grant = await this.admit(policyArg, digest(token), clientArg.name ?? clientArg.sessionScope, clientArg.name);
+    const grant = await this.admit(policyArg, digest(token), clientArg.name ?? clientArg.sessionScope, clientArg.name,
+      clientArg.route ?? 'loopback');
     return { ...grant, token };
   }
 
@@ -521,24 +564,26 @@ export class InferenceGateway {
     if (leaseArg.sessionScope !== undefined && !clientNamePattern.test(leaseArg.sessionScope)) {
       throw new Error('A gateway client name is invalid.');
     }
-    return this.admit(policyArg, Buffer.from(leaseArg.digest, 'hex'), leaseArg.sessionScope, undefined);
+    return this.admit(policyArg, Buffer.from(leaseArg.digest, 'hex'), leaseArg.sessionScope, undefined, leaseArg.route ?? 'loopback');
   }
 
   private async admit(policyArg: IInferenceRoutingPolicy, digestArg: Buffer, scopeNameArg: string | undefined,
-    nameArg: string | undefined): Promise<IInferenceGatewayGrant> {
+    nameArg: string | undefined, routeArg: TInferenceGatewayRoute): Promise<IInferenceGatewayGrant> {
     assertInferenceRoutingPolicy(policyArg);
+    if (routeArg === 'confined') assertConfinedClient(policyArg, nameArg, this.options.confinedSocketPath);
     await (this.startTask ??= this.start());
     this.abort.signal.throwIfAborted();
     if (this.clients.size >= 128) throw new Error('The gateway has reached its client limit.');
     const client: IClient = { digest: digestArg, policy: structuredClone(policyArg), abort: new AbortController(), pending: 0,
       sessionScope: scopeNameArg === undefined ? `credential:${digestArg.toString('hex')}` : `client:${scopeNameArg}`,
-      ...(nameArg === undefined ? {} : { name: nameArg }) };
+      route: routeArg, ...(nameArg === undefined ? {} : { name: nameArg }) };
     if ([...this.clients].some((entry) => plugins.crypto.timingSafeEqual(entry.digest, client.digest))) {
       throw new Error('A gateway credential must name exactly one client.');
     }
     this.clients.add(client);
     return { baseUrl: `http://${this.host}`, digest: digestArg.toString('hex'), setPolicy: (nextArg) => {
       assertInferenceRoutingPolicy(nextArg);
+      if (routeArg === 'confined') assertConfinedClient(nextArg, nameArg, this.options.confinedSocketPath);
       client.policy = structuredClone(nextArg);
     }, close: () => {
       this.clients.delete(client);
@@ -554,27 +599,58 @@ export class InferenceGateway {
       this.turnStates.clear();
       this.sessionsInFlight.clear();
       await this.startTask?.catch(() => undefined);
-      if (this.server) await new Promise<void>((resolve) => {
-        this.server!.close(() => resolve());
-        this.server!.closeAllConnections();
-      });
+      for (const server of [this.server, this.confinedServer]) {
+        if (server) await new Promise<void>((resolve) => {
+          server.close(() => resolve());
+          server.closeAllConnections();
+        });
+      }
       await Promise.allSettled(this.pending);
       await Promise.allSettled(this.streams);
       await Promise.allSettled(this.placementWrites);
     })();
   }
 
+  /**
+   * Binds the loopback listener, then the confined one when the gateway has its socket. A stop that comes meanwhile
+   * closes whatever was bound.
+   */
   private async start(): Promise<void> {
+    const server = this.createServer('loopback');
+    this.server = server;
+    await new Promise<void>((resolve, reject) => {
+      server.once('error', reject);
+      server.listen(this.options.port ?? 0, '127.0.0.1', () => { server.off('error', reject); resolve(); });
+    });
+    const address = server.address();
+    if (!address || typeof address === 'string') throw new Error('The gateway did not acquire a loopback port.');
+    this.host = `127.0.0.1:${address.port}`;
+    const socketPath = this.options.confinedSocketPath;
+    if (socketPath === undefined) return;
+    this.abort.signal.throwIfAborted();
+    await claimProxySocketPath(socketPath, 'confined proxy socket', 'Another AGL proxy serves the confined proxy socket.');
+    this.abort.signal.throwIfAborted();
+    const confined = this.createServer('confined');
+    this.confinedServer = confined;
+    await new Promise<void>((resolve, reject) => {
+      confined.once('error', reject);
+      confined.listen(socketPath, () => { confined.off('error', reject); resolve(); });
+    });
+    // The directory is this user's alone already; the socket is too, so only processes of the proxy's user connect.
+    await plugins.fs.promises.chmod(socketPath, 0o600);
+  }
+
+  /** One listener: the loopback port or the confined socket, each with the same bounds and handling. */
+  private createServer(routeArg: TInferenceGatewayRoute): plugins.http.Server {
     const server = plugins.http.createServer({ maxHeaderSize: inferenceGatewayMaximumHeaderBytes },
       plugins.anthropicMessagesNode.createAnthropicMessagesNodeListener({
       handle: (requestArg) => {
-        const pending = this.handle(requestArg);
+        const pending = this.handle(requestArg, routeArg);
         this.pending.add(pending);
         void pending.finally(() => this.pending.delete(pending)).catch(() => undefined);
         return pending;
       },
     }));
-    this.server = server;
     const rejectedSockets = new WeakSet<plugins.stream.Duplex>();
     const activeSockets = new WeakMap<plugins.stream.Duplex, Set<plugins.http.ServerResponse>>();
     server.on('request', (requestArg, responseArg) => {
@@ -604,17 +680,16 @@ export class InferenceGateway {
     server.requestTimeout = 60_000;
     // Idle keep-alive connections of every client count here as well as requests in flight.
     server.maxConnections = this.limits.total * 2;
-    await new Promise<void>((resolve, reject) => {
-      server.once('error', reject);
-      server.listen(this.options.port ?? 0, '127.0.0.1', () => { server.off('error', reject); resolve(); });
-    });
-    const address = server.address();
-    if (!address || typeof address === 'string') throw new Error('The gateway did not acquire a loopback port.');
-    this.host = `127.0.0.1:${address.port}`;
+    return server;
   }
 
-  private authenticate(requestArg: Request): IClient {
-    if (requestArg.headers.get('host') !== this.host || requestArg.headers.has('origin')) {
+  /**
+   * The client a request's credential names, among those accepted on the listener it came in on. A loopback request must
+   * name the listener's exact host; on the confined socket the host is irrelevant, nothing but a mounted container
+   * reaches it. Neither takes a browser's request. A credential of the other listener is refused like an unknown one.
+   */
+  private authenticate(requestArg: Request, routeArg: TInferenceGatewayRoute): IClient {
+    if ((routeArg === 'loopback' && requestArg.headers.get('host') !== this.host) || requestArg.headers.has('origin')) {
       throw new InferenceRoutingError(403, 'forbidden', 'The inference gateway accepts local harness requests only.');
     }
     const authorization = requestArg.headers.get('authorization');
@@ -622,13 +697,13 @@ export class InferenceGateway {
     const presented = token && token.length <= 512 ? digest(token) : undefined;
     let client: IClient | undefined;
     if (presented) for (const candidate of this.clients) {
-      if (plugins.crypto.timingSafeEqual(candidate.digest, presented)) client = candidate;
+      if (plugins.crypto.timingSafeEqual(candidate.digest, presented) && candidate.route === routeArg) client = candidate;
     }
     if (!client) throw new InferenceRoutingError(401, 'authentication_error', 'The gateway credential is invalid or expired.');
     return client;
   }
 
-  private async handle(requestArg: Request): Promise<Response> {
+  private async handle(requestArg: Request, routeArg: TInferenceGatewayRoute): Promise<Response> {
     let client: IClient | undefined;
     let transferred = false;
     let admittedRequest = false;
@@ -636,7 +711,13 @@ export class InferenceGateway {
     let releaseRoute: (() => void) | undefined;
     let protocol: TProtocol | undefined;
     try {
-      client = this.authenticate(requestArg);
+      if (routeArg === 'confined') protocol = 'claude';
+      client = this.authenticate(requestArg, routeArg);
+      if (routeArg === 'confined' && (client.policy.provider !== 'anthropic'
+        || !confinedEndpoints.has(`${requestArg.method} ${new URL(requestArg.url).pathname}`))) {
+        throw new InferenceRoutingError(404, 'not_found', 'The confined listener serves the Claude pool\'s '
+          + 'GET /anthropic/v1/models, POST /anthropic/v1/messages and POST /anthropic/v1/messages/count_tokens alone.');
+      }
       if (this.inFlight >= this.limits.total) throw new InferenceRoutingError(429, 'concurrency_limit', 'The gateway has too many requests in flight.', 1);
       if (client.pending >= this.limits.perClient) throw new InferenceRoutingError(429, 'concurrency_limit', 'This gateway client has too many requests.', 1);
       client.pending += 1;

package/ts/classes.inferenceservice.ts

@@ -34,6 +34,8 @@ export interface IInferenceServiceOptions {
   spendStore: IInferenceSpendStore;
   providerFetch?: typeof fetch;
   limits?: IInferenceGatewayLimits;
+  /** The confined listener's socket (see `IInferenceGatewayOptions.confinedSocketPath`); none when unset. */
+  confinedSocketPath?: string;
 }
 
 /** How many of the latest placements the status shows. */
@@ -135,7 +137,8 @@ export class InferenceService {
     });
     this.gateway = new InferenceGateway({ router: this.router, signatureKey: options.signatureKey,
       affinity: options.affinity, placements: options.placements, usageLedger: options.usageLedger, port: options.port,
-      ...(options.limits ? { limits: options.limits } : {}) });
+      ...(options.limits ? { limits: options.limits } : {}),
+      ...(options.confinedSocketPath === undefined ? {} : { confinedSocketPath: options.confinedSocketPath }) });
   }
 
   /**
@@ -156,8 +159,8 @@ export class InferenceService {
   }
 
   /**
-   * Takes the port, then reclaims the bindings an earlier run of this installation left: acquiring the port
-   * comes before authority reads, cleanup or bindings, so a second process cannot fence this one.
+   * Takes the port and the confined socket, then reclaims the bindings an earlier run of this installation left:
+   * acquiring the port comes before authority reads, cleanup or bindings, so a second process cannot fence this one.
    */
   public async start(signalArg?: AbortSignal): Promise<string> {
     if (this.started || this.stopTask) throw new Error('The gateway service cannot be started twice.');

package/ts/classes.proxycontrol.ts

@@ -6,6 +6,7 @@ import { isInferenceUsageRequest, type IInferenceUsageChangesRequest, type IInfe
 import type { IInferenceAccountStatus, IInferenceRoutingPolicy, TInferenceClaudeModel,
   TInferenceModel } from './classes.inferencerouter.js';
 import {
+  aglProxyConfinedIdPattern,
   inferenceCredentials,
   inferenceProviders,
   proxyClientNamePattern,
@@ -16,6 +17,7 @@ import {
 } from './functions.proxycontract.js';
 import { isAuthorityAccountId } from '../ts_interfaces/functions.authorityscope.js';
 import { proxyControlMaximumFrameBytes, readProxyControlLine } from './classes.proxycontrolclient.js';
+import { claimProxySocketPath } from './functions.proxysocket.js';
 
 type ITypedRequest = plugins.typedrequestInterfaces.ITypedRequest;
 
@@ -60,6 +62,19 @@ export interface IAglProxyStatus {
   nextPlacement: Record<TInferenceProvider, string | null>;
   /** The latest sessions placed or moved, newest first, with why (at most 20). */
   recentPlacements: IInferencePlacementStatus[];
+  /** The confined listener's socket, or `null` for a proxy without one. */
+  confinedSocketPath: string | null;
+  /** The confined runs whose credential the proxy serves, oldest first. */
+  confinedRuns: IAglProxyConfinedRunStatus[];
+}
+
+/** A confined run whose credential the proxy serves (see `IReq_AglProxyConfined`). */
+export interface IAglProxyConfinedRunStatus {
+  /** The run's id: the first 12 hex characters of its credential's SHA-256 digest, never the credential. */
+  id: string;
+  createdAt: string;
+  /** False while a restarted proxy serves the credential for its reclaim window, waiting for its holder to take it back. */
+  held: boolean;
 }
 
 /**
@@ -119,13 +134,48 @@ export interface IReq_AglProxyLease extends ITypedRequest {
 /**
  * Takes back a lease a restarted proxy kept, by its credential: the lease then lives as long as this connection, with
  * the policy and sessions it was issued with. A credential the proxy does not keep unclaimed is refused alike, whether
- * it is unknown, expired or still held.
+ * it is unknown, expired or still held. A confined run's credential is taken back the same way.
  */
 export interface IReq_AglProxyReclaim extends ITypedRequest {
   method: 'agl.proxy.reclaim';
   request: { token: string };
-  /** Where the lease is served now; a holder whose child was configured with another address cannot continue. */
-  response: { baseUrl: string };
+  /**
+   * Where the lease is served now; a holder whose child was configured with another address cannot continue. A confined
+   * run's credential answers its confined grant's `baseUrl` and `socketPath`.
+   */
+  response: { baseUrl: string; socketPath?: string };
+}
+
+/**
+ * A confined run's credential: accepted on the confined listener alone, never on the loopback one, and served there from
+ * the Claude pool exactly as the loopback listener serves a Claude client, its sessions those of the client
+ * `aglProxyConfinedClient`. Like a lease it lives as long as the connection that asked for it, a restarted proxy keeps it
+ * for its holder to take back (`agl.proxy.reclaim`), and the proxy keeps only its digest. `agl.proxy.confined.end` ends it
+ * at once.
+ */
+export interface IReq_AglProxyConfined extends ITypedRequest {
+  method: 'agl.proxy.confined';
+  request: Record<string, never>;
+  response: IAglProxyConfinedGrant;
+}
+
+/** What a confined run is given: its id, its credential, the confined listener's socket and the origin to name with it. */
+export interface IAglProxyConfinedGrant {
+  /** See `IAglProxyConfinedRunStatus.id`. */
+  id: string;
+  token: string;
+  socketPath: string;
+  baseUrl: string;
+}
+
+/**
+ * Ends a confined run's credential at once, by the run's id: the proxy refuses it from then on, forgets it, and closes
+ * its holder's connection, telling the holder why.
+ */
+export interface IReq_AglProxyConfinedEnd extends ITypedRequest {
+  method: 'agl.proxy.confined.end';
+  request: { id: string };
+  response: { id: string };
 }
 
 /**
@@ -144,6 +194,11 @@ export interface IAglProxyConnection {
   onClose(listenerArg: () => void): void;
   /** Aborts when the connection closes, so work for a client that went away stops. */
   readonly signal: AbortSignal;
+  /**
+   * Closes a lease's connection from the proxy's side, after one last line that tells its holder why the proxy ended the
+   * lease (`{"ended": reasonArg}`), so the holder reports that instead of taking the lease back.
+   */
+  end(reasonArg: string): void;
 }
 
 export interface IAglProxyControlHandlers {
@@ -152,11 +207,13 @@ export interface IAglProxyControlHandlers {
   catalog(requestArg: IReq_AglProxyCatalog['request'], connectionArg: IAglProxyConnection): Promise<IReq_AglProxyCatalog['response']>;
   lease(requestArg: IReq_AglProxyLease['request'], connectionArg: IAglProxyConnection): Promise<IReq_AglProxyLease['response']>;
   reclaim(requestArg: IReq_AglProxyReclaim['request'], connectionArg: IAglProxyConnection): Promise<IReq_AglProxyReclaim['response']>;
+  confined(connectionArg: IAglProxyConnection): Promise<IReq_AglProxyConfined['response']>;
+  confinedEnd(requestArg: IReq_AglProxyConfinedEnd['request']): Promise<IReq_AglProxyConfinedEnd['response']>;
   usage(requestArg: IReq_AglProxyUsage['request'], connectionArg: IAglProxyConnection): Promise<IReq_AglProxyUsage['response']>;
 }
 
 /** The requests whose answered connection stays open: it holds the lease the request was answered with. */
-const leaseHoldingMethods: ReadonlySet<string> = new Set(['agl.proxy.lease', 'agl.proxy.reclaim']);
+const leaseHoldingMethods: ReadonlySet<string> = new Set(['agl.proxy.lease', 'agl.proxy.reclaim', 'agl.proxy.confined']);
 /** A lease credential the proxy issues is 43 characters; one it was given for a named client at most 512 bytes. */
 const maximumReclaimTokenLength = 512;
 
@@ -245,6 +302,17 @@ export class AglProxyControlServer {
       }
       return this.handlers!.reclaim(requestArg, connectionArg);
     }));
+    this.router.addTypedHandler(handler<IReq_AglProxyConfined>('agl.proxy.confined', (requestArg, connectionArg) => {
+      if (!isRecord(requestArg) || Object.keys(requestArg).length !== 0) throw new AglProxyControlRefusal('Invalid proxy confined request.');
+      return this.handlers!.confined(connectionArg);
+    }));
+    this.router.addTypedHandler(handler<IReq_AglProxyConfinedEnd>('agl.proxy.confined.end', (requestArg) => {
+      if (!isRecord(requestArg) || typeof requestArg.id !== 'string' || !aglProxyConfinedIdPattern.test(requestArg.id)
+        || Object.keys(requestArg).length !== 1) {
+        throw new AglProxyControlRefusal('Invalid proxy confined end request.');
+      }
+      return this.handlers!.confinedEnd(requestArg);
+    }));
     this.router.addTypedHandler(handler<IReq_AglProxyUsage>('agl.proxy.usage', (requestArg, connectionArg) => {
       if (!isInferenceUsageRequest(requestArg)) throw new AglProxyControlRefusal('Invalid proxy usage request.');
       return this.handlers!.usage(requestArg, connectionArg);
@@ -258,14 +326,7 @@ export class AglProxyControlServer {
   }
 
   private async listenOnce(): Promise<void> {
-    const directory = plugins.path.dirname(this.socketPath);
-    await plugins.fs.promises.mkdir(directory, { recursive: true, mode: 0o700 });
-    const stat = await plugins.fs.promises.lstat(directory);
-    if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== process.getuid?.()) {
-      throw new Error('The proxy socket directory is not private.');
-    }
-    await plugins.fs.promises.chmod(directory, 0o700);
-    await this.clearStaleSocket();
+    await claimProxySocketPath(this.socketPath, 'proxy socket', 'Another AGL proxy is already running for this AGL home.');
     const server = plugins.net.createServer((socketArg) => this.accept(socketArg));
     await new Promise<void>((resolve, reject) => {
       server.once('error', reject);
@@ -305,33 +366,6 @@ export class AglProxyControlServer {
     if (server) await new Promise<void>((resolve) => server.close(() => resolve()));
   }
 
-  /** A pathname a killed proxy left: removed only while it is an unchanged, owned socket nobody answers on. */
-  private async clearStaleSocket(): Promise<void> {
-    let before: plugins.fs.Stats;
-    try { before = await plugins.fs.promises.lstat(this.socketPath); }
-    catch (errorArg) {
-      if ((errorArg as NodeJS.ErrnoException).code === 'ENOENT') return;
-      throw errorArg;
-    }
-    if (!before.isSocket() || before.uid !== process.getuid?.()) throw new Error('The proxy socket path is unsafe.');
-    const refused = await new Promise<boolean>((resolve, reject) => {
-      const probe = plugins.net.createConnection(this.socketPath);
-      probe.setTimeout(1_000, () => { probe.destroy(); reject(new Error('The proxy socket probe timed out.')); });
-      probe.once('connect', () => { probe.destroy(); resolve(false); });
-      probe.once('error', (errorArg) => {
-        probe.destroy();
-        if ((errorArg as NodeJS.ErrnoException).code === 'ECONNREFUSED') resolve(true);
-        else reject(errorArg);
-      });
-    });
-    if (!refused) throw new Error('Another AGL proxy is already running for this AGL home.');
-    const after = await plugins.fs.promises.lstat(this.socketPath);
-    if (!after.isSocket() || after.dev !== before.dev || after.ino !== before.ino) {
-      throw new Error('The proxy socket path changed during startup.');
-    }
-    await plugins.fs.promises.unlink(this.socketPath);
-  }
-
   private accept(socketArg: plugins.net.Socket): void {
     this.sockets.add(socketArg);
     const closeListeners: Array<() => void> = [];
@@ -348,6 +382,9 @@ export class AglProxyControlServer {
     });
     const connection: IAglProxyConnection = { signal: abort.signal, onClose: (listenerArg) => {
       if (socketArg.destroyed) listenerArg(); else closeListeners.push(listenerArg);
+    }, end: (reasonArg) => {
+      if (!socketArg.writable) { socketArg.destroy(); return; }
+      socketArg.end(JSON.stringify({ ended: reasonArg }) + '\n', () => socketArg.destroy());
     } };
     const chunks: Buffer[] = [];
     let bytes = 0;

package/ts/classes.proxycontrolclient.ts

@@ -5,6 +5,8 @@ import type {
   IAglProxyRefusalData,
   IAglProxyStatus,
   IReq_AglProxyCatalog,
+  IReq_AglProxyConfined,
+  IReq_AglProxyConfinedEnd,
   IReq_AglProxyCredential,
   IReq_AglProxyLease,
   IReq_AglProxyReclaim,
@@ -21,14 +23,17 @@ import type { TInferenceCredential, TInferenceProvider, TProxyCredentialDelivery
  * runs for its credential (`agl proxy credential <client>`) starts without loading the rest of AGL.
  *
  * The socket speaks one typed request per connection, one JSON line each way: the request as `TypedRequest` sends it
- * (`method`, `request`, `correlation`), and the router's answer with `response` or `error`. A lease and a reclaim keep
- * their connection; every other request closes it.
+ * (`method`, `request`, `correlation`), and the router's answer with `response` or `error`. A lease, a reclaim and a
+ * confined run keep their connection; every other request closes it.
  */
 
-/** The connection a lease lives as long as: closing it ends the lease, and `closed` settles once it is gone. */
+/**
+ * The connection a lease lives as long as: closing it ends the lease, and `closed` settles once it is gone, with the
+ * proxy's reason when the proxy ended the lease itself (a confined run the operator ended), `undefined` otherwise.
+ */
 export interface IAglProxyLeaseConnection {
   close: () => void;
-  closed: Promise<void>;
+  closed: Promise<string | undefined>;
 }
 
 /** One request per connection, as one JSON line each way; at most this many bytes. */
@@ -70,24 +75,28 @@ interface IWireAnswer {
   error?: { text?: unknown; data?: unknown } | null;
 }
 
-/** Sends one typed request on its own connection; `keepArg` receives the connection of an answered lease. */
+/**
+ * Sends one typed request on its own connection; `keepArg` receives the connection of an answered lease, with what the
+ * proxy sent after its answer.
+ */
 const exchange = <TResponse>(socketPathArg: string, methodArg: string, requestArg: unknown, signalArg: AbortSignal,
-  keepArg?: (socketArg: net.Socket) => void): Promise<TResponse> => new Promise((resolve, reject) => {
+  keepArg?: (socketArg: net.Socket, restArg: Buffer) => void): Promise<TResponse> => new Promise((resolve, reject) => {
   const signal = AbortSignal.any([signalArg, AbortSignal.timeout(requestTimeoutMs)]);
   if (signal.aborted) { reject(signal.reason); return; }
   const socket = net.createConnection(socketPathArg);
   const chunks: Buffer[] = [];
   let bytes = 0;
   let settled = false;
-  const finish = (errorArg?: unknown, answerArg?: IWireAnswer): void => {
+  const finish = (errorArg?: unknown, answerArg?: IWireAnswer, restArg = Buffer.alloc(0)): void => {
     if (settled) return;
     settled = true;
     signal.removeEventListener('abort', abort);
+    socket.off('data', read);
     const failure = errorArg ?? (answerArg?.method !== methodArg
       ? new Error('The proxy answered another request.')
       : answerArg.error ? new AglProxyRefusedError(typeof answerArg.error.text === 'string' ? answerArg.error.text : 'The proxy refused.',
         answerArg.error.data) : undefined);
-    if (!failure && keepArg) keepArg(socket);
+    if (!failure && keepArg) keepArg(socket, restArg);
     else socket.destroy();
     if (failure) reject(failure);
     else resolve(answerArg!.response as TResponse);
@@ -100,18 +109,24 @@ const exchange = <TResponse>(socketPathArg: string, methodArg: string, requestAr
     method: methodArg, request: requestArg, response: null, requestInstanceId: crypto.randomUUID(),
     correlation: { id: crypto.randomUUID(), phase: 'request' },
   }) + '\n'));
-  socket.on('data', (chunkArg: Buffer) => {
+  function read(chunkArg: Buffer): void {
     bytes += chunkArg.length;
     if (bytes > proxyControlMaximumFrameBytes) { finish(new Error('The proxy response is too large.')); return; }
     chunks.push(chunkArg);
+    // A kept connection may carry the proxy's notice right behind the answer; any other answer is the frame's one line.
+    const frame = Buffer.concat(chunks, bytes);
+    const end = frame.indexOf(0x0a);
+    const rest = end < 0 ? Buffer.alloc(0) : frame.subarray(end + 1);
     let line: string | null;
-    try { line = readProxyControlLine(chunks, bytes); } catch (errorArg) { finish(errorArg); return; }
+    try { line = readProxyControlLine([keepArg ? frame.subarray(0, end + 1) : frame], keepArg ? end + 1 : bytes); }
+    catch (errorArg) { finish(errorArg); return; }
     if (line === null) return;
     let answer: unknown;
     try { answer = JSON.parse(line); } catch { finish(new Error('The proxy response could not be decoded.')); return; }
     if (!answer || typeof answer !== 'object' || Array.isArray(answer)) { finish(new Error('The proxy response could not be decoded.')); return; }
-    finish(undefined, answer as IWireAnswer);
-  });
+    finish(undefined, answer as IWireAnswer, rest);
+  }
+  socket.on('data', read);
   // Nobody listening is a proxy that is not running; a connection that fails once open is a proxy that broke off.
   socket.on('error', () => finish(connected ? new Error('The proxy closed the connection before answering.') : new AglProxyUnavailableError()));
   socket.on('close', () => finish(new Error('The proxy closed the connection before answering.')));
@@ -157,9 +172,9 @@ export class AglProxyControlClient {
    */
   public async lease(policyArg: IInferenceRoutingPolicy, clientArg: string,
     signalArg: AbortSignal): Promise<IReq_AglProxyLease['response'] & IAglProxyLeaseConnection> {
-    let held: net.Socket | undefined;
+    let held: { socket: net.Socket; rest: Buffer } | undefined;
     const response = await exchange<IReq_AglProxyLease['response']>(this.socketPath, 'agl.proxy.lease', { policy: policyArg, client: clientArg },
-      signalArg, (socketArg) => { held = socketArg; });
+      signalArg, (socketArg, restArg) => { held = { socket: socketArg, rest: restArg }; });
     return { ...response, ...leaseConnection(held) };
   }
 
@@ -168,17 +183,54 @@ export class AglProxyControlClient {
    * connection. A refusal (`AglProxyRefusedError`) means the proxy no longer keeps it.
    */
   public async reclaim(tokenArg: string, signalArg: AbortSignal): Promise<IReq_AglProxyReclaim['response'] & IAglProxyLeaseConnection> {
-    let held: net.Socket | undefined;
+    let held: { socket: net.Socket; rest: Buffer } | undefined;
     const response = await exchange<IReq_AglProxyReclaim['response']>(this.socketPath, 'agl.proxy.reclaim', { token: tokenArg },
-      signalArg, (socketArg) => { held = socketArg; });
+      signalArg, (socketArg, restArg) => { held = { socket: socketArg, rest: restArg }; });
     return { ...response, ...leaseConnection(held) };
   }
+
+  /**
+   * A confined run's credential, the confined listener's socket and the origin to name with it; the credential lives as
+   * long as the returned connection (see `IReq_AglProxyConfined`).
+   */
+  public async confined(signalArg: AbortSignal): Promise<IReq_AglProxyConfined['response'] & IAglProxyLeaseConnection> {
+    let held: { socket: net.Socket; rest: Buffer } | undefined;
+    const response = await exchange<IReq_AglProxyConfined['response']>(this.socketPath, 'agl.proxy.confined', {},
+      signalArg, (socketArg, restArg) => { held = { socket: socketArg, rest: restArg }; });
+    return { ...response, ...leaseConnection(held) };
+  }
+
+  /** Ends the confined run `idArg` names at once; a refusal (`AglProxyRefusedError`) means the proxy serves no such run. */
+  public async endConfined(idArg: string, signalArg: AbortSignal): Promise<IReq_AglProxyConfinedEnd['response']> {
+    return exchange<IReq_AglProxyConfinedEnd['response']>(this.socketPath, 'agl.proxy.confined.end', { id: idArg }, signalArg);
+  }
 }
 
-const leaseConnection = (socketArg: net.Socket | undefined): IAglProxyLeaseConnection => {
-  if (!socketArg) throw new Error('The proxy lease connection was not kept.');
-  const socket = socketArg;
+/**
+ * A kept connection: after its answer the proxy sends at most one line, `{"ended": reason}`, when it ends the lease
+ * itself, and closes the connection; `closed` then settles with that reason.
+ */
+const leaseConnection = (heldArg: { socket: net.Socket; rest: Buffer } | undefined): IAglProxyLeaseConnection => {
+  if (!heldArg) throw new Error('The proxy lease connection was not kept.');
+  const socket = heldArg.socket;
+  let pending = heldArg.rest;
+  let ended: string | undefined;
+  const read = (chunkArg: Buffer): void => {
+    pending = Buffer.concat([pending, chunkArg]);
+    if (pending.length > proxyControlMaximumFrameBytes) { socket.destroy(); return; }
+    const end = pending.indexOf(0x0a);
+    if (end < 0) return;
+    try {
+      const notice: unknown = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(pending.subarray(0, end)));
+      if (notice && typeof notice === 'object' && 'ended' in notice && typeof notice.ended === 'string') ended = notice.ended;
+    } catch { /* Not a notice: the connection ends all the same, without a reason. */ }
+    socket.destroy();
+  };
   socket.on('error', () => socket.destroy());
-  const closed = new Promise<void>((resolve) => { if (socket.destroyed) resolve(); else socket.once('close', () => resolve()); });
+  socket.on('data', read);
+  if (pending.length) read(Buffer.alloc(0));
+  const closed = new Promise<string | undefined>((resolve) => {
+    if (socket.destroyed) resolve(ended); else socket.once('close', () => resolve(ended));
+  });
   return { close: () => socket.destroy(), closed };
 };