agentfootprint 9.26.0 → 9.28.0

package/dist/esm/adapters/hosting/googleAgentEngine.js

@@ -0,0 +1,368 @@
+/**
+ * agentEngineSessions — conversations in Vertex AI's own session service, so a
+ * fleet shares them.
+ *
+ * `memorySessions()` loses everything on restart and says so. `sqliteSessions()`
+ * survives a restart on ONE machine and says so. The row above both — *many
+ * containers, one conversation* — is where a managed session service belongs,
+ * and on this column that service is the `sessions` collection under a
+ * reasoning engine.
+ *
+ * ── The name, said once ─────────────────────────────────────────────────────
+ * The product was **Agent Engine**, is now **Agent Runtime**, and the API
+ * resource is still spelled `reasoningEngines`. This factory keeps the name it
+ * was designed under; where the product name and the API disagree, the API is
+ * the one that has not moved.
+ *
+ * ── The fit, and it is a good one ───────────────────────────────────────────
+ * `Session.sessionState` is an arbitrary JSON `Struct`. A `CheckpointEnvelope`
+ * is arbitrary JSON. So the envelope goes in whole, under one key, and comes
+ * back whole — no event log to fold, no blob encoding to get wrong, no
+ * per-turn append. That is a materially better fit than the other column's
+ * session store, which had to learn the hard way that an object handed to an
+ * event blob comes back as somebody else's `toString()`.
+ *
+ * ── The four facts that shaped the code, all read off the installed SDK ─────
+ *  1. **`sessions.create` takes a caller-supplied `sessionId`.** So our session
+ *     id IS the resource id and `hydrate` is one `get` by name. No mapping
+ *     table, no listing to find a conversation.
+ *  2. **`create` and `delete` answer a long-running Operation; `get` and
+ *     `patch` answer the Session.** Every write here therefore waits for the
+ *     operation to report `done` before it returns — a `persist` that returned
+ *     early would make the very next `hydrate` a race whose failure mode is
+ *     "no conversation", which nobody can tell from a new user.
+ *  3. **`Session.userId` is required and immutable.** Our port's
+ *     `persist(sessionId, envelope)` carries no user, so one has to be
+ *     resolved — see {@link AgentEngineSessionsOptions.userId}. Immutable
+ *     means the first write decides forever, which is exactly the ownership
+ *     rule this library already enforces in its own stores; here the service
+ *     enforces it for us.
+ *  4. **`ttl` is input-only with a 24-hour floor**, and `expireTime` always
+ *     comes back. Sliding expiry is free; an hour-long TTL is not available at
+ *     any price.
+ *
+ * ── The laws it inherits rather than re-implements ──────────────────────────
+ * `checkEnvelope` runs on the way OUT and on the way IN, so an envelope whose
+ * `format` this runtime does not know is refused by name, and a session that
+ * is PRESENT but unreadable is refused by name too. Only a session that was
+ * never written hydrates as `undefined`. A conversation that exists and cannot
+ * be read must never be answered with a fresh start — that failure is
+ * indistinguishable, from the outside, from a brand-new user.
+ */
+import { checkEnvelope, envelopeOwner, envelopeTranscript } from '../../hosting/envelope.js';
+import { UnreadableEnvelopeError } from '../../hosting/errors.js';
+import { awaitOperation, buildAiPlatformClient, DEFAULT_OPERATION_TIMEOUT_MS, googleSdkFailure, isAlreadyExists, isNotFound, resolveEngine, safeResourceId, } from '../google/aiPlatform.js';
+const ADAPTER = 'agentEngineSessions';
+/**
+ * The `sessionState` key the envelope lives under.
+ *
+ * One key, namespaced, rather than spreading the envelope's own fields across
+ * `sessionState`: the struct belongs to whoever owns the reasoning engine, an
+ * agent framework is a guest in it, and a guest that scatters `format` and
+ * `data` at the top level collides with the next guest. Namespacing also makes
+ * the console readable — one entry that says whose it is.
+ */
+export const SESSION_STATE_KEY = 'agentfootprint.envelope';
+/** What a conversation that named nobody is stored under. */
+export const DEFAULT_USER_ID = 'agentfootprint-anonymous';
+/**
+ * Conversations in Vertex AI's session service — the store that survives a
+ * fleet, not just a restart.
+ *
+ * **Status: contract-shaped and tested; awaiting field use.** Every call is
+ * exercised through an injected client and pinned against the really-installed
+ * SDK. None of it has yet answered a request from Google in a real project.
+ *
+ * @example  A standing agent whose conversations are shared across instances
+ *   import { standingAgent, nodeHost } from 'agentfootprint/hosting';
+ *   import { agentEngineSessions } from 'agentfootprint/hosting';
+ *
+ *   const handle = await standingAgent({
+ *     agentFactory: () => buildAgent(),
+ *     host: nodeHost({ port: 8080 }),
+ *     sessions: agentEngineSessions({
+ *       project: 'my-project',
+ *       location: 'us-central1',
+ *       reasoningEngine: '1234567890',
+ *     }),
+ *   });
+ */
+export function agentEngineSessions(options) {
+    const scope = resolveEngine(ADAPTER, options);
+    const client = buildAiPlatformClient(ADAPTER, options, scope);
+    const sessions = client.projects.locations.reasoningEngines.sessions;
+    const operationTimeoutMs = options.operationTimeoutMs ?? DEFAULT_OPERATION_TIMEOUT_MS;
+    const resolveUserId = userIdResolver(options.userId);
+    let closed = false;
+    const open = (verb) => {
+        if (!closed)
+            return;
+        throw new Error(`[hosting] the ${ADAPTER} store for '${scope.parent}' is closed, so it cannot ${verb}. ` +
+            `close() is final by design — reconnecting behind you would hide a shutdown-ordering ` +
+            `bug rather than surface it. Build a new store if you need one after closing this.`);
+    };
+    const nameOf = (sessionId) => `${scope.parent}/sessions/${safeResourceId(sessionId)}`;
+    return {
+        parent: scope.parent,
+        async hydrate(sessionId) {
+            open('hydrate a session');
+            let session;
+            try {
+                session = (await sessions.get({ name: nameOf(sessionId) }))?.data;
+            }
+            catch (err) {
+                // The ONE failure that means "no conversation". Everything else is a
+                // failure to READ, which is a different fact and never answered with a
+                // fresh start.
+                if (isNotFound(err))
+                    return undefined;
+                throw googleSdkFailure(ADAPTER, 'sessions.get', err);
+            }
+            if (session === undefined)
+                return undefined;
+            const state = session.sessionState;
+            // A session with no state at all was created by something that is not
+            // this library — or by us, and never written to. Nothing here ever
+            // claimed to be a conversation, so it is an absence.
+            if (state === null || state === undefined)
+                return undefined;
+            const stored = state[SESSION_STATE_KEY];
+            if (stored === undefined)
+                return undefined;
+            // Present and not an object: a conversation EXISTS here and this runtime
+            // cannot read it. Refused by name, never as `undefined`.
+            if (stored === null || typeof stored !== 'object') {
+                throw new UnreadableEnvelopeError(stored, sessionId);
+            }
+            // Validated HERE as well as in the composer, so a refusal points at the
+            // store that produced the bytes rather than at whoever read them next.
+            return checkEnvelope(stored, sessionId);
+        },
+        async persist(sessionId, envelope) {
+            open('persist a session');
+            // Checked on the way IN as well as out: a session this store could not
+            // read back is one it has no business writing.
+            const checked = checkEnvelope(envelope, sessionId);
+            const name = nameOf(sessionId);
+            const body = {
+                sessionState: { [SESSION_STATE_KEY]: checked },
+                ...(options.ttl !== undefined && { ttl: options.ttl }),
+            };
+            // PATCH first, CREATE on 404 — rather than the other way round.
+            //
+            // The steady state of a conversation is "it already exists": a session
+            // is created once and written on every turn after that. Trying create
+            // first would mean one guaranteed-to-fail call per turn for the life of
+            // every conversation, and would burn a long-running operation to learn
+            // something a patch answers directly.
+            try {
+                await sessions.patch({
+                    name,
+                    // Only the fields we own. Without a mask a patch is a REPLACE, and a
+                    // replace would drop `userId` — which is immutable, so the service
+                    // would refuse the write and a conversation would stop persisting.
+                    updateMask: maskFor(body),
+                    requestBody: body,
+                });
+                return;
+            }
+            catch (err) {
+                if (!isNotFound(err))
+                    throw googleSdkFailure(ADAPTER, 'sessions.patch', err);
+            }
+            const userId = resolveUserId(sessionId, checked);
+            let created;
+            try {
+                created = await sessions.create({
+                    parent: scope.parent,
+                    sessionId: safeResourceId(sessionId),
+                    requestBody: { ...body, userId },
+                });
+            }
+            catch (err) {
+                // Two writers opened the same conversation at once and the other one
+                // won. That is not a failure: the session exists now, which is all
+                // this call wanted, so the patch below writes our state onto it.
+                if (!isAlreadyExists(err))
+                    throw googleSdkFailure(ADAPTER, 'sessions.create', err);
+                try {
+                    await sessions.patch({ name, updateMask: maskFor(body), requestBody: body });
+                }
+                catch (patchErr) {
+                    throw googleSdkFailure(ADAPTER, 'sessions.patch', patchErr);
+                }
+                return;
+            }
+            // OUTSIDE the try on purpose: this refusal is already sanitized and
+            // already says what to do, and re-wrapping it would replace a precise
+            // diagnosis with a generic one.
+            await awaitOperation(ADAPTER, sessions.operations, created?.data, `creating session '${sessionId}'`, operationTimeoutMs);
+        },
+        async listByUser(userId, listOptions) {
+            open('list a user’s sessions');
+            const limit = Math.max(1, Math.floor(listOptions?.limit ?? DEFAULT_PAGE));
+            let page;
+            try {
+                page = (await sessions.list({
+                    parent: scope.parent,
+                    // The service's own filter over its own immutable field, with the
+                    // caller's id as a quoted literal — see quoteFilterValue.
+                    filter: `user_id=${quoteFilterValue(userId)}`,
+                    orderBy: 'update_time desc',
+                    pageSize: limit,
+                    ...(listOptions?.cursor !== undefined && { pageToken: listOptions.cursor }),
+                }))?.data;
+            }
+            catch (err) {
+                throw googleSdkFailure(ADAPTER, 'sessions.list', err);
+            }
+            const summaries = (page?.sessions ?? []).map((session) => {
+                const sessionId = lastSegment(session.name);
+                const stored = session.sessionState?.[SESSION_STATE_KEY];
+                // A listing must not fail because ONE row is unreadable — a sidebar
+                // that 500s over a corrupt conversation is worse than one that shows
+                // it with an honest zero. The transcript op reads the envelope itself
+                // and refuses there, which is where a reader can act on it.
+                const readable = stored !== null && typeof stored === 'object' ? stored : undefined;
+                return {
+                    sessionId,
+                    savedAt: toMillis(session.updateTime ?? session.createTime),
+                    format: formatOf(readable),
+                    messageCount: readable === undefined ? 0 : envelopeTranscript(readable).length,
+                };
+            });
+            const cursor = page?.nextPageToken;
+            return {
+                sessions: summaries,
+                ...(typeof cursor === 'string' && cursor !== '' && { cursor }),
+            };
+        },
+        async ownerOf(sessionId) {
+            open('read a session’s owner');
+            try {
+                const session = (await sessions.get({ name: nameOf(sessionId) }))?.data;
+                const userId = session?.userId;
+                // `undefined` for "no such session" AND for a session stored under the
+                // anonymous placeholder — the deliberate ambiguity the composer's one
+                // not-found rests on. A store that answered those differently would
+                // hand a caller an oracle for which session ids are real.
+                return typeof userId === 'string' && userId !== '' && userId !== DEFAULT_USER_ID
+                    ? userId
+                    : undefined;
+            }
+            catch (err) {
+                if (isNotFound(err))
+                    return undefined;
+                throw googleSdkFailure(ADAPTER, 'sessions.get', err);
+            }
+        },
+        async forget(sessionId) {
+            open('forget a session');
+            let deleted;
+            try {
+                deleted = await sessions.delete({ name: nameOf(sessionId) });
+            }
+            catch (err) {
+                // Already gone is the outcome this asked for.
+                if (isNotFound(err))
+                    return;
+                throw googleSdkFailure(ADAPTER, 'sessions.delete', err);
+            }
+            await awaitOperation(ADAPTER, sessions.operations, deleted?.data, `deleting session '${sessionId}'`, operationTimeoutMs);
+        },
+        close() {
+            closed = true;
+        },
+    };
+}
+// ─── Internals ───────────────────────────────────────────────────────
+/** How many rows one `listByUser` page carries when the caller names no limit. */
+const DEFAULT_PAGE = 50;
+/**
+ * A user id as an AIP-160 string literal — **backslash first, then the quote.**
+ *
+ * The order is the whole point. This grammar honours backslash escapes, so
+ * escaping only the quote leaves the escape character itself free to escape our
+ * escape: a user id of `\" OR user_id!=` renders as `user_id="\\" OR user_id!=""`,
+ * where `\\` is a literal backslash, the quote after it CLOSES the literal, and
+ * the rest of the id is filter syntax the service evaluates. The listing then
+ * matches every session with a non-empty user id and hands back other people's
+ * conversation ids, timestamps and message counts.
+ *
+ * The benign case matters too: any id merely ENDING in a backslash swallows the
+ * closing quote and the call fails with a malformed-filter 400 whose text
+ * {@link googleSdkFailure} withholds — a local error delivered as a censored
+ * remote one. Escaping the backslash first fixes both.
+ *
+ * A user id is caller data on every column of this library. It is never
+ * concatenated into a query language without passing through here.
+ */
+function quoteFilterValue(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+/**
+ * Resolve the immutable `userId` a session is created under.
+ *
+ * See {@link AgentEngineSessionsOptions.userId} for why the default reads the
+ * envelope rather than inventing anything.
+ */
+function userIdResolver(option) {
+    if (typeof option === 'function') {
+        return (sessionId, envelope) => {
+            const resolved = option(sessionId, envelope);
+            if (typeof resolved !== 'string' || resolved.trim() === '') {
+                throw new TypeError(`${ADAPTER}: the 'userId' resolver returned ${JSON.stringify(resolved)} for session ` +
+                    `'${sessionId}'. The service requires a non-empty user id on create and will not ` +
+                    `let it be changed afterwards, so this refuses rather than storing the ` +
+                    `conversation under a name nobody chose.\n` +
+                    `  Return '${DEFAULT_USER_ID}' explicitly if an anonymous conversation is what ` +
+                    `you mean.`);
+            }
+            return resolved;
+        };
+    }
+    if (typeof option === 'string') {
+        if (option.trim() === '') {
+            throw new TypeError(`${ADAPTER}: 'userId' was an empty string. The service requires one on create and ` +
+                `treats it as immutable. Pass a real id, a resolver function, or leave it unset to ` +
+                `derive the owner from the conversation itself.`);
+        }
+        return () => option;
+    }
+    // The default: the principal the conversation was signed with, so the
+    // service's owner and this library's own ownership index agree.
+    return (_sessionId, envelope) => envelopeOwner(envelope) ?? DEFAULT_USER_ID;
+}
+/**
+ * The update mask for a patch.
+ *
+ * A patch with no mask REPLACES the resource, which would clear `userId` — and
+ * `userId` is immutable, so the service refuses the write and the conversation
+ * silently stops persisting. Naming the fields we own is the whole fix.
+ */
+function maskFor(body) {
+    const fields = ['sessionState'];
+    if (body.ttl !== undefined)
+        fields.push('ttl');
+    return fields.join(',');
+}
+/** The id out of a resource name, which is everything after the last `/`. */
+function lastSegment(name) {
+    if (typeof name !== 'string')
+        return '';
+    const at = name.lastIndexOf('/');
+    return at === -1 ? name : name.slice(at + 1);
+}
+/** An RFC 3339 timestamp as unix milliseconds, or 0 when it is not one. */
+function toMillis(value) {
+    if (typeof value !== 'string')
+        return 0;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : 0;
+}
+/** The stored envelope's `format`, without trusting it to be one of ours. */
+function formatOf(stored) {
+    const format = stored?.format;
+    return typeof format === 'string' ? format : 'unknown';
+}
+//# sourceMappingURL=googleAgentEngine.js.map

package/dist/esm/adapters/hosting/googleAgentEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"googleAgentEngine.js","sourceRoot":"","sources":["../../../../src/adapters/hosting/googleAgentEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAEH,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AAC7F,OAAO,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAOlE,OAAO,EACL,cAAc,EACd,qBAAqB,EACrB,4BAA4B,EAC5B,gBAAgB,EAChB,eAAe,EACf,UAAU,EACV,aAAa,EACb,cAAc,GAMf,MAAM,yBAAyB,CAAC;AAEjC,MAAM,OAAO,GAAG,qBAAqB,CAAC;AAEtC;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,yBAAyB,CAAC;AAgD3D,6DAA6D;AAC7D,MAAM,CAAC,MAAM,eAAe,GAAG,0BAA0B,CAAC;AA0B1D;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,mBAAmB,CAAC,OAAmC;IACrE,MAAM,KAAK,GAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC3D,MAAM,MAAM,GAAyB,qBAAqB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,CAAC;IACpF,MAAM,QAAQ,GAAgB,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,gBAAgB,CAAC,QAAQ,CAAC;IAClF,MAAM,kBAAkB,GAAG,OAAO,CAAC,kBAAkB,IAAI,4BAA4B,CAAC;IACtF,MAAM,aAAa,GAAG,cAAc,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAErD,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,MAAM,IAAI,GAAG,CAAC,IAAY,EAAQ,EAAE;QAClC,IAAI,CAAC,MAAM;YAAE,OAAO;QACpB,MAAM,IAAI,KAAK,CACb,iBAAiB,OAAO,eAAe,KAAK,CAAC,MAAM,6BAA6B,IAAI,IAAI;YACtF,sFAAsF;YACtF,mFAAmF,CACtF,CAAC;IACJ,CAAC,CAAC;IAEF,MAAM,MAAM,GAAG,CAAC,SAAiB,EAAU,EAAE,CAC3C,GAAG,KAAK,CAAC,MAAM,aAAa,cAAc,CAAC,SAAS,CAAC,EAAE,CAAC;IAE1D,OAAO;QACL,MAAM,EAAE,KAAK,CAAC,MAAM;QAEpB,KAAK,CAAC,OAAO,CAAC,SAAiB;YAC7B,IAAI,CAAC,mBAAmB,CAAC,CAAC;YAC1B,IAAI,OAAkC,CAAC;YACvC,IAAI,CAAC;gBACH,OAAO,GAAG,CAAC,MAAM,QAAQ,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,CAAC;YACpE,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,qEAAqE;gBACrE,uEAAuE;gBACvE,eAAe;gBACf,IAAI,UAAU,CAAC,GAAG,CAAC;oBAAE,OAAO,SAAS,CAAC;gBACtC,MAAM,gBAAgB,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,CAAC,CAAC;YACvD,CAAC;YACD,IAAI,OAAO,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC;YAE5C,MAAM,KAAK,GAAG,OAAO,CAAC,YAAY,CAAC;YACnC,sEAAsE;YACtE,mEAAmE;YACnE,qDAAqD;YACrD,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC;YAC5D,MAAM,MAAM,GAAG,KAAK,CAAC,iBAAiB,CAAC,CAAC;YACxC,IAAI,MAAM,KAAK,SAAS;gBAAE,OAAO,SAAS,CAAC;YAC3C,yEAAyE;YACzE,yDAAyD;YACzD,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;gBAClD,MAAM,IAAI,uBAAuB,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;YACvD,CAAC;YACD,wEAAwE;YACxE,uEAAuE;YACvE,OAAO,aAAa,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;QAC1C,CAAC;QAED,KAAK,CAAC,OAAO,CAAC,SAAiB,EAAE,QAA4B;YAC3D,IAAI,CAAC,mBAAmB,CAAC,CAAC;YAC1B,uEAAuE;YACvE,+CAA+C;YAC/C,MAAM,OAAO,GAAG,aAAa,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC;YACnD,MAAM,IAAI,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;YAC/B,MAAM,IAAI,GAAkB;gBAC1B,YAAY,EAAE,EAAE,CAAC,iBAAiB,CAAC,EAAE,OAA6C,EAAE;gBACpF,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;aACvD,CAAC;YAEF,gEAAgE;YAChE,EAAE;YACF,uEAAuE;YACvE,sEAAsE;YACtE,wEAAwE;YACxE,uEAAuE;YACvE,sCAAsC;YACtC,IAAI,CAAC;gBACH,MAAM,QAAQ,CAAC,KAAK,CAAC;oBACnB,IAAI;oBACJ,qEAAqE;oBACrE,mEAAmE;oBACnE,mEAAmE;oBACnE,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC;oBACzB,WAAW,EAAE,IAAI;iBAClB,CAAC,CAAC;gBACH,OAAO;YACT,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;oBAAE,MAAM,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,CAAC,CAAC;YAC/E,CAAC;YAED,MAAM,MAAM,GAAG,aAAa,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;YACjD,IAAI,OAAO,CAAC;YACZ,IAAI,CAAC;gBACH,OAAO,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC;oBAC9B,MAAM,EAAE,KAAK,CAAC,MAAM;oBACpB,SAAS,EAAE,cAAc,CAAC,SAAS,CAAC;oBACpC,WAAW,EAAE,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE;iBACjC,CAAC,CAAC;YACL,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,qEAAqE;gBACrE,mEAAmE;gBACnE,iEAAiE;gBACjE,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC;oBAAE,MAAM,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,EAAE,GAAG,CAAC,CAAC;gBACnF,IAAI,CAAC;oBACH,MAAM,QAAQ,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC/E,CAAC;gBAAC,OAAO,QAAQ,EAAE,CAAC;oBAClB,MAAM,gBAAgB,CAAC,OAAO,EAAE,gBAAgB,EAAE,QAAQ,CAAC,CAAC;gBAC9D,CAAC;gBACD,OAAO;YACT,CAAC;YACD,oEAAoE;YACpE,sEAAsE;YACtE,gCAAgC;YAChC,MAAM,cAAc,CAClB,OAAO,EACP,QAAQ,CAAC,UAAU,EACnB,OAAO,EAAE,IAAI,EACb,qBAAqB,SAAS,GAAG,EACjC,kBAAkB,CACnB,CAAC;QACJ,CAAC;QAED,KAAK,CAAC,UAAU,CAAC,MAAc,EAAE,WAAgC;YAC/D,IAAI,CAAC,wBAAwB,CAAC,CAAC;YAC/B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,IAAI,YAAY,CAAC,CAAC,CAAC;YAC1E,IAAI,IAAI,CAAC;YACT,IAAI,CAAC;gBACH,IAAI,GAAG,CACL,MAAM,QAAQ,CAAC,IAAI,CAAC;oBAClB,MAAM,EAAE,KAAK,CAAC,MAAM;oBACpB,kEAAkE;oBAClE,0DAA0D;oBAC1D,MAAM,EAAE,WAAW,gBAAgB,CAAC,MAAM,CAAC,EAAE;oBAC7C,OAAO,EAAE,kBAAkB;oBAC3B,QAAQ,EAAE,KAAK;oBACf,GAAG,CAAC,WAAW,EAAE,MAAM,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,CAAC;iBAC5E,CAAC,CACH,EAAE,IAAI,CAAC;YACV,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,gBAAgB,CAAC,OAAO,EAAE,eAAe,EAAE,GAAG,CAAC,CAAC;YACxD,CAAC;YAED,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,QAAQ,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE;gBACvD,MAAM,SAAS,GAAG,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;gBAC5C,MAAM,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,iBAAiB,CAAC,CAAC;gBACzD,oEAAoE;gBACpE,qEAAqE;gBACrE,sEAAsE;gBACtE,4DAA4D;gBAC5D,MAAM,QAAQ,GAAG,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;gBACpF,OAAO;oBACL,SAAS;oBACT,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,UAAU,CAAC;oBAC3D,MAAM,EAAE,QAAQ,CAAC,QAAQ,CAAC;oBAC1B,YAAY,EAAE,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAC,MAAM;iBAC/E,CAAC;YACJ,CAAC,CAAC,CAAC;YAEH,MAAM,MAAM,GAAG,IAAI,EAAE,aAAa,CAAC;YACnC,OAAO;gBACL,QAAQ,EAAE,SAAS;gBACnB,GAAG,CAAC,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;aAC/D,CAAC;QACJ,CAAC;QAED,KAAK,CAAC,OAAO,CAAC,SAAiB;YAC7B,IAAI,CAAC,wBAAwB,CAAC,CAAC;YAC/B,IAAI,CAAC;gBACH,MAAM,OAAO,GAAG,CAAC,MAAM,QAAQ,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,CAAC;gBACxE,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,CAAC;gBAC/B,uEAAuE;gBACvE,sEAAsE;gBACtE,oEAAoE;gBACpE,0DAA0D;gBAC1D,OAAO,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,EAAE,IAAI,MAAM,KAAK,eAAe;oBAC9E,CAAC,CAAC,MAAM;oBACR,CAAC,CAAC,SAAS,CAAC;YAChB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,UAAU,CAAC,GAAG,CAAC;oBAAE,OAAO,SAAS,CAAC;gBACtC,MAAM,gBAAgB,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,CAAC,CAAC;YACvD,CAAC;QACH,CAAC;QAED,KAAK,CAAC,MAAM,CAAC,SAAiB;YAC5B,IAAI,CAAC,kBAAkB,CAAC,CAAC;YACzB,IAAI,OAAO,CAAC;YACZ,IAAI,CAAC;gBACH,OAAO,GAAG,MAAM,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;YAC/D,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,8CAA8C;gBAC9C,IAAI,UAAU,CAAC,GAAG,CAAC;oBAAE,OAAO;gBAC5B,MAAM,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,EAAE,GAAG,CAAC,CAAC;YAC1D,CAAC;YACD,MAAM,cAAc,CAClB,OAAO,EACP,QAAQ,CAAC,UAAU,EACnB,OAAO,EAAE,IAAI,EACb,qBAAqB,SAAS,GAAG,EACjC,kBAAkB,CACnB,CAAC;QACJ,CAAC;QAED,KAAK;YACH,MAAM,GAAG,IAAI,CAAC;QAChB,CAAC;KACF,CAAC;AACJ,CAAC;AAED,wEAAwE;AAExE,kFAAkF;AAClF,MAAM,YAAY,GAAG,EAAE,CAAC;AAExB;;;;;;;;;;;;;;;;;;GAkBG;AACH,SAAS,gBAAgB,CAAC,KAAa;IACrC,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC;AAClE,CAAC;AAED;;;;;GAKG;AACH,SAAS,cAAc,CACrB,MAA4C;IAE5C,IAAI,OAAO,MAAM,KAAK,UAAU,EAAE,CAAC;QACjC,OAAO,CAAC,SAAS,EAAE,QAAQ,EAAE,EAAE;YAC7B,MAAM,QAAQ,GAAG,MAAM,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;YAC7C,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;gBAC3D,MAAM,IAAI,SAAS,CACjB,GAAG,OAAO,oCAAoC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,eAAe;oBACnF,IAAI,SAAS,qEAAqE;oBAClF,wEAAwE;oBACxE,2CAA2C;oBAC3C,aAAa,eAAe,oDAAoD;oBAChF,WAAW,CACd,CAAC;YACJ,CAAC;YACD,OAAO,QAAQ,CAAC;QAClB,CAAC,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,IAAI,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;YACzB,MAAM,IAAI,SAAS,CACjB,GAAG,OAAO,yEAAyE;gBACjF,oFAAoF;gBACpF,gDAAgD,CACnD,CAAC;QACJ,CAAC;QACD,OAAO,GAAG,EAAE,CAAC,MAAM,CAAC;IACtB,CAAC;IACD,sEAAsE;IACtE,gEAAgE;IAChE,OAAO,CAAC,UAAU,EAAE,QAAQ,EAAE,EAAE,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,eAAe,CAAC;AAC9E,CAAC;AAED;;;;;;GAMG;AACH,SAAS,OAAO,CAAC,IAAmB;IAClC,MAAM,MAAM,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC,IAAI,IAAI,CAAC,GAAG,KAAK,SAAS;QAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC/C,OAAO,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC1B,CAAC;AAED,6EAA6E;AAC7E,SAAS,WAAW,CAAC,IAA+B;IAClD,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,EAAE,CAAC;IACxC,MAAM,EAAE,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IACjC,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;AAC/C,CAAC;AAED,2EAA2E;AAC3E,SAAS,QAAQ,CAAC,KAAgC;IAChD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACjC,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED,6EAA6E;AAC7E,SAAS,QAAQ,CAAC,MAAe;IAC/B,MAAM,MAAM,GAAI,MAA2C,EAAE,MAAM,CAAC;IACpE,OAAO,OAAO,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;AACzD,CAAC"}

package/dist/esm/adapters/identity/google.d.ts

@@ -0,0 +1,179 @@
+/**
+ * googleIdentity — the {@link CredentialProvider} port over Google's own
+ * credential machinery (peer-dep `google-auth-library`).
+ *
+ *   import { googleIdentity } from 'agentfootprint/security';
+ *   const credentials = googleIdentity();
+ *
+ * ── What it is, and what it deliberately is not ─────────────────────────────
+ * This is the **narrow** adapter: it vends *Google* access tokens for *Google*
+ * APIs, from whatever credential the environment already has — Application
+ * Default Credentials on Cloud Run or GKE, a workload-identity federation
+ * config, a service account, optionally impersonating another service account.
+ * That is one job and it is done completely.
+ *
+ * It is **not** a token vault and does not pretend to be one. The other
+ * column's identity adapter can vend a *GitHub* token for a *user* because
+ * that service runs a vault with per-user OAuth grants behind it. Google's
+ * equivalent — the Agent Identity auth manager — is Preview with no Node
+ * surface, so `mode: 'user'` here is **refused by name** rather than quietly
+ * served with a machine token. A machine token returned where a user token was
+ * asked for is the exact silent downgrade the port exists to prevent: the call
+ * succeeds, the data comes back, and it was the agent's access rather than the
+ * person's. See {@link googleIdentity} for the refusal's wording.
+ *
+ * ── The one-hour fact, and where it bites ───────────────────────────────────
+ * A Google OAuth access token lives about an hour. That is fine wherever the
+ * credential is fetched per use — which is how `ctx.credential` works, so the
+ * ordinary path is unaffected. It bites in exactly one place, and it is worth
+ * naming because it looks like it should work:
+ *
+ * > **The OpenAI-compatible endpoint trap.** Google publishes an
+ * > OpenAI-compatible Gemini endpoint, and `openai({ baseURL, apiKey })` does
+ * > reach it. If you fill that `apiKey` with a token from here, it works for
+ * > an hour and then every call fails with a 401 — because `apiKey` is a
+ * > STRING captured when the provider is constructed, and a long-lived agent
+ * > process outlives it. There is no refresh home in the OpenAI provider's
+ * > options for a credential that expires. Use the native `gemini()` provider,
+ * > which reads ADC through the SDK and refreshes underneath you.
+ *
+ * `expiresAt` is reported on every issued credential so a caller that caches
+ * one can tell. This adapter never caches: {@link CachedGoogleClient} keeps
+ * the *client*, and the client's own refresh logic keeps the token fresh.
+ *
+ * ── Secrets ─────────────────────────────────────────────────────────────────
+ * The `sdkFailure` law, same as every other credential-touching adapter here:
+ * the library's own message never comes through, because auth libraries echo
+ * request detail into failure text and a message thrown from a
+ * `CredentialProvider` reaches the LLM as a tool result AND rides
+ * `agentfootprint.credential.failed` to every sink. What comes through is the
+ * operation that failed and the error's NAME. The original is not attached as
+ * `cause` — a cause travels into every serializer that walks own properties,
+ * which would undo all of it in one `JSON.stringify`.
+ *
+ * Pattern: Adapter (GoF) + lazy peer-dep load — `google-auth-library` is
+ * required the first time `getCredential` runs, or never if you inject one.
+ */
+import type { CredentialProvider } from '../../identity/types.js';
+/** The scope every Google Cloud data-plane API accepts. */
+export declare const CLOUD_PLATFORM_SCOPE = "https://www.googleapis.com/auth/cloud-platform";
+/**
+ * The slice of an auth client this adapter calls — a `GoogleAuth`, an
+ * `OAuth2Client` and an `Impersonated` all satisfy it, which is why nothing
+ * here switches on which one it has.
+ */
+export interface GoogleAuthClientLike {
+    /** The current access token, refreshed if the library thinks it is stale. */
+    getAccessToken(): Promise<{
+        token?: string | null;
+    } | string | null | undefined>;
+    /** Where the library records the expiry it knows about, in unix ms. */
+    readonly credentials?: {
+        readonly expiry_date?: number | null;
+    };
+}
+/** The slice of a `GoogleAuth` this adapter calls. */
+export interface GoogleAuthLike {
+    getClient(): Promise<GoogleAuthClientLike>;
+}
+/** The slice of `google-auth-library` this adapter loads. */
+export interface GoogleAuthSdkModule {
+    readonly GoogleAuth?: new (options: {
+        scopes?: readonly string[];
+    }) => GoogleAuthLike;
+    readonly Impersonated?: new (options: {
+        sourceClient: GoogleAuthClientLike;
+        targetPrincipal: string;
+        targetScopes: string[];
+        delegates?: string[];
+        lifetime?: number;
+    }) => GoogleAuthClientLike;
+}
+/** Impersonate another service account for the tokens this provider vends. */
+export interface GoogleImpersonation {
+    /**
+     * The service account to act as, e.g.
+     * `'agent-runner@my-project.iam.gserviceaccount.com'`. The credential the
+     * environment already has must hold `roles/iam.serviceAccountTokenCreator`
+     * on it; without that the exchange fails with a 403 whose text this adapter
+     * withholds, so the permission is worth checking before you wonder why.
+     */
+    readonly targetPrincipal: string;
+    /** A delegation chain, when one account cannot impersonate the target directly. */
+    readonly delegates?: readonly string[];
+    /**
+     * How long the impersonated token lives, in seconds. The service's own
+     * ceiling is 3600 (one hour) unless the org policy raises it, and asking for
+     * more than it allows is refused by Google rather than clamped.
+     */
+    readonly lifetimeSeconds?: number;
+}
+/** Options for {@link googleIdentity}. */
+export interface GoogleIdentityOptions {
+    /**
+     * The OAuth scopes to request. Default `[cloud-platform]`, which is what
+     * every Google Cloud data-plane API accepts.
+     *
+     * A request's own `scopes` win when it names any — a tool that knows it only
+     * needs read access should say so, and this is where that is honoured.
+     */
+    readonly scopes?: readonly string[];
+    /**
+     * Act as another service account. Off by default; see
+     * {@link GoogleImpersonation}.
+     */
+    readonly impersonate?: GoogleImpersonation;
+    /**
+     * Which downstream services this provider will answer for.
+     *
+     * Unset — the default — it answers for ANY `service`, because the token it
+     * vends is a Google credential and the caller knows better than this adapter
+     * which Google API they are about to call.
+     *
+     * Set it and a request for a service outside the list is refused BY NAME
+     * rather than served. That is the useful setting in a deployment where tools
+     * declare `needs: [{ credential: 'github' }]` alongside Google ones: without
+     * it, this provider would happily hand a Google access token to the tool
+     * that wanted a GitHub one, and the failure would surface as a puzzling 401
+     * from GitHub rather than as a wiring error here.
+     */
+    readonly services?: readonly string[];
+    /** Stable provider id (default `'google-identity'`). */
+    readonly id?: string;
+    /**
+     * @internal Test seam — a pre-built auth client. Bypasses the SDK entirely,
+     * so the suite runs with no package and no credential.
+     */
+    readonly _client?: GoogleAuthClientLike;
+    /** @internal Test seam — the SDK module, to exercise the real construction. */
+    readonly _sdk?: GoogleAuthSdkModule;
+}
+/**
+ * Vend Google access tokens from whatever credential this environment has.
+ *
+ * **Status: contract-shaped and tested; awaiting field use.** Every path is
+ * exercised through an injected client and the loaded surface is pinned
+ * against the really-installed package. None of it has yet answered a real
+ * Google token request in a live project.
+ *
+ * @throws when `mode: 'user'` is requested — Google's per-user token vault has
+ *   no Node surface, and a machine token returned in its place would be a
+ *   silent downgrade.
+ * @throws when `services` is configured and the request names another one.
+ *
+ * @example  A tool that calls a Google API with the deployment's own identity
+ *   const agent = Agent.create({ provider, credentials: googleIdentity() })
+ *     .tool(defineTool({
+ *       name: 'read_sheet',
+ *       needs: [{ credential: 'sheets', scopes: ['https://www.googleapis.com/auth/spreadsheets.readonly'] }],
+ *       execute: async (args, ctx) =>
+ *         fetch(url, { headers: ctx.credential!.toHeaders() }).then((r) => r.text()),
+ *     }))
+ *     .build();
+ *
+ * @example  Acting as a dedicated service account
+ *   googleIdentity({
+ *     impersonate: { targetPrincipal: 'agent-runner@my-project.iam.gserviceaccount.com' },
+ *   });
+ */
+export declare function googleIdentity(options?: GoogleIdentityOptions): CredentialProvider;