agentfootprint 7.20.0 → 7.22.0

package/dist/esm/hosting/httpHost.js

@@ -25,6 +25,15 @@
  * `HostRequest` and `HostReply` say exactly what they said before. The gap was
  * in the first adapter, which had no seam, not in the port, which needed none.
  *
+ * ── The second thing a deployment gets to re-decide: who owns the socket ─────
+ * By default this file creates a server and listens on it. Pass `server` and it
+ * attaches to yours instead — because a container is sometimes given exactly
+ * one port, and an agent that privately owns the socket cannot share it with a
+ * WebSocket upgrade or with routes that were there first. Attached, the host
+ * answers its two paths, writes nothing on anyone else's, and `close()`
+ * detaches and drains without closing a socket it never opened. That is the
+ * whole difference; every other law on this page is the same either way.
+ *
  * Pattern: Template method via configuration (Strategy on the wire format).
  * Everything HTTP lives here and in the wires; `types.ts` knows none of it.
  */
@@ -64,6 +73,17 @@ const DEFAULT_CAPABILITIES = ['streaming'];
  */
 export function httpHost(options) {
     const { name, wire, invokePath, healthPath } = options;
+    const ownServer = options.server;
+    // Refused at construction, not ignored at serve time: a `port` next to a
+    // server this host does not bind is a caller who believes something untrue
+    // about where their agent will answer, and silently dropping it is how they
+    // stay believing it.
+    if (ownServer && (options.port !== undefined || options.hostname !== undefined)) {
+        throw new Error(`[hosting] httpHost('${name}') was given both a caller-owned 'server' and a ` +
+            `'${options.port !== undefined ? 'port' : 'hostname'}'. A server you own already has ` +
+            `an address, and this host binds nothing when you pass one. Drop the port/hostname, ` +
+            `or drop the server and let this host bind its own socket.`);
+    }
     const port = options.port ?? 8080;
     const hostname = options.hostname ?? '0.0.0.0';
     const capabilities = options.capabilities ?? DEFAULT_CAPABILITIES;
@@ -71,18 +91,26 @@ export function httpHost(options) {
         name,
         capabilities,
         async serve(handler) {
-            const { createServer } = await import('node:http');
             const startedAt = Date.now();
             const inFlight = new Set();
             let accepting = true;
             let closing;
-            const server = createServer((req, res) => {
+            const onRequest = (req, res) => {
+                // On a shared server an earlier listener may already have answered.
+                // Writing again would corrupt its reply; there is nothing to add.
+                if (res.headersSent)
+                    return;
                 const path = (req.url ?? '').split('?')[0];
                 if (req.method === 'GET' && path === healthPath) {
                     sendJson(res, 200, wire.health(Date.now() - startedAt));
                     return;
                 }
                 if (req.method !== 'POST' || path !== invokePath) {
+                    // On a server we own, an unmatched path is nobody else's, so saying
+                    // so is the honest answer. On a server the CALLER owns it is theirs,
+                    // and a 404 from us would answer for their application.
+                    if (ownServer)
+                        return;
                     sendJson(res, 404, wire.failure(`no route for ${req.method ?? '?'} ${path}`));
                     return;
                 }
@@ -94,14 +122,40 @@ export function httpHost(options) {
                 const served = serveOne(req, res, handler, wire);
                 inFlight.add(served);
                 void served.finally(() => inFlight.delete(served));
-            });
-            await new Promise((resolve, reject) => {
-                server.once('error', reject);
-                server.listen(port, hostname, resolve);
-            });
+            };
+            let server;
+            if (ownServer) {
+                server = ownServer;
+                if (!server.listening) {
+                    throw new Error(`[hosting] httpHost('${name}') was handed a server that is not listening yet. ` +
+                        `This handle promises the url and port it is answering on, and a server with ` +
+                        `no address has neither. Call server.listen(...) first, then serve() — ` +
+                        `attaching after listen() is safe and is the intended order.`);
+                }
+                server.on('request', onRequest);
+            }
+            else {
+                const { createServer } = await import('node:http');
+                server = createServer(onRequest);
+                await new Promise((resolve, reject) => {
+                    server.once('error', reject);
+                    server.listen(port, hostname, resolve);
+                });
+            }
             const address = server.address();
-            const boundPort = typeof address === 'object' && address ? address.port : port;
-            const displayHost = hostname === '0.0.0.0' || hostname === '::' ? '127.0.0.1' : hostname;
+            const tcp = typeof address === 'object' && address !== null ? address : undefined;
+            if (ownServer && !tcp) {
+                server.off('request', onRequest);
+                throw new Error(`[hosting] httpHost('${name}') was handed a server bound to ${JSON.stringify(address)}` +
+                    ` — a pipe or socket path, which has no port. This handle promises a url and a ` +
+                    `port, and inventing one would be worse than refusing. Serve on a TCP server, or ` +
+                    `drive the handler yourself.`);
+            }
+            const boundPort = tcp ? tcp.port : port;
+            // With our own socket the requested hostname IS the answer; with the
+            // caller's we ask the socket, because we never chose it.
+            const boundHost = ownServer ? tcp?.address ?? '127.0.0.1' : hostname;
+            const displayHost = boundHost === '0.0.0.0' || boundHost === '::' ? '127.0.0.1' : boundHost;
             return {
                 url: `http://${displayHost}:${boundPort}`,
                 port: boundPort,
@@ -109,6 +163,16 @@ export function httpHost(options) {
                     // Idempotent: the first call owns the shutdown, later ones await it.
                     closing ??= (async () => {
                         accepting = false;
+                        if (ownServer) {
+                            // Detach FIRST. The paths stop being ours the moment close() is
+                            // called, so a request arriving now falls through to the caller
+                            // rather than collecting a refusal from a host that is leaving.
+                            server.off('request', onRequest);
+                            // Then drain what we are already serving — and stop there. The
+                            // socket, the idle connections and the shutdown are the caller's.
+                            await Promise.allSettled([...inFlight]);
+                            return;
+                        }
                         // Drain BEFORE touching sockets — an in-flight request is work the
                         // caller is still waiting on, and dropping it would be the exact
                         // thing close() promises not to do.

package/dist/esm/hosting/httpHost.js.map

@@ -1 +1 @@
-{"version":3,"file":"httpHost.js","sourceRoot":"","sources":["../../../src/hosting/httpHost.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"httpHost.js","sourceRoot":"","sources":["../../../src/hosting/httpHost.ts"],"names":[],"mappings":"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"}

package/dist/esm/hosting/index.d.ts

@@ -31,7 +31,9 @@
  *     itself, parameterised by the JSON dialect it speaks. `nodeHost` is one
  *     configuration of it; an adapter for someone's container runtime is
  *     another. Two paths and five body shapes are all a second HTTP adapter
- *     re-decides.
+ *     re-decides. Pass `server` and it attaches to a `node:http` server YOU
+ *     own instead of binding one — for the container that gets a single port
+ *     and must serve a WebSocket upgrade (or anything else) beside the agent.
  *   • `memorySessions()` — conversations in a Map, for tests and local dev.
  *   • `standingAgent({ agent, sessions, host, durability? })` — the composer.
  *   • `toEnvelope` / `readEnvelope` — pack a conversation, and refuse by name to

package/dist/esm/hosting/index.js

@@ -31,7 +31,9 @@
  *     itself, parameterised by the JSON dialect it speaks. `nodeHost` is one
  *     configuration of it; an adapter for someone's container runtime is
  *     another. Two paths and five body shapes are all a second HTTP adapter
- *     re-decides.
+ *     re-decides. Pass `server` and it attaches to a `node:http` server YOU
+ *     own instead of binding one — for the container that gets a single port
+ *     and must serve a WebSocket upgrade (or anything else) beside the agent.
  *   • `memorySessions()` — conversations in a Map, for tests and local dev.
  *   • `standingAgent({ agent, sessions, host, durability? })` — the composer.
  *   • `toEnvelope` / `readEnvelope` — pack a conversation, and refuse by name to

package/dist/esm/hosting/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/hosting/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AAEH,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGnD,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAStD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/hosting/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAEH,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAGnD,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAStD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,YAAY,EACZ,aAAa,EACb,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,aAAa,CAAC"}

package/dist/esm/hosting/nodeHost.d.ts

@@ -16,6 +16,11 @@
  * a colleague's convention. A path is a deployment detail, so it is a knob
  * here and absent from the port entirely.
  *
+ * **The socket can be yours.** Pass `server` — a `node:http` server you
+ * created and listened on — and this adapter attaches its two routes to it
+ * instead of binding one, so a WebSocket upgrade or your own routes can share
+ * the port. `close()` then detaches and drains, and your socket stays up.
+ *
  * **Streaming is the caller's choice, not the server's.** Send
  * `Accept: text/event-stream` and the reply is Server-Sent Events, one `chunk`
  * event per `reply.emit(...)` then a final `complete`. Send anything else and
@@ -29,17 +34,31 @@
  * never quietly drift apart on what `close()` drains or what a handler that
  * throws does. `types.ts` knows none of it either way.
  */
+/// <reference types="node" />
 import { type HttpHost, type HttpHostHandle, type HttpWire } from './httpHost.js';
 /** Options for {@link nodeHost}. */
 export interface NodeHostOptions {
-    /** Port to bind. Default `8080`. Pass `0` for an ephemeral port. */
+    /** Port to bind. Default `8080`. Pass `0` for an ephemeral port. Refused alongside `server`. */
     readonly port?: number;
-    /** Interface to bind. Default `'0.0.0.0'`. */
+    /** Interface to bind. Default `'0.0.0.0'`. Refused alongside `server`. */
     readonly hostname?: string;
     /** Path that takes a request. Default `'/invoke'`. */
     readonly invokePath?: string;
     /** Path that answers a health probe. Default `'/health'`. */
     readonly healthPath?: string;
+    /**
+     * A `node:http` server **you** own, already listening. Given one, this
+     * adapter attaches its two routes to it instead of binding a socket of its
+     * own — the only way to serve something else (a WebSocket upgrade, routes
+     * that were there first) on the same port, which matters when the thing
+     * running your process gives it exactly one.
+     *
+     * You keep `listen()` and you keep the shutdown; `close()` detaches this
+     * host and drains what it was already serving. On a server you own the host
+     * never writes a 404 either: a path it does not own is yours to answer. The
+     * full set of laws is on `httpHost`'s own `server` option, which this is.
+     */
+    readonly server?: import('node:http').Server;
 }
 /**
  * What {@link nodeHost}'s `serve()` resolves to — a `HostHandle` that also

package/dist/esm/hosting/nodeHost.js

@@ -16,6 +16,11 @@
  * a colleague's convention. A path is a deployment detail, so it is a knob
  * here and absent from the port entirely.
  *
+ * **The socket can be yours.** Pass `server` — a `node:http` server you
+ * created and listened on — and this adapter attaches its two routes to it
+ * instead of binding one, so a WebSocket upgrade or your own routes can share
+ * the port. `close()` then detaches and drains, and your socket stays up.
+ *
  * **Streaming is the caller's choice, not the server's.** Send
  * `Accept: text/event-stream` and the reply is Server-Sent Events, one `chunk`
  * event per `reply.emit(...)` then a final `complete`. Send anything else and
@@ -82,8 +87,13 @@ export function nodeHost(options = {}) {
         // particular runtime's container-contract path literal.
         invokePath: options.invokePath ?? '/invoke',
         healthPath: options.healthPath ?? '/health',
+        // Passed through as given, never defaulted: with a caller-owned server
+        // there is no port to default, and a port passed WITH one is a caller who
+        // believes something untrue about where their agent answers — `httpHost`
+        // refuses that pair by name rather than picking a winner.
         ...(options.port !== undefined && { port: options.port }),
         ...(options.hostname !== undefined && { hostname: options.hostname }),
+        ...(options.server !== undefined && { server: options.server }),
     });
 }
 //# sourceMappingURL=nodeHost.js.map

package/dist/esm/hosting/nodeHost.js.map

@@ -1 +1 @@
-{"version":3,"file":"nodeHost.js","sourceRoot":"","sources":["../../../src/hosting/nodeHost.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,QAAQ,EAAqD,MAAM,eAAe,CAAC;AAwB5F,MAAM,SAAS,GAAG,UAAU,CAAC;AAE7B;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAa;IAChC,WAAW,CAAC,KAAK;QACf,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3E,wEAAwE;QACxE,4EAA4E;QAC5E,MAAM,QAAQ,GAAG,OAAO,KAAK,CAAC,IAAI,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;QAC7F,MAAM,SAAS,GAAG,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;QAC5D,4EAA4E;QAC5E,wEAAwE;QACxE,0CAA0C;QAC1C,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC;QACrC,OAAO;YACL,KAAK;YACL,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;YAC7C,GAAG,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,CAAC;SAC5C,CAAC;IACJ,CAAC;IACD,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAClD,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC,OAAO,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IAC1E,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;IAC3B,QAAQ,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;CAC/C,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,QAAQ,CAAC,UAA2B,EAAE;IACpD,OAAO,QAAQ,CAAC;QACd,IAAI,EAAE,SAAS;QACf,IAAI,EAAE,QAAQ;QACd,yEAAyE;QACzE,wDAAwD;QACxD,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,SAAS;QAC3C,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,SAAS;QAC3C,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;QACzD,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;KACtE,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"nodeHost.js","sourceRoot":"","sources":["../../../src/hosting/nodeHost.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,OAAO,EAAE,QAAQ,EAAqD,MAAM,eAAe,CAAC;AAqC5F,MAAM,SAAS,GAAG,UAAU,CAAC;AAE7B;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAa;IAChC,WAAW,CAAC,KAAK;QACf,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3E,wEAAwE;QACxE,4EAA4E;QAC5E,MAAM,QAAQ,GAAG,OAAO,KAAK,CAAC,IAAI,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC;QAC7F,MAAM,SAAS,GAAG,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC;QAC5D,4EAA4E;QAC5E,wEAAwE;QACxE,0CAA0C;QAC1C,MAAM,QAAQ,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC;QACrC,OAAO;YACL,KAAK;YACL,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;YAC7C,GAAG,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,CAAC;SAC5C,CAAC;IACJ,CAAC;IACD,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAClD,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC,OAAO,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;IAC1E,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;IAC3B,QAAQ,EAAE,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;CAC/C,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,QAAQ,CAAC,UAA2B,EAAE;IACpD,OAAO,QAAQ,CAAC;QACd,IAAI,EAAE,SAAS;QACf,IAAI,EAAE,QAAQ;QACd,yEAAyE;QACzE,wDAAwD;QACxD,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,SAAS;QAC3C,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,SAAS;QAC3C,uEAAuE;QACvE,0EAA0E;QAC1E,yEAAyE;QACzE,0DAA0D;QAC1D,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC;QACzD,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;QACrE,GAAG,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,CAAC;KAChE,CAAC,CAAC;AACL,CAAC"}

package/dist/esm/hosting/types.d.ts

@@ -140,6 +140,12 @@ export interface HostHandle {
      * transport. Idempotent, so a shutdown hook and an explicit close can
      * coexist. Requests arriving after it are refused with a
      * {@link HostClosedError} naming the adapter.
+     *
+     * "Release the transport" is as strong as the port can be, because an
+     * adapter may be serving on a transport the CALLER owns rather than one it
+     * created. Releasing one of those means handing the routes back — never
+     * closing it — and a request arriving afterwards is the caller's to answer,
+     * not this host's to refuse.
      */
     close(): Promise<void>;
 }

package/dist/esm/lib/injection-engine/factories/defineFact.d.ts

@@ -10,7 +10,7 @@
  * Produces an `Injection` with:
  *   - flavor: `'fact'`
  *   - trigger: configurable (default `'always'`)
- *   - inject: `systemPrompt` — the slot that reaches the model
+ *   - inject: `systemPrompt` (default), or `messages` with a declared role
  *
  * @example
  *   const userProfile = defineFact({
@@ -23,21 +23,14 @@
  *     data: `Current time: ${new Date().toISOString()}`,
  *   });
  */
+import type { WireRole } from '../../../adapters/types.js';
 import type { Injection, InjectionContext } from '../types.js';
 import type { CachePolicy } from '../../../cache/types.js';
-export interface DefineFactOptions {
+interface DefineFactBase {
     readonly id: string;
     readonly description?: string;
     /** The fact (data string) to inject. */
     readonly data: string;
-    /**
-     * Which slot to land in. `'system-prompt'` (the default) is the only
-     * slot a fact can land in: it is the one every provider delivers.
-     *
-     * `'messages'` is REFUSED — see {@link messagesSlotRefusal}. It was
-     * accepted before 7.19.1, recorded as injected, and never sent.
-     */
-    readonly slot?: 'system-prompt';
     /**
      * Trigger control. Defaults to always-on. For conditional facts
      * (e.g., "only show user profile after iteration 3"), pass a
@@ -53,4 +46,39 @@ export interface DefineFactOptions {
      */
     readonly cache?: CachePolicy;
 }
+/**
+ * `slot` and `role` are ONE decision, so the type makes them one choice.
+ *
+ * `slot: 'messages'` requires a `role` and there is deliberately no default:
+ * who appears to speak is a meaning the app owns. (Before 7.19.1 the option
+ * existed with `role` defaulting to `'system'` — a default that reached the
+ * model on OpenAI-family providers and vanished on Anthropic-family ones.
+ * Now the role is stated, and a provider that cannot carry it refuses at run
+ * start by name.) `slot: 'system-prompt'` forbids `role`, because there is no
+ * role in a system prompt to choose.
+ */
+export type DefineFactOptions = DefineFactBase & ({
+    /** The default. The one placement every provider delivers. */
+    readonly slot?: 'system-prompt';
+    readonly role?: never;
+} | {
+    /**
+     * Deliver the fact into the conversation itself — it enters
+     * `scope.history` at the injection-engine boundary, so the window
+     * strategies, the slots and the wire all see the same past.
+     * Placed at the END of the window; if its role would collide with
+     * the turn already there, delivery defers to the next boundary and
+     * says so on `messagesDelivery.deferred`.
+     */
+    readonly slot: 'messages';
+    /**
+     * Who appears to say it. Required — no default. Refused at run start
+     * when the attached provider does not carry it inside `messages`
+     * (the Anthropic family drops `'system'` there; the OpenAI family
+     * carries it). `'tool'` is refused outright: a tool message answers a
+     * specific call, and an injection has no call to answer.
+     */
+    readonly role: WireRole;
+});
 export declare function defineFact(opts: DefineFactOptions): Injection;
+export {};

package/dist/esm/lib/injection-engine/factories/defineFact.js

@@ -10,7 +10,7 @@
  * Produces an `Injection` with:
  *   - flavor: `'fact'`
  *   - trigger: configurable (default `'always'`)
- *   - inject: `systemPrompt` — the slot that reaches the model
+ *   - inject: `systemPrompt` (default), or `messages` with a declared role
  *
  * @example
  *   const userProfile = defineFact({
@@ -23,7 +23,7 @@
  *     data: `Current time: ${new Date().toISOString()}`,
  *   });
  */
-import { messagesSlotRefusal } from '../messagesSlotRefusal.js';
+import { messagesToolRoleRefusal } from '../messagesSlotRefusal.js';
 import { resolveCachePolicy } from '../../../cache/applyCachePolicy.js';
 export function defineFact(opts) {
     if (!opts.id || opts.id.trim().length === 0) {
@@ -32,16 +32,28 @@ export function defineFact(opts) {
     if (!opts.data || opts.data.length === 0) {
         throw new Error(`defineFact(${opts.id}): \`data\` is required.`);
     }
-    // The type already rules `'messages'` out for TypeScript callers; this
-    // catches the JavaScript ones and the `as never` casts, because a
-    // refusal that only exists at compile time is not a refusal.
-    if (opts.slot === 'messages') {
-        throw new Error(messagesSlotRefusal(`defineFact('${opts.id}')`));
+    // The runtime guards read a WIDENED view on purpose. The declared type
+    // already pairs `slot` with `role` correctly, and TypeScript narrows so well
+    // that `opts.role` is provably present inside a `slot === 'messages'` branch
+    // — which makes the checks below unreachable *to the compiler* and therefore
+    // invisible to the JavaScript callers and `as never` casts they exist for. A
+    // refusal that only holds at compile time is not a refusal.
+    const raw = opts;
+    const toMessages = raw.slot === 'messages';
+    if (toMessages && !raw.role) {
+        throw new Error(`defineFact('${opts.id}'): \`slot: 'messages'\` requires a \`role\` — ` +
+            `'user', 'assistant', or 'system' on a provider that carries it. There is no ` +
+            `default: who appears to speak is a meaning your app owns, not one the library picks.`);
+    }
+    if (toMessages && raw.role === 'tool') {
+        throw new Error(messagesToolRoleRefusal(`defineFact('${opts.id}')`));
     }
     const trigger = opts.activeWhen
         ? { kind: 'rule', activeWhen: opts.activeWhen }
         : { kind: 'always' };
-    const inject = { systemPrompt: opts.data };
+    const inject = toMessages
+        ? { messages: [{ role: raw.role, content: opts.data }] }
+        : { systemPrompt: opts.data };
     const cache = resolveCachePolicy('fact', opts.cache);
     // Two-stage cast (`as unknown as Injection`) is required because
     // `flavor: 'fact'` narrows tighter than `ContextSource`. Both stages

package/dist/esm/lib/injection-engine/factories/defineFact.js.map

@@ -1 +1 @@
-{"version":3,"file":"defineFact.js","sourceRoot":"","sources":["../../../../../src/lib/injection-engine/factories/defineFact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAgCxE,MAAM,UAAU,UAAU,CAAC,IAAuB;IAChD,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CAAC,cAAc,IAAI,CAAC,EAAE,0BAA0B,CAAC,CAAC;IACnE,CAAC;IACD,uEAAuE;IACvE,kEAAkE;IAClE,6DAA6D;IAC7D,IAAK,IAAI,CAAC,IAA2B,KAAK,UAAU,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,eAAe,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;IACnE,CAAC;IACD,MAAM,OAAO,GAAqB,IAAI,CAAC,UAAU;QAC/C,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE;QAC/C,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IACvB,MAAM,MAAM,GAAG,EAAE,YAAY,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;IAE3C,MAAM,KAAK,GAAG,kBAAkB,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IACrD,iEAAiE;IACjE,qEAAqE;IACrE,uEAAuE;IACvE,gEAAgE;IAChE,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,GAAG,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;QAC1D,MAAM,EAAE,MAAe;QACvB,OAAO;QACP,MAAM;QACN,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;KACnC,CAAyB,CAAC;AAC7B,CAAC"}
+{"version":3,"file":"defineFact.js","sourceRoot":"","sources":["../../../../../src/lib/injection-engine/factories/defineFact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AA+DxE,MAAM,UAAU,UAAU,CAAC,IAAuB;IAChD,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzC,MAAM,IAAI,KAAK,CAAC,cAAc,IAAI,CAAC,EAAE,0BAA0B,CAAC,CAAC;IACnE,CAAC;IACD,uEAAuE;IACvE,6EAA6E;IAC7E,6EAA6E;IAC7E,6EAA6E;IAC7E,6EAA6E;IAC7E,4DAA4D;IAC5D,MAAM,GAAG,GAAG,IAAwC,CAAC;IACrD,MAAM,UAAU,GAAG,GAAG,CAAC,IAAI,KAAK,UAAU,CAAC;IAC3C,IAAI,UAAU,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACb,eAAe,IAAI,CAAC,EAAE,iDAAiD;YACrE,8EAA8E;YAC9E,sFAAsF,CACzF,CAAC;IACJ,CAAC;IACD,IAAI,UAAU,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,eAAe,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;IACvE,CAAC;IACD,MAAM,OAAO,GAAqB,IAAI,CAAC,UAAU;QAC/C,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE;QAC/C,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IACvB,MAAM,MAAM,GAAG,UAAU;QACvB,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAgB,EAAE,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE;QACpE,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;IAEhC,MAAM,KAAK,GAAG,kBAAkB,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IACrD,iEAAiE;IACjE,qEAAqE;IACrE,uEAAuE;IACvE,gEAAgE;IAChE,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,GAAG,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;QAC1D,MAAM,EAAE,MAAe;QACvB,OAAO;QACP,MAAM;QACN,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;KACnC,CAAyB,CAAC;AAC7B,CAAC"}

package/dist/esm/lib/injection-engine/factories/defineInstruction.d.ts

@@ -11,7 +11,8 @@
  * Produces an `Injection` with:
  *   - flavor: `'instructions'`
  *   - trigger: `{ kind: 'rule', activeWhen }` (or `'always'` if omitted)
- *   - inject: `{ systemPrompt: prompt }`
+ *   - inject: `{ systemPrompt: prompt }`, or `{ messages: [{ role, content }] }`
+ *     when `slot: 'messages'` names the role it speaks as
  *
  * @example
  *   const calmTone = defineInstruction({
@@ -27,9 +28,10 @@
  *     prompt: 'PII has been redacted. Do not include emails or phone numbers.',
  *   });
  */
+import type { WireRole } from '../../../adapters/types.js';
 import type { Injection, InjectionContext } from '../types.js';
 import type { CachePolicy } from '../../../cache/types.js';
-export interface DefineInstructionOptions {
+interface DefineInstructionBase {
     readonly id: string;
     readonly description?: string;
     /**
@@ -41,20 +43,8 @@ export interface DefineInstructionOptions {
      * `agentfootprint.context.evaluated`.
      */
     readonly activeWhen?: (ctx: InjectionContext) => boolean;
-    /** Instruction text. Lands in the system-prompt slot. */
+    /** Instruction text. */
     readonly prompt: string;
-    /**
-     * Where the instruction lands. `'system-prompt'` (the default) is the
-     * only slot an instruction can land in: it is the one every provider
-     * delivers.
-     *
-     * `'messages'` is REFUSED — see {@link messagesSlotRefusal}. It was
-     * accepted before 7.19.1 and documented as the recency-first
-     * placement; it was recorded as injected and never sent. To make a
-     * rule salient at the moment it matters, return it from the tool whose
-     * result it is about — a tool result IS a recent message.
-     */
-    readonly slot?: 'system-prompt';
     /**
      * Cache policy for this instruction. Defaults to `'never'` —
      * instructions are typically rule-based (volatile per-iter
@@ -66,4 +56,41 @@ export interface DefineInstructionOptions {
      */
     readonly cache?: CachePolicy;
 }
+/**
+ * `slot` and `role` are ONE decision, so the type makes them one choice —
+ * see {@link DefineFactOptions} for the full reasoning. In short:
+ * `slot: 'messages'` requires a `role` with no default (who appears to speak
+ * is the app's meaning to set), and `slot: 'system-prompt'` forbids one.
+ */
+export type DefineInstructionOptions = DefineInstructionBase & ({
+    /**
+     * The default. Appended to the system prompt — the one placement
+     * every provider delivers. An `on-tool-return` instruction already
+     * lands on exactly the turn it matters; this is a system prompt that
+     * says it on that one turn, rather than on every turn.
+     */
+    readonly slot?: 'system-prompt';
+    readonly role?: never;
+} | {
+    /**
+     * Deliver the instruction into the conversation itself — it enters
+     * `scope.history` at the injection-engine boundary, at the END of the
+     * window, so the model reads it at the recency this option is
+     * reaching for. If its role would collide with the turn already at
+     * the end, delivery defers to the next boundary and says so on
+     * `messagesDelivery.deferred` rather than reordering anything.
+     *
+     * In a tool-using loop the window ends on the user's turn or on tool
+     * results, so a `'user'` role typically never gets a slot. Use
+     * `'assistant'`, use `'system'` on a provider that carries it, or
+     * return the words from the tool whose result they are about.
+     */
+    readonly slot: 'messages';
+    /**
+     * Who appears to say it. Required — no default. Refused at run start
+     * when the attached provider does not carry it inside `messages`.
+     */
+    readonly role: WireRole;
+});
 export declare function defineInstruction(opts: DefineInstructionOptions): Injection;
+export {};

package/dist/esm/lib/injection-engine/factories/defineInstruction.js

@@ -11,7 +11,8 @@
  * Produces an `Injection` with:
  *   - flavor: `'instructions'`
  *   - trigger: `{ kind: 'rule', activeWhen }` (or `'always'` if omitted)
- *   - inject: `{ systemPrompt: prompt }`
+ *   - inject: `{ systemPrompt: prompt }`, or `{ messages: [{ role, content }] }`
+ *     when `slot: 'messages'` names the role it speaks as
  *
  * @example
  *   const calmTone = defineInstruction({
@@ -27,7 +28,7 @@
  *     prompt: 'PII has been redacted. Do not include emails or phone numbers.',
  *   });
  */
-import { messagesSlotRefusal } from '../messagesSlotRefusal.js';
+import { messagesToolRoleRefusal } from '../messagesSlotRefusal.js';
 import { resolveCachePolicy } from '../../../cache/applyCachePolicy.js';
 export function defineInstruction(opts) {
     if (!opts.id || opts.id.trim().length === 0) {
@@ -36,14 +37,24 @@ export function defineInstruction(opts) {
     if (!opts.prompt || opts.prompt.length === 0) {
         throw new Error(`defineInstruction(${opts.id}): \`prompt\` is required.`);
     }
-    // Refused at run time as well as in the type — see defineFact for why.
-    if (opts.slot === 'messages') {
-        throw new Error(messagesSlotRefusal(`defineInstruction('${opts.id}')`));
+    // Refused at run time as well as in the type, read through a widened view —
+    // see defineFact for why the widening is deliberate.
+    const raw = opts;
+    const toMessages = raw.slot === 'messages';
+    if (toMessages && !raw.role) {
+        throw new Error(`defineInstruction('${opts.id}'): \`slot: 'messages'\` requires a \`role\` — ` +
+            `'user', 'assistant', or 'system' on a provider that carries it. There is no ` +
+            `default: who appears to speak is a meaning your app owns, not one the library picks.`);
+    }
+    if (toMessages && raw.role === 'tool') {
+        throw new Error(messagesToolRoleRefusal(`defineInstruction('${opts.id}')`));
     }
     const trigger = opts.activeWhen
         ? { kind: 'rule', activeWhen: opts.activeWhen }
         : { kind: 'always' };
-    const inject = { systemPrompt: opts.prompt };
+    const inject = toMessages
+        ? { messages: [{ role: raw.role, content: opts.prompt }] }
+        : { systemPrompt: opts.prompt };
     const cache = resolveCachePolicy('instruction', opts.cache);
     return Object.freeze({
         id: opts.id,

package/dist/esm/lib/injection-engine/factories/defineInstruction.js.map

@@ -1 +1 @@
-{"version":3,"file":"defineInstruction.js","sourceRoot":"","sources":["../../../../../src/lib/injection-engine/factories/defineInstruction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAyCxE,MAAM,UAAU,iBAAiB,CAAC,IAA8B;IAC9D,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;IAChF,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CAAC,qBAAqB,IAAI,CAAC,EAAE,4BAA4B,CAAC,CAAC;IAC5E,CAAC;IACD,uEAAuE;IACvE,IAAK,IAAI,CAAC,IAA2B,KAAK,UAAU,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,sBAAsB,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;IAC1E,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU;QAC7B,CAAC,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE;QACxD,CAAC,CAAC,EAAE,IAAI,EAAE,QAAiB,EAAE,CAAC;IAChC,MAAM,MAAM,GAAqB,EAAE,YAAY,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;IAC/D,MAAM,KAAK,GAAG,kBAAkB,CAAC,aAAa,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5D,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,GAAG,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;QAC1D,MAAM,EAAE,cAAuB;QAC/B,OAAO;QACP,MAAM;QACN,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;KACnC,CAAyB,CAAC;AAC7B,CAAC"}
+{"version":3,"file":"defineInstruction.js","sourceRoot":"","sources":["../../../../../src/lib/injection-engine/factories/defineInstruction.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH,OAAO,EAAE,uBAAuB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAsExE,MAAM,UAAU,iBAAiB,CAAC,IAA8B;IAC9D,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,4DAA4D,CAAC,CAAC;IAChF,CAAC;IACD,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,KAAK,CAAC,qBAAqB,IAAI,CAAC,EAAE,4BAA4B,CAAC,CAAC;IAC5E,CAAC;IACD,4EAA4E;IAC5E,qDAAqD;IACrD,MAAM,GAAG,GAAG,IAAwC,CAAC;IACrD,MAAM,UAAU,GAAG,GAAG,CAAC,IAAI,KAAK,UAAU,CAAC;IAC3C,IAAI,UAAU,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CACb,sBAAsB,IAAI,CAAC,EAAE,iDAAiD;YAC5E,8EAA8E;YAC9E,sFAAsF,CACzF,CAAC;IACJ,CAAC;IACD,IAAI,UAAU,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QACtC,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,sBAAsB,IAAI,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;IAC9E,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU;QAC7B,CAAC,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE;QACxD,CAAC,CAAC,EAAE,IAAI,EAAE,QAAiB,EAAE,CAAC;IAChC,MAAM,MAAM,GAAqB,UAAU;QACzC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,IAAgB,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE;QACtE,CAAC,CAAC,EAAE,YAAY,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC;IAClC,MAAM,KAAK,GAAG,kBAAkB,CAAC,aAAa,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IAC5D,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,GAAG,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;QAC1D,MAAM,EAAE,cAAuB;QAC/B,OAAO;QACP,MAAM;QACN,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;KACnC,CAAyB,CAAC;AAC7B,CAAC"}