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

package/dist/browser/index.js

@@ -2407,6 +2407,7 @@ class WSTransport extends EventCore {
         return `${this.id}:${event}`;
     }
     url;
+    urlProvider;
     socket = null;
     _isConnected = false;
     _isConnecting = false;
@@ -2432,6 +2433,7 @@ class WSTransport extends EventCore {
             throw new Error("WSTransport: `url` is required");
         }
         this.url = opts.url;
+        this.urlProvider = opts.urlProvider;
         this.id = opts.id ?? `ws${++__wsInstanceSeq}`;
         this.autoReconnect = opts.autoReconnect ?? true;
         this.reconnectDelay = opts.reconnectDelay ?? 3000;
@@ -2448,6 +2450,18 @@ class WSTransport extends EventCore {
             throw new Error("WSTransport: already connected or connecting");
         }
         this._isConnecting = true;
+        // On a RECONNECT, refresh the URL (the baked-in single-use ticket is spent).
+        // The first connect uses `url` as-is. If the provider throws (e.g. can't
+        // mint a ticket), surface it and let scheduleReconnect retry.
+        if (this.urlProvider && this.reconnectAttempts > 0) {
+            try {
+                this.url = await this.urlProvider();
+            }
+            catch (err) {
+                this._isConnecting = false;
+                throw err;
+            }
+        }
         return new Promise((resolve, reject) => {
             try {
                 const socket = new WebSocket(this.url);
@@ -2620,7 +2634,12 @@ class WSTransport extends EventCore {
                 await this.connect();
             }
             catch {
-                // scheduleReconnect will fire again from onclose
+                // A failed reconnect never opened the socket, so its `onclose` won't
+                // re-schedule (that path is guarded by `wasConnected`). Re-schedule here
+                // so we keep retrying (with a fresh ticket each time) until we succeed
+                // or hit the attempt cap.
+                if (this.autoReconnect)
+                    this.scheduleReconnect();
             }
         }, this.reconnectDelay);
     }
@@ -3936,6 +3955,8 @@ class FileStorage {
         const fileId = input.fileId ?? generateId();
         const createdAt = Date.now();
         const chunks = [];
+        const totalChunks = Math.max(1, Math.ceil(data.length / this.chunkSize));
+        input.onProgress?.(0, totalChunks);
         // Slicing + encrypting + encoding + uploading is done per-chunk so
         // the peak memory footprint stays at ~chunkSize even for huge files.
         // Within a chunk, the shard uploads are parallelized up to
@@ -3945,6 +3966,7 @@ class FileStorage {
             const end = Math.min(start + this.chunkSize, data.length);
             const plaintext = data.subarray(start, end);
             chunks.push(await this.writeChunk(plaintext, chunkIndex));
+            input.onProgress?.(chunks.length, totalChunks);
             // Stop after one iteration if the file is empty — we still emit a
             // single zero-length chunk so the manifest has a stable shape.
             if (data.length === 0)
@@ -4691,6 +4713,9 @@ class HttpClient {
     post(path, body) {
         return this.request("POST", path, body);
     }
+    patch(path, body) {
+        return this.request("PATCH", path, body);
+    }
     del(path, body) {
         return this.request("DELETE", path, body);
     }
@@ -5280,6 +5305,92 @@ class KvNamespace {
     }
 }
 
+/**
+ * `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.
+ */
+/** A handle to one table — the ergonomic surface for row operations. */
+class DbTable {
+    http;
+    name;
+    constructor(http, name) {
+        this.http = http;
+        this.name = name;
+    }
+    base() {
+        return `/api/db/${encodeURIComponent(this.name)}`;
+    }
+    /** Insert a row. Returns the created row and its primary-key value. */
+    async insert(values) {
+        return this.http.post(this.base(), { values });
+    }
+    /** Fetch a row by primary key, or `null` if it doesn't exist. */
+    async get(id) {
+        try {
+            const res = await this.http.get(`${this.base()}/${encodeURIComponent(String(id))}`);
+            return res.row;
+        }
+        catch (e) {
+            if (e?.status === 404)
+                return null;
+            throw e;
+        }
+    }
+    /** Query rows with filters, ordering, and keyset pagination. */
+    async query(query = {}) {
+        return this.http.post(`${this.base()}/query`, query);
+    }
+    /** Update a row by primary key. Returns the updated row. */
+    async update(id, values) {
+        return this.http.patch(`${this.base()}/${encodeURIComponent(String(id))}`, { values });
+    }
+    /** Delete a row by primary key. Returns the number of rows removed (0 or 1). */
+    async delete(id) {
+        const res = await this.http.del(`${this.base()}/${encodeURIComponent(String(id))}`);
+        return res.deleted ?? 0;
+    }
+}
+class DbNamespace {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * 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(name) {
+        return new DbTable(this.deps.http, name);
+    }
+}
+
 /**
  * `client.storage` — file storage. Hides the `FileStorage` / `ShardClient` /
  * `SharedSpaceClient` primitives behind the unified client.
@@ -5659,12 +5770,27 @@ class Space {
     /** Open the space websocket (resolves the ticket + identity lazily). */
     async connect() {
         if (!this.channel) {
-            const ticket = await this.deps.fetchTicket();
-            const url = `${this.deps.wsBaseUrl}/api/spaces/${encodeURIComponent(this.name)}/websocket` +
-                (ticket ? `?ticket=${encodeURIComponent(ticket)}` : "");
+            // The WS upgrade ticket is single-use + short-TTL, so a reconnect
+            // must mint a FRESH one — otherwise the socket drops (idle timeout,
+            // network blip) and never comes back. `buildUrl` is handed to the
+            // transport as a `urlProvider` it calls before each reconnect.
+            const buildUrl = async () => {
+                const ticket = await this.deps.fetchTicket();
+                return (`${this.deps.wsBaseUrl}/api/spaces/${encodeURIComponent(this.name)}/websocket` +
+                    (ticket ? `?ticket=${encodeURIComponent(ticket)}` : ""));
+            };
+            const url = await buildUrl();
             this.channel = this.deps.createChannel
                 ? this.deps.createChannel(url, this.deps.myId())
-                : new BroadcastChannel({ url, myId: this.deps.myId(), autoAnnounce: false });
+                : new BroadcastChannel({
+                    url,
+                    myId: this.deps.myId(),
+                    autoAnnounce: false,
+                    urlProvider: buildUrl,
+                    // Keep recovering across network flaps (each attempt mints a
+                    // fresh ticket); teardown calls disconnect() which stops it.
+                    maxReconnectAttempts: 0,
+                });
             for (const [event, handler] of this.pending)
                 this.channel.on(event, handler);
             this.pending.length = 0;
@@ -5868,8 +5994,8 @@ class Space {
         return this.requireKeyring().rotate(roster);
     }
     // -- room-scoped files (no websocket needed) -------------------------------
-    async putFile(file, metadata) {
-        return this.fileStorage().writeFileToShards({ data: file, metadata });
+    async putFile(file, metadata, opts = {}) {
+        return this.fileStorage().writeFileToShards({ data: file, metadata, onProgress: opts.onProgress });
     }
     async getFile(manifest) {
         return this.fileStorage().readFileFromShards(manifest);
@@ -6026,6 +6152,12 @@ class Space {
      * nothing to verify against → reject.
      */
     async verifySender(packet) {
+        // Trust our OWN messages — we sent them, so there's nothing to prove
+        // against the roster. This also keeps a returning member (who loaded a
+        // cached key and never re-published a join-request) from dropping the
+        // echo of their own messages when their `ecdsaPub` isn't in the roster.
+        if (packet.source === this.deps.myId())
+            return true;
         const keyring = this.deps.keyring;
         const sig = packet.headers?.sig;
         if (!keyring || typeof sig !== "string")
@@ -6522,6 +6654,34 @@ class KeyringClient {
     async invite(username) {
         await this.post("/keyring/invite", { username });
     }
+    // -- Shareable invite links ----------------------------------------------
+    // A capability token tied to this space. Redeeming it allowlists the holder
+    // so the keeper admits them — the link IS the invitation. Mint/list/revoke
+    // require the caller to be the creator or an existing member.
+    async createInviteLink(opts = {}) {
+        return this.post("/keyring/link", opts);
+    }
+    async listInviteLinks() {
+        const body = await this.get("/keyring/links");
+        return body.links ?? [];
+    }
+    /** Set a member's role ("viewer" | "editor"). Owner-only on the server. */
+    async setMemberRole(username, role) {
+        await this.post("/keyring/role", { username, role });
+    }
+    /** Roster with roles (owner/members only). */
+    async members() {
+        const body = await this.get("/keyring/members");
+        return body.members ?? [];
+    }
+    async revokeInviteLink(token) {
+        await this.post("/keyring/link-revoke", { token });
+    }
+    /** Redeem a link: the server allowlists this member and asks the keeper to
+     *  wrap the group key for their identity. Caller must be authenticated. */
+    async redeemInvite(req) {
+        await this.post("/keyring/redeem", req);
+    }
     async fetchMetadata() {
         try {
             return await this.get("/metadata");
@@ -6659,6 +6819,56 @@ class SpaceNamespace {
         return this.joinSpace(spaceId, opts);
     }
     // -------------------------------------------------------------------------
+    // Invite links — shareable, keeper-gated invitations to a space. The token
+    // is a capability: anyone signed in who redeems it is admitted by the
+    // keeper. Mint/list/revoke require the caller to be the space's creator or
+    // an existing member.
+    // -------------------------------------------------------------------------
+    /** 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. */
+    async createInviteLink(spaceId, opts = {}) {
+        return this.keyringFor(spaceId).createInviteLink(opts);
+    }
+    /** Set a member's role on a space ("viewer" | "editor"). Owner-only. */
+    async setMemberRole(spaceId, username, role) {
+        await this.keyringFor(spaceId).setMemberRole(username, role);
+    }
+    /** Roster with roles (owner/members only). */
+    async members(spaceId) {
+        return this.keyringFor(spaceId).members();
+    }
+    /** List a space's active invite links (creator/members only). */
+    async listInviteLinks(spaceId) {
+        return this.keyringFor(spaceId).listInviteLinks();
+    }
+    /** Revoke an invite link by token. */
+    async revokeInviteLink(spaceId, token) {
+        await this.keyringFor(spaceId).revokeInviteLink(token);
+    }
+    /**
+     * 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}.
+     */
+    async joinByInvite(spaceId, token, opts = {}) {
+        const memberId = this.myId();
+        const { ecdhPub, ecdsaPub } = await this.ensureIdentity(memberId);
+        await this.keyringFor(spaceId).redeemInvite({ token, identityEcdhPub: ecdhPub, identityEcdsaPub: ecdsaPub });
+        return this.joinSpace(spaceId, opts);
+    }
+    /** The current member roster of a space (member id → identity public keys). */
+    async roster(spaceId) {
+        return this.keyringFor(spaceId).fetchRoster();
+    }
+    keyringFor(spaceId) {
+        return new KeyringClient({
+            spaceId,
+            httpBaseUrl: this.deps.http.baseUrl,
+            fetch: this.deps.http.fetch,
+        });
+    }
+    // -------------------------------------------------------------------------
     // Internals
     // -------------------------------------------------------------------------
     async build(spaceId, historyPolicy) {
@@ -6725,6 +6935,138 @@ class SpaceNamespace {
     }
 }
 
+/**
+ * `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.
+ */
+class AgentsNamespace {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** List the app's agents. */
+    async list(appId, opts = {}) {
+        const res = await this.deps.http.get(this.path(appId, "", opts));
+        return res.agents ?? [];
+    }
+    /** Read one agent (config + identity keys). */
+    async get(appId, agentId, opts = {}) {
+        return this.deps.http.get(this.path(appId, `/${encodeURIComponent(agentId)}`, opts));
+    }
+    /** Create an agent (owner/editor only). */
+    async create(appId, input, opts = {}) {
+        return this.deps.http.post(this.path(appId, "", {}), { ...input, space: opts.space });
+    }
+    /** Update an agent's editor-settable fields (owner/editor only). */
+    async update(appId, agentId, patch, opts = {}) {
+        return this.deps.http.patch(this.path(appId, `/${encodeURIComponent(agentId)}`, {}), { ...patch, space: opts.space });
+    }
+    /** Delete an agent (owner/editor only). */
+    async delete(appId, agentId, opts = {}) {
+        return this.deps.http.del(this.path(appId, `/${encodeURIComponent(agentId)}`, {}), { space: opts.space });
+    }
+    /** Enable the agent on a Space (per-Space opt-in). */
+    async enable(appId, agentId, spaceId, opts = {}) {
+        return this.deps.http.post(this.path(appId, `/${encodeURIComponent(agentId)}/enable`, {}), { targetSpaceId: spaceId, space: opts.space });
+    }
+    /** Disable the agent on a Space. */
+    async disable(appId, agentId, spaceId, opts = {}) {
+        return this.deps.http.post(this.path(appId, `/${encodeURIComponent(agentId)}/disable`, {}), { targetSpaceId: spaceId, space: opts.space });
+    }
+    path(appId, suffix, opts) {
+        const q = opts.space ? `?space=${encodeURIComponent(opts.space)}` : "";
+        return `/api/apps/${encodeURIComponent(appId)}/agents${suffix}${q}`;
+    }
+}
+
+/**
+ * `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).
+ */
+class FunctionsNamespace {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** List the app's functions. */
+    async list(appId, opts = {}) {
+        const res = await this.deps.http.get(this.path(appId, "", opts));
+        return res.functions ?? [];
+    }
+    /** Read one function's config. */
+    async get(appId, functionId, opts = {}) {
+        return this.deps.http.get(this.path(appId, `/${encodeURIComponent(functionId)}`, opts));
+    }
+    /** Read a function's decrypted source (owner/editor; for the editor UI). */
+    async code(appId, functionId, opts = {}) {
+        return this.deps.http.get(this.path(appId, `/${encodeURIComponent(functionId)}/code`, opts));
+    }
+    /** Deploy (create) a function (owner/editor only). */
+    async deploy(appId, input, opts = {}) {
+        return this.deps.http.post(this.path(appId, "", {}), { ...input, space: opts.space });
+    }
+    /** Update a function's editor-settable fields and/or redeploy its `code`. */
+    async update(appId, functionId, patch, opts = {}) {
+        return this.deps.http.patch(this.path(appId, `/${encodeURIComponent(functionId)}`, {}), { ...patch, space: opts.space });
+    }
+    /** Delete a function (owner/editor only). */
+    async delete(appId, functionId, opts = {}) {
+        return this.deps.http.del(this.path(appId, `/${encodeURIComponent(functionId)}`, {}), { space: opts.space });
+    }
+    /** Enable the function on a Space (per-Space opt-in for the `space` trigger). */
+    async enable(appId, functionId, spaceId, opts = {}) {
+        return this.deps.http.post(this.path(appId, `/${encodeURIComponent(functionId)}/enable`, {}), { targetSpaceId: spaceId, space: opts.space });
+    }
+    /** Disable the function on a Space. */
+    async disable(appId, functionId, spaceId, opts = {}) {
+        return this.deps.http.post(this.path(appId, `/${encodeURIComponent(functionId)}/disable`, {}), { targetSpaceId: spaceId, space: opts.space });
+    }
+    path(appId, suffix, opts) {
+        const q = opts.space ? `?space=${encodeURIComponent(opts.space)}` : "";
+        return `/api/apps/${encodeURIComponent(appId)}/functions${suffix}${q}`;
+    }
+}
+
 /**
  * `Client` — the single entry point to the Muhkoo SDK.
  *
@@ -6763,12 +7105,18 @@ class Client {
     auth;
     /** Per-user key/value storage — `client.kv.set(...)`, etc. */
     kv;
+    /** App scalable database — `client.db.table('todos').query(...)`, etc. */
+    db;
     /** File storage — `client.storage.writeFile(...)`, etc. */
     storage;
     /** Realtime messaging — `client.message.subscribe(...)`, etc. */
     message;
     /** Fan-out group spaces — `client.space.createSpace(...)`, etc. */
     space;
+    /** Programmable Agents — `client.agents.create(appId, …)`, etc. */
+    agents;
+    /** Serverless functions — `client.functions.deploy(appId, …)`, etc. */
+    functions;
     session;
     http;
     /** Subscribers notified when a session expires and can't be recovered. */
@@ -6796,6 +7144,7 @@ class Client {
         const wsBaseUrl = toWsBase(this.baseUrl);
         this.auth = new AuthNamespace({ auth: authClient, circuits, session: this.session });
         this.kv = new KvNamespace({ http: this.http, session: this.session, wsBaseUrl });
+        this.db = new DbNamespace({ http: this.http });
         this.storage = new StorageNamespace({ http: this.http, baseUrl: this.baseUrl, kv: this.kv });
         this.message = new MessageNamespace({ http: this.http, session: this.session, wsBaseUrl });
         // Group keys are cached in the user's PersonalSpace (encrypted at rest
@@ -6811,6 +7160,8 @@ class Client {
             wsBaseUrl,
             cache: spaceKeyCache,
         });
+        this.agents = new AgentsNamespace({ http: this.http });
+        this.functions = new FunctionsNamespace({ http: this.http });
     }
     /** The currently signed-in user, or `null`. */
     get user() {
@@ -6864,6 +7215,177 @@ class Client {
     }
 }
 
+/**
+ * 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.
+ */
+// Per-class metadata store, keyed by the class constructor. Member decorators
+// run during class-body evaluation (before the class decorator), so each
+// decorator get-or-creates the descriptor and they all converge on one entry.
+const REGISTRY = new WeakMap();
+function descriptorFor(ctor) {
+    let d = REGISTRY.get(ctor);
+    if (!d) {
+        d = { spaces: [], tables: [], functions: [] };
+        REGISTRY.set(ctor, d);
+    }
+    return d;
+}
+/** Resolve the owning class constructor from a decorator `target` — the
+ *  prototype for instance members, the constructor itself for static ones. */
+function ctorOf(target) {
+    return typeof target === "function" ? target : target.constructor;
+}
+/**
+ * Class decorator. Declares the app's agent identity, purpose, and behavioral
+ * guidance. Apply it to the class whose members carry the surface decorators.
+ */
+function MuhkooAgent(meta) {
+    return (target) => {
+        descriptorFor(target).agent = meta;
+    };
+}
+/** Member decorator. Marks a channel/Space the agent can resolve and post to. */
+function MuhkooSpace(meta) {
+    return ((target, propertyKey) => {
+        descriptorFor(ctorOf(target)).spaces.push({
+            name: meta.name ?? String(propertyKey),
+            description: meta.description,
+        });
+    });
+}
+/** Member decorator. Marks an app database table the agent can query/mutate. */
+function MuhkooDB(meta) {
+    return ((target, propertyKey) => {
+        descriptorFor(ctorOf(target)).tables.push({
+            table: meta.table ?? String(propertyKey),
+            access: meta.access ?? "read",
+            description: meta.description,
+        });
+    });
+}
+/** Member decorator. Marks a serverless function the agent can call. */
+function MuhkooFunction(meta) {
+    return ((target, propertyKey) => {
+        descriptorFor(ctorOf(target)).functions.push({
+            name: meta.name ?? String(propertyKey),
+            description: meta.description,
+        });
+    });
+}
+/** Read back the raw descriptor a class accumulated (for tooling/tests). */
+function getMuhkooAppDescriptor(appClass) {
+    return REGISTRY.get(appClass);
+}
+/**
+ * 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.
+ */
+function ejectAgentPrompt(appClass) {
+    const d = REGISTRY.get(appClass);
+    if (!d || !d.agent) {
+        throw new Error("ejectAgentPrompt: the class must be decorated with @MuhkooAgent");
+    }
+    const { agent } = d;
+    const lines = [];
+    lines.push(`You are ${agent.name}. ${agent.purpose}`.trim());
+    if (agent.guidance?.length) {
+        lines.push("", "Guidance:");
+        for (const g of agent.guidance)
+            lines.push(`- ${g}`);
+    }
+    if (d.spaces.length) {
+        lines.push("", "Channels (Spaces) you can resolve with resolve_channel and post messages into:");
+        for (const s of d.spaces)
+            lines.push(`- ${s.name}: ${s.description}`);
+    }
+    if (d.tables.length) {
+        lines.push("", "App database tables:");
+        for (const t of d.tables) {
+            const verbs = t.access === "write"
+                ? "read & write — db_query/db_get/db_insert/db_update/db_delete"
+                : "read-only — db_query/db_get";
+            lines.push(`- ${t.table} (${verbs}): ${t.description}`);
+        }
+    }
+    if (d.functions.length) {
+        lines.push("", "Functions you can invoke with call_function:");
+        for (const f of d.functions)
+            lines.push(`- ${f.name}: ${f.description}`);
+    }
+    if (agent.instructions?.trim()) {
+        lines.push("", agent.instructions.trim());
+    }
+    // How to respond — the load-bearing behavioral contract. Without this, models
+    // (especially gpt-oss) tend to run tool calls and then end their turn with no
+    // user-facing message, so the user sees the work happen but gets no reply.
+    const hasTools = d.tables.length > 0 || d.functions.length > 0;
+    lines.push("", "How to respond:");
+    if (hasTools) {
+        lines.push("- When you need information or need to make a change, call your tools immediately — don't ask the user to do it, and don't describe or name the tools to them.", "- After your tool calls return, you MUST send one final reply to the channel, in plain language, that answers the request using the results.");
+    }
+    lines.push("- Always end your turn with a short written reply (one or two sentences). Never finish with only tool calls and no message, and never reply with an empty message.", "- Don't restate function names, parameters, JSON, or your list of tools to the user — just give them the answer.");
+    lines.push("", "The exact columns, function parameters, and the full list of callable tools are supplied to you by the runtime. Follow that authoritative list — never invent tables, columns, functions, or tools.");
+    return lines.join("\n");
+}
+/**
+ * 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).
+ */
+function ejectAgentTools(appClass, opts) {
+    const d = REGISTRY.get(appClass);
+    if (!d) {
+        throw new Error("ejectAgentTools: the class must be decorated with @MuhkooAgent");
+    }
+    const anyWrite = d.tables.some((t) => t.access === "write");
+    const mode = d.tables.length === 0 ? "off" : anyWrite ? "write" : "read";
+    return {
+        enabled: d.tables.length > 0 || d.functions.length > 0 || d.spaces.length > 0,
+        db: { mode, tables: d.tables.map((t) => t.table) },
+        functions: d.functions.map((f) => f.name),
+        channels: d.spaces.length > 0,
+        maxIterations: opts?.maxIterations ?? 6,
+    };
+}
+
 /**
  * PacketCipher — the strategy `Network` uses to seal/open a packet's payload.
  *
@@ -6930,5 +7452,5 @@ var bundledLoader = /*#__PURE__*/Object.freeze({
   default: loadRsWasm
 });
 
-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 { 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 };
 //# sourceMappingURL=index.js.map