@loomcycle/client 1.125.0 → 1.126.0

package/dist/types.d.ts

@@ -210,6 +210,38 @@ export type RunFileInput = {
     doc_path?: string;
     scope?: string;
     tags?: string[];
+    /** import: where the document came from, kept on it as a link back. */
+    source?: RunFileImportSource;
+    /** import: headings to add by line number, so a file whose structure is only
+     *  in its numbering imports as sections. The file is not changed, so the
+     *  document keeps the record of where it came from. */
+    headings?: RunFileImportHeading[];
+};
+/** import's `source`: the item's web link (a SharePoint `webUrl`, an email's
+ *  `webLink`), never a download or upload link. */
+export interface RunFileImportSource {
+    /** An http(s) link, at most 2048 bytes; a signature in its query is masked. */
+    url?: string;
+    kind?: "sharepoint" | "email" | "attachment" | "web" | "other";
+    /** One line, at most 300 characters. */
+    title?: string;
+}
+/** One entry of import's `headings`. Lines count from 1 in the file as it is;
+ *  give entries in increasing line order. */
+export type RunFileImportHeading = 
+/** The line itself becomes a heading; `lines` (1–10) joins a wrapped title. */
+{
+    line: number;
+    level: 2 | 3 | 4 | 5 | 6;
+    as: "heading";
+    lines?: number;
+}
+/** A heading with `title` is inserted before the line, which stays body text. */
+ | {
+    line: number;
+    level: 2 | 3 | 4 | 5 | 6;
+    as: "marker";
+    title: string;
 };
 /** What {@link LoomcycleClient.downloadRunInboxFile} returns: one inbox file's
  *  bytes and what the server says about them. */
@@ -1404,6 +1436,11 @@ export interface ClientOptions {
      *  When present, attached as `Authorization: Bearer <token>` on
      *  every request. */
     authToken?: string;
+    /** A source of short-lived bearers, instead of `authToken` (pass one or
+     *  the other): every request asks it for the token, and a 401 is retried
+     *  once with the token it hands back. An app signed in through loomcycle
+     *  passes an `OAuthTokenProvider`, which refreshes before expiry. */
+    tokenProvider?: TokenProvider;
     /** Custom fetch implementation; defaults to global `fetch`.
      *  Useful for testing (vi.fn()) or for runtimes that ship their
      *  own fetch (e.g. node-fetch on older Node). */
@@ -2088,19 +2125,34 @@ export interface UserSummary {
     registered?: boolean;
     display_name?: string;
     access_mode?: string;
-    status?: string;
+    /** The registered user's status; `""` for a subject seen only in runs. */
+    status?: UserStatus | (string & {});
 }
 export interface ListUsersResponse {
     users: UserSummary[];
 }
-/** One first-class users-table row (POST/PATCH /v1/_users). The tenant is
- *  server-derived from the authenticated principal, never sent. */
+/** A first-class user's status.
+ *
+ *  - `active` — the user may do what its access mode and bindings allow.
+ *  - `disabled` — refused everywhere; its delegated tokens are retired.
+ *  - `pending` — provisioned by a sign-in gate whose new users await
+ *    approval: the person can sign in, but every request is refused until
+ *    {@link LoomcycleClient.approveUser} makes the user `active`. Only a gate
+ *    puts a user here and only the approval takes one out, so createUser and
+ *    updateUser refuse it.
+ *
+ *  Fields typed `UserStatus | (string & {})` still accept a status a newer
+ *  server adds. */
+export type UserStatus = "active" | "disabled" | "pending";
+/** One first-class users-table row (POST/PATCH /v1/_users). The tenant is the
+ *  authenticated principal's, or the one an admin or `auth:manage` caller
+ *  names with `opts.tenant`; it is never in the body. */
 export interface UserRecord {
     tenant_id: string;
     subject: string;
     display_name: string;
     access_mode: string;
-    status: string;
+    status: UserStatus | (string & {});
     created_at: string;
     created_by: string;
 }
@@ -2110,14 +2162,18 @@ export interface CreateUserBody {
     /** "tenant" (default) collaborates on the tenant's shared primitives;
      *  "isolated" confines the member to its own user scope. */
     access_mode?: string;
-    status?: string;
+    /** Default `active`. `pending` is refused (400 `invalid_status`). */
+    status?: "active" | "disabled" | (string & {});
 }
 /** PATCH body — an omitted key leaves the column unchanged; a present key
  *  (even the empty string) is applied. */
 export interface UpdateUserBody {
     display_name?: string;
     access_mode?: string;
-    status?: string;
+    /** `disabled` also retires the user's delegated tokens. `pending` is
+     *  refused (400 `invalid_status`), and `active` on a pending user with 409
+     *  `use_approve`: call {@link LoomcycleClient.approveUser} instead. */
+    status?: "active" | "disabled" | (string & {});
 }
 /** The show-once result of POST /v1/_users/{subject}/tokens. `token` is the
  *  plaintext bearer, returned exactly once and never retrievable again. */
@@ -2170,6 +2226,171 @@ export interface ListUserTokensResponse {
     subject: string;
     tokens: UserTokenMeta[];
 }
+/** One identity-provider account a user signs in with, from
+ *  GET /v1/_users/{subject}/identities. Never a secret. */
+export interface UserIdentity {
+    /** The configured sign-in gate. */
+    gate: string;
+    /** The provider's issuer, when it reports one. */
+    issuer?: string;
+    /** The account's subject at the provider. */
+    external_subject: string;
+    email?: string;
+    email_verified: boolean;
+    created_at: string;
+    /** Absent until the account has been used to sign in. */
+    last_login_at?: string;
+}
+export interface UserIdentitiesResponse {
+    subject: string;
+    identities: UserIdentity[];
+}
+/** A sign-in gate's kind. Fields typed with it still accept a kind a newer
+ *  server adds. */
+export type AuthGateKind = "token" | "password" | "oidc" | "oauth" | "external" | "device" | (string & {});
+/** One configured sign-in gate, from GET /v1/_authgate. Never key material. */
+export interface AuthGate {
+    name: string;
+    kind: AuthGateKind;
+    label: string;
+    /** Whether a browser can sign in through it. */
+    interactive: boolean;
+    /** The gate's identity map, when it has one: whether it may provision
+     *  beyond the new-user floor, the tenant it maps to (or the claim naming
+     *  it) and how it provisions users. */
+    trusted?: boolean;
+    tenant?: string;
+    tenant_claim?: string;
+    provision?: string;
+    /** An external gate's signing key. */
+    key?: AuthGateKey;
+    callback_url?: string;
+    discovery_url?: string;
+    /** With `probe: true`: what the external gate's discovery document said. */
+    probe?: AuthGateProbe;
+    /** An external gate's removal timing. */
+    on_removed?: AuthGateRemoval;
+}
+/** An external gate's key as configured: algorithm, key id and fingerprint,
+ *  or for an HMAC secret the NAME of the env var holding it — never a key. */
+export interface AuthGateKey {
+    alg: string;
+    kid?: string;
+    fingerprint?: string;
+    secret_env?: string;
+}
+/** Durations, e.g. `168h0m0s`; `erase_after` may be `never`. */
+export interface AuthGateRemoval {
+    unbind_after: string;
+    erase_after: string;
+}
+export interface AuthGateProbe {
+    reachable: boolean;
+    /** The discovery document's HTTP status. */
+    status?: number;
+    /** A failure class (`unreachable`, `status`, …), never the response. */
+    error?: string;
+    name_matches: boolean;
+    key_matches: boolean;
+    capabilities?: string[];
+}
+export interface AuthGateListResponse {
+    gates: AuthGate[];
+}
+/** POST /v1/_authgate/{gate}/invites. The tenant is `opts.tenant`, not a
+ *  field here. */
+export interface CreateInviteBody {
+    /** An existing user to give a login at this gate. It keeps its access mode
+     *  and groups: the invite may restate but never raise them. Omitted, the
+     *  invite makes a new user when it is redeemed. */
+    subject?: string;
+    /** A new user's access mode, `tenant` or `isolated`; default the gate's
+     *  new-user floor. Beyond the floor only on a trusted gate (403
+     *  `beyond_floor` otherwise). */
+    access_mode?: string;
+    /** Groups for the new user; each must exist in the tenant. */
+    groups?: string[];
+    /** Fix the login the invitee gets; otherwise the invitee picks one (409
+     *  `login_taken` if it is in use at the gate). */
+    login?: string;
+    email?: string;
+    /** How long the link lives, as a Go duration (`72h`); default and maximum
+     *  are the gate's. */
+    ttl?: string;
+    /** Where the person lands after redeeming: a path on the server, or one
+     *  of the gate's `allowed_return_to`. */
+    return_to?: string;
+}
+/** A one-time invite link. `url` carries the code in its fragment: hand it to
+ *  the person and do not log it. It is shown once — listing invites never
+ *  returns it. */
+export interface CreatedInvite {
+    invite_id: string;
+    url: string;
+    expires_at: string;
+}
+export type AuthInviteState = "live" | "redeemed" | "revoked" | "expired";
+/** One invite from GET /v1/_authgate/{gate}/invites. Never its code. */
+export interface AuthInvite {
+    invite_id: string;
+    gate: string;
+    tenant_id: string;
+    /** Set for an invite to an existing user. */
+    subject?: string;
+    access_mode?: string;
+    groups: string[];
+    login?: string;
+    email?: string;
+    return_to?: string;
+    /** The owner invite of a tenant that has never had a user. */
+    bootstrap?: boolean;
+    created_by?: string;
+    created_at: string;
+    expires_at: string;
+    state: AuthInviteState;
+    redeemed_at?: string;
+    redeemed_subject?: string;
+    revoked_at?: string;
+}
+export interface AuthInviteListResponse {
+    invites: AuthInvite[];
+}
+/** A one-time password-reset link; like {@link CreatedInvite}, `url`
+ *  carries the code and is shown once. */
+export interface CreatedPasswordReset {
+    reset_id: string;
+    url: string;
+    expires_at: string;
+}
+/** A user's login at one gate, from GET /v1/_authgate/{gate}/identities. */
+export interface GateIdentity {
+    gate: string;
+    login: string;
+    email?: string;
+    email_verified: boolean;
+    created_at: string;
+    last_login_at?: string;
+    /** Whether the user has a password set. */
+    has_password: boolean;
+    /** Whether the user has a confirmed authenticator. */
+    has_totp: boolean;
+}
+export interface GateIdentitiesResponse {
+    tenant_id: string;
+    subject: string;
+    identities: GateIdentity[];
+}
+/** GET /v1/_authgate/{gate}/tenant-status: what a website needs to decide
+ *  on an owner (bootstrap) invite, and nothing about who the users are. */
+export interface GateTenantStatus {
+    tenant_id: string;
+    /** Whether the tenant has a user now. */
+    has_users: boolean;
+    /** Whether it has ever had one; once true, no owner invite or owner create
+     *  by an `auth:manage` credential is possible again. */
+    bootstrapped: boolean;
+    bootstrap_invite_live: boolean;
+}
 /** One entry in the runnable-agent catalog — the name to run + its tier.
  *  Intentionally lean: no operator metadata (versions, retired, hashes). */
 export interface RunnableAgent {
@@ -2204,6 +2425,8 @@ export interface WhoamiResponse {
     /** How the caller signed in. Absent on a server that predates Web UI
      *  sessions. */
     auth?: WhoamiAuth;
+    /** What narrows the caller's token below its scopes, when anything does. */
+    restrictions?: TokenRestrictions;
 }
 /** GET /v1/_me's sign-in block. `mode` is always present; the rest only when
  *  a Web UI session (not a bearer) authenticated the request. */
@@ -2218,6 +2441,10 @@ export interface WhoamiAuth {
     auth_time?: string;
     /** When the session stops authenticating unless renewed by activity. */
     session_expires_at?: string;
+    /** `pending` when the session's user awaits approval: every other request
+     *  the session makes is refused until the user is approved. Absent
+     *  otherwise. */
+    status?: "pending";
 }
 /** GET /v1/_me's capability summary. Bounded and non-secret: a fixed list of
  *  Web UI pages, no per-instance data. */
@@ -4415,6 +4642,16 @@ export interface AgentTranscription {
     /** At most the operator's `transcription.stt.max_minutes_per_run`. */
     max_minutes_per_run?: number;
 }
+/** An agent's text-to-speech settings. It can switch speech off for the agent
+ *  and lower the operator's per-run character cap; it can never raise it or
+ *  pick an engine, a model or a voice list. */
+export interface AgentSpeech {
+    /** Whether the agent may speak. Default `true` when the operator configured
+     *  an engine; `false` switches it off for this agent. */
+    enabled?: boolean;
+    /** At most the operator's `speech.max_chars_per_run`. */
+    max_chars_per_run?: number;
+}
 /** The `context` block of an {@link AgentDefOverlay}: {@link ContextOptions}
  *  in its wire spelling — see there for what each field does. A fork merges it
  *  per field, and the spawn tree inherits it. */
@@ -4611,6 +4848,8 @@ export interface AgentDefOverlay {
     compaction?: AgentCompaction;
     /** OCR and speech-to-text settings, merged per field. */
     transcription?: AgentTranscription;
+    /** Text-to-speech settings, merged per field. */
+    speech?: AgentSpeech;
     /** How history is distilled, merged per field. */
     context?: AgentContext;
     /** Volumes the file and exec tools may resolve paths against. None declared
@@ -5483,8 +5722,16 @@ export interface LLMEmbeddingsResponse {
 }
 /** A whitelisted grouping dimension for the usage report. */
 export type UsageDimension = "tenant" | "user" | "provider" | "model" | "source"
-/** What the calls were for: chat | ocr | stt. */
- | "purpose";
+/** What the calls were for (see `UsageAggregate.purpose`). */
+ | "purpose"
+/** The model tier the calls were resolved through; "pinned" for a named model. */
+ | "tier" | "user_tier"
+/** The agent that made the calls — the per-call detail window only. */
+ | "agent"
+/** foreground | background, derived from the purpose. */
+ | "class";
+/** The period a usage report splits its window into (UTC; weeks start Monday). */
+export type UsageBucket = "hour" | "day" | "week" | "month";
 /** One grouped row of a usage report; only the grouped dimensions are set. */
 export interface UsageAggregate {
     tenant_id?: string;
@@ -5493,8 +5740,21 @@ export interface UsageAggregate {
     model?: string;
     /** operator | tenant | user */
     credential_source?: string;
-    /** chat | ocr | stt — set when grouped by `purpose`. */
+    /** chat | gateway | consolidation | rerank | decision | compaction | recap |
+     *  unit_generation | image_description | embedding | ocr | stt | tts — set
+     *  when grouped by `purpose`. */
     purpose?: string;
+    tier?: string;
+    user_tier?: string;
+    agent?: string;
+    /** foreground | background — set when grouped by `class`. */
+    class?: string;
+    /** RFC 3339 start of the UTC period the row sums, when a bucket was asked for. */
+    period?: string;
+    /** The row folds every value of the first dimension outside `top`. */
+    other?: boolean;
+    /** Characters text-to-speech and embedding calls sent; absent when none. */
+    input_chars?: number;
     input_tokens: number;
     output_tokens: number;
     cache_creation_tokens: number;
@@ -5503,15 +5763,20 @@ export interface UsageAggregate {
     currency?: string;
     call_count: number;
     unpriced_calls: number;
-    /** Seconds of audio the group's speech-to-text calls transcribed (the unit
-     *  their per-minute price is computed from); absent when it has none. */
+    /** Seconds of audio the group's speech calls transcribed (stt) or produced
+     *  (tts), the unit a per-minute price is computed from; absent when it has none. */
     audio_seconds?: number;
 }
 export interface UsageReportResponse {
     group_by: string[];
     from?: string;
     to?: string;
+    bucket?: UsageBucket;
     rows: UsageAggregate[];
+    /** The oldest instant the per-call ledger holds; before it only whole days
+     *  survive, so hour buckets and the agent dimension stop there. Absent when
+     *  nothing is archived. */
+    detail_since?: string;
 }
 /** A per-scope token budget (RFC AW) plus its live month-to-date usage.
  *  `soft_limit` / `hard_limit` are absent when that tier is unset (no ceiling
@@ -6834,3 +7099,239 @@ export interface AuthzSimulateResponse {
     /** Lists the draft's bindings name that no layer has. */
     missing_acls: string[] | null;
 }
+/** The authorization server's metadata (RFC 8414), from
+ *  `GET /.well-known/oauth-authorization-server`. Published only when the
+ *  server knows its public address (`LOOMCYCLE_PUBLIC_URL`). */
+export interface OAuthServerMetadata {
+    issuer: string;
+    authorization_endpoint: string;
+    token_endpoint: string;
+    revocation_endpoint: string;
+    response_types_supported: string[];
+    grant_types_supported: string[];
+    code_challenge_methods_supported: string[];
+    token_endpoint_auth_methods_supported: string[];
+    revocation_endpoint_auth_methods_supported: string[];
+    /** The server adds `iss` to every authorization response (RFC 9207). */
+    authorization_response_iss_parameter_supported: boolean;
+}
+/** The token endpoint's answer (RFC 6749 §5.1). */
+export interface OAuthTokenResponse {
+    access_token: string;
+    /** Always `Bearer`. */
+    token_type: string;
+    /** Seconds the access token lives. */
+    expires_in: number;
+    /** Single use: each refresh returns a new one and spends the old one.
+     *  Presenting a spent one ends the whole sign-in. */
+    refresh_token: string;
+}
+/** A token answer with the moment the access token expires — what a caller
+ *  persists. */
+export interface OAuthTokenSet extends OAuthTokenResponse {
+    /** When the access token expires, in milliseconds since the epoch
+     *  (`Date.now()` at receipt plus `expires_in`). */
+    expires_at: number;
+}
+/** Input to `LoomcycleOAuth.beginAuthorize`. */
+export interface BeginAuthorizeOptions {
+    /** The app's registered client id. */
+    clientId: string;
+    /** One of the app's registered redirect URIs, exactly (a loopback one may
+     *  carry any port). */
+    redirectUri: string;
+    /** An opaque value to round-trip; a random one is generated when omitted.
+     *  1 to 1024 characters. */
+    state?: string;
+}
+/** What `LoomcycleOAuth.beginAuthorize` returns. Persist `verifier` and
+ *  `state` (session storage, never a URL) until the redirect comes back, then
+ *  send the person to `url`. */
+export interface AuthorizeRequest {
+    url: string;
+    /** The PKCE code verifier. A secret until the exchange: keep it out of
+     *  URLs and logs. */
+    verifier: string;
+    state: string;
+}
+/** The parameters the server puts on the redirect back to the app: `code`
+ *  on success, `error` (+ `error_description`) otherwise, `state` as sent,
+ *  and `iss` when the server knows its issuer (RFC 9207). */
+export interface AuthorizeResponseParams {
+    code?: string;
+    state?: string;
+    iss?: string;
+    error?: string;
+    error_description?: string;
+}
+/** Input to `LoomcycleOAuth.completeAuthorize`: the redirect's parameters
+ *  plus what `beginAuthorize` returned. */
+export interface CompleteAuthorizeOptions extends AuthorizeResponseParams {
+    /** The `state` beginAuthorize returned; a redirect carrying any other is
+     *  refused before the code is used. */
+    expectedState: string;
+    verifier: string;
+    clientId: string;
+    /** The same redirect URI the authorization request named. */
+    redirectUri: string;
+    signal?: AbortSignal;
+}
+/** Input to `LoomcycleOAuth.refresh`. */
+export interface RefreshTokenOptions {
+    refreshToken: string;
+    clientId: string;
+    signal?: AbortSignal;
+}
+/** Input to `LoomcycleOAuth.revoke`. */
+export interface RevokeTokenOptions {
+    /** A refresh token (ends the whole sign-in) or an access token (ends that
+     *  token only). */
+    token: string;
+    clientId: string;
+    signal?: AbortSignal;
+}
+/** Supplies the bearer for every request of a `LoomcycleClient` built with
+ *  `tokenProvider` instead of `authToken`. `OAuthTokenProvider` implements it
+ *  for an app sign-in; any other source of short-lived tokens can too. */
+export interface TokenProvider {
+    /** The token for the next request, refreshed ahead of expiry; undefined
+     *  sends none. A throw fails the request with that error. */
+    getToken(): Promise<string | undefined>;
+    /** Called at most once per request, after the server answered 401 to
+     *  `rejected`: a different token to retry with once, or undefined to let
+     *  the 401 stand. */
+    onUnauthorized?(rejected: string | undefined): Promise<string | undefined>;
+}
+/** A client's refresh-token lifetimes: Go durations or whole days (`"7d"`). */
+export interface AppClientRefresh {
+    idle?: string;
+    absolute?: string;
+}
+/** An app client's definition: an entry of the config's `auth.clients`, and
+ *  the body of a ClientDef. */
+export interface AppClientConfig {
+    /** `public`, the only kind: the app holds no secret and PKCE binds a code
+     *  to it. */
+    kind: string;
+    /** The name the login page shows. */
+    label?: string;
+    /** Exact https URIs, loopback URIs (any port, exact path) and private-use
+     *  scheme URIs (`myapp://callback`). */
+    redirect_uris: string[];
+    /** Origins allowed to call the token and revoke endpoints from a browser:
+     *  https, loopback, `chrome-extension://`, `moz-extension://`, `tauri://`. */
+    allowed_origins?: string[];
+    /** Go duration, 1m to 24h; default 1h. */
+    access_token_ttl?: string;
+    refresh?: AppClientRefresh;
+    /** Narrows every token the client's sign-ins mint, as a token's
+     *  restrictions record does. */
+    restrictions?: Record<string, unknown>;
+}
+/** The body of `POST /v1/_clientdef`. */
+export interface ClientDefInput {
+    op: "create" | "update" | "get" | "list" | "retire" | "verify";
+    /** The client id. Unique across the deployment, retired names included. */
+    name?: string;
+    def_id?: string;
+    client?: AppClientConfig;
+    description?: string;
+    /** Admin only. On create: the tenant whose people the client signs in, ""
+     *  (the default) for every tenant. On list: focus one tenant. A tenant
+     *  operator's clients are always its own tenant's. */
+    tenant?: string;
+    /** verify: the content hash to compare with the deployed one. */
+    content_sha256?: string;
+}
+/** A runtime-registered client (a ClientDef version). */
+export interface ClientDefRecord {
+    name: string;
+    source: "def";
+    def_id: string;
+    version: number;
+    /** The tenant whose people it signs in; "" for every tenant. */
+    tenant_id: string;
+    all_tenants: boolean;
+    label: string;
+    redirect_uris: string[];
+    /** The definition as stored. */
+    client: AppClientConfig;
+    description: string;
+    content_sha256: string;
+    created_at: string;
+    created_by: string;
+    created_by_tenant: string;
+    read_only: false;
+}
+/** A client declared in the server's config: read only through the API. */
+export interface ConfigAppClient {
+    name: string;
+    source: "config";
+    label: string;
+    all_tenants: true;
+    tenant_id: string;
+    redirect_uris: string[];
+    allowed_origins: string[];
+    access_token_ttl: string;
+    refresh_idle: string;
+    refresh_absolute: string;
+    read_only: true;
+}
+/** A client as `get` and `list` report it. */
+export type AppClientEntry = ClientDefRecord | ConfigAppClient;
+/** `op: "list"`: the clients the caller may see, config ones included. */
+export interface ClientDefListResponse {
+    clients: AppClientEntry[];
+}
+/** `op: "verify"`: whether a client is deployed and matches a hash. An absent
+ *  client (or one the caller may not see) answers `deployed: false`. */
+export interface ClientDefVerifyResult {
+    name: string;
+    deployed: boolean;
+    current_def_id?: string;
+    current_sha256?: string;
+    version?: number;
+    matches: boolean;
+}
+/** `op: "retire"`. */
+export interface ClientDefRetireResult {
+    name: string;
+    retired: boolean;
+}
+/** One row of `GET /v1/_clientdef/names`. */
+export interface ClientDefNameSummary {
+    name: string;
+    source: "def" | "config";
+    tenant_id: string;
+    label: string;
+    read_only: boolean;
+}
+export interface ClientDefNamesResponse {
+    names: ClientDefNameSummary[];
+}
+/** What to show the person: open `verificationUri` and type `userCode`, or
+ *  open `verificationUriComplete`, which carries the code. */
+export interface DeviceLoginPrompt {
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete?: string;
+    /** Seconds until the code expires. */
+    expiresIn: number;
+}
+export interface DeviceLoginOptions {
+    /** How the client names itself on the approval page (default "loomcycle-ts"). */
+    clientId?: string;
+    /** Called once with the code to show; polling starts after it returns. */
+    onPrompt: (prompt: DeviceLoginPrompt) => void | Promise<void>;
+    signal?: AbortSignal;
+}
+/** The token issued to the person who approved the login: their own member
+ *  token, never wider than the session they approved from and never living
+ *  past it. Keep it in an OS credential store, never a plain file. */
+export interface DeviceLoginResult {
+    accessToken: string;
+    tokenType: string;
+    /** Seconds until the token expires. */
+    expiresIn?: number;
+    scope?: string[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loomcycle/client",
-  "version": "1.125.0",
+  "version": "1.126.0",
   "description": "TypeScript client for the loomcycle sidecar (HTTP+SSE). 71 methods covering run streaming, agent metadata, pause/resume/state, resolver re-probe (resolveProbe — issue #88 operator escape hatch), operator-token admin (operatorTokenDef — RFC L OSS multi-tenant auth) + whoami (RFC L authoritative principal, v0.17.0) + tenant-scoped listUsers / listUserAgents, dynamic MCP registration (mcpServerDef + v0.18.0 typed mcpServerDefVerify + ensureMcpServer idempotent register-if-changed), snapshot lifecycle, memory admin (incl. v0.9.0 Vector Memory embed_stats + reembed AND v0.11.5 setMemoryEntry + deleteMemoryEntry), interruption resolve, hook management, v0.8.22 substrate admin (agentDef + skillDef), v0.9.x n8n Phase 0 (listChannels + streamUserRunStates), v0.9.x Channel CRUD (publishChannel + subscribeChannel + peekChannel + ackChannel), v0.11.5 Channel admin CRUD (createChannel + updateChannel + deleteChannel — runtime substrate; yaml channels refuse mutation with HTTP 409), v0.9.x content_sha256 verify, v0.9.1 transcript first-cycle, v0.9.x dynamic MCP server registration (mcpServerDef + MCPServerDefVerifyResult), v0.10.3 Library v2 enumeration (listLibraryAgents + listLibrarySkills + listLibraryMcpServers), and v0.11.0 LLM Gateway (llmChat + llmStream — direct provider routing without agent overhead; primary target is n8n's LoomCycleChatModel AI Agent sub-node and any LangChain-compatible consumer). v0.10.1 — dual ESM + CommonJS distribution (additive — ESM consumers unchanged; CJS consumers like n8n's community-node loader now work). v0.19.0 — typed inline code-js agent ingestion (AgentDefOverlay.code_body + ensureCodeAgent — register a deterministic code agent through the substrate with no host filesystem bind; RFC J). v0.20.0 — ensureMcpServer surfaces discoveredToolCount straight from create (loomcycle now auto-discovers MCP tools at ingestion); rediscover is now an explicit force-refresh. v0.21.0 — run/continue accept optional non-secret `metadata` (repo name, review policy, …) passed to the agent, symmetric with the WebHook/Schedule trigger paths. v0.22.0 — version-aligned lockstep release; no client-surface change (RFC N tenant isolation of the agent/skill/MCP/Schedule/Webhook definition plane + real op-schemas on the builtin MCP meta-tools are both server-side). v0.23.0 — version-aligned lockstep release; no client-surface change (RFCs O/P/R MCP-server hardening + thin client and the RFC Q DeepSeek tool-content fix are all server-side / MCP-transport-side). v0.24.0 — purgeChannel clears a channel's buffered messages without deleting its definition (allowed on yaml-declared channels too, unlike deleteChannel — F20); AgentDefOverlay gains channels / evaluation_scopes / interruption so a COMPLETE interactive/multi-agent agent round-trips over the substrate (F14). (Consolidates the interim 0.24/0.25 package bumps, which were never tag-published, back into lockstep with the loomcycle v0.24.0 tag.) v0.25.0 — adds the RFC S channel fan-in/fan-out client twins: awaitChannels() (wait for any/all/at_least N messages across channels, or a timeout — non-committing) + broadcastChannels() (publish one payload to N channels in one atomic-pre-flight call), the client-facing counterparts of the in-band Channel.await / Channel.broadcast tool ops (the rest of v0.25.0 — the manual-management Web UI console + Context op=time + max_fires self-retiring schedules — is server-side / in-band, no client-surface change). v0.29.1 — Usage gains optional `max_context_tokens` (the serving model's context-window ceiling, stamped by the loop from Provider.Capabilities() on each usage event) so a consumer can render a 'context used / max' gauge without a hard-coded per-model table; additive + optional, no behavior change. (Lockstep catch-up: the field landed in loomcycle v0.29.0 but the adapter publish skipped on a version mismatch; v0.29.1 realigns the package version with the release tag so it publishes.) v0.33.0 — gRPC + TS client parity for the RFC Y external fan-out and the compaction surface: spawnRunBatch() (POST /v1/runs:batch — spawn up to 32 fresh runs concurrently in one call, combined index-aligned envelope, per-child failures in-envelope) + compactRun(runId) (POST /v1/runs/{run_id}/compact — summarize a parked run's context); plus per-run sampling + compaction overrides now accepted on runStreaming / continueSession (an explicit temperature 0 is preserved as deterministic, not dropped as falsy). (The gRPC half adds the matching SpawnRunBatch / CompactRun RPCs + the sampling/compaction fields on RunRequest/ContinueRequest — server-side.) v0.34.0 — version-aligned lockstep release; no client-surface change (context-transform plugins / RFC Z Phase 1a are server-side config; the exp7 hardening pass is server-side; the R2 cross-provider thinking-model downgrade surfaces a new `model_downgraded` SSE event the generic stream passes through unchanged). v0.35.0 — RFC AH dynamic filesystem volumes: volumeDef() (POST /v1/_volumedef — op-discriminated create/get/list/delete/purge; a Volume is flat, so delete unmaps + purge RemoveAll's, no retire/promote/fork) + listVolumes() / listEphemeralVolumes() (GET /v1/_volumes[/ephemeral] — tenant-scoped; host paths redacted for non-operator callers). Tenant-confined; the runtime derives the path inside an operator-blessed dynamic_root, so callers pass name + mode, never a host path. v1.1.1 — RFC AI interactive agentic sessions: an `interactive: true` flag on runStreaming/continueSession (a run that parks at end_turn for steering) + sendRunInput(runId, text) (POST /v1/runs/{id}/input — steer a live run) + streamRunByID(runId, {fromSeq}) (GET /v1/runs/{id}/stream — re-attach by run_id; the operator's prior turns replay as `steer` events so a cold client reconstructs the whole conversation) + a high-level InteractiveSession driver (client.interactiveSession / attachInteractiveSession — events()/send()/cancel(), the adapter port of the Web UI run terminal). The AgentEvent union gains awaiting_input/steer/context_compaction frames. Version-aligned with the loomcycle v1.1.x line so the v1.1.1 tag publishes it (also carrying the previously-unpublished v0.35.0 volume surface). v1.4.0 — RFC AL Path VFS + RFC AK Document on the wire: path(input) (POST /v1/_path — a Unix-like filesystem over Memory/Volumes/Documents; resolve/ls/stat/mkdir/mv/rm) + document(input) (POST /v1/_document — chunked-graph documents; 13 ops, needs SQL Memory on the sidecar). Scope (agent/user/tenant) + tenant are resolved server-side from the authenticated principal, never the wire; an off-run scope:'user' op keys on the principal subject so it interoperates with that user's agent runs. New PathToolInput / DocumentToolInput types; responses are op-varying (unknown — narrow as needed). v1.7.0 — RFC AT image/vision input: the PromptContent union gains an `image` variant ({ type:'image'; media_type: ImageMediaType; data: base64-no-prefix }) accepted in a user segment by runStreaming / continueSession (segments pass through unchanged — no method change). The model must be vision-capable or the run errors before the call. New ImageMediaType type (image/png|jpeg|gif|webp). v1.12.1 — Path/Document browse-by-subject + the full Document op set (RFC AS/AK): path(input, opts) / document(input, opts) accept optional scopeId / tenant browse overrides sent as ?scope_id= / ?tenant= query params (server reads them from the URL, re-checks authorization; omit both to browse your own subject — byte-identical to the pre-RFC-AS request), and DocumentToolInput.op now covers all 16 backend ops (adds set_path, export_md, import_md) with the matching include_metadata / markdown fields. Additive — existing path() / document() callers are unchanged. v1.16.0 — RFC BC client-executed tools (local tool host): connectClientTools({tools,onInvoke}) opens a persistent WebSocket to /v1/client-tools, registers tools this client runs on the user's machine (browser DOM / files / shell), and answers the invoke frames loomcycle routes when an agent of your principal calls a client:<tool> — returning your reply as an ordinary tool result. Returns a ClientToolHost driver (.close() to stop; auto-reconnect); dependency-free (global WebSocket in browsers / Node 22+, or an injected WebSocketImpl like the ws package on older Node); the bearer rides the Sec-WebSocket-Protocol subprotocol (browsers can't set an Authorization header on a WebSocket). The runtime's first WebSocket surface. v1.45.0 — RFC BL P5 subject erasure: erasureReport(subject, {tenant}) (GET /v1/_erasure — what this deployment holds about one subject, in three tiers: deletable with existing primitives, subject-keyed but not deletable, and facts ABOUT the subject in scopes they do not own) + erasureExecute(subject, {dryRun, confirm, tenant}) (POST /v1/_erasure — removes tiers 1 and 2). DEFAULTS TO A DRY RUN: dryRun defaults true and a live run also requires confirm === subject. The tier-3 residue is traceable only through the subject's chats, which a live run deletes, so a report afterwards shows rows: 0 while those facts remain — the returned object is the only durable record of what was not reached; persist it. New ErasureReport / ErasureResult / ErasureTier / ErasureResidue types. v1.47.0 — RFC BV memory-view SDK: memorySearch() (POST /v1/_memory/search — off-run unified semantic search spanning k/v entries AND document-chunk bodies in one ranked list, each hit tagged kind memory|document with chunk_id on document hits) + memoryEmbedStats(scope) + reembedMemory(scope, scopeId, {dryRun,limit}) (the Vector Memory embed-admin reads the memory-view console needs; dry_run defaults true). Fact reads (list_facts + get_chunk's entity block) ride the existing document() passthrough. Additive — existing callers unchanged. v1.61.0 — RFC CJ per-run context-window override: runStreaming / continueSession accept an optional maxContextTokens (integer tokens) that wins over the agent's own max_context_tokens; omitted inherits it (which defers to the provider/driver default). Distinct from a model's output cap; primarily for local inference (Ollama num_ctx). Serialized as the snake_case max_context_tokens field on POST /v1/runs + the continuation body; additive, existing callers unchanged. v1.72.1 — the TeamDef version lifecycle: listTeamVersions(name) (op=list — every version of one team, newest first), promoteTeam(defId) (op=promote — point the active pointer, which is what a run BY NAME executes; forkTeam defaults to promote:false, so authoring and putting in force stay two steps), retireTeam(defId, retired) (op=retire — reversible and version-scoped, unlike deleteTeam) and verifyTeam(name, contentSha256) (op=verify — the drift check for a workflow kept in source control and pushed to several deployments; an absent team answers deployed:false rather than raising). The ops existed on the substrate and over HTTP; a client that could author a team could not put one in force.",
   "license": "Apache-2.0",
   "type": "module",