agentfootprint 9.26.0 → 9.28.0

package/dist/types/adapters/google/aiPlatform.d.ts

@@ -0,0 +1,454 @@
+/**
+ * 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.
+ */
+/**
+ * One REST call's answer. The discovery clients wrap every response as
+ * `{ data }`, and that wrapper is part of the contract an injected `_client`
+ * has to honour.
+ */
+export interface RestResponse<T> {
+    readonly data: T;
+}
+/** A long-running operation, as these adapters read it. */
+export interface LongRunningOperation {
+    readonly name?: string | null;
+    readonly done?: boolean | null;
+    readonly error?: {
+        readonly code?: number | null;
+        readonly message?: string | null;
+    } | null;
+    readonly response?: Record<string, unknown> | null;
+}
+/** The `operations` sub-resource, which both collections carry identically. */
+export interface OperationsApi {
+    /**
+     * Block server-side until the operation finishes or `timeout` elapses, then
+     * answer whatever state it is in.
+     *
+     * `wait` rather than a `get` poll loop: it is the operation the service
+     * publishes for exactly this, and it turns "poll every 200 ms for ten
+     * seconds" into one or two round trips. It may still answer un-done, so
+     * {@link awaitOperation} loops it against a deadline — a server-side wait is
+     * not a promise that the work is finished, and treating it as one is how an
+     * adapter reads a resource that is not there yet.
+     */
+    wait(params: {
+        name: string;
+        timeout?: string;
+    }): Promise<RestResponse<LongRunningOperation> | undefined>;
+}
+/** A Vertex `Session`, in the fields these adapters read or write. */
+export interface VertexSession {
+    readonly name?: string | null;
+    readonly userId?: string | null;
+    readonly sessionState?: Record<string, unknown> | null;
+    readonly createTime?: string | null;
+    readonly updateTime?: string | null;
+    readonly expireTime?: string | null;
+    readonly ttl?: string | null;
+}
+/** The `sessions` collection. Every method here is pinned. */
+export interface SessionsApi {
+    create(params: {
+        parent: string;
+        sessionId?: string;
+        requestBody: VertexSession;
+    }): Promise<RestResponse<LongRunningOperation> | undefined>;
+    get(params: {
+        name: string;
+    }): Promise<RestResponse<VertexSession> | undefined>;
+    patch(params: {
+        name: string;
+        updateMask?: string;
+        requestBody: VertexSession;
+    }): Promise<RestResponse<VertexSession> | undefined>;
+    delete(params: {
+        name: string;
+    }): Promise<RestResponse<LongRunningOperation> | undefined>;
+    list(params: {
+        parent: string;
+        filter?: string;
+        orderBy?: string;
+        pageSize?: number;
+        pageToken?: string;
+    }): Promise<RestResponse<{
+        sessions?: VertexSession[];
+        nextPageToken?: string | null;
+    }> | undefined>;
+    readonly operations: OperationsApi;
+}
+/** One typed metadata scalar. Memory Bank's metadata map is NOT free JSON. */
+export interface VertexMemoryMetadataValue {
+    readonly stringValue?: string | null;
+    readonly doubleValue?: number | null;
+    readonly boolValue?: boolean | null;
+    readonly timestampValue?: string | null;
+}
+/** A Vertex `Memory`, in the fields these adapters read or write. */
+export interface VertexMemory {
+    readonly name?: string | null;
+    readonly fact?: string | null;
+    readonly scope?: Record<string, string> | null;
+    readonly metadata?: Record<string, VertexMemoryMetadataValue> | null;
+    readonly createTime?: string | null;
+    readonly updateTime?: string | null;
+    readonly expireTime?: string | null;
+    readonly ttl?: string | null;
+}
+/** One row of a retrieval answer — and the whole ranking trap in two fields. */
+export interface VertexRetrievedMemory {
+    /**
+     * **A DISTANCE. Smaller is closer.** The SDK's own words for this field are
+     * "the distance between the query and the retrieved Memory. Smaller values
+     * indicate more similar memories."
+     *
+     * The port's `ScoredEntry.score` is a cosine similarity, where HIGHER is
+     * closer. These two facts are the silent-inversion trap this column was
+     * warned about, and the type says so here so that nothing downstream can
+     * copy it into a `score` field by looking only at its shape.
+     *
+     * Only set when similarity search was used; a simple retrieval has no
+     * ranking at all and reports none.
+     */
+    readonly distance?: number | null;
+    readonly memory?: VertexMemory;
+}
+/** The `memories` collection. Every method here is pinned. */
+export interface MemoriesApi {
+    create(params: {
+        parent: string;
+        memoryId?: string;
+        requestBody: VertexMemory;
+    }): Promise<RestResponse<LongRunningOperation> | undefined>;
+    get(params: {
+        name: string;
+    }): Promise<RestResponse<VertexMemory> | undefined>;
+    patch(params: {
+        name: string;
+        updateMask?: string;
+        requestBody: VertexMemory;
+    }): Promise<RestResponse<LongRunningOperation> | undefined>;
+    delete(params: {
+        name: string;
+    }): Promise<RestResponse<LongRunningOperation> | undefined>;
+    list(params: {
+        parent: string;
+        filter?: string;
+        pageSize?: number;
+        pageToken?: string;
+    }): Promise<RestResponse<{
+        memories?: VertexMemory[];
+        nextPageToken?: string | null;
+    }> | undefined>;
+    retrieve(params: {
+        parent: string;
+        requestBody: {
+            scope: Record<string, string>;
+            similaritySearchParams?: {
+                searchQuery: string;
+                topK?: number;
+            };
+            simpleRetrievalParams?: {
+                pageSize?: number;
+                pageToken?: string;
+            };
+        };
+    }): Promise<RestResponse<{
+        retrievedMemories?: VertexRetrievedMemory[];
+        nextPageToken?: string | null;
+    }> | undefined>;
+    readonly operations: OperationsApi;
+}
+/**
+ * The shape both adapters call, and the shape an injected `_client` must have.
+ *
+ * It is the SDK's own nesting rather than a flattened convenience surface, on
+ * purpose: the surface pin walks these exact property paths against the really
+ * installed package, and a flattened shim would move the names being checked
+ * out of the file that does the calling.
+ */
+export interface AiPlatformClientLike {
+    readonly projects: {
+        readonly locations: {
+            readonly reasoningEngines: {
+                readonly sessions: SessionsApi;
+                readonly memories: MemoriesApi;
+            };
+        };
+    };
+}
+/** The slice of `@googleapis/aiplatform` this module loads. */
+export interface AiPlatformSdkModule {
+    readonly aiplatform?: (options: {
+        version: string;
+        rootUrl?: string;
+        auth?: unknown;
+    }) => AiPlatformClientLike;
+    readonly auth?: {
+        readonly GoogleAuth?: new (options: unknown) => unknown;
+    };
+}
+/**
+ * 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 declare const AI_PLATFORM_API_VERSION: "v1";
+/** The OAuth scope every Vertex data-plane call needs. */
+export declare const CLOUD_PLATFORM_SCOPE = "https://www.googleapis.com/auth/cloud-platform";
+/** What every adapter in this column needs to reach one reasoning engine. */
+export interface AiPlatformConnection {
+    /**
+     * The Google Cloud project. Read from `GOOGLE_CLOUD_PROJECT` when omitted;
+     * refused by name when neither is available, because a project guessed wrong
+     * is a 404 that reads like a missing resource.
+     */
+    readonly project?: string;
+    /**
+     * The region, e.g. `'us-central1'`. **Load-bearing twice over:** it composes
+     * the resource name AND selects the regional host. There is no default — a
+     * guess here calls the wrong continent.
+     */
+    readonly location: string;
+    /**
+     * The reasoning engine these sessions or memories live under: either the
+     * bare id (`'1234567890'`) or a full resource name
+     * (`'projects/p/locations/l/reasoningEngines/1234567890'`), in which case
+     * the project and location are read from it and need not be repeated.
+     *
+     * A reasoning engine resource is REQUIRED even when you deploy no code to
+     * it: sessions and memories are children of it, and there is nowhere else to
+     * put them. Creating one is a control-plane job this library does not do.
+     */
+    readonly reasoningEngine: string;
+    /**
+     * Credentials. Anything the discovery client accepts — a `GoogleAuth`, an
+     * `OAuth2Client`, an `Impersonated`. Omit and Application Default
+     * Credentials are used with the cloud-platform scope, which is the ordinary
+     * path on Cloud Run, GKE, or a developer machine that has run
+     * `gcloud auth application-default login`.
+     */
+    readonly auth?: unknown;
+    /**
+     * @internal Test seam — a pre-built client. Skips the SDK load entirely, so
+     * a suite never needs the package installed or a credential configured.
+     */
+    readonly _client?: AiPlatformClientLike;
+    /** @internal Test seam — the SDK module, to exercise the real construction. */
+    readonly _sdk?: AiPlatformSdkModule;
+}
+/** A resolved engine: the parent resource name, plus the pieces it was built from. */
+export interface EngineScope {
+    readonly project: string;
+    readonly location: string;
+    readonly engineId: string;
+    /** `projects/{project}/locations/{location}/reasoningEngines/{engine}` */
+    readonly parent: string;
+}
+/**
+ * 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 declare function resolveEngine(adapter: string, connection: AiPlatformConnection): EngineScope;
+/**
+ * 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 declare function regionalRootUrl(location: string): string;
+/**
+ * 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 declare function buildAiPlatformClient(adapter: string, connection: AiPlatformConnection, scope: EngineScope): AiPlatformClientLike;
+/** How long {@link awaitOperation} keeps waiting before it refuses, by default. */
+export declare const DEFAULT_OPERATION_TIMEOUT_MS = 30000;
+/**
+ * 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 declare function awaitOperation(adapter: string, operations: OperationsApi, operation: LongRunningOperation | undefined, what: string, timeoutMs?: number): Promise<void>;
+/**
+ * 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 declare const OPERATION_ERROR_NAME = "GoogleOperationError";
+/**
+ * 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 declare function isSanitizedGoogleError(err: unknown): boolean;
+/**
+ * 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 declare function googleSdkFailure(adapter: string, operation: string, err: unknown): Error;
+/**
+ * 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 declare function httpStatusOf(err: unknown): number | undefined;
+/** Is this the service's "no such resource"? */
+export declare function isNotFound(err: unknown): boolean;
+/** Is this "a resource by that name already exists"? */
+export declare function isAlreadyExists(err: unknown): boolean;
+/** The longest a resource id may be in both collections this column writes to. */
+export declare 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 declare const LEGAL_RESOURCE_ID: RegExp;
+/**
+ * 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 declare function safeResourceId(raw: string, max?: number): string;
+/**
+ * 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 declare function fingerprint(value: string): string;
+//# sourceMappingURL=aiPlatform.d.ts.map

package/dist/types/adapters/google/aiPlatform.d.ts.map

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

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

@@ -0,0 +1,157 @@
+/**
+ * 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;
+//# sourceMappingURL=googleAgentEngine.d.ts.map

package/dist/types/adapters/hosting/googleAgentEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"googleAgentEngine.d.ts","sourceRoot":"","sources":["../../../../src/adapters/hosting/googleAgentEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAIH,OAAO,KAAK,EACV,kBAAkB,EAClB,gBAAgB,EAGjB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAUL,KAAK,oBAAoB,EAI1B,MAAM,yBAAyB,CAAC;AAIjC;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,4BAA4B,CAAC;AAE3D,+CAA+C;AAC/C,MAAM,WAAW,0BAA2B,SAAQ,oBAAoB;IACtE;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,kBAAkB,KAAK,MAAM,CAAC,CAAC;IACzF;;;;;;;;OAQG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;;;OAOG;IACH,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAED,6DAA6D;AAC7D,eAAO,MAAM,eAAe,6BAA6B,CAAC;AAE1D;;;;;;GAMG;AACH,MAAM,WAAW,mBAAoB,SAAQ,gBAAgB;IAC3D,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,0EAA0E;IAC1E,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACzC;;;;;;;;OAQG;IACH,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,0BAA0B,GAAG,mBAAmB,CA0M5F"}