Sessions and storage

The session lifecycle

Method	What it does
ensure(input?)	Reuses a valid stored session, or mints a new one via getBootstrapAssertion.
getStoredSession()	Returns public session metadata, or null.
clearStoredSession()	Removes the locally stored session.
revokeSession()	Revokes the session server-side.

const stored = await client.getStoredSession();
if (stored && stored.expiresAt < Date.now()) {
  await client.ensure({ forceRefresh: true });
}

getStoredSession() returns PublicStoredExternalAgentSession — the stored record minus its sessionToken. There is no public method that hands the bearer token back to you.

Storage adapters

By default the SDK keeps the session in memory, so it is lost on reload. Provide a RuntimeStorage adapter to persist it:

import type { RuntimeStorage } from '@agentshelf/agent-runtime-sdk-core';
import type { ExternalAgentStoredSessionRecord } from '@agentshelf/external-agents-sdk';

const storage: RuntimeStorage<ExternalAgentStoredSessionRecord> = {
  get: async (key) => secureStore.get(key),
  set: async (key, value) => secureStore.set(key, value),
  remove: async (key) => secureStore.remove(key),
};

const client = createExternalAgentClient({
  externalAgentRef: 'ext_agent_public_12345678',
  getBootstrapAssertion,
  storage,
  storageKey: 'agentshelf:checkout-agent',
});

All three methods may return synchronously or as a promise.

Choose the store deliberately

The stored record includes sessionToken — the bearer credential the SDK uses for every public API call. Anything that can read your storage can act as that session until it expires.

In a browser, localStorage is readable by any script on the origin, including injected third-party scripts. Prefer a shorter-lived store, scope the session narrowly, and call revokeSession() when the user logs out.

Use a distinct storageKey per agent if one page embeds more than one, otherwise the second client will overwrite the first client's session.

What is in a session record

ExternalAgentStoredSessionRecord holds externalAgentRef, sessionRef, sessionToken, expiresAt, and optionally externalAppRef, externalUserRef, and workspaceBindingRef. Every identifier in it is a public ref.