agentfootprint 9.9.0 → 9.10.0

package/dist/esm/hosting/nodeHost.js

@@ -48,46 +48,113 @@
  */
 import { headerValue, httpHost, } from './httpHost.js';
 const HOST_NAME = 'nodeHost';
+/** The header this dialect reads a session id from when nobody says otherwise. */
+export const DEFAULT_SESSION_HEADER = 'x-session-id';
 /**
- * This adapter's own JSON dialect: `{ input, sessionId? }` in, `{ output }`
- * out, `{ status: 'ok', uptimeMs }` on the health path.
+ * Build this adapter's JSON dialect: `{ input, sessionId? }` in, `{ output }`
+ * out, `{ status: 'ok', uptimeMs }` on the health path — with the session
+ * plumbing a deployment gets to re-decide.
  *
  * Exported by name so a deployment that has to keep these exact bodies while
  * changing something else about the host reuses them rather than retyping them
  * and getting one field subtly wrong.
  */
-export const jsonWire = {
-    readRequest(facts) {
-        const input = typeof facts.body.input === 'string' ? facts.body.input : '';
-        // sessionId is caller data whichever way it arrives; the body wins so a
-        // caller that sets both is not surprised by which one the server preferred.
-        const fromBody = typeof facts.body.sessionId === 'string' ? facts.body.sessionId : undefined;
-        const sessionId = fromBody ?? facts.headers['x-session-id'];
-        // Read as-is and never coerced: `decision` is a person's answer to whatever
-        // a tool asked, and this dialect does not get to decide what that looks
-        // like. Its PRESENCE is the whole signal.
-        const decision = facts.body.decision;
-        return {
-            input,
-            ...(sessionId !== undefined && { sessionId }),
-            ...(decision !== undefined && { decision }),
-        };
-    },
-    health: (uptimeMs) => ({ status: 'ok', uptimeMs }),
-    output: (output) => ({ output }),
-    failure: (error, code) => ({ error, ...(code !== undefined && { code }) }),
-    chunk: (text) => ({ text }),
-    awaiting: (pending) => ({ awaiting: pending }),
-    readConversation(facts) {
-        // A handshake has no body, so this dialect names the two places a session
-        // id can be: the header a server-side caller sets, and the query a BROWSER
-        // has to use because the WebSocket API gives it no way to set a header.
-        // Header wins, so a caller that sets both is not surprised by which one the
-        // server preferred — the same rule the request dialect uses for body-vs-header.
-        const sessionId = headerValue(facts, 'x-session-id') ?? facts.query.get('sessionId') ?? undefined;
-        return { ...(sessionId !== undefined && sessionId.length > 0 && { sessionId }) };
-    },
-};
+export function jsonWireWith(options = {}) {
+    const sessionHeader = options.sessionHeader ?? DEFAULT_SESSION_HEADER;
+    const sessionCookie = options.sessionCookie;
+    return {
+        readRequest(facts) {
+            const input = typeof facts.body.input === 'string' ? facts.body.input : '';
+            // sessionId is caller data whichever way it arrives; the body wins so a
+            // caller that sets both is not surprised by which one the server preferred.
+            // The cookie is last, because a caller that named a session explicitly
+            // meant that one — the cookie is what the BROWSER remembered, and the
+            // explicit value is what this request said.
+            const fromBody = typeof facts.body.sessionId === 'string' ? facts.body.sessionId : undefined;
+            const fromHeader = headerValue(facts, sessionHeader);
+            const fromCookie = sessionCookie !== undefined ? cookieValue(facts.headers.cookie, sessionCookie) : undefined;
+            const carried = fromBody ?? fromHeader ?? fromCookie;
+            // Issued ONLY in cookie mode, and only when this request carried no
+            // session at all. A caller holding a session already has a conversation;
+            // handing it a second handle would split it in two.
+            const minted = sessionCookie !== undefined && carried === undefined ? mintSessionId() : undefined;
+            const sessionId = carried ?? minted;
+            // Read as-is and never coerced: `decision` is a person's answer to whatever
+            // a tool asked, and this dialect does not get to decide what that looks
+            // like. Its PRESENCE is the whole signal.
+            const decision = facts.body.decision;
+            return {
+                input,
+                ...(sessionId !== undefined && { sessionId }),
+                ...(decision !== undefined && { decision }),
+                ...(minted !== undefined &&
+                    sessionCookie !== undefined && {
+                    responseHeaders: { 'set-cookie': sessionCookieHeader(sessionCookie, minted) },
+                }),
+            };
+        },
+        health: (uptimeMs) => ({ status: 'ok', uptimeMs }),
+        output: (output) => ({ output }),
+        failure: (error, code) => ({ error, ...(code !== undefined && { code }) }),
+        chunk: (text) => ({ text }),
+        awaiting: (pending) => ({ awaiting: pending }),
+        readConversation(facts) {
+            // A handshake has no body, so this dialect names the three places a
+            // session id can be: the header a server-side caller sets, the cookie the
+            // browser sends on its own (when cookie mode is on), and the query a
+            // BROWSER has to use because the WebSocket API gives it no way to set a
+            // header. Header wins, so a caller that sets both is not surprised by
+            // which one the server preferred — the same rule the request dialect uses
+            // for body-vs-header.
+            //
+            // Nothing is MINTED here, in either mode: the 101 this door writes is not
+            // a reply a wire composes, so a session issued on a handshake could never
+            // reach the client and would be a conversation nobody could resume.
+            const sessionId = headerValue(facts, sessionHeader) ??
+                (sessionCookie !== undefined
+                    ? cookieValue(facts.headers.cookie, sessionCookie)
+                    : undefined) ??
+                facts.query.get('sessionId') ??
+                undefined;
+            return { ...(sessionId !== undefined && sessionId.length > 0 && { sessionId }) };
+        },
+    };
+}
+/**
+ * This adapter's own JSON dialect with its defaults: the session on
+ * `x-session-id`, no cookie.
+ */
+export const jsonWire = jsonWireWith();
+/**
+ * One cookie's value out of a `Cookie` header, or `undefined`.
+ *
+ * Deliberately small: it splits on `;`, takes the first `=`, and trims. It does
+ * not decode, because a session id this library minted is URL-safe and a value
+ * somebody else's system minted is theirs to interpret — guessing at an
+ * encoding is how a session id silently becomes a different string.
+ */
+function cookieValue(header, name) {
+    if (header === undefined || header.length === 0)
+        return undefined;
+    for (const pair of header.split(';')) {
+        const at = pair.indexOf('=');
+        if (at < 0)
+            continue;
+        if (pair.slice(0, at).trim() !== name)
+            continue;
+        const value = pair.slice(at + 1).trim();
+        return value.length > 0 ? value : undefined;
+    }
+    return undefined;
+}
+/** The `Set-Cookie` this dialect issues. See {@link JsonWireOptions.sessionCookie}. */
+function sessionCookieHeader(name, value) {
+    return `${name}=${value}; Path=/; HttpOnly; SameSite=Lax`;
+}
+/** A session id for a caller that carried none. Node 20+ has global `crypto`. */
+function mintSessionId() {
+    return globalThis.crypto.randomUUID();
+}
 /**
  * An HTTP host for one handler.
  *
@@ -101,9 +168,17 @@ export const jsonWire = {
  *   await handle.close();
  */
 export function nodeHost(options = {}) {
+    // The shared default instance when nothing about sessions was re-decided, so
+    // a host built with no options is the same object graph it always was.
+    const wire = options.sessionHeader === undefined && options.sessionCookie === undefined
+        ? jsonWire
+        : jsonWireWith({
+            ...(options.sessionHeader !== undefined && { sessionHeader: options.sessionHeader }),
+            ...(options.sessionCookie !== undefined && { sessionCookie: options.sessionCookie }),
+        });
     return httpHost({
         name: HOST_NAME,
-        wire: jsonWire,
+        wire,
         // Chosen, not inherited — see the test in this folder that greps for one
         // particular runtime's container-contract path literal.
         invokePath: options.invokePath ?? '/invoke',

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

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

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

@@ -51,33 +51,69 @@
  * Resuming a PAUSED run is different in kind: it is not a replay at all — the
  * engine continues from its own checkpoint, and no earlier tool call re-runs.
  *
- * ── Why one run at a time ───────────────────────────────────────────────────
- * An Agent instance holds per-run state on itself, and this composer shares ONE
- * instance across every session. Two runs overlapping on it do not crash —
- * which is precisely the danger. They both finish, and the state the composer
- * reads afterwards belongs to whichever started last, so one session's envelope
- * can end up holding another session's conversation. Nothing in the recording
- * would say so. Runs are therefore serialized, globally, and that is a
- * correctness requirement rather than a tuning choice.
+ * ── Why one run at a time, and where that bound actually is ─────────────────
+ * An Agent instance holds per-run state on itself. Two runs overlapping on ONE
+ * instance do not crash — which is precisely the danger. They both finish, and
+ * the state the composer reads afterwards belongs to whichever started last, so
+ * one session's envelope can end up holding another session's conversation.
+ * Nothing in the recording would say so. **Runs on one instance are therefore
+ * serialized, and that is a correctness requirement rather than a tuning
+ * choice.**
+ *
+ * What CHANGED in 9.10.0 is not that rule but its scope. `{ agent }` hands this
+ * composer one instance to share, so the serialization is global — the shape
+ * every earlier release had, unchanged to the byte. `{ agentFactory }` hands it
+ * a way to MAKE instances, so each session gets its own and the same rule binds
+ * per session: sessions run in parallel, each session's turns queue behind that
+ * session's own instance.
+ *
+ *   standingAgent({ agent })          → one instance,  global queue
+ *   standingAgent({ agentFactory })   → one per session, a queue each
+ *
+ * Everything else is identical between the two: the same stores, the same
+ * durability modes, the same pause/resume contract, the same refusals. The
+ * session store is keyed per session already, which is why the pool can evict a
+ * session's instance without the person on the other end noticing — the
+ * CONVERSATION was never in the instance.
  *
  * `onConcurrentInvoke` is the separate question of what to do when a second
  * turn of the SAME conversation arrives while the first is running: refuse it
- * (default) or queue it. A request for a DIFFERENT session is never refused —
- * there is nothing wrong with it; it simply waits its turn.
+ * (default) or queue it. It means the same thing in both shapes. A request for
+ * a DIFFERENT session is never refused — there is nothing wrong with it; in the
+ * shared shape it waits its turn, and in the pooled shape it does not have to.
+ *
+ * ── The pool, in one paragraph ──────────────────────────────────────────────
+ * One instance per ACTIVE session, built on first sight by the factory, bounded
+ * by `maxActiveSessions` (default 100) and evicted least-recently-used. An
+ * evicted session's agent has its tool sessions closed with reason `'evicted'`
+ * — the 9.7.0 vocabulary, not a new one — and is then shut down; its
+ * conversation stays in the store, so its next request re-hydrates onto a fresh
+ * instance and nothing was lost. A session that is RUNNING is never evicted:
+ * the bound is on retained idle instances, and a cache policy does not get to
+ * end somebody's turn. Requests with NO session share one fallback instance,
+ * because there is no conversation to isolate and an instance per anonymous
+ * request would be an instance per request.
  *
  * Pattern: Composition root. It owns wiring and ordering; it invents no
  * mechanism of its own.
  */
 import type { HostHandle, StandingAgentOptions } from './types.js';
 /**
- * Serve one agent, with per-session conversation memory, on any
+ * Serve an agent, with per-session conversation memory, on any
  * {@link AgentHost}.
  *
  * Resolves once the host is live. Closing the returned handle closes the host,
- * detaches the listeners this composer added to the agent, and removes its
- * durability wiring.
+ * detaches the listeners this composer added, and removes its durability
+ * wiring.
+ *
+ * Two shapes, one composer — see the file header for the full comparison:
  *
- * @example
+ *  - `{ agent }` — one instance for every session, runs serialized globally.
+ *    Correct, and unchanged from every earlier release.
+ *  - `{ agentFactory }` — one instance per active session, sessions in
+ *    PARALLEL, each session's turns serialized on its own instance.
+ *
+ * @example  One agent, every session
  *   const handle = await standingAgent({
  *     agent,
  *     sessions: memorySessions(),
@@ -86,5 +122,13 @@ import type { HostHandle, StandingAgentOptions } from './types.js';
  *     durability: 'sync',
  *   });
  *   process.on('SIGTERM', () => void handle.close());
+ *
+ * @example  One agent per session — they answer at the same time
+ *   const handle = await standingAgent({
+ *     agentFactory: () => Agent.create({ provider, model }).system('…').build(),
+ *     sessions: sqliteSessions({ file: './sessions.db' }),
+ *     host: nodeHost({ port: 8080 }),
+ *     maxActiveSessions: 200,
+ *   });
  */
 export declare function standingAgent<TH extends HostHandle>(options: StandingAgentOptions<TH>): Promise<TH>;