agentfootprint 9.26.0 → 9.28.0

package/dist/esm/adapters/google/aiPlatform.js

@@ -0,0 +1,424 @@
+/**
+ * adapters/google/aiPlatform — the one place this package builds a Vertex AI
+ * REST client, names a Vertex resource, waits on a Vertex operation, or
+ * describes a Vertex failure.
+ *
+ * Three adapters sit on top of it — `agentEngineSessions`, `memoryBankStore`
+ * and (for its auth half only) `googleIdentity` — and none of them repeats any
+ * of the four things above. That is the whole reason this file exists: the AWS
+ * column learned, expensively, that a shim duplicated across three adapters is
+ * three places for the same wire fact to go stale, and only one of them gets
+ * fixed.
+ *
+ * ── Which client, and why THIS one ──────────────────────────────────────────
+ * `@googleapis/aiplatform` — the **split, per-API** discovery package (31.0.0,
+ * 27 MB) rather than the `googleapis` mega-package (174.0.1, 209 MB) that
+ * carries every Google API at once for the same generated code. Both were
+ * installed and measured before this was written.
+ *
+ * The gax/proto client (`@google-cloud/aiplatform`, 78 MB) was rejected on a
+ * fact rather than on size: its Memory Bank surface is **v1beta1 only**, while
+ * the REST **v1** surface is complete — `memories.purge` and `memories.rollback`
+ * exist at v1 and do not exist at v1beta1. One client, at the version that has
+ * everything, beats two clients at two versions.
+ *
+ * `@google-cloud/vertexai` is past its own announced removal date and is not
+ * loaded anywhere in this package, ever.
+ *
+ * ── The endpoint fact that is not in anybody's design doc ───────────────────
+ * The generated client defaults to `https://aiplatform.googleapis.com/` — the
+ * GLOBAL host. Reasoning engines, their sessions and their memories are
+ * **regional** resources. An adapter that accepts the default calls the wrong
+ * host and gets a 404 that reads exactly like "your resource does not exist".
+ * So {@link buildAiPlatformClient} always sets a regional `rootUrl`, derived
+ * from the same `location` that composes the resource name, and the surface pin
+ * asserts the default really is the global one so this comment cannot go stale
+ * quietly.
+ *
+ * ── Secrets ─────────────────────────────────────────────────────────────────
+ * {@link googleSdkFailure} is the `sdkFailure` law from the AWS identity
+ * adapter, re-aimed at a Gaxios error: the SDK's own message never comes
+ * through. It is not that a Vertex error always contains a secret — it is that
+ * a REST client echoes the request into failure text, our requests carry
+ * conversation state and access tokens, and an error message here reaches the
+ * model as a tool result AND rides the event stream to every sink attached.
+ * One echo publishes it to both at once.
+ */
+import { lazyRequire } from '../../lib/lazyRequire.js';
+// ─── Connection ──────────────────────────────────────────────────────
+/**
+ * The API version every adapter in this column dials, **stated rather than
+ * defaulted**.
+ *
+ * v1, not v1beta1, and that is a decision with evidence behind it: at v1 the
+ * memories collection carries `purge` and `rollback`; at v1beta1 it does not.
+ * The Google column's pin asserts this against the installed package on every
+ * test run, because "which version does this really call" is the question that
+ * made the pin exist.
+ */
+export const AI_PLATFORM_API_VERSION = 'v1';
+/** The OAuth scope every Vertex data-plane call needs. */
+export const CLOUD_PLATFORM_SCOPE = 'https://www.googleapis.com/auth/cloud-platform';
+const ENGINE_NAME = /^projects\/([^/]+)\/locations\/([^/]+)\/reasoningEngines\/([^/]+)$/;
+/**
+ * Work out which reasoning engine this adapter talks to, from either spelling
+ * of `reasoningEngine`.
+ *
+ * A full resource name wins over `project` / `location` and is CHECKED against
+ * them rather than silently overriding: two spellings of one fact that could
+ * disagree is the same law the builder refuses `agent` beside `agentFactory`
+ * under, and a name that says `us-central1` under a config that says
+ * `europe-west4` is a bug somebody should be told about, not arbitrated.
+ */
+export function resolveEngine(adapter, connection) {
+    const { reasoningEngine, location } = connection;
+    if (typeof reasoningEngine !== 'string' || reasoningEngine.trim() === '') {
+        throw new TypeError(`${adapter} requires 'reasoningEngine' — the id of the Agent Runtime resource these ` +
+            `live under, or its full resource name.\n` +
+            `  Sessions and memories are CHILDREN of a reasoning engine; there is nowhere else ` +
+            `to put them, so one has to exist even if you deploy no code to it.\n` +
+            `  Creating it is a control-plane job (gcloud / Terraform / the console) that this ` +
+            `library deliberately does not do.`);
+    }
+    const match = ENGINE_NAME.exec(reasoningEngine.trim());
+    if (match) {
+        const [, project, engineLocation, engineId] = match;
+        if (connection.project !== undefined && connection.project !== project) {
+            throw new TypeError(`${adapter}: 'reasoningEngine' names project '${project}' but 'project' says ` +
+                `'${connection.project}'. Two spellings of one fact that disagree are refused rather ` +
+                `than arbitrated — drop one of them.`);
+        }
+        if (location !== undefined && location !== engineLocation) {
+            throw new TypeError(`${adapter}: 'reasoningEngine' names location '${engineLocation}' but 'location' says ` +
+                `'${location}'. The location picks the regional host as well as the resource name, ` +
+                `so a mismatch would call one region for a resource that lives in another. Drop one.`);
+        }
+        return { project, location: engineLocation, engineId, parent: reasoningEngine.trim() };
+    }
+    const project = connection.project ?? readEnv('GOOGLE_CLOUD_PROJECT');
+    if (project === undefined || project === '') {
+        throw new TypeError(`${adapter} requires 'project' — no project was configured and GOOGLE_CLOUD_PROJECT is ` +
+            `not set.\n` +
+            `  Pass it, set the environment variable, or give 'reasoningEngine' as a full resource ` +
+            `name ('projects/…/locations/…/reasoningEngines/…'), which carries the project with it.`);
+    }
+    if (typeof location !== 'string' || location.trim() === '') {
+        throw new TypeError(`${adapter} requires 'location' (e.g. 'us-central1'). There is no default, on purpose: ` +
+            `it selects the REGIONAL API host as well as composing the resource name, so a guess ` +
+            `does not fail — it calls a different region and answers "not found".`);
+    }
+    const engineId = reasoningEngine.trim();
+    return {
+        project,
+        location: location.trim(),
+        engineId,
+        parent: `projects/${project}/locations/${location.trim()}/reasoningEngines/${engineId}`,
+    };
+}
+/** `process.env` without assuming `process` exists (browser bundles do not have one). */
+function readEnv(name) {
+    return typeof process !== 'undefined' && process.env ? process.env[name] : undefined;
+}
+/**
+ * The regional host for a location.
+ *
+ * See the module header: the client's own default is the global host, and
+ * these resources are regional. This is the fix, in one line, applied at every
+ * construction.
+ */
+export function regionalRootUrl(location) {
+    return `https://${location}-aiplatform.googleapis.com/`;
+}
+/**
+ * Build the REST client, or refuse by name.
+ *
+ * An injected `_client` short-circuits everything below it, which is how every
+ * test in this column runs with no package installed and no credential.
+ */
+export function buildAiPlatformClient(adapter, connection, scope) {
+    if (connection._client)
+        return connection._client;
+    let mod;
+    if (connection._sdk) {
+        mod = connection._sdk;
+    }
+    else {
+        try {
+            mod = lazyRequire('@googleapis/aiplatform');
+        }
+        catch {
+            throw new Error(`${adapter} requires the \`@googleapis/aiplatform\` peer dependency.\n` +
+                `  Install:  npm install @googleapis/aiplatform\n` +
+                `  It is the SPLIT per-API package (~27 MB), not the \`googleapis\` mega-package ` +
+                `(~209 MB) that carries every Google API for the same generated code.\n` +
+                `  It is optional and loaded only when you construct this adapter, so nothing else ` +
+                `in this library pays for it.`);
+        }
+    }
+    if (typeof mod.aiplatform !== 'function') {
+        throw new Error(`${adapter}: \`@googleapis/aiplatform\` is installed but exports no \`aiplatform\` ` +
+            `factory. This adapter is built against the 31.x package — update it, or pass a ` +
+            `pre-built client.`);
+    }
+    const auth = connection.auth ?? defaultAuth(adapter, mod);
+    return mod.aiplatform({
+        version: AI_PLATFORM_API_VERSION,
+        // Never the client's global default — see the module header.
+        rootUrl: regionalRootUrl(scope.location),
+        auth,
+    });
+}
+/**
+ * Application Default Credentials, from the SDK's own re-exported auth surface.
+ *
+ * Taken from `@googleapis/aiplatform` rather than by loading
+ * `google-auth-library` separately: the package already carries it, and one
+ * load is one version to reason about instead of two that can drift apart.
+ */
+function defaultAuth(adapter, mod) {
+    const GoogleAuth = mod.auth?.GoogleAuth;
+    if (typeof GoogleAuth !== 'function') {
+        throw new Error(`${adapter}: \`@googleapis/aiplatform\` exposes no \`auth.GoogleAuth\`, so Application ` +
+            `Default Credentials cannot be resolved.\n` +
+            `  Pass 'auth' with your own GoogleAuth / OAuth2Client, or update the package.`);
+    }
+    return new GoogleAuth({ scopes: [CLOUD_PLATFORM_SCOPE] });
+}
+// ─── Long-running operations ─────────────────────────────────────────
+/** How long {@link awaitOperation} keeps waiting before it refuses, by default. */
+export const DEFAULT_OPERATION_TIMEOUT_MS = 30_000;
+/** One server-side wait, in the duration spelling the API takes. */
+const WAIT_SLICE = '10s';
+/**
+ * Wait for a long-running operation to finish, or refuse by name.
+ *
+ * ── Why any of this exists ──────────────────────────────────────────────────
+ * `sessions.create`, `sessions.delete`, `memories.create`, `memories.patch`
+ * and `memories.delete` **all answer with an Operation, not with the resource**
+ * — verified against the installed package's own return types before a line of
+ * either adapter was written. `get`, `list`, `patch`-on-a-session and
+ * `retrieve` are the synchronous ones.
+ *
+ * That asymmetry is the trap: a `put` that returns as soon as the service
+ * accepts the request, followed by a `get`, is a race that passes on a warm
+ * day and fails under load — and fails by answering "no data", which is
+ * indistinguishable from the truth. So every write in this column goes through
+ * here and does not return until the service says `done`.
+ *
+ * An operation that finished with an error is raised as one. The operation's
+ * own message is a Google-side description of OUR request, so it is subject to
+ * the same secrecy law as everything else here: the code comes through, the
+ * text does not.
+ */
+export async function awaitOperation(adapter, operations, operation, what, timeoutMs = DEFAULT_OPERATION_TIMEOUT_MS) {
+    if (operation === undefined)
+        return;
+    // Some services answer an already-finished operation on the first call. That
+    // is the common case for a small write, and it costs no round trip.
+    if (operation.done === true) {
+        throwIfOperationFailed(adapter, operation, what);
+        return;
+    }
+    const name = operation.name;
+    if (typeof name !== 'string' || name === '') {
+        // Nothing to wait ON. Answering as though the write had landed would be
+        // exactly the silent success this whole function exists to prevent.
+        throw operationError(`${adapter}: ${what} was accepted but the service returned an operation with no name, ` +
+            `so there is nothing to wait on and no way to confirm the write landed.\n` +
+            `  Refusing rather than reporting a success this adapter cannot verify.`);
+    }
+    const deadline = Date.now() + Math.max(0, timeoutMs);
+    let current = operation;
+    while (current.done !== true) {
+        if (Date.now() >= deadline) {
+            throw operationError(`${adapter}: ${what} did not finish within ${timeoutMs}ms.\n` +
+                `  The operation is still running on Google's side — it may yet succeed — but this ` +
+                `call will not report a write it has not seen land.\n` +
+                `  Raise the adapter's 'operationTimeoutMs' if your engine is routinely slower.`);
+        }
+        const answer = await operations.wait({ name, timeout: WAIT_SLICE });
+        current = answer?.data ?? {};
+    }
+    throwIfOperationFailed(adapter, current, what);
+}
+function throwIfOperationFailed(adapter, operation, what) {
+    const error = operation.error;
+    if (error === null || error === undefined)
+        return;
+    const code = typeof error.code === 'number' ? ` (code ${error.code})` : '';
+    throw operationError(`${adapter}: ${what} failed${code}.\n` +
+        `  The operation's own message is withheld: it is Google's description of OUR request, ` +
+        `and this request carried conversation state. Check Cloud Logging for the full text.`);
+}
+/**
+ * The name every refusal from this function carries.
+ *
+ * It exists so a caller's `catch` can tell "the operation went wrong" — which
+ * is already sanitized and already says what to do — apart from "the transport
+ * went wrong", which still needs {@link googleSdkFailure} run over it. Without
+ * the distinction an adapter re-wraps its own refusal and replaces a precise
+ * diagnosis ("did not finish within 30000ms") with a generic one.
+ */
+export const OPERATION_ERROR_NAME = 'GoogleOperationError';
+function operationError(message) {
+    const err = new Error(message);
+    err.name = OPERATION_ERROR_NAME;
+    return err;
+}
+/**
+ * Has this error already been sanitized by this module? Used by every adapter's
+ * `catch` so a refusal is reported once rather than wrapped twice.
+ */
+export function isSanitizedGoogleError(err) {
+    return (err instanceof Error && (err.name === OPERATION_ERROR_NAME || err.name === 'GoogleApiError'));
+}
+// ─── Failures ────────────────────────────────────────────────────────
+/**
+ * Re-raise a failed REST call **without its text** — the `sdkFailure` law from
+ * the AWS identity adapter, re-aimed at a Gaxios error.
+ *
+ * What comes through is the part that is both safe and actionable: which
+ * operation failed and the HTTP status. What does not is the message, because
+ * a REST client echoes the request into its failure text and these requests
+ * carry a whole conversation's state, a user id, and an access token in the
+ * headers. A thrown message here reaches the LLM as a tool result AND rides the
+ * event stream to every sink attached to the agent.
+ *
+ * **The original is deliberately not attached as `cause`** — a cause travels
+ * with the error into every serializer that walks own properties, which would
+ * undo all of this in one `JSON.stringify`.
+ */
+export function googleSdkFailure(adapter, operation, err) {
+    const status = httpStatusOf(err);
+    const failure = new Error(`${adapter}: ${operation} failed` +
+        (status === undefined ? '' : ` (HTTP ${status})`) +
+        `.\n  The SDK's own message is withheld: this request carried session state and an ` +
+        `access token, and REST clients echo request detail into failure text. Check Cloud ` +
+        `Logging for the full error.`);
+    failure.name = 'GoogleApiError';
+    return failure;
+}
+/**
+ * The HTTP status of a failed call, wherever this client happened to put it.
+ *
+ * Three places rather than one because the client reports a transport failure,
+ * an API error and a thrown `GaxiosError` slightly differently, and a
+ * classification that only reads one of them silently stops classifying the
+ * day the client is upgraded.
+ */
+export function httpStatusOf(err) {
+    const e = err;
+    if (e === null || typeof e !== 'object')
+        return undefined;
+    for (const candidate of [e.status, e.code, e.response?.status]) {
+        if (typeof candidate === 'number' && Number.isFinite(candidate))
+            return candidate;
+        // Gaxios sometimes reports the status as a numeric STRING.
+        if (typeof candidate === 'string' && /^\d{3}$/.test(candidate))
+            return Number(candidate);
+    }
+    return undefined;
+}
+/** Is this the service's "no such resource"? */
+export function isNotFound(err) {
+    return httpStatusOf(err) === 404;
+}
+/** Is this "a resource by that name already exists"? */
+export function isAlreadyExists(err) {
+    return httpStatusOf(err) === 409;
+}
+// ─── Ids ─────────────────────────────────────────────────────────────
+/** The longest a resource id may be in both collections this column writes to. */
+export const MAX_RESOURCE_ID_LENGTH = 63;
+/**
+ * The id grammar this column really has to satisfy — the INTERSECTION of the
+ * two documented rules, so one function is right for both callers and neither
+ * has to remember which is stricter: `[a-z0-9-]`, first character a letter,
+ * last character a letter or a digit.
+ *
+ * Exported so the surface pin can hold it against the installed package's own
+ * words rather than against this file's memory of them.
+ */
+export const LEGAL_RESOURCE_ID = /^[a-z]$|^[a-z][a-z0-9-]*[a-z0-9]$/;
+/**
+ * Turn caller data into a resource id the service will accept — and never into
+ * a DIFFERENT caller's id.
+ *
+ * ── The grammar, quoted rather than guessed ─────────────────────────────────
+ * This function used to state that "Vertex resource ids accept `[A-Za-z0-9_-]`".
+ * That is a Google-wide habit and it is not what either collection this column
+ * writes to documents. From the installed package (`@googleapis/aiplatform`
+ * 31.0.0, `build/v1.d.ts`), verbatim:
+ *
+ *   `memoryId`  — "This value may be up to 63 characters, and valid characters
+ *                 are `[a-z0-9-]`. The first character must be a letter, and
+ *                 the last character must be a letter or number."
+ *   `sessionId` — "This value may be up to 63 characters, and valid characters
+ *                 are `[a-z0-9-]`. The first and last characters must be a
+ *                 letter or number."
+ *
+ * So UPPERCASE and `_` are illegal in both, and a leading digit is illegal for
+ * a memory. Under the old grammar a UUID entry id (leading digit) and a ULID
+ * session id (uppercase Crockford base32) — two of the most ordinary id shapes
+ * there are — went to the wire unchanged, to be refused by Google with a 400
+ * whose text {@link googleSdkFailure} then withholds. A grammar error the
+ * adapter could have caught locally, delivered as a censored 400, is the one
+ * place the secrecy law and the teaching-refusal law collide; the fix is to not
+ * send it. The surface pin reads those two sentences out of the installed
+ * `.d.ts` and checks them against {@link LEGAL_RESOURCE_ID}, so this cannot
+ * drift back to a guess.
+ *
+ * ── Why a hash and not just a fold ──────────────────────────────────────────
+ * Lowercasing and substituting are LOSSY: `Alice` folds onto `alice`, `a_b`
+ * onto `a-b`. Two ids that folded together would be ONE row, which is the same
+ * silent overwrite this column's addressing law exists to prevent. So the
+ * readable fast path is taken only when the caller's id already is a legal id
+ * byte for byte; anything the fold touched — or that overruns 63 characters —
+ * is carried by a {@link fingerprint} of the ORIGINAL, which keeps distinct
+ * inputs distinct.
+ */
+export function safeResourceId(raw, max = MAX_RESOURCE_ID_LENGTH) {
+    const slug = raw.toLowerCase().replace(/[^a-z0-9-]/g, '-');
+    if (slug === raw && slug.length <= max && LEGAL_RESOURCE_ID.test(slug))
+        return slug;
+    const suffix = fingerprint(raw);
+    const room = max - suffix.length - 1;
+    if (room < 2) {
+        // Returning something longer than `max` would be a silently invalid id —
+        // refused rather than sent, since only a caller of this function can fix it.
+        throw new RangeError(`safeResourceId: max of ${max} leaves no room for the fingerprint that keeps two ` +
+            `folded ids apart. The smallest workable bound is ${suffix.length + 3}.`);
+    }
+    // `id-` rather than the bare slug: the first character must be a LETTER, and
+    // the fold cannot promise one. The fingerprint is base36, so the last
+    // character is a letter or a digit by construction — which also makes this
+    // function IDEMPOTENT: its own output is a legal id and comes back unchanged.
+    // `agentEngineSessions.listByUser` relies on that, since it hands composed
+    // resource ids back to callers who feed them to `hydrate`.
+    const head = `id-${slug}`.slice(0, room).replace(/-+$/, '');
+    return `${head}-${suffix}`;
+}
+/**
+ * A stable fingerprint of a string, in `[0-9a-z-]`.
+ *
+ * TWO FNV-1a lanes rather than one, because of what this hash is now asked to
+ * carry: it is the only thing keeping two ids apart once the fold has run them
+ * together, and it is half of how `memoryBankStore` addresses one identity's
+ * memories apart from another's. A single 32-bit lane collides at around one
+ * chance in a hundred across ten thousand ids, which is too often for either
+ * job; two lanes cost one more multiply per character and make it negligible.
+ *
+ * It is a fingerprint, not a security boundary — a colliding address is still
+ * refused by the scope check that runs before every read and every overwrite.
+ */
+export function fingerprint(value) {
+    let a = 0x811c9dc5;
+    let b = 0x01000193;
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        a = Math.imul(a ^ code, 0x01000193);
+        b = Math.imul(b ^ code, 0x85ebca6b);
+    }
+    return `${(a >>> 0).toString(36)}-${(b >>> 0).toString(36)}`;
+}
+//# sourceMappingURL=aiPlatform.js.map

package/dist/esm/adapters/google/aiPlatform.js.map

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

package/dist/esm/adapters/hosting/googleAgentEngine.d.ts

@@ -0,0 +1,156 @@
+/**
+ * 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 type { CheckpointEnvelope, SessionLifecycle } from '../../hosting/types.js';
+import { type AiPlatformConnection } from '../google/aiPlatform.js';
+/**
+ * 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 declare const SESSION_STATE_KEY = "agentfootprint.envelope";
+/** Options for {@link agentEngineSessions}. */
+export interface AgentEngineSessionsOptions extends AiPlatformConnection {
+    /**
+     * WHO a session belongs to — required by the service on create, and
+     * **immutable** once written.
+     *
+     * The port hands `persist` a session id and an envelope, never a user, so
+     * this is where the missing half comes from. Two spellings:
+     *
+     *  - a **function**, called with the session id and the envelope about to be
+     *    stored. The recommended shape: return `envelopeOwner(envelope)` — the
+     *    principal the conversation itself was signed with — so the service's
+     *    idea of the owner and this library's own ownership index agree by
+     *    construction rather than by coincidence. That is what the default does.
+     *  - a **string**, when every conversation in this engine belongs to one
+     *    service identity. Honest for a single-tenant deployment and wrong the
+     *    moment it is not, which is why it is not the default.
+     *
+     * The default resolver reads the envelope's own principal and falls back to
+     * {@link DEFAULT_USER_ID} for a conversation that ran anonymously. It never
+     * invents a per-session user id: the service treats `userId` as the thing
+     * you filter a listing by, and minting a unique one per session would make
+     * every listing return exactly one row and look like it worked.
+     */
+    readonly userId?: string | ((sessionId: string, envelope: CheckpointEnvelope) => string);
+    /**
+     * How long a session lives after its last write, as a duration string the
+     * API accepts (`'86400s'`). **The service's own floor is 24 hours** and it
+     * rejects anything shorter, so this is a knob for keeping conversations
+     * LONGER, never for expiring them sooner.
+     *
+     * Omit and no `ttl` is sent, which leaves the service's own default
+     * expiry in charge.
+     */
+    readonly ttl?: string;
+    /**
+     * How long a write waits for its long-running operation before refusing.
+     * Default {@link DEFAULT_OPERATION_TIMEOUT_MS} (30s).
+     *
+     * It refuses rather than returning: a `persist` that reported success on an
+     * operation it never saw finish is a conversation that may or may not be
+     * there next turn.
+     */
+    readonly operationTimeoutMs?: number;
+}
+/** What a conversation that named nobody is stored under. */
+export declare const DEFAULT_USER_ID = "agentfootprint-anonymous";
+/**
+ * A session store in Vertex AI's session service.
+ *
+ * It is a {@link SessionLifecycle} plus the two things a real store owns beyond
+ * the port — forgetting, and closing — because the port deliberately asks for
+ * two methods and leaves the rest to whoever implements it.
+ */
+export interface AgentEngineSessions extends SessionLifecycle {
+    /** The resource these sessions live under. Useful in an incident. */
+    readonly parent: string;
+    /** Forget one session. A session that was never there is not an error. */
+    forget(sessionId: string): Promise<void>;
+    /**
+     * Stop using this store. Idempotent, and **final** — reading or writing
+     * afterwards refuses by name rather than quietly reconnecting, because a
+     * store that reopened behind you would hide a shutdown-ordering bug instead
+     * of surfacing it.
+     *
+     * Nothing is torn down on Google's side: the sessions outlive this process,
+     * which is the entire reason to use a managed store.
+     */
+    close(): void;
+}
+/**
+ * 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 declare function agentEngineSessions(options: AgentEngineSessionsOptions): AgentEngineSessions;