@stigmer/sdk 3.1.7 → 3.1.9

package/src/gen/agentshare.ts

@@ -0,0 +1,148 @@
+// Code generated by stigmer-codegen. DO NOT EDIT.
+
+import { wrapError } from "./errors.js";
+import { stripUndefined } from "./proto-utils.js";
+import { type ResourceRef } from "./types.js";
+import { create } from "@bufbuild/protobuf";
+import { createClient, type Client, type Transport } from "@connectrpc/connect";
+import { AgentShareSchema, type AgentShare } from "@stigmer/protos/ai/stigmer/agentic/agentshare/v1/api_pb";
+import { AgentShareCommandController } from "@stigmer/protos/ai/stigmer/agentic/agentshare/v1/command_pb";
+import { AgentShareIdSchema, RotateShareLinkInputSchema, GetAgentSharesByAgentRequestSchema, AgentShareListSchema, ListAgentSharesRequestSchema, GetSharedProfileRequestSchema, SharedAgentProfileSchema, type RotateShareLinkInput, type GetAgentSharesByAgentRequest, type AgentShareList, type ListAgentSharesRequest, type GetSharedProfileRequest, type SharedAgentProfile } from "@stigmer/protos/ai/stigmer/agentic/agentshare/v1/io_pb";
+import { AgentShareQueryController } from "@stigmer/protos/ai/stigmer/agentic/agentshare/v1/query_pb";
+import { AgentShareSpecSchema, AgentShareAudience, AgentShareMessagesSchema } from "@stigmer/protos/ai/stigmer/agentic/agentshare/v1/spec_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+import { ApiResourceReferenceSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+
+/** Provides operations on agentshare resources. */
+export class AgentShareClient {
+  private readonly command: Client<typeof AgentShareCommandController>;
+  private readonly query: Client<typeof AgentShareQueryController>;
+
+  constructor(transport: Transport) {
+    this.command = createClient(AgentShareCommandController, transport);
+    this.query = createClient(AgentShareQueryController, transport);
+  }
+
+  async apply(input: AgentShareInput): Promise<AgentShare> {
+    try {
+      return await this.command.apply(buildAgentShareProto(input));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async create(input: AgentShareInput): Promise<AgentShare> {
+    try {
+      return await this.command.create(buildAgentShareProto(input));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async update(input: AgentShareInput): Promise<AgentShare> {
+    try {
+      return await this.command.update(buildAgentShareProto(input));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async rotateShareLink(input: RotateShareLinkInput): Promise<AgentShare> {
+    try {
+      return await this.command.rotateShareLink(input);
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async delete(id: string): Promise<AgentShare> {
+    try {
+      return await this.command.delete(create(AgentShareIdSchema, { value: id }));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async get(id: string): Promise<AgentShare> {
+    try {
+      return await this.query.get(create(AgentShareIdSchema, { value: id }));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async getByReference(ref: ResourceRef): Promise<AgentShare> {
+    try {
+      return await this.query.getByReference(create(ApiResourceReferenceSchema, { ...ref, kind: ApiResourceKind.agent_share }));
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async getByAgent(input: GetAgentSharesByAgentRequest): Promise<AgentShareList> {
+    try {
+      return await this.query.getByAgent(input);
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async list(input: ListAgentSharesRequest): Promise<AgentShareList> {
+    try {
+      return await this.query.list(input);
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async getSharedProfile(input: GetSharedProfileRequest): Promise<SharedAgentProfile> {
+    try {
+      return await this.query.getSharedProfile(input);
+    } catch (e) { throw wrapError(e); }
+  }
+
+  async getSharedProfileForMember(ref: ResourceRef): Promise<SharedAgentProfile> {
+    try {
+      return await this.query.getSharedProfileForMember(create(ApiResourceReferenceSchema, { ...ref, kind: ApiResourceKind.agent_share }));
+    } catch (e) { throw wrapError(e); }
+  }
+}
+
+/** Input for creating/updating a AgentShare. */
+export interface AgentShareInput {
+  name: string;
+  slug?: string;
+  org: string;
+  labels?: Record<string, string>;
+  visibility?: ApiResourceVisibility;
+  agentRef: ResourceRef;
+  enabled?: boolean;
+  audience?: AgentShareAudience;
+  allowedOrigins?: string[];
+  messages?: AgentShareMessagesInput;
+  environmentRefs?: ResourceRef[];
+}
+
+/** SDK input type for AgentShareMessages. */
+export interface AgentShareMessagesInput {
+  rateLimited?: string;
+  unavailable?: string;
+  conversationEnded?: string;
+}
+
+function buildAgentShareMessagesProto(input: AgentShareMessagesInput) {
+  return Object.assign(create(AgentShareMessagesSchema), stripUndefined({
+    rateLimited: input.rateLimited,
+    unavailable: input.unavailable,
+    conversationEnded: input.conversationEnded,
+  }));
+}
+
+export function buildAgentShareProto(input: AgentShareInput): AgentShare {
+  const agentRef = (input.agentRef?.slug || input.agentRef?.org) ? create(ApiResourceReferenceSchema, { ...input.agentRef, kind: 40 }) : undefined;
+  const messages = input.messages ? buildAgentShareMessagesProto(input.messages) : undefined;
+  const environmentRefs = input.environmentRefs?.map(r => create(ApiResourceReferenceSchema, { ...r, kind: 53 }));
+  return Object.assign(create(AgentShareSchema), {
+    apiVersion: "agentic.stigmer.ai/v1",
+    kind: "AgentShare",
+    metadata: Object.assign(create(ApiResourceMetadataSchema), {
+      name: input.name,
+      org: input.org,
+      ...(input.slug && { slug: input.slug }),
+      ...(input.labels && { labels: input.labels }),
+      ...(input.visibility && { visibility: input.visibility }),
+    }),
+    spec: Object.assign(create(AgentShareSpecSchema), stripUndefined({
+      agentRef,
+      enabled: input.enabled,
+      audience: input.audience,
+      allowedOrigins: input.allowedOrigins,
+      messages,
+      environmentRefs,
+    })),
+  }) as AgentShare;
+}

package/src/gen/authorization-config.ts

@@ -23,6 +23,7 @@ export const GRANTABLE_ROLES: ReadonlyMap<ApiResourceKind, readonly IamRole[]> =
   [ApiResourceKind.skill, [IamRole.owner, IamRole.viewer]],
   [ApiResourceKind.mcp_server, [IamRole.owner, IamRole.viewer]],
   [ApiResourceKind.agent_instance, [IamRole.owner, IamRole.viewer]],
+  [ApiResourceKind.agent_share, [IamRole.owner, IamRole.viewer]],
   [ApiResourceKind.workflow, [IamRole.owner, IamRole.viewer]],
   [ApiResourceKind.workflow_instance, [IamRole.owner, IamRole.viewer]],
   [ApiResourceKind.workflow_execution, [IamRole.owner, IamRole.viewer]],

package/src/gen/client.ts

@@ -4,6 +4,7 @@ import type { Transport } from "@connectrpc/connect";
 import { AgentClient } from "./agent.js";
 import { AgentExecutionClient } from "./agentexecution.js";
 import { AgentInstanceClient } from "./agentinstance.js";
+import { AgentShareClient } from "./agentshare.js";
 import { ApiKeyClient } from "./apikey.js";
 import { ArtifactClient } from "./artifact.js";
 import { EnvironmentClient } from "./environment.js";
@@ -28,6 +29,7 @@ export class GeneratedClient {
   readonly agent: AgentClient;
   readonly agentExecution: AgentExecutionClient;
   readonly agentInstance: AgentInstanceClient;
+  readonly agentShare: AgentShareClient;
   readonly apiKey: ApiKeyClient;
   readonly artifact: ArtifactClient;
   readonly environment: EnvironmentClient;
@@ -51,6 +53,7 @@ export class GeneratedClient {
     this.agent = new AgentClient(transport);
     this.agentExecution = new AgentExecutionClient(transport);
     this.agentInstance = new AgentInstanceClient(transport);
+    this.agentShare = new AgentShareClient(transport);
     this.apiKey = new ApiKeyClient(transport);
     this.artifact = new ArtifactClient(transport);
     this.environment = new EnvironmentClient(transport);
@@ -79,6 +82,8 @@ export { AgentExecutionClient } from "./agentexecution.js";
 export { type AgentExecutionInput, type ExecutionConfigInput, type ContextManagementConfigInput, type AttachmentInput } from "./agentexecution.js";
 export { AgentInstanceClient } from "./agentinstance.js";
 export { type AgentInstanceInput } from "./agentinstance.js";
+export { AgentShareClient } from "./agentshare.js";
+export { type AgentShareInput, type AgentShareMessagesInput } from "./agentshare.js";
 export { ApiKeyClient } from "./apikey.js";
 export { type ApiKeyInput } from "./apikey.js";
 export { ArtifactClient } from "./artifact.js";

package/src/gen/environment.ts

@@ -12,7 +12,7 @@ import { EnvironmentQueryController } from "@stigmer/protos/ai/stigmer/agentic/e
 import { EnvironmentValueSchema, EnvironmentSpecSchema, type EnvironmentValue } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
-import { ApiResourceIdSchema, ApiResourceReferenceSchema, ApiResourceDeleteInputSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import { ApiResourceIdSchema, ApiResourceReferenceSchema, ApiResourceDeleteInputSchema, type UpdateVisibilityInput } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
 import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
 
 /** Provides operations on environment resources. */
@@ -43,6 +43,12 @@ export class EnvironmentClient {
     } catch (e) { throw wrapError(e); }
   }
 
+  async updateVisibility(input: UpdateVisibilityInput): Promise<Environment> {
+    try {
+      return await this.command.updateVisibility(input);
+    } catch (e) { throw wrapError(e); }
+  }
+
   async delete(input: DeleteResourceInput): Promise<Environment> {
     try {
       return await this.command.delete(create(ApiResourceDeleteInputSchema, {

package/src/gen/platformclient.ts

@@ -14,7 +14,7 @@ import { PlatformClientCommandController } from "@stigmer/protos/ai/stigmer/iam/
 import { PlatformClientCreateResponseSchema, PlatformClientIdSchema, ListPlatformClientsByOrgInputSchema, PlatformClientsSchema, type PlatformClientCreateResponse, type ListPlatformClientsByOrgInput, type PlatformClients } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/io_pb";
 import { PlatformClientQueryController } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/query_pb";
 import { PlatformClientSpecSchema } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/spec_pb";
-import { PlatformClientTokenController, MintUserTokenRequestSchema, MintUserTokenResponseSchema, type MintUserTokenRequest, type MintUserTokenResponse } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/token_pb";
+import { PlatformClientTokenController, MintUserTokenRequestSchema, MintUserTokenResponseSchema, MintGuestTokenRequestSchema, MintGuestTokenResponseSchema, type MintUserTokenRequest, type MintUserTokenResponse, type MintGuestTokenRequest, type MintGuestTokenResponse } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/token_pb";
 import { IamRole } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
 
 /** Provides operations on platformclient resources. */
@@ -80,6 +80,12 @@ export class PlatformClientClient {
       return await this.token.mintUserToken(input);
     } catch (e) { throw wrapError(e); }
   }
+
+  async mintGuestToken(input: MintGuestTokenRequest): Promise<MintGuestTokenResponse> {
+    try {
+      return await this.token.mintGuestToken(input);
+    } catch (e) { throw wrapError(e); }
+  }
 }
 
 /** Input for creating/updating a PlatformClient. */

package/src/gen/session.ts

@@ -9,7 +9,7 @@ import { ToolApprovalOverrideSchema, McpServerUsageSchema } from "@stigmer/proto
 import { SessionSchema, type Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
 import { SessionCommandController } from "@stigmer/protos/ai/stigmer/agentic/session/v1/command_pb";
 import { Harness, CursorMode, ExecutionTarget, GitWriteBackMode } from "@stigmer/protos/ai/stigmer/agentic/session/v1/enum_pb";
-import { SessionIdSchema, UpdateSessionSubjectRequestSchema, ListSessionsRequestSchema, SessionListSchema, ListSessionsByAgentRequestSchema, type UpdateSessionSubjectRequest, type ListSessionsRequest, type SessionList, type ListSessionsByAgentRequest } from "@stigmer/protos/ai/stigmer/agentic/session/v1/io_pb";
+import { SessionIdSchema, UpdateSessionSubjectRequestSchema, ListSessionsRequestSchema, SessionListSchema, ListSessionsByAgentInstanceRequestSchema, type UpdateSessionSubjectRequest, type ListSessionsRequest, type SessionList, type ListSessionsByAgentInstanceRequest } from "@stigmer/protos/ai/stigmer/agentic/session/v1/io_pb";
 import { SessionQueryController } from "@stigmer/protos/ai/stigmer/agentic/session/v1/query_pb";
 import { SessionSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/spec_pb";
 import { GitRepoSourceSchema, LocalPathSourceSchema, WorkspaceSourceSchema, WorkspaceEntrySchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/workspace_pb";
@@ -69,9 +69,9 @@ export class SessionClient {
     } catch (e) { throw wrapError(e); }
   }
 
-  async listByAgent(input: ListSessionsByAgentRequest): Promise<SessionList> {
+  async listByAgentInstance(input: ListSessionsByAgentInstanceRequest): Promise<SessionList> {
     try {
-      return await this.query.listByAgent(input);
+      return await this.query.listByAgentInstance(input);
     } catch (e) { throw wrapError(e); }
   }
 }

package/src/guest-auth.ts

@@ -0,0 +1,334 @@
+import { createGrpcWebTransport } from "@connectrpc/connect-web";
+import { createClient, type Client } from "@connectrpc/connect";
+import { create } from "@bufbuild/protobuf";
+import { PlatformClientTokenController } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/token_pb";
+import { MintGuestTokenRequestSchema } from "@stigmer/protos/ai/stigmer/iam/platformclient/v1/token_pb";
+import { wrapError } from "./gen/errors.js";
+import {
+  rpcMetadataInterceptor,
+  errorStripInterceptor,
+} from "./internal/interceptors.js";
+
+/**
+ * Minimal persistence contract for the visitor's guest id.
+ *
+ * Matches the subset of the Web Storage API that {@link GuestAuth}
+ * needs, so `localStorage` satisfies it directly. Inject a custom
+ * implementation for non-browser environments or tests.
+ */
+export interface GuestIdStorage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+}
+
+/**
+ * Configuration for a guest token-minting helper.
+ *
+ * Unlike {@link PlatformClientAuthConfig}, this carries **no
+ * credentials** — `mintGuestToken` is a public RPC gated server-side
+ * on an enabled AgentShare at the given org/slug. It is therefore safe
+ * to use directly from a browser.
+ *
+ * @example
+ * ```typescript
+ * import { createGuestAuth } from "@stigmer/sdk";
+ *
+ * const guestAuth = createGuestAuth({
+ *   baseUrl: "https://api.stigmer.ai",
+ *   org: "acme",
+ *   slug: "support-agent",
+ * });
+ * ```
+ */
+export interface GuestAuthConfig {
+  /** Stigmer API server URL (e.g., "https://api.stigmer.ai"). */
+  readonly baseUrl: string;
+
+  /** Organization slug from the share URL. */
+  readonly org: string;
+
+  /**
+   * Share slug from the share URL. Defaults to the shared agent's slug
+   * when the owner never customized it, so existing links pass the
+   * agent's slug here unchanged.
+   */
+  readonly slug: string;
+
+  /**
+   * Where to persist the visitor's guest id across visits.
+   *
+   * Defaults to `localStorage` when available, falling back to
+   * in-memory storage (guest identity then lasts one page load).
+   * The stored value is an opaque server-generated id — not a
+   * credential — that keys this browser's session read-isolation.
+   */
+  readonly storage?: GuestIdStorage;
+
+  /**
+   * Web origin of the page embedding the shared agent.
+   *
+   * Set this when the chat runs embedded — inside an iframe (the
+   * embedding page's origin, discovered via `@stigmer/embed`'s
+   * `resolveParentOrigin`) or directly in your own app
+   * (`window.location.origin`). Leave unset on the unframed hosted
+   * page. The server validates it against the share's
+   * `allowed_origins` at mint (an empty list admits any origin) and
+   * refuses with `"permission-denied"` when the origin is not allowed.
+   */
+  readonly embedOrigin?: string;
+
+  /**
+   * Share-link token from the URL's `?k=` parameter.
+   *
+   * Required when the share link has been locked with a rotatable
+   * token; harmless (ignored server-side) on plain links. On a locked
+   * link a missing or rotated-away token refuses the mint with
+   * `"not-found"` — deliberately indistinguishable from an agent that
+   * does not exist.
+   */
+  readonly linkToken?: string;
+}
+
+/**
+ * How long before expiry a cached guest token is considered stale.
+ * Re-minting inside this window keeps long-lived streams from starting
+ * with a token that expires moments later.
+ */
+const EXPIRY_SKEW_MS = 60_000;
+
+/** Storage key prefix for the persisted guest id, namespaced per org. */
+const GUEST_ID_STORAGE_PREFIX = "stigmer:guest-id:";
+
+/**
+ * Guest token-minting helper for shared-agent pages.
+ *
+ * A minimal, purpose-built companion to the main Stigmer client: it
+ * lazily mints short-lived guest JWTs via the public `mintGuestToken`
+ * RPC, caches them in memory until just before expiry, and persists
+ * the server-issued guest id so the same browser resolves to the same
+ * guest across visits.
+ *
+ * Wire {@link getAccessToken} into a `Stigmer` client — the SDK calls
+ * it per request, so refresh is automatic and no token ever needs to
+ * be stored outside memory.
+ *
+ * Failure semantics: when minting fails (e.g. sharing was revoked —
+ * the server answers NOT_FOUND, indistinguishable from "no such
+ * agent"), {@link getAccessToken} rejects with a `StigmerError`, which
+ * fails the triggering request with the real cause instead of sending
+ * it unauthenticated.
+ *
+ * @example
+ * ```typescript
+ * const guestAuth = createGuestAuth({
+ *   baseUrl: "https://api.stigmer.ai",
+ *   org: "acme",
+ *   slug: "support-agent",
+ * });
+ *
+ * const client = new Stigmer({
+ *   baseUrl: "https://api.stigmer.ai",
+ *   getAccessToken: guestAuth.getAccessToken,
+ * });
+ * ```
+ */
+export class GuestAuth {
+  private readonly tokenClient: Client<typeof PlatformClientTokenController>;
+  private readonly org: string;
+  private readonly slug: string;
+  private readonly storage: GuestIdStorage;
+  private readonly storageKey: string;
+  private readonly embedOrigin: string;
+  private readonly linkToken: string;
+
+  private cached: { accessToken: string; expiresAt: number } | null = null;
+  private pendingMint: Promise<string> | null = null;
+
+  /** @internal Use {@link createGuestAuth} instead. */
+  constructor(config: GuestAuthConfig) {
+    this.org = config.org;
+    this.slug = config.slug;
+    this.storage = config.storage ?? resolveDefaultStorage();
+    this.storageKey = `${GUEST_ID_STORAGE_PREFIX}${config.org}`;
+    this.embedOrigin = config.embedOrigin ?? "";
+    this.linkToken = config.linkToken ?? "";
+
+    const transport = createGrpcWebTransport({
+      baseUrl: config.baseUrl,
+      interceptors: [rpcMetadataInterceptor, errorStripInterceptor],
+    });
+
+    this.tokenClient = createClient(PlatformClientTokenController, transport);
+  }
+
+  /**
+   * The visitor's persisted guest id, or `null` before the first
+   * successful mint in this browser.
+   */
+  get guestCookieId(): string | null {
+    return safeGetItem(this.storage, this.storageKey);
+  }
+
+  /**
+   * Token provider for `StigmerConfig.getAccessToken`.
+   *
+   * Returns the cached guest JWT while it has more than a minute of
+   * life left; otherwise mints a fresh one. Concurrent callers during
+   * a mint share the same in-flight request (single-flight).
+   *
+   * Defined as an arrow property so it can be passed detached:
+   * `new Stigmer({ ..., getAccessToken: guestAuth.getAccessToken })`.
+   *
+   * @throws {StigmerError} with code `"not-found"` when the agent is
+   *   not shared (or sharing was revoked — the server keeps the two
+   *   indistinguishable by design)
+   * @throws {StigmerError} with code `"permission-denied"` when
+   *   `embedOrigin` is not in the agent's `allowed_origins` — embeds
+   *   should hide the widget on this code rather than surface an error
+   * @throws {StigmerError} with code `"invalid-argument"` when org or
+   *   slug is malformed
+   */
+  readonly getAccessToken = async (): Promise<string | null> => {
+    if (this.cached && this.cached.expiresAt - Date.now() > EXPIRY_SKEW_MS) {
+      return this.cached.accessToken;
+    }
+
+    // Single-flight: the provider is invoked once per request, so a
+    // burst at page load (registry fetches + profile resolution) must
+    // collapse into one mint — both for latency and because concurrent
+    // first mints would otherwise race to persist different guest ids.
+    this.pendingMint ??= this.mint().finally(() => {
+      this.pendingMint = null;
+    });
+
+    return this.pendingMint;
+  };
+
+  private async mint(): Promise<string> {
+    try {
+      const response = await this.tokenClient.mintGuestToken(
+        create(MintGuestTokenRequestSchema, {
+          org: this.org,
+          slug: this.slug,
+          guestCookieId: safeGetItem(this.storage, this.storageKey) ?? "",
+          embedOrigin: this.embedOrigin,
+          linkToken: this.linkToken,
+        }),
+      );
+
+      safeSetItem(this.storage, this.storageKey, response.guestCookieId);
+      this.cached = {
+        accessToken: response.accessToken,
+        expiresAt: Date.now() + response.expiresIn * 1000,
+      };
+      return response.accessToken;
+    } catch (e) {
+      throw wrapError(e);
+    }
+  }
+}
+
+/**
+ * `localStorage` when usable, otherwise an in-memory fallback.
+ *
+ * Access is probed inside try/catch because merely touching
+ * `localStorage` can throw (e.g. sandboxed iframes with storage
+ * blocked). With the fallback, the chat still works — the visitor
+ * just gets a fresh guest identity per page load.
+ *
+ * `globalThis` is typed structurally because this package compiles
+ * without DOM libs (it is also consumed from Node, where
+ * `localStorage` does not exist).
+ */
+function resolveDefaultStorage(): GuestIdStorage {
+  try {
+    const { localStorage: storage } = globalThis as {
+      localStorage?: GuestIdStorage & { removeItem(key: string): void };
+    };
+    if (storage) {
+      const probeKey = "stigmer:storage-probe";
+      storage.setItem(probeKey, "1");
+      storage.removeItem(probeKey);
+      return storage;
+    }
+  } catch {
+    // Fall through to the in-memory storage below.
+  }
+
+  const memory = new Map<string, string>();
+  return {
+    getItem: (key) => memory.get(key) ?? null,
+    setItem: (key, value) => {
+      memory.set(key, value);
+    },
+  };
+}
+
+/**
+ * Storage reads/writes never fail the mint: the guest id is a
+ * convenience (stable identity across visits), not a requirement —
+ * the server issues a fresh id when none is presented.
+ */
+function safeGetItem(storage: GuestIdStorage, key: string): string | null {
+  try {
+    return storage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+
+function safeSetItem(storage: GuestIdStorage, key: string, value: string): void {
+  try {
+    storage.setItem(key, value);
+  } catch {
+    // Persisting the id is best-effort; see safeGetItem.
+  }
+}
+
+/**
+ * Create a guest token-minting helper for a shared agent's hosted page
+ * or embed.
+ *
+ * This is the browser-side counterpart of `createPlatformClientAuth`:
+ * it involves **no credentials** — the server gates minting on an
+ * enabled AgentShare and issues a short-lived guest JWT scoped to the
+ * sharing org. Pass {@link GuestAuth.getAccessToken} to a `Stigmer`
+ * client and every request authenticates as this visitor.
+ *
+ * @example
+ * ```typescript
+ * import { Stigmer, createGuestAuth } from "@stigmer/sdk";
+ *
+ * const guestAuth = createGuestAuth({
+ *   baseUrl: "https://api.stigmer.ai",
+ *   org: "acme",
+ *   slug: "support-agent",
+ * });
+ *
+ * const client = new Stigmer({
+ *   baseUrl: "https://api.stigmer.ai",
+ *   getAccessToken: guestAuth.getAccessToken,
+ * });
+ * ```
+ *
+ * @throws {Error} if `baseUrl`, `org`, or `slug` is missing or empty
+ */
+export function createGuestAuth(config: GuestAuthConfig): GuestAuth {
+  if (!config.baseUrl) {
+    throw new Error(
+      "createGuestAuth: baseUrl is required (e.g., \"https://api.stigmer.ai\")",
+    );
+  }
+  if (!config.org) {
+    throw new Error(
+      "createGuestAuth: org is required — the organization slug from the share URL",
+    );
+  }
+  if (!config.slug) {
+    throw new Error(
+      "createGuestAuth: slug is required — the share slug from the share URL",
+    );
+  }
+
+  return new GuestAuth(config);
+}

package/src/index.ts

@@ -13,6 +13,26 @@ export {
 // Configuration
 export { type StigmerConfig, type TokenProvider } from "./config.js";
 
+// Guest auth (shared-agent pages and embeds; browser-safe, credential-free)
+export {
+  createGuestAuth,
+  GuestAuth,
+  type GuestAuthConfig,
+  type GuestIdStorage,
+} from "./guest-auth.js";
+
+// Agent sharing (hosted link + embed snippet; framework-free)
+export {
+  MAX_ALLOWED_ORIGINS,
+  LINK_TOKEN_PARAM,
+  validateOrigin,
+  chatPath,
+  buildChatUrl,
+  appendLinkToken,
+  buildEmbedLoaderUrl,
+  buildEmbedSnippet,
+} from "./sharing.js";
+
 // Error handling
 export {
   StigmerError,
@@ -125,6 +145,11 @@ export {
   AgentInstanceClient,
   type AgentInstanceInput,
 } from "./gen/agentinstance.js";
+export {
+  AgentShareClient,
+  type AgentShareInput,
+  type AgentShareMessagesInput,
+} from "./gen/agentshare.js";
 export { ApiKeyClient, type ApiKeyInput } from "./gen/apikey.js";
 export {
   EnvironmentClient,