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

package/dist/server/index.js

@@ -2790,6 +2790,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);
     }
@@ -3272,6 +3275,7 @@ class WSTransport extends EventCore {
         return `${this.id}:${event}`;
     }
     url;
+    urlProvider;
     socket = null;
     _isConnected = false;
     _isConnecting = false;
@@ -3297,6 +3301,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;
@@ -3313,6 +3318,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);
@@ -3485,7 +3502,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);
     }
@@ -3652,6 +3674,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);
+    }
+}
+
 /**
  * Wire types for the storage layer.
  *
@@ -4266,6 +4374,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
@@ -4275,6 +4385,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)
@@ -5390,12 +5501,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;
@@ -5599,8 +5725,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);
@@ -5757,6 +5883,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")
@@ -6253,6 +6385,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");
@@ -6390,6 +6550,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) {
@@ -6456,6 +6666,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.
  *
@@ -6494,12 +6836,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. */
@@ -6527,6 +6875,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
@@ -6542,6 +6891,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() {
@@ -6595,6 +6946,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,
+    };
+}
+
 const appLogger$1 = new Logger("connect", 'ERROR');
 globalThis.appLogger = appLogger$1;
 
@@ -7131,5 +7653,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, Logger, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PersonalSpaceClient, Poseidon, PreimagePoK, Ready, ReedSolomonCodec, Retry, Space as Room, SerializeMessage, SessionState, ShardClient, SharedSpaceClient, Space, SpaceKeyring, SpaceNamespace, SpacePacketCipher, StorageNamespace, WSTransport, ZkAuth, _accountId, _formatBytes, _messageId, _objectId, _packetId, _socketId, _userId, appLogger$1 as appLogger, assertType, base58Decode, base58Encode, buildCommitment, compilePrograms, concatBytes, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deserialize, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, fromBase64, fromBase64Url, fromHex, generateAuthProof, generateChecksum, generateId, getIPAddress, getId, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, isNumber, log, manifestToStat, poseidonHash, quickVerify, randomBytes, serialize, shardHash, signMessage, toBase64, toBase64Url, toField, toHex, unwrapWithPassphrase, utf8Decode, utf8Encode, verify, verifyChecksum, 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, DbNamespace, DbTable, DoubleRatchet, DoubleRatchetCipher, DoubleRatchetManager, EncryptedSession, EventCore, EventCoreEvents, Field, Field as FieldElement, FileStorage, FunctionsNamespace, HashKnowledge, HttpClient, HttpError, KEEPER_MEMBER_ID, KeyStore, KeyringClient, KvNamespace, LocalStorageSessionStore, Logger, MemorySessionStore, Message, Message as MessageDefault, MessageNamespace, MuhkooAgent, MuhkooDB, MuhkooFunction, MuhkooSpace, PBKDF2_DEFAULT_ITERATIONS, PREIMAGE_POK_VERIFICATION_KEY, Packet, PersonalSpaceClient, Poseidon, PreimagePoK, Ready, ReedSolomonCodec, Retry, Space as Room, SerializeMessage, SessionState, ShardClient, SharedSpaceClient, Space, SpaceKeyring, SpaceNamespace, SpacePacketCipher, StorageNamespace, WSTransport, ZkAuth, _accountId, _formatBytes, _messageId, _objectId, _packetId, _socketId, _userId, appLogger$1 as appLogger, assertType, base58Decode, base58Encode, buildCommitment, compilePrograms, concatBytes, decodeFromHex, decorators, decryptAesGcm, defaultCircuitUrls, defaultSessionStore, deriveAesKeyFromPassphrase, deriveBitsHkdf, deriveIdentity, deserialize, ejectAgentPrompt, ejectAgentTools, encodeToHex, encryptAesGcm, exportPublicKeyBase64, exportPublicKeyHex, fromBase64, fromBase64Url, fromHex, generateAuthProof, generateChecksum, generateId, getIPAddress, getId, getMuhkooAppDescriptor, getSubtle, initBn128Wasm, initRsWasm, initializeCircuits, isNumber, log, manifestToStat, poseidonHash, quickVerify, randomBytes, serialize, shardHash, signMessage, toBase64, toBase64Url, toField, toHex, unwrapWithPassphrase, utf8Decode, utf8Encode, verify, verifyChecksum, verifyGroth16, verifyHashKnowledge, verifyPreimagePoK, wrapWithPassphrase };
 //# sourceMappingURL=index.js.map