@semiont/sdk 0.4.22 → 0.5.1

package/README.md

@@ -26,42 +26,54 @@ npm install @semiont/sdk
 
 ## Quick start (HTTP)
 
+For one-shot scripts, `SemiontClient.signIn(...)` is the credentials-first one-line construction:
+
 ```ts
-import {
-  SemiontSession,
-  InMemorySessionStorage,
-  setStoredSession,
-  type KnowledgeBase,
-} from '@semiont/sdk';
-import { accessToken } from '@semiont/core';
-import { firstValueFrom } from 'rxjs';
-import { filter } from 'rxjs/operators';
+import { SemiontClient } from '@semiont/sdk';
+
+const semiont = await SemiontClient.signIn({
+  baseUrl: 'http://localhost:4000',
+  email: 'me@example.com',
+  password: 'pwd',
+});
+
+const resources = await semiont.browse.resources({ limit: 10 });
+console.log(resources);
+
+semiont.dispose();
+```
+
+For long-running scripts that need to survive token expiry, use `SemiontSession.signIn(...)` — same credentials shape, plus proactive refresh, validation, storage-adapter wiring, and disposal. `kb` is required; its `id` is the storage key for this session, so distinct scripts must use distinct ids:
+
+```ts
+import { SemiontSession, InMemorySessionStorage, type KnowledgeBase } from '@semiont/sdk';
 
 const kb: KnowledgeBase = {
-  id: 'local',
-  label: 'Local Backend',
+  id: 'my-watcher',
+  label: 'My Watcher',
   protocol: 'http',
   host: 'localhost',
   port: 4000,
   email: 'me@example.com',
 };
 
-const storage = new InMemorySessionStorage();
-setStoredSession(storage, kb.id, {
-  access: accessToken('your-jwt'),
-  refresh: '',
+const session = await SemiontSession.signIn({
+  kb,
+  storage: new InMemorySessionStorage(),
+  baseUrl: 'http://localhost:4000',
+  email: 'me@example.com',
+  password: 'pwd',
 });
 
-const session = await SemiontSession.create({ kb, storage });
+// session.client is the same SemiontClient surface; the session manages
+// the token$ lifecycle around it (default refresh callback wired automatically).
+const resources = await session.client.browse.resources({ limit: 10 });
 
-const resources = await firstValueFrom(
-  session.client.browse.resources({ limit: 10 }).pipe(
-    filter((r): r is NonNullable<typeof r> => r !== undefined),
-  ),
-);
-console.log(resources);
+await session.dispose();
 ```
 
+If you already have an access token (CLI cached-token path, env-var token, embedded auth flow), use `SemiontClient.fromHttp({ baseUrl, token })` or `SemiontSession.fromHttp({ baseUrl, token, storage, kb, refresh, ... })` to skip the auth round-trip.
+
 ## Quick start (in-process)
 
 When you want the SDK without an HTTP backend — e.g. in a CLI, a unit test, or an Electron-style desktop app — wire `LocalTransport` directly to a knowledge system:
@@ -86,23 +98,25 @@ const client = new SemiontClient(
 );
 ```
 
-Same `SemiontClient`, same verb namespaces — no network involved.
+Same `SemiontClient`, same verb namespaces — no network involved. There is no `fromLocal` factory because the in-process transport's dependencies (knowledgeSystem, eventBus, userId) are not boilerplate the SDK can hide.
 
 ## Verb namespaces
 
-All ten namespaces hang off `SemiontClient`. Each method either returns a `Promise` (one-shot RPC-style operations) or an `Observable` (streaming subscriptions). The bus is invisible to callers — channel strings, correlation IDs, and reconnection are internal.
+All ten namespaces hang off `SemiontClient`. Methods that return data return either a `Promise<T>` (atomic ops like `mark.archive`) or an awaitable Observable subclass — `StreamObservable<T>` for streams (`mark.assist`, `gather.annotation`, `match.search`, `yield.fromAnnotation`) and `CacheObservable<T>` for live queries (`browse.*`). Both subclasses implement `PromiseLike<T>`, so consumers can `await` them directly. Reactive consumers can `.subscribe(...)` exactly as with a plain Observable. The bus is invisible to callers — channel strings, correlation IDs, and reconnection are internal.
 
 ```ts
-// Browse — read the knowledge graph.
-await client.browse.resources({ limit: 10 });
+// Browse — live queries; await yields the loaded value, subscribe yields
+// loading-then-loaded.
+const resources = await client.browse.resources({ limit: 10 });
 client.browse.resource(resourceId).subscribe(/* ... */);
 
-// Mark / Bind — create and modify annotations.
+// Mark / Bind — atomic operations return Promise<T>.
 const { annotationId } = await client.mark.annotation(rid, request);
 await client.bind.body(rid, aid, [{ op: 'add', item: { /* W3C body */ } }]);
 
-// Gather / Match — assemble context and run semantic search.
-const ctx = await lastValueFrom(client.gather.annotation(aid, rid));
+// Gather / Match — bounded streams; await yields the final value, subscribe
+// yields every progress emission.
+const ctx = await client.gather.annotation(aid, rid);
 client.match.search(rid, refId, ctx, { limit: 10 }).subscribe(/* ... */);
 
 // Yield — author new resources.
@@ -116,9 +130,17 @@ client.beckon.hover(annotationId);
 
 The verb-by-verb walkthroughs live in [docs/flows](https://github.com/The-AI-Alliance/semiont/tree/main/docs/flows).
 
+`.pipe(...)` returns a plain `Observable<T>` — once you compose with RxJS operators you've explicitly entered RxJS land, and `lastValueFrom` from `rxjs` is the right bridge. The `firstValueFrom`/`lastValueFrom` re-exports from `@semiont/sdk` stay available for that case.
+
+## Documentation
+
+- [`docs/Usage.md`](https://github.com/The-AI-Alliance/semiont/blob/main/packages/sdk/docs/Usage.md) — per-namespace tour with concrete examples for Browse, Mark, Bind, Gather, Match, Yield, Beckon, Auth, Admin, Job, plus SSE and error handling.
+- [`docs/CACHE-SEMANTICS.md`](https://github.com/The-AI-Alliance/semiont/blob/main/packages/sdk/docs/CACHE-SEMANTICS.md) — the cache primitive's behavioral contract.
+- [`docs/protocol/TRANSPORT-CONTRACT.md`](https://github.com/The-AI-Alliance/semiont/blob/main/docs/protocol/TRANSPORT-CONTRACT.md) — the transport interface every `ITransport` must honor.
+
 ## Behavioral contract
 
-The guarantees every `ITransport` implementation must honor — what `subscribe()` does on disconnect, what `LastEventId` replay must look like, what `puts` must be idempotent — are documented in [packages/core/docs/TRANSPORT-CONTRACT.md](https://github.com/The-AI-Alliance/semiont/blob/main/packages/core/docs/TRANSPORT-CONTRACT.md). HTTP-specific guarantees (the `/bus/emit` gateway, SSE reconnect, `Last-Event-ID` replay window) live alongside the backend at [apps/backend/docs/TRANSPORT.md](https://github.com/The-AI-Alliance/semiont/blob/main/apps/backend/docs/TRANSPORT.md).
+The guarantees every `ITransport` implementation must honor — what `subscribe()` does on disconnect, what `LastEventId` replay must look like, what `puts` must be idempotent — are documented in [docs/protocol/TRANSPORT-CONTRACT.md](https://github.com/The-AI-Alliance/semiont/blob/main/docs/protocol/TRANSPORT-CONTRACT.md). HTTP-specific guarantees (the `/bus/emit` gateway, SSE reconnect, `Last-Event-ID` replay window) live in [docs/protocol/TRANSPORT-HTTP.md](https://github.com/The-AI-Alliance/semiont/blob/main/docs/protocol/TRANSPORT-HTTP.md).
 
 When implementing a new transport (gRPC, WebSocket, IPC, …), implement those interfaces from `@semiont/core` directly — there is no inheritance from `HttpTransport`.
 

package/dist/index.d.ts

@@ -1,28 +1,104 @@
 import * as rxjs from 'rxjs';
 import { Observable, BehaviorSubject, Subject } from 'rxjs';
+export { firstValueFrom, lastValueFrom } from 'rxjs';
 import * as _semiont_core from '@semiont/core';
-import { components, UserDID, paths, ResourceId, AnnotationId, BodyOperation, EventMap, ResourceDescriptor, Annotation, GraphConnection, Motivation, GatheredContext, JobId, ITransport, EventBus, IContentTransport, BaseUrl, AccessToken, ConnectionState, Selector } from '@semiont/core';
-export { ConnectionState, Logger } from '@semiont/core';
+import { components, UserDID, paths, ResourceId, AnnotationId, BodyOperation, EventMap, ResourceDescriptor, Annotation, GraphConnection, Motivation, GatheredContext, JobId, ITransport, EventBus, IContentTransport, BaseUrl, AccessToken, SemiontError, ConnectionState, Selector } from '@semiont/core';
+export { AccessToken, Annotation, AnnotationId, BaseUrl, BodyItem, BodyOperation, ConnectionState, EntityType, EventMap, GatheredContext, IContentTransport, ITransport, Logger, Motivation, RefreshToken, ResourceDescriptor, ResourceId, SemiontError, UserId, accessToken, annotationId, baseUrl, entityType, refreshToken, resourceId, userId } from '@semiont/core';
 import { ActorVM } from '@semiont/api-client';
-export { APIError, ActorVM, ActorVMOptions, BusEvent, DEGRADED_THRESHOLD_MS, HttpContentTransport, HttpTransport, HttpTransportConfig, TokenRefresher, createActorVM } from '@semiont/api-client';
+export { APIError, APIErrorCode, ActorVM, ActorVMOptions, BusEvent, DEGRADED_THRESHOLD_MS, HttpContentTransport, HttpTransport, HttpTransportConfig, TokenRefresher, createActorVM } from '@semiont/api-client';
+
+/**
+ * Thenable Observable subclasses.
+ *
+ * Two thin Observable subclasses that also implement `PromiseLike<T>`. Used as
+ * the public return type of namespace methods that emit streams (job
+ * lifecycle, generation progress) and cache reads (Browse live queries).
+ *
+ * The point: scripts can `await` the call directly without `lastValueFrom` /
+ * `firstValueFrom` wrappers; reactive consumers (frontend view-models) keep
+ * using `.subscribe(...)` and `.pipe(...)` exactly as before.
+ *
+ * The asymmetric `.then()` semantics — last-value-on-completion for streams,
+ * first-non-undefined-value for caches — is encoded by the subclass name. The
+ * docstring on the namespace method tells the consumer which one applies.
+ *
+ * `.pipe(...)` returns a plain `Observable<T>` (RxJS doesn't propagate
+ * subclasses through `pipe`). Once you compose, you've explicitly entered
+ * RxJS land; `lastValueFrom` from `rxjs` is the right bridge there.
+ */
+
+/**
+ * Bounded Observable stream — emits zero-or-more progress values, then a
+ * final value on completion. Used by job-lifecycle methods like
+ * `mark.assist`, `gather.annotation`, `match.search`, `yield.fromAnnotation`.
+ *
+ * Awaiting resolves to the **last** emitted value (via `lastValueFrom`).
+ * Subscribing yields every emission, ending in `complete`.
+ */
+declare class StreamObservable<T> extends Observable<T> implements PromiseLike<T> {
+    then<R1 = T, R2 = never>(onfulfilled?: ((v: T) => R1 | PromiseLike<R1>) | null, onrejected?: ((e: unknown) => R2 | PromiseLike<R2>) | null): PromiseLike<R1 | R2>;
+    /** Wrap an existing Observable's subscribe behavior in a StreamObservable. */
+    static from<T>(source: Observable<T>): StreamObservable<T>;
+}
+/**
+ * Multicast cache observable — emits `undefined` while the underlying value
+ * is loading, then the value, then re-emits when bus events invalidate the
+ * cache entry. Used by Browse live-query methods (`browse.resource`,
+ * `browse.annotations`, etc.).
+ *
+ * Awaiting resolves to the **first non-undefined** value (waits past the
+ * loading state). Subscribing yields the full sequence including the
+ * initial `undefined`, so reactive consumers can render a loading state.
+ *
+ * The class is parameterized as `CacheObservable<T>` even though the
+ * stream's element type is `T | undefined` — `T` is what the consumer
+ * gets from `await`, and that's the contract we want to advertise. The
+ * `Observable<T | undefined>` shape leaks through `.subscribe` and
+ * `.pipe` in the natural way.
+ */
+declare class CacheObservable<T> extends Observable<T | undefined> implements PromiseLike<T> {
+    then<R1 = T, R2 = never>(onfulfilled?: ((v: T) => R1 | PromiseLike<R1>) | null, onrejected?: ((e: unknown) => R2 | PromiseLike<R2>) | null): PromiseLike<R1 | R2>;
+    /**
+     * Wrap an existing Observable's subscribe behavior in a `CacheObservable`.
+     *
+     * Memoizes on source identity: passing the same `source` returns the same
+     * wrapper instance. The Browse cache primitive already returns a stable
+     * Observable per key (its B4 contract), so this preserves that contract
+     * through the awaitable wrapping. Without the memo, every public-method
+     * call would produce a fresh wrapper and break referential-equality
+     * guarantees that React-side consumers depend on.
+     *
+     * Backed by a `WeakMap`, so wrappers are GC'd when their source is.
+     */
+    static from<T>(source: Observable<T | undefined>): CacheObservable<T>;
+}
 
 /**
  * Verb Namespace Interfaces
  *
- * These interfaces define the public API of the Semiont api-client,
- * organized by the 7 domain flows (Browse, Mark, Bind, Gather, Match,
- * Yield, Beckon) plus infrastructure namespaces (Job, Auth, Admin).
+ * These interfaces define the public API of `@semiont/sdk`, organized by
+ * the 7 domain flows (Browse, Mark, Bind, Gather, Match, Yield, Beckon)
+ * plus infrastructure namespaces (Job, Auth, Admin).
  *
- * Each namespace maps 1:1 to a flow. Each flow maps to a clear actor
- * on the backend. The frontend calls `client.mark.annotation()` and the
- * proxy handles HTTP, auth, SSE, and caching internally.
+ * Each namespace maps 1:1 to a flow. Each flow maps to a clear actor on
+ * the backend. The frontend calls `client.mark.annotation()` and the
+ * client handles HTTP, auth, SSE, and caching internally.
  *
  * Return type conventions:
- * - Browse live queries → Observable (bus gateway driven, cached)
- * - Browse one-shot reads → Promise (fetch once, no cache)
- * - Commands (mark, bind, yield.resource) → Promise (fire-and-forget)
- * - Long-running ops (gather, match, yield.fromAnnotation, mark.assist) → Observable (progress + result)
- * - Ephemeral signals (beckon) → void
+ * - Browse live queries → `CacheObservable<T>` (bus-driven, cached;
+ *   subscribe yields `T | undefined`, await yields `T` after first load)
+ * - Browse one-shot reads → `Promise<T>` (fetch once, no cache)
+ * - Commands (mark, bind, yield.resource) → `Promise<T>` (atomic ops)
+ * - Long-running ops (gather, match, yield.fromAnnotation, mark.assist)
+ *   → `StreamObservable<T>` (progress + result; subscribe yields every
+ *   emit, await yields the last one)
+ * - Ephemeral signals (beckon) → `void`
+ *
+ * `StreamObservable` and `CacheObservable` are `Observable` subclasses
+ * that also implement `PromiseLike<T>` — `await client.X.Y(...)` works
+ * directly without `lastValueFrom`/`firstValueFrom` wrappers.
+ * `.pipe(...)` returns a plain `Observable<T>` (the thenable subclass
+ * does not propagate through pipe — by design).
  */
 
 type StoredEventResponse$2 = components['schemas']['StoredEventResponse'];
@@ -171,17 +247,17 @@ type YieldGenerationEvent = {
  * Event prefix: browse:*
  */
 interface BrowseNamespace$1 {
-    resource(resourceId: ResourceId): Observable<ResourceDescriptor | undefined>;
+    resource(resourceId: ResourceId): CacheObservable<ResourceDescriptor>;
     resources(filters?: {
         limit?: number;
         archived?: boolean;
         search?: string;
-    }): Observable<ResourceDescriptor[] | undefined>;
-    annotations(resourceId: ResourceId): Observable<Annotation[] | undefined>;
-    annotation(resourceId: ResourceId, annotationId: AnnotationId): Observable<Annotation | undefined>;
-    entityTypes(): Observable<string[] | undefined>;
-    referencedBy(resourceId: ResourceId): Observable<ReferencedByEntry[] | undefined>;
-    events(resourceId: ResourceId): Observable<StoredEventResponse$2[] | undefined>;
+    }): CacheObservable<ResourceDescriptor[]>;
+    annotations(resourceId: ResourceId): CacheObservable<Annotation[]>;
+    annotation(resourceId: ResourceId, annotationId: AnnotationId): CacheObservable<Annotation>;
+    entityTypes(): CacheObservable<string[]>;
+    referencedBy(resourceId: ResourceId): CacheObservable<ReferencedByEntry[]>;
+    events(resourceId: ResourceId): CacheObservable<StoredEventResponse$2[]>;
     resourceContent(resourceId: ResourceId): Promise<string>;
     resourceRepresentation(resourceId: ResourceId, options?: {
         accept?: string;
@@ -216,14 +292,14 @@ interface BrowseNamespace$1 {
  */
 interface MarkNamespace$1 {
     annotation(resourceId: ResourceId, input: CreateAnnotationInput): Promise<{
-        annotationId: string;
+        annotationId: AnnotationId;
     }>;
     delete(resourceId: ResourceId, annotationId: AnnotationId): Promise<void>;
     entityType(type: string): Promise<void>;
     entityTypes(types: string[]): Promise<void>;
     archive(resourceId: ResourceId): Promise<void>;
     unarchive(resourceId: ResourceId): Promise<void>;
-    assist(resourceId: ResourceId, motivation: Motivation, options: MarkAssistOptions): Observable<MarkAssistEvent>;
+    assist(resourceId: ResourceId, motivation: Motivation, options: MarkAssistOptions): StreamObservable<MarkAssistEvent>;
     request(selector: components['schemas']['MarkRequestedEvent']['selector'], motivation: Motivation): void;
     /** Fire-and-forget variant of `assist` — mark-vm orchestrates the call and its progress Observable. */
     requestAssist(motivation: Motivation, options: MarkAssistOptions, correlationId?: string): void;
@@ -265,10 +341,10 @@ interface BindNamespace$1 {
 interface GatherNamespace$1 {
     annotation(annotationId: AnnotationId, resourceId: ResourceId, options?: {
         contextWindow?: number;
-    }): Observable<GatherAnnotationProgress>;
+    }): StreamObservable<GatherAnnotationProgress>;
     resource(resourceId: ResourceId, options?: {
         contextWindow?: number;
-    }): Observable<GatherAnnotationProgress>;
+    }): StreamObservable<GatherAnnotationProgress>;
 }
 /**
  * Match — search and ranking
@@ -280,10 +356,10 @@ interface GatherNamespace$1 {
  * Event prefix: match:*
  */
 interface MatchNamespace$1 {
-    search(resourceId: ResourceId, referenceId: string, context: GatheredContext, options?: {
+    search(resourceId: ResourceId, referenceId: AnnotationId, context: GatheredContext, options?: {
         limit?: number;
         useSemanticScoring?: boolean;
-    }): Observable<MatchSearchProgress>;
+    }): StreamObservable<MatchSearchProgress>;
     /** Fire-and-forget variant: match-vm orchestrates the call and its result Observable. */
     requestSearch(input: components['schemas']['MatchSearchRequest']): void;
 }
@@ -300,7 +376,7 @@ interface YieldNamespace$1 {
     resource(data: CreateResourceInput): Promise<{
         resourceId: string;
     }>;
-    fromAnnotation(resourceId: ResourceId, annotationId: AnnotationId, options: GenerationOptions): Observable<YieldGenerationEvent>;
+    fromAnnotation(resourceId: ResourceId, annotationId: AnnotationId, options: GenerationOptions): StreamObservable<YieldGenerationEvent>;
     cloneToken(resourceId: ResourceId): Promise<{
         token: string;
         expiresAt: string;
@@ -437,13 +513,13 @@ declare class BrowseNamespace implements BrowseNamespace$1 {
      */
     private readonly annotationListObs;
     constructor(transport: ITransport, bus: EventBus, content: IContentTransport);
-    resource(resourceId: ResourceId): Observable<ResourceDescriptor | undefined>;
-    resources(filters?: ResourceListFilters): Observable<ResourceDescriptor[] | undefined>;
-    annotations(resourceId: ResourceId): Observable<Annotation[] | undefined>;
-    annotation(resourceId: ResourceId, annotationId: AnnotationId): Observable<Annotation | undefined>;
-    entityTypes(): Observable<string[] | undefined>;
-    referencedBy(resourceId: ResourceId): Observable<ReferencedByEntry[] | undefined>;
-    events(resourceId: ResourceId): Observable<StoredEventResponse$1[] | undefined>;
+    resource(resourceId: ResourceId): CacheObservable<ResourceDescriptor>;
+    resources(filters?: ResourceListFilters): CacheObservable<ResourceDescriptor[]>;
+    annotations(resourceId: ResourceId): CacheObservable<Annotation[]>;
+    annotation(resourceId: ResourceId, annotationId: AnnotationId): CacheObservable<Annotation>;
+    entityTypes(): CacheObservable<string[]>;
+    referencedBy(resourceId: ResourceId): CacheObservable<ReferencedByEntry[]>;
+    events(resourceId: ResourceId): CacheObservable<StoredEventResponse$1[]>;
     resourceContent(resourceId: ResourceId): Promise<string>;
     resourceRepresentation(resourceId: ResourceId, options?: {
         accept?: string;
@@ -507,14 +583,14 @@ declare class MarkNamespace implements MarkNamespace$1 {
     private readonly bus;
     constructor(transport: ITransport, bus: EventBus);
     annotation(resourceId: ResourceId, input: CreateAnnotationInput): Promise<{
-        annotationId: string;
+        annotationId: AnnotationId;
     }>;
     delete(resourceId: ResourceId, annotationId: AnnotationId): Promise<void>;
     entityType(type: string): Promise<void>;
     entityTypes(types: string[]): Promise<void>;
     archive(resourceId: ResourceId): Promise<void>;
     unarchive(resourceId: ResourceId): Promise<void>;
-    assist(resourceId: ResourceId, motivation: Motivation, options: MarkAssistOptions): Observable<MarkAssistEvent>;
+    assist(resourceId: ResourceId, motivation: Motivation, options: MarkAssistOptions): StreamObservable<MarkAssistEvent>;
     request(selector: components['schemas']['MarkRequestedEvent']['selector'], motivation: Motivation): void;
     requestAssist(motivation: Motivation, options: MarkAssistOptions, correlationId?: string): void;
     submit(input: components['schemas']['MarkSubmitEvent']): void;
@@ -541,10 +617,10 @@ declare class GatherNamespace implements GatherNamespace$1 {
     constructor(transport: ITransport, bus: EventBus);
     annotation(annotationId: AnnotationId, resourceId: ResourceId, options?: {
         contextWindow?: number;
-    }): Observable<GatherAnnotationProgress>;
+    }): StreamObservable<GatherAnnotationProgress>;
     resource(_resourceId: ResourceId, _options?: {
         contextWindow?: number;
-    }): Observable<GatherAnnotationProgress>;
+    }): StreamObservable<GatherAnnotationProgress>;
 }
 
 declare class MatchNamespace implements MatchNamespace$1 {
@@ -552,10 +628,10 @@ declare class MatchNamespace implements MatchNamespace$1 {
     private readonly bus;
     constructor(transport: ITransport, bus: EventBus);
     requestSearch(input: components['schemas']['MatchSearchRequest']): void;
-    search(resourceId: ResourceId, referenceId: string, context: GatheredContext, options?: {
+    search(resourceId: ResourceId, referenceId: AnnotationId, context: GatheredContext, options?: {
         limit?: number;
         useSemanticScoring?: boolean;
-    }): Observable<MatchSearchProgress>;
+    }): StreamObservable<MatchSearchProgress>;
 }
 
 declare class YieldNamespace implements YieldNamespace$1 {
@@ -566,7 +642,7 @@ declare class YieldNamespace implements YieldNamespace$1 {
     resource(data: CreateResourceInput): Promise<{
         resourceId: string;
     }>;
-    fromAnnotation(resourceId: ResourceId, annotationId: AnnotationId, options: GenerationOptions): Observable<YieldGenerationEvent>;
+    fromAnnotation(resourceId: ResourceId, annotationId: AnnotationId, options: GenerationOptions): StreamObservable<YieldGenerationEvent>;
     cloneToken(resourceId: ResourceId): Promise<{
         token: string;
         expiresAt: string;
@@ -722,10 +798,59 @@ declare class SemiontClient {
     get state$(): rxjs.Observable<_semiont_core.ConnectionState>;
     subscribeToResource(resourceId: ResourceId): () => void;
     dispose(): void;
+    /**
+     * Convenience factory for the default HTTP setup. Constructs a
+     * `BehaviorSubject<AccessToken | null>` internally, plus an
+     * `HttpTransport` and `HttpContentTransport`, and returns the wired
+     * `SemiontClient`.
+     *
+     * Use this for one-shot scripts, CLI commands, or any consumer that
+     * doesn't need to drive the token from outside (no manual refresh,
+     * no cross-tab sync). For long-running scripts that need refresh,
+     * use `SemiontSession.fromHttp(...)` instead — it owns the same
+     * transport/client wiring plus the proactive-refresh + storage
+     * machinery.
+     *
+     * Strings are accepted for `baseUrl` and `token`; they are branded
+     * via `baseUrl()` / `accessToken()` from `@semiont/core` automatically.
+     * Pass the already-branded values if you have them.
+     *
+     * Omit `token` for unauthenticated usage (public endpoints only).
+     */
+    static fromHttp(opts: {
+        baseUrl: BaseUrl | string;
+        token?: AccessToken | string | null;
+    }): SemiontClient;
+    /**
+     * Async factory for the credentials-first script case. Builds a
+     * transient transport, calls `auth.password(email, password)` to
+     * acquire an access token, and returns the wired client with the
+     * token populated.
+     *
+     * This is the right entry point for skills, CLI scripts, and any
+     * consumer that starts with email + password rather than a JWT
+     * already on hand. For consumers that already hold a token (CLI
+     * cached-token path, env-var token, embedded auth flow), use
+     * `fromHttp({ baseUrl, token })` instead.
+     *
+     * For long-running scripts that need refresh, use
+     * `SemiontSession.signIn(...)` — same credentials shape, plus the
+     * session machinery for proactive refresh and persistence.
+     *
+     * Throws if authentication fails. The transient client is disposed
+     * before the throw, so no resources leak on failure.
+     */
+    static signIn(opts: {
+        baseUrl: BaseUrl | string;
+        email: string;
+        password: string;
+    }): Promise<SemiontClient>;
 }
 
-declare class BusRequestError extends Error {
-    constructor(message: string);
+type BusRequestErrorCode = 'bus.timeout' | 'bus.rejected' | 'bus.bad-payload' | 'bus.unauthorized' | 'bus.forbidden' | 'bus.not-found';
+declare class BusRequestError extends SemiontError {
+    code: BusRequestErrorCode;
+    constructor(message: string, code: BusRequestErrorCode, details?: Record<string, unknown>);
 }
 /**
  * Subset of ITransport that `busRequest` needs: a way to send a command and
@@ -741,7 +866,7 @@ declare function busRequest<TResult>(bus: BusRequestPrimitive, emitChannel: stri
 /**
  * RxJS-native read-through cache primitive.
  *
- * Behavioral contract: packages/api-client/docs/CACHE-SEMANTICS.md (B1–B13).
+ * Behavioral contract: packages/sdk/docs/CACHE-SEMANTICS.md (B1–B13).
  *
  * Framework-agnostic: no React, no dependency on any namespace. Used by
  * `BrowseNamespace` to back its per-key stores, but equally usable from
@@ -825,12 +950,17 @@ type KbSessionStatus = 'authenticated' | 'expired' | 'signed-out' | 'unreachable
  * failures that make the session itself unusable (auth failed, actor
  * couldn't start, token refresh terminally exhausted). Per-request
  * errors stay with the caller as normal Promise rejections.
+ *
+ * `SemiontSessionError` extends `SemiontError` (the unified Semiont base)
+ * so consumers can catch with `instanceof SemiontError` for any error
+ * surfaced through the SDK.
  */
-type SemiontErrorCode = 'session.construct-failed' | 'session.auth-failed' | 'session.refresh-exhausted' | 'browser.sign-in-failed';
-declare class SemiontError extends Error {
-    readonly code: SemiontErrorCode;
+
+type SemiontSessionErrorCode = 'session.construct-failed' | 'session.auth-failed' | 'session.refresh-exhausted' | 'browser.sign-in-failed';
+declare class SemiontSessionError extends SemiontError {
+    code: SemiontSessionErrorCode;
     readonly kbId: string | null;
-    constructor(code: SemiontErrorCode, message: string, kbId?: string | null);
+    constructor(code: SemiontSessionErrorCode, message: string, kbId?: string | null);
 }
 
 /**
@@ -944,7 +1074,7 @@ interface SemiontSessionConfig {
      */
     onAuthFailed?: (message: string | null) => void;
     /** Called for session-level failures (auth, refresh exhaustion). */
-    onError?: (err: SemiontError) => void;
+    onError?: (err: SemiontSessionError) => void;
 }
 declare class SemiontSession {
     readonly kb: KnowledgeBase;
@@ -1001,6 +1131,61 @@ declare class SemiontSession {
      */
     subscribe<K extends keyof EventMap>(channel: K, handler: (payload: EventMap[K]) => void): () => void;
     dispose(): Promise<void>;
+    /**
+     * Convenience factory for the default HTTP setup. Constructs the
+     * shared `BehaviorSubject<AccessToken | null>`, an `HttpTransport`,
+     * an `HttpContentTransport`, and a `SemiontClient`, then wires
+     * the session over them. Removes the load-bearing
+     * "same-token$-instance" invariant from the caller's hands.
+     *
+     * Strings are accepted for `baseUrl` and `token`; they are branded
+     * via `baseUrl()` / `accessToken()` from `@semiont/core` automatically.
+     *
+     * The remaining options (`refresh`, `validate`, `onAuthFailed`,
+     * `onError`) match `SemiontSessionConfig` exactly.
+     */
+    static fromHttp(opts: {
+        kb: KnowledgeBase;
+        storage: SessionStorage;
+        baseUrl: BaseUrl | string;
+        token?: AccessToken | string | null;
+        refresh?: () => Promise<string | null>;
+        validate?: (token: AccessToken) => Promise<UserInfo | null>;
+        onAuthFailed?: (message: string | null) => void;
+        onError?: (err: SemiontSessionError) => void;
+    }): SemiontSession;
+    /**
+     * Async factory for the credentials-first long-running script case.
+     * Builds the transport stack, calls `auth.password(email, password)`
+     * to acquire access + refresh tokens, persists them via the storage
+     * adapter, wires a default `refresh` callback that exchanges the
+     * refresh token via `auth.refresh(...)`, and returns the ready
+     * session.
+     *
+     * The consumer-supplied `refresh` callback becomes optional — only
+     * needed for non-standard refresh flows (worker-pool shared secret,
+     * OAuth refresh-token grant, interactive re-prompt). The default
+     * uses the refresh token returned by `auth.password`.
+     *
+     * `kb` is required and must be a full `KnowledgeBase`. The `id` field
+     * is the storage key for this session — distinct scripts sharing the
+     * same `SessionStorage` instance must use distinct ids to avoid
+     * trampling each other's tokens. The factory does not synthesize a
+     * default; the consumer makes the choice.
+     *
+     * Throws on auth failure with no resources leaked. On success, the
+     * returned session's `ready` promise has already resolved.
+     */
+    static signIn(opts: {
+        kb: KnowledgeBase;
+        storage: SessionStorage;
+        baseUrl: BaseUrl | string;
+        email: string;
+        password: string;
+        validate?: (token: AccessToken) => Promise<UserInfo | null>;
+        onAuthFailed?: (message: string | null) => void;
+        onError?: (err: SemiontSessionError) => void;
+    }): Promise<SemiontSession>;
 }
 
 /**
@@ -1109,7 +1294,7 @@ declare class SemiontBrowser {
      */
     readonly sessionActivating$: BehaviorSubject<boolean>;
     readonly openResources$: BehaviorSubject<OpenResource[]>;
-    readonly error$: Subject<SemiontError>;
+    readonly error$: Subject<SemiontSessionError>;
     readonly identityToken$: BehaviorSubject<string | null>;
     private readonly storage;
     /**
@@ -1685,4 +1870,4 @@ interface ComposePageVM extends ViewModel {
 }
 declare function createComposePageVM(client: SemiontClient, browse: ShellVM, params: ComposeParams, auth?: AccessToken): ComposePageVM;
 
-export { type ActiveJob, AdminNamespace, type AdminSecurityVM, type AdminUsersVM, type AnnotationGroups, type AnnotationHistoryResponse, AuthNamespace, BeckonNamespace, type BeckonVM, BindNamespace, BrowseNamespace, BusRequestError, type BusRequestPrimitive, COMMON_PANELS, type Cache, type CloneData, type ComposeMode, type ComposePageVM, type ComposeParams, type CreateAnnotationInput, type CreateFromTokenOptions, type CreateResourceInput, type DiscoverVM, type EntityTagsVM, type ExchangeVM, FrontendSessionSignals, type GatherAnnotationProgress, GatherNamespace, type GatherVM, type GenerateDocumentOptions, type GenerationOptions, type GetBrowserOptions, HOVER_DELAY_MS, type HoverHandlers, type ImportPreview, InMemorySessionStorage, type Job, type JobAssignment, type JobClaimAdapter, type JobClaimAdapterOptions, JobNamespace, type JobQueueVM, type KbSessionStatus, type KnowledgeBase, type MarkAssistEvent, type MarkAssistOptions, type MarkAssistProgress, MarkNamespace, type MarkVM, MatchNamespace, type MatchSearchProgress, type MatchVM, type NewKnowledgeBase, type OpenResource, type PendingAnnotation, RESOURCE_PANELS, type ReferenceData, type ReferencedByEntry, type RequestContent, type ResourceLoaderVM, type ResourceViewerPageVM, type ResponseContent, type SaveResourceParams, type SearchPipeline, type SearchPipelineOptions, type SearchState, SemiontBrowser, type SemiontBrowserConfig, SemiontClient, SemiontError, type SemiontErrorCode, SemiontSession, type SemiontSessionConfig, type SessionStorage, type SessionVM, type ShellVM, type ShellVMOptions, type SmelterActorVM, type SmelterActorVMOptions, type SmelterEvent, type StoredSession, type ToolbarPanelType, type User, type UserInfo, type ViewModel, type WelcomeVM, type WizardState, type YieldGenerationEvent, YieldNamespace, type YieldVM, busRequest, createAdminSecurityVM, createAdminUsersVM, createBeckonVM, createCache, createComposePageVM, createDiscoverVM, createDisposer, createEntityTagsVM, createExchangeVM, createGatherVM, createHoverHandlers, createJobClaimAdapter, createJobQueueVM, createMarkVM, createMatchVM, createResourceLoaderVM, createResourceViewerPageVM, createSearchPipeline, createSessionVM, createShellVM, createSmelterActorVM, createWelcomeVM, createYieldVM, defaultProtocol, getBrowser, isValidHostname, kbBackendUrl, notifyPermissionDenied, notifySessionExpired, setStoredSession };
+export { type ActiveJob, AdminNamespace, type AdminSecurityVM, type AdminUsersVM, type AnnotationGroups, type AnnotationHistoryResponse, AuthNamespace, BeckonNamespace, type BeckonVM, BindNamespace, BrowseNamespace, BusRequestError, type BusRequestErrorCode, type BusRequestPrimitive, COMMON_PANELS, type Cache, CacheObservable, type CloneData, type ComposeMode, type ComposePageVM, type ComposeParams, type CreateAnnotationInput, type CreateFromTokenOptions, type CreateResourceInput, type DiscoverVM, type EntityTagsVM, type ExchangeVM, FrontendSessionSignals, type GatherAnnotationProgress, GatherNamespace, type GatherVM, type GenerateDocumentOptions, type GenerationOptions, type GetBrowserOptions, HOVER_DELAY_MS, type HoverHandlers, type ImportPreview, InMemorySessionStorage, type Job, type JobAssignment, type JobClaimAdapter, type JobClaimAdapterOptions, JobNamespace, type JobQueueVM, type KbSessionStatus, type KnowledgeBase, type MarkAssistEvent, type MarkAssistOptions, type MarkAssistProgress, MarkNamespace, type MarkVM, MatchNamespace, type MatchSearchProgress, type MatchVM, type NewKnowledgeBase, type OpenResource, type PendingAnnotation, RESOURCE_PANELS, type ReferenceData, type ReferencedByEntry, type RequestContent, type ResourceLoaderVM, type ResourceViewerPageVM, type ResponseContent, type SaveResourceParams, type SearchPipeline, type SearchPipelineOptions, type SearchState, SemiontBrowser, type SemiontBrowserConfig, SemiontClient, SemiontSession, type SemiontSessionConfig, SemiontSessionError, type SemiontSessionErrorCode, type SessionStorage, type SessionVM, type ShellVM, type ShellVMOptions, type SmelterActorVM, type SmelterActorVMOptions, type SmelterEvent, type StoredSession, StreamObservable, type ToolbarPanelType, type User, type UserInfo, type ViewModel, type WelcomeVM, type WizardState, type YieldGenerationEvent, YieldNamespace, type YieldVM, busRequest, createAdminSecurityVM, createAdminUsersVM, createBeckonVM, createCache, createComposePageVM, createDiscoverVM, createDisposer, createEntityTagsVM, createExchangeVM, createGatherVM, createHoverHandlers, createJobClaimAdapter, createJobQueueVM, createMarkVM, createMatchVM, createResourceLoaderVM, createResourceViewerPageVM, createSearchPipeline, createSessionVM, createShellVM, createSmelterActorVM, createWelcomeVM, createYieldVM, defaultProtocol, getBrowser, isValidHostname, kbBackendUrl, notifyPermissionDenied, notifySessionExpired, setStoredSession };