@muhkoo/connect 0.3.0-alpha.0 → 0.6.0-alpha.1

package/dist/connect.d.ts

@@ -936,6 +936,14 @@ declare class EncryptedSession {
 interface WSTransportOptions {
     /** WebSocket URL, e.g. `ws://localhost:8787/foo`. */
     url: string;
+    /**
+     * Optional async provider for a FRESH connection URL, called before each
+     * RECONNECT. Use it when the URL carries a single-use/expiring credential
+     * (e.g. a one-time WS upgrade ticket): on reconnect the baked-in ticket is
+     * already consumed/expired, so without this the reconnect is rejected and the
+     * transport burns through its attempts. The initial connect uses `url` as-is.
+     */
+    urlProvider?: () => string | Promise<string>;
     /**
      * Stable identifier for this connection (a channel / space / personal-space
      * id). Lifecycle + MESSAGE events are namespaced by it on the shared
@@ -991,6 +999,7 @@ declare class WSTransport extends EventCore {
     readonly off: (event: EventCoreEvents, handler: EventListener | CallableFunction) => void;
     private scopedEvent;
     private url;
+    private urlProvider?;
     private socket;
     private _isConnected;
     private _isConnecting;
@@ -1586,6 +1595,12 @@ interface WriteToShardsInput {
      * resumable uploads: the same id always maps to the same manifest slot.
      */
     fileId?: string;
+    /**
+     * Optional upload-progress callback, invoked after each chunk finishes
+     * (`completed` of `total` chunks). Lets a UI show a progress bar. Called once
+     * with `(0, total)` before the first chunk so a bar can render immediately.
+     */
+    onProgress?: (completed: number, total: number) => void;
 }
 declare class FileStorage {
     private readonly space;
@@ -2279,6 +2294,7 @@ declare class HttpClient {
     readonly fetch: typeof fetch;
     get<T = unknown>(path: string): Promise<T>;
     post<T = unknown>(path: string, body?: unknown): Promise<T>;
+    patch<T = unknown>(path: string, body?: unknown): Promise<T>;
     del<T = unknown>(path: string, body?: unknown): Promise<T>;
     private request;
 }
@@ -2357,6 +2373,101 @@ declare class KvNamespace {
     private getCipher;
 }
 
+/**
+ * `client.db` — the app's scalable database. A developer defines tables in the
+ * Muhkoo portal (columns + indexes); each table is backed by its own Durable
+ * Object SQLite instance and reachable through a sanitized REST gateway. This
+ * namespace wraps that gateway:
+ *
+ *   const todos = client.db.table('todos');
+ *   const { id } = await todos.insert({ title: 'Buy milk', done: false });
+ *   const one    = await todos.get(id);
+ *   const { rows, nextCursor } = await todos.query({
+ *     where: [{ column: 'done', op: 'eq', value: false }],
+ *     orderBy: { column: 'rank', dir: 'asc' },
+ *     limit: 50,
+ *   });
+ *   await todos.update(id, { done: true });
+ *   await todos.delete(id);
+ *
+ * Authorization is the **app key** ({@link HttpClient} stamps it on every
+ * request); the appId + environment are resolved server-side from the key, so a
+ * key can only ever reach its own app's tables. The front end never touches the
+ * database directly — this REST surface is the only gateway, and all input is
+ * validated against the table's schema (parameterized statements, column +
+ * operator allowlists). There is no raw-SQL passthrough.
+ *
+ * Schema is authored in the portal, not here (the SDK reads + writes rows, it
+ * doesn't create tables). Pagination is keyset-based: pass the `nextCursor` from
+ * a previous `query()` back as `cursor` to fetch the next page.
+ */
+
+interface DbNamespaceDeps {
+    http: HttpClient;
+}
+/** Comparison operators allowed in a {@link DbQuery} `where` clause. */
+type DbFilterOp = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "in" | "like" | "likeStartsWith" | "likeContains";
+interface DbWhereCondition {
+    column: string;
+    op: DbFilterOp;
+    /** Scalar for most ops; an array for `in`; a string for the `like` family. */
+    value: unknown;
+}
+interface DbQuery {
+    /** Columns to return; omit for all columns. */
+    select?: string[];
+    /** Conditions AND-combined. */
+    where?: DbWhereCondition[];
+    /** Sort by a column (defaults to the primary key, ascending). */
+    orderBy?: {
+        column: string;
+        dir?: "asc" | "desc";
+    };
+    /** Page size, clamped server-side to 100. */
+    limit?: number;
+    /** Opaque keyset cursor from a previous query's `nextCursor`. */
+    cursor?: string;
+}
+interface DbQueryResult<T = Record<string, unknown>> {
+    rows: T[];
+    /** Cursor for the next page, or `null` when the last page was returned. */
+    nextCursor: string | null;
+}
+/** A handle to one table — the ergonomic surface for row operations. */
+declare class DbTable<T extends Record<string, unknown> = Record<string, unknown>> {
+    private readonly http;
+    private readonly name;
+    constructor(http: HttpClient, name: string);
+    private base;
+    /** Insert a row. Returns the created row and its primary-key value. */
+    insert(values: Partial<T>): Promise<{
+        row: T;
+        id: unknown;
+    }>;
+    /** Fetch a row by primary key, or `null` if it doesn't exist. */
+    get(id: string | number): Promise<T | null>;
+    /** Query rows with filters, ordering, and keyset pagination. */
+    query(query?: DbQuery): Promise<DbQueryResult<T>>;
+    /** Update a row by primary key. Returns the updated row. */
+    update(id: string | number, values: Partial<T>): Promise<{
+        row: T;
+    }>;
+    /** Delete a row by primary key. Returns the number of rows removed (0 or 1). */
+    delete(id: string | number): Promise<number>;
+}
+declare class DbNamespace {
+    private readonly deps;
+    constructor(deps: DbNamespaceDeps);
+    /**
+     * A handle to a table defined in the portal. The optional type parameter
+     * gives row operations a typed shape:
+     *
+     *   interface Todo { _id: number; title: string; done: boolean }
+     *   const todos = client.db.table<Todo>('todos');
+     */
+    table<T extends Record<string, unknown> = Record<string, unknown>>(name: string): DbTable<T>;
+}
+
 /**
  * `client.storage` — file storage. Hides the `FileStorage` / `ShardClient` /
  * `SharedSpaceClient` primitives behind the unified client.
@@ -2516,6 +2627,23 @@ interface RosterMember {
     /** Base64url-encoded JWK of the member's identity ECDSA public key. */
     identityEcdsaPub?: string;
 }
+/** A shareable invite link to a space. Redeeming it allowlists the holder so
+ *  the keeper admits them. */
+interface InviteLink {
+    /** The capability token; embed in a URL to share. */
+    token: string;
+    /** Member id (username) that created the link. */
+    createdBy?: string;
+    createdAt?: number;
+    /** Epoch ms when the link stops working; 0 = never. */
+    expiresAt?: number;
+    /** Max redemptions; 0 = unlimited. */
+    maxUses?: number;
+    /** Redemptions so far. */
+    uses?: number;
+    /** Access level granted to redeemers ("viewer" | "editor"). */
+    role?: string;
+}
 
 /**
  * PacketCipher — the strategy `Network` uses to seal/open a packet's payload.
@@ -2929,7 +3057,9 @@ declare class Space {
         memberId: string;
         identityEcdhPub: string;
     }>): Promise<number>;
-    putFile(file: File | Blob | Uint8Array, metadata: SpaceFileMetadata): Promise<{
+    putFile(file: File | Blob | Uint8Array, metadata: SpaceFileMetadata, opts?: {
+        onProgress?: (completed: number, total: number) => void;
+    }): Promise<{
         manifest: FileManifest;
         stat: FileStat;
     }>;
@@ -3135,6 +3265,40 @@ declare class SpaceNamespace {
     joinChannel(name: string, opts?: {
         timeoutMs?: number;
     }): Promise<Space>;
+    /** Mint a shareable invite link for a space. `opts.expiresInSec` / `maxUses`
+     *  bound it (0/undefined = unlimited); `opts.role` ("viewer"|"editor") is the
+     *  access granted to redeemers (default viewer). Returns the link. */
+    createInviteLink(spaceId: string, opts?: {
+        expiresInSec?: number;
+        maxUses?: number;
+        role?: string;
+    }): Promise<InviteLink>;
+    /** Set a member's role on a space ("viewer" | "editor"). Owner-only. */
+    setMemberRole(spaceId: string, username: string, role: string): Promise<void>;
+    /** Roster with roles (owner/members only). */
+    members(spaceId: string): Promise<Array<{
+        memberId: string;
+        role: string;
+    }>>;
+    /** List a space's active invite links (creator/members only). */
+    listInviteLinks(spaceId: string): Promise<InviteLink[]>;
+    /** Revoke an invite link by token. */
+    revokeInviteLink(spaceId: string, token: string): Promise<void>;
+    /**
+     * Join a space using an invite link: redeem the token (the keeper admits
+     * this member), then connect and resolve once the group key arrives.
+     * Returns the open {@link Space}.
+     */
+    joinByInvite(spaceId: string, token: string, opts?: {
+        timeoutMs?: number;
+    }): Promise<Space>;
+    /** The current member roster of a space (member id → identity public keys). */
+    roster(spaceId: string): Promise<Array<{
+        memberId: string;
+        identityEcdhPub: string;
+        identityEcdsaPub?: string;
+    }>>;
+    private keyringFor;
     private build;
     /** Ensure the member has an identity keypair; return its public ECDH + ECDSA keys. */
     private ensureIdentity;
@@ -3143,6 +3307,270 @@ declare class SpaceNamespace {
     private myId;
 }
 
+/**
+ * `client.agents` — manage an app's **Programmable Agents** (server-side
+ * "virtual users" backed by Workers AI).
+ *
+ *   const { config } = await client.agents.create(appId, {
+ *     handle: '@assistant', displayName: 'Assistant',
+ *     systemPrompt: 'You are a helpful teammate in this Space.',
+ *     triggers: [{ type: 'mention' }],
+ *   });
+ *   await client.agents.enable(appId, config.agentId, spaceId);  // per-Space opt-in
+ *
+ * These are MANAGEMENT calls — the agent itself runs on the accelerator. Only an
+ * app's owner or an editor of its shared Space may create/update/enable an agent
+ * (viewers can read). Authorization rides the user session token; non-owner
+ * editors pass their management Space via `opts.space`.
+ *
+ * An agent is "prompts + persona": a system prompt, a model, named prompt
+ * `skills`, and `triggers` that decide when it speaks — plus optional `tools`
+ * that let it act on the app (query/write its database, call its functions,
+ * resolve its channels) via a server-side function-calling loop. See
+ * {@link AgentToolsConfig}. Pair with the `@MuhkooAgent`/`@MuhkooSpace`/
+ * `@MuhkooDB`/`@MuhkooFunction` decorators + `ejectAgentPrompt`/`ejectAgentTools`
+ * to generate `systemPrompt` and `tools` straight from your app's surface.
+ */
+
+type AgentTriggerType = "mention" | "keyword" | "regex" | "always";
+/** How much database access the agent's tool-use has. */
+type AgentDbToolMode = "off" | "read" | "write";
+/**
+ * Tool-use config — lets the agent act on the app through a function-calling
+ * loop. Opt-in and conservatively gated server-side: a fresh agent has tools
+ * off, the DB is read-only and per-table allowlisted, functions are per-name
+ * allowlisted, and channels are off. **Enabling tools requires a
+ * function-calling `model` in the same create/update payload** (the server
+ * rejects `enabled: true` otherwise). `ejectAgentTools` produces this shape.
+ */
+interface AgentToolsConfig {
+    enabled: boolean;
+    db: {
+        /** `off` = no DB tools; `read` = query/get; `write` = + insert/update/delete. */
+        mode: AgentDbToolMode;
+        /** Allowlisted table names the agent may touch. */
+        tables: string[];
+    };
+    /** Allowlisted serverless-function names the agent may call. */
+    functions: string[];
+    /** Whether the agent may resolve the app's PUBLIC channels. */
+    channels: boolean;
+    /** Max tool-call rounds per reply (1..6). */
+    maxIterations: number;
+}
+interface AgentTrigger {
+    type: AgentTriggerType;
+    /** Required for `keyword` (case-insensitive substring) and `regex`. */
+    pattern?: string;
+    /** Name of a {@link AgentSkill} to run on match. */
+    skill?: string;
+}
+interface AgentSkill {
+    name: string;
+    prompt: string;
+}
+interface AgentConfig {
+    agentId: string;
+    /** @-mention target, e.g. "@assistant". */
+    handle: string;
+    displayName: string;
+    model: string;
+    systemPrompt: string;
+    skills: AgentSkill[];
+    triggers: AgentTrigger[];
+    /** Space ids this agent is enabled on (per-Space opt-in). */
+    enabledSpaces: string[];
+    caps: {
+        dailyTokenBudget: number;
+    };
+    /** Tool-use config (absent / `enabled: false` = prompt-only). */
+    tools?: AgentToolsConfig;
+    createdAt: number;
+    updatedAt: number;
+}
+/** The editor-settable fields when creating an agent. */
+interface AgentCreateInput {
+    handle: string;
+    displayName: string;
+    systemPrompt: string;
+    model?: string;
+    skills?: AgentSkill[];
+    triggers?: AgentTrigger[];
+    caps?: {
+        dailyTokenBudget: number;
+    };
+    /** Grant tool-use. Requires `model` to be a function-calling model. */
+    tools?: AgentToolsConfig;
+}
+type AgentUpdateInput = Partial<AgentCreateInput>;
+/** Create/get response — the config plus the agent's published identity keys. */
+interface AgentProvisioned {
+    config: AgentConfig;
+    /** The agent's Space member id (`__agent__:<agentId>`). */
+    memberId: string;
+    /** base64url-JWK identity ECDH public key (null until provisioned). */
+    ecdhPub: string | null;
+    /** base64url-JWK identity ECDSA public key — verifies the agent's messages. */
+    ecdsaPub: string | null;
+}
+interface AgentsNamespaceDeps {
+    http: HttpClient;
+}
+/** Common option: a management Space for delegated (non-owner) access. */
+interface AgentScopeOpts {
+    space?: string;
+}
+declare class AgentsNamespace {
+    private readonly deps;
+    constructor(deps: AgentsNamespaceDeps);
+    /** List the app's agents. */
+    list(appId: string, opts?: AgentScopeOpts): Promise<AgentConfig[]>;
+    /** Read one agent (config + identity keys). */
+    get(appId: string, agentId: string, opts?: AgentScopeOpts): Promise<AgentProvisioned>;
+    /** Create an agent (owner/editor only). */
+    create(appId: string, input: AgentCreateInput, opts?: AgentScopeOpts): Promise<AgentProvisioned>;
+    /** Update an agent's editor-settable fields (owner/editor only). */
+    update(appId: string, agentId: string, patch: AgentUpdateInput, opts?: AgentScopeOpts): Promise<{
+        config: AgentConfig;
+    }>;
+    /** Delete an agent (owner/editor only). */
+    delete(appId: string, agentId: string, opts?: AgentScopeOpts): Promise<{
+        deleted: boolean;
+    }>;
+    /** Enable the agent on a Space (per-Space opt-in). */
+    enable(appId: string, agentId: string, spaceId: string, opts?: AgentScopeOpts): Promise<{
+        config: AgentConfig;
+    }>;
+    /** Disable the agent on a Space. */
+    disable(appId: string, agentId: string, spaceId: string, opts?: AgentScopeOpts): Promise<{
+        config: AgentConfig;
+    }>;
+    private path;
+}
+
+/**
+ * `client.functions` — manage an app's **serverless functions** (developer-
+ * authored code that runs on the accelerator).
+ *
+ *   const { config } = await client.functions.deploy(appId, {
+ *     name: 'hello', displayName: 'Hello',
+ *     code: `export default { fetch: () => new Response('hi') }`,
+ *     triggers: { http: { enabled: true } },
+ *   });
+ *   // HTTP-reachable at  hello--<slug>.fns.muhkoo.dev
+ *   await client.functions.enable(appId, config.functionId, spaceId); // Space-bound
+ *
+ * These are MANAGEMENT calls — the function itself runs on the accelerator
+ * (uploaded just-in-time, decrypted only at invocation). Only an app's owner or
+ * an editor of its shared Space may deploy/update/enable (viewers read).
+ * Authorization rides the user session token; non-owner editors pass their
+ * management Space via `opts.space`.
+ *
+ * v1 is "compute-only": a function is an untrusted single-module ES worker
+ * (`export default { fetch }`) with NO platform bindings — it reaches the
+ * platform as an external client (the end-user session is passed through). Two
+ * triggers: `http` (its own subdomain) and `space` (invoked on Space messages,
+ * like a Programmable Agent).
+ */
+
+type FunctionTriggerType = "keyword" | "regex" | "always";
+interface FunctionTrigger {
+    type: FunctionTriggerType;
+    /** Required for `keyword` (case-insensitive substring) and `regex`. */
+    pattern?: string;
+}
+interface FunctionTriggers {
+    /** HTTP-invocable at `<name>--<slug>.fns.<zone>`. */
+    http?: {
+        enabled: boolean;
+        methods?: string[];
+    };
+    /** Invoked on matching Space messages (per-Space opt-in via enable). */
+    space?: {
+        match: FunctionTrigger[];
+    };
+}
+interface FunctionCaps {
+    /** Per-invocation CPU ceiling (ms). */
+    cpuMs: number;
+    /** Per-invocation subrequest ceiling. */
+    subRequests: number;
+    /** Hard daily invocation cap (0 = unlimited). */
+    dailyInvocationBudget: number;
+}
+interface FunctionConfig {
+    functionId: string;
+    /** DNS-safe slug — the function's subdomain label + WfP script name part. */
+    name: string;
+    displayName: string;
+    triggers: FunctionTriggers;
+    /** Space ids this function is enabled on (per-Space opt-in for `space`). */
+    enabledSpaces: string[];
+    caps: FunctionCaps;
+    scriptName: string;
+    /** sha-256 of the last-deployed source. */
+    codeHash?: string;
+    /** When the source was last (re)deployed. */
+    deployedAt?: number;
+    createdAt: number;
+    updatedAt: number;
+}
+/** The editor-settable fields when deploying a function. */
+interface FunctionDeployInput {
+    name: string;
+    displayName: string;
+    /** Raw single-module ES worker source (`export default { fetch }`). */
+    code: string;
+    triggers?: FunctionTriggers;
+    caps?: Partial<FunctionCaps>;
+}
+/** Update input — any subset, including new `code` to redeploy. */
+type FunctionUpdateInput = Partial<FunctionDeployInput>;
+interface FunctionsNamespaceDeps {
+    http: HttpClient;
+}
+/** Common option: a management Space for delegated (non-owner) access. */
+interface FunctionScopeOpts {
+    space?: string;
+}
+declare class FunctionsNamespace {
+    private readonly deps;
+    constructor(deps: FunctionsNamespaceDeps);
+    /** List the app's functions. */
+    list(appId: string, opts?: FunctionScopeOpts): Promise<FunctionConfig[]>;
+    /** Read one function's config. */
+    get(appId: string, functionId: string, opts?: FunctionScopeOpts): Promise<{
+        config: FunctionConfig;
+    }>;
+    /** Read a function's decrypted source (owner/editor; for the editor UI). */
+    code(appId: string, functionId: string, opts?: FunctionScopeOpts): Promise<{
+        functionId: string;
+        code: string;
+        codeHash: string | null;
+    }>;
+    /** Deploy (create) a function (owner/editor only). */
+    deploy(appId: string, input: FunctionDeployInput, opts?: FunctionScopeOpts): Promise<{
+        config: FunctionConfig;
+    }>;
+    /** Update a function's editor-settable fields and/or redeploy its `code`. */
+    update(appId: string, functionId: string, patch: FunctionUpdateInput, opts?: FunctionScopeOpts): Promise<{
+        config: FunctionConfig;
+    }>;
+    /** Delete a function (owner/editor only). */
+    delete(appId: string, functionId: string, opts?: FunctionScopeOpts): Promise<{
+        deleted: boolean;
+    }>;
+    /** Enable the function on a Space (per-Space opt-in for the `space` trigger). */
+    enable(appId: string, functionId: string, spaceId: string, opts?: FunctionScopeOpts): Promise<{
+        config: FunctionConfig;
+    }>;
+    /** Disable the function on a Space. */
+    disable(appId: string, functionId: string, spaceId: string, opts?: FunctionScopeOpts): Promise<{
+        config: FunctionConfig;
+    }>;
+    private path;
+}
+
 /** The hosted Muhkoo Accelerator — the default {@link ClientOptions.baseUrl}. */
 declare const DEFAULT_BASE_URL = "https://api.muhkoo.dev";
 interface ClientOptions {
@@ -3182,12 +3610,18 @@ declare class Client {
     readonly auth: AuthNamespace;
     /** Per-user key/value storage — `client.kv.set(...)`, etc. */
     readonly kv: KvNamespace;
+    /** App scalable database — `client.db.table('todos').query(...)`, etc. */
+    readonly db: DbNamespace;
     /** File storage — `client.storage.writeFile(...)`, etc. */
     readonly storage: StorageNamespace;
     /** Realtime messaging — `client.message.subscribe(...)`, etc. */
     readonly message: MessageNamespace;
     /** Fan-out group spaces — `client.space.createSpace(...)`, etc. */
     readonly space: SpaceNamespace;
+    /** Programmable Agents — `client.agents.create(appId, …)`, etc. */
+    readonly agents: AgentsNamespace;
+    /** Serverless functions — `client.functions.deploy(appId, …)`, etc. */
+    readonly functions: FunctionsNamespace;
     private readonly session;
     private readonly http;
     /** Subscribers notified when a session expires and can't be recovered. */
@@ -3220,6 +3654,134 @@ declare class Client {
     recoverSession(): Promise<boolean>;
 }
 
+/**
+ * Muhkoo app decorators — declare your app's agent-facing surface in code, then
+ * "eject" a system prompt you hand to a Programmable Agent.
+ *
+ * You annotate a plain class with `@MuhkooAgent` (the app's identity + how the
+ * agent should behave) plus per-surface decorators — `@MuhkooSpace`,
+ * `@MuhkooDB`, `@MuhkooFunction` — that describe what each channel, table, and
+ * function is *for*. {@link ejectAgentPrompt} reads those annotations and
+ * produces a `systemPrompt` string:
+ *
+ * ```ts
+ * @MuhkooAgent({
+ *   name: "Chat Assistant",
+ *   purpose: "A helpful assistant inside a real-time team chat.",
+ *   guidance: ["Keep replies short.", "Only chime in when relevant."],
+ * })
+ * class ChatAssistant {
+ *   @MuhkooSpace({ description: "Main team discussion." })            general!: string;
+ *   @MuhkooDB({ access: "read", description: "Chat message history." }) messages!: unknown;
+ *   @MuhkooFunction({ description: "Open a support ticket." })         openTicket!: () => void;
+ * }
+ *
+ * const systemPrompt = ejectAgentPrompt(ChatAssistant);
+ * await client.agents.create({ handle: "assistant", displayName: "Assistant", systemPrompt });
+ * ```
+ *
+ * The ejected prompt owns the **semantic** layer — what the app is, how to act,
+ * and what each surface means. The Muhkoo runtime separately appends the
+ * **authoritative** roster (exact columns, function parameters, and the closed
+ * list of callable tools), so the prompt here never needs to restate schema and
+ * can't drift from it. Decorators only describe; they never change runtime
+ * behavior, so they're safe to apply to a throwaway descriptor class.
+ *
+ * Requires `experimentalDecorators` (already enabled in this package). Metadata
+ * is captured in a per-class registry — no `reflect-metadata` dependency.
+ */
+
+/** Whether the agent may only read a table, or read and write it. */
+type MuhkooDBAccess = "read" | "write";
+/** App-level identity + behavioral guidance — the heart of the ejected prompt. */
+interface MuhkooAgentMeta {
+    /** The agent persona's name (e.g. "Chat Assistant"). */
+    name: string;
+    /** What the app is and the agent's role in it. One or two sentences. */
+    purpose: string;
+    /** Short behavioral rules, rendered as a bulleted list. */
+    guidance?: string[];
+    /** Optional free-form instructions appended verbatim after the surface. */
+    instructions?: string;
+}
+/** A channel/Space the agent can resolve and post into. */
+interface MuhkooSpaceMeta {
+    /** Channel name. Defaults to the decorated member's name. */
+    name?: string;
+    description: string;
+}
+/** An app database table the agent can query (and optionally mutate). */
+interface MuhkooDBMeta {
+    /** Table name. Defaults to the decorated member's name. */
+    table?: string;
+    /** Read-only by default. */
+    access?: MuhkooDBAccess;
+    description: string;
+}
+/** A serverless function the agent can invoke via `call_function`. */
+interface MuhkooFunctionMeta {
+    /** Function name. Defaults to the decorated member's name. */
+    name?: string;
+    description: string;
+}
+interface SpaceEntry {
+    name: string;
+    description: string;
+}
+interface TableEntry {
+    table: string;
+    access: MuhkooDBAccess;
+    description: string;
+}
+interface FunctionEntry {
+    name: string;
+    description: string;
+}
+/** The full annotated surface gathered from one decorated class. */
+interface MuhkooAppDescriptor {
+    agent?: MuhkooAgentMeta;
+    spaces: SpaceEntry[];
+    tables: TableEntry[];
+    functions: FunctionEntry[];
+}
+/**
+ * Class decorator. Declares the app's agent identity, purpose, and behavioral
+ * guidance. Apply it to the class whose members carry the surface decorators.
+ */
+declare function MuhkooAgent(meta: MuhkooAgentMeta): ClassDecorator;
+/** Member decorator. Marks a channel/Space the agent can resolve and post to. */
+declare function MuhkooSpace(meta: MuhkooSpaceMeta): PropertyDecorator & MethodDecorator;
+/** Member decorator. Marks an app database table the agent can query/mutate. */
+declare function MuhkooDB(meta: MuhkooDBMeta): PropertyDecorator & MethodDecorator;
+/** Member decorator. Marks a serverless function the agent can call. */
+declare function MuhkooFunction(meta: MuhkooFunctionMeta): PropertyDecorator & MethodDecorator;
+/** Read back the raw descriptor a class accumulated (for tooling/tests). */
+declare function getMuhkooAppDescriptor(appClass: Function): MuhkooAppDescriptor | undefined;
+/**
+ * Compose the agent system prompt from a `@MuhkooAgent`-decorated class. Throws
+ * if the class isn't decorated. The result is the semantic layer only — the
+ * runtime appends exact schema + the closed tool list at invocation time.
+ */
+declare function ejectAgentPrompt(appClass: Function): string;
+/**
+ * The tools-config shape the Muhkoo platform uses to gate an agent. Alias of
+ * `client.agents`' {@link AgentToolsConfig} so {@link ejectAgentTools} output
+ * drops straight into `client.agents.create({ tools })`.
+ */
+type MuhkooAgentToolsConfig = AgentToolsConfig;
+/**
+ * Derive a suggested tools allowlist from a decorated class — the db tables
+ * (and whether any are writable), the callable functions, and whether channels
+ * are in play. Pair with {@link ejectAgentPrompt} when configuring the agent.
+ *
+ * If any tables/functions are present the result has `enabled: true`; to
+ * actually grant tools you must also pass a function-calling `model` in the same
+ * `client.agents.create`/`update` call (the server enforces this).
+ */
+declare function ejectAgentTools(appClass: Function, opts?: {
+    maxIterations?: number;
+}): AgentToolsConfig;
+
 /**
  * KeyringClient — HTTP implementation of {@link KeyringTransport} against the
  * accelerator's per-space keyring endpoints. All blobs are opaque to the
@@ -3255,8 +3817,30 @@ declare class KeyringClient implements KeyringTransport {
         epoch: number;
     }>;
     invite(username: string): Promise<void>;
+    createInviteLink(opts?: {
+        expiresInSec?: number;
+        maxUses?: number;
+        role?: string;
+    }): Promise<InviteLink>;
+    listInviteLinks(): Promise<InviteLink[]>;
+    /** Set a member's role ("viewer" | "editor"). Owner-only on the server. */
+    setMemberRole(username: string, role: string): Promise<void>;
+    /** Roster with roles (owner/members only). */
+    members(): Promise<Array<{
+        memberId: string;
+        role: string;
+    }>>;
+    revokeInviteLink(token: string): Promise<void>;
+    /** Redeem a link: the server allowlists this member and asks the keeper to
+     *  wrap the group key for their identity. Caller must be authenticated. */
+    redeemInvite(req: {
+        token: string;
+        identityEcdhPub: string;
+        identityEcdsaPub?: string;
+        desiredEpoch?: number;
+    }): Promise<void>;
     fetchMetadata(): Promise<SpaceMetadata | null>;
 }
 
-export { AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES, AuthClient, AuthNamespace, AuthPublicInput, Authenticator, BroadcastChannel, BroadcastChannelEvents, ChannelExistsError, ChannelNotFoundError, ChunkCipher, Client, DEFAULT_BASE_URL, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, HashKnowledge, HttpClient, HttpError, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvNamespace, LocalStorageSessionStore, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PersonalSpaceClient, Poseidon, PreimagePoK, ReedSolomonCodec, Space as Room, SerializeMessage, SessionState, ShardClient, SharedSpaceClient, Space, SpaceKeyring, SpaceNamespace, SpacePacketCipher, StorageNamespace, WSTransport, ZkAuth, buildCommitment, compilePrograms, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, generateAuthProof, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, manifestToStat, poseidonHash, quickVerify, randomBytes, shardHash, signMessage, toField, unwrapWithPassphrase, verify, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase };
-export type { ACL, ACLEntry, AuthClientOptions, AuthKeyPair, AuthSuccess, AuthToken, AuthType, AuthUser, Bn128WasmInstance, BroadcastChannelEvent, BroadcastChannelOptions, ChannelLike, ChunkKeyMaterial, ChunkManifest, CipherFrame, CipherMessage, CipherMessageHeader, CircuitBufferConfig, CircuitUrls, ClientOptions, DehydratedKeypair, DehydratedKeys, DoubleRatchetCipherDeps, ECDHCurve, EncodeResult, EphemeralEvent, EpochKeyProvider, FileManifest, FileNamespaceDeps, FileStat, FileStorageOptions, Groth16Proof, HttpClientOptions, IncomingFrame, KeyExchangeFrame, KeyPair, Keypair, KeyringClientDeps, KeyringTransport, KvNamespaceDeps, LoginOptions, MessageBody, MessageDeletedEvent, MessageEvent, MessageHeaders, MessageNamespaceDeps, MessageOptions, MessageSubscription, MuhkooMessageEvent, OAuthProvider, PacketCipher, PacketHeaders, PacketOptions, Participant, Permission, PermissionCheckRequest, PermissionCheckResult, PersonalSpaceClientOptions, PublicKeyJWK, RatchetState, ReceiveResult, RegisterParams, Role, SpaceDeps as RoomDeps, SpaceFileMetadata as RoomFileMetadata, SealedHeaders, Session, SessionOptions, SessionStore, SetOptions, ShardClientOptions, SharedSpaceClientOptions, SnarkProof, SpaceChannelLike, SpaceDeps, SpaceFileMetadata, SpaceKeyCache, SpaceKeyringDeps, SpaceMessageEvent, SpaceNamespaceDeps, StorageChangeEvent, StoredSession, Subscription, UserIdentity, VerificationKey, WSMessage, WSMessageType, WSTransportOptions, WrappedPayload, WriteFileInput, WriteFileOptions, WriteToShardsInput, ZkAuthDeps, ZkAuthenticateRequest, ZkChallengeResponse, ZkCompiled, ZkIdentity, ZkRegisterRequest, ZkRegisterResponse };
+export { AES_GCM_IV_BYTES, AES_GCM_KEY_BYTES, AES_GCM_TAG_BYTES, AgentsNamespace, AuthClient, AuthNamespace, AuthPublicInput, Authenticator, BroadcastChannel, BroadcastChannelEvents, ChannelExistsError, ChannelNotFoundError, ChunkCipher, Client, DEFAULT_BASE_URL, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HashKnowledge, HttpClient, HttpError, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvNamespace, LocalStorageSessionStore, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, MuhkooAgent, MuhkooDB, MuhkooFunction, MuhkooSpace, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PersonalSpaceClient, Poseidon, PreimagePoK, ReedSolomonCodec, Space as Room, SerializeMessage, SessionState, ShardClient, SharedSpaceClient, Space, SpaceKeyring, SpaceNamespace, SpacePacketCipher, StorageNamespace, WSTransport, ZkAuth, buildCommitment, compilePrograms, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, ejectAgentPrompt, ejectAgentTools, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, generateAuthProof, getMuhkooAppDescriptor, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, manifestToStat, poseidonHash, quickVerify, randomBytes, shardHash, signMessage, toField, unwrapWithPassphrase, verify, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase };
+export type { ACL, ACLEntry, AgentConfig, AgentCreateInput, AgentDbToolMode, AgentProvisioned, AgentScopeOpts, AgentSkill, AgentToolsConfig, AgentTrigger, AgentTriggerType, AgentUpdateInput, AgentsNamespaceDeps, AuthClientOptions, AuthKeyPair, AuthSuccess, AuthToken, AuthType, AuthUser, Bn128WasmInstance, BroadcastChannelEvent, BroadcastChannelOptions, ChannelLike, ChunkKeyMaterial, ChunkManifest, CipherFrame, CipherMessage, CipherMessageHeader, CircuitBufferConfig, CircuitUrls, ClientOptions, DehydratedKeypair, DehydratedKeys, DoubleRatchetCipherDeps, ECDHCurve, EncodeResult, EphemeralEvent, EpochKeyProvider, FileManifest, FileNamespaceDeps, FileStat, FileStorageOptions, FunctionCaps, FunctionConfig, FunctionDeployInput, FunctionScopeOpts, FunctionTrigger, FunctionTriggerType, FunctionTriggers, FunctionUpdateInput, FunctionsNamespaceDeps, Groth16Proof, HttpClientOptions, IncomingFrame, KeyExchangeFrame, KeyPair, Keypair, KeyringClientDeps, KeyringTransport, KvNamespaceDeps, LoginOptions, MessageBody, MessageDeletedEvent, MessageEvent, MessageHeaders, MessageNamespaceDeps, MessageOptions, MessageSubscription, MuhkooAgentMeta, MuhkooAgentToolsConfig, MuhkooAppDescriptor, MuhkooDBAccess, MuhkooDBMeta, MuhkooFunctionMeta, MuhkooMessageEvent, MuhkooSpaceMeta, OAuthProvider, PacketCipher, PacketHeaders, PacketOptions, Participant, Permission, PermissionCheckRequest, PermissionCheckResult, PersonalSpaceClientOptions, PublicKeyJWK, RatchetState, ReceiveResult, RegisterParams, Role, SpaceDeps as RoomDeps, SpaceFileMetadata as RoomFileMetadata, SealedHeaders, Session, SessionOptions, SessionStore, SetOptions, ShardClientOptions, SharedSpaceClientOptions, SnarkProof, SpaceChannelLike, SpaceDeps, SpaceFileMetadata, SpaceKeyCache, SpaceKeyringDeps, SpaceMessageEvent, SpaceNamespaceDeps, StorageChangeEvent, StoredSession, Subscription, UserIdentity, VerificationKey, WSMessage, WSMessageType, WSTransportOptions, WrappedPayload, WriteFileInput, WriteFileOptions, WriteToShardsInput, ZkAuthDeps, ZkAuthenticateRequest, ZkChallengeResponse, ZkCompiled, ZkIdentity, ZkRegisterRequest, ZkRegisterResponse };