@muhkoo/connect 0.4.0-alpha.1 → 0.6.0-alpha.1

package/README.md

@@ -2,12 +2,13 @@
 
 Client SDK for the Muhkoo Accelerator. The headline surface is a single
 **`Client`** that hangs everything off its namespaces —
-`client.auth` / `client.kv` / `client.storage` / `client.message` /
-`client.space` / `client.agents` / `client.functions` — backed by
+`client.auth` / `client.kv` / `client.db` / `client.storage` /
+`client.message` / `client.space` / `client.agents` / `client.functions` —
+backed by
 end-to-end-encrypted messaging (fan-out group channels with history, plus Double
 Ratchet + ECDH P-384 for direct messages), ZK identity + personal/shared spaces,
-server-side Programmable Agents, developer-authored serverless functions, and a
-Cloudflare-Workers-compatible Groth16 verifier — all bundled from a single
+server-side Programmable Agents, developer-authored serverless functions, and an
+edge-compatible Groth16 verifier — all bundled from a single
 TypeScript source tree.
 
 See [`CHANGELOG.md`](./CHANGELOG.md) for what's new.
@@ -18,10 +19,17 @@ See [`CHANGELOG.md`](./CHANGELOG.md) for what's new.
 ## What's in the box
 
 - **`Client`** — the unified entry point. `new Client({ apiKey, baseUrl })`
-  exposes `auth` (ZK register/login), `storage` (per-user encrypted KV +
-  files), and `message` (pub/sub + E2E direct messages) over one shared
-  session. This is the supported surface; everything below is a building block
-  it composes.
+  exposes, over one shared session: `auth` (ZK register/login), `kv` (per-user
+  encrypted key/value), `db` (the app's scalable database), `storage` (encrypted
+  files), `message` (pub/sub + E2E direct messages), `space` (fan-out group
+  channels with history), `agents` (server-side Programmable Agents), and
+  `functions` (developer-authored serverless functions). This is the supported
+  surface; everything below is a building block it composes.
+
+- **App-describing decorators** — `@MuhkooAgent` / `@MuhkooSpace` / `@MuhkooDB` /
+  `@MuhkooFunction` annotate a plain class with your app's agent-facing surface;
+  `ejectAgentPrompt()` / `ejectAgentTools()` turn that into a `systemPrompt` +
+  tool allowlist for a Programmable Agent. See the [agents reference](https://docs.muhkoo.dev/reference/agents/).
 
 - **`BroadcastChannel`** — multi-peer end-to-end-encrypted "room". Wires
   `WSTransport` (socket lifecycle, reconnect, offline queue) together with
@@ -191,7 +199,7 @@ await client.space.roster(space.id);              // member identity pubkeys
 ```
 
 **Programmable Agents (`client.agents`).** Server-side "virtual users" backed by
-Cloudflare Workers AI: an app editor gives an agent a persona (system prompt), a
+the edge AI runtime: an app editor gives an agent a persona (system prompt), a
 model, and **triggers** (e.g. reply on @-mention), then enables it per-Space;
 members chat with it inside that Space. Management is session-authed (owner or
 Space editor) and **paid-tier-only**. Enabling an agent on a Space makes that
@@ -202,7 +210,7 @@ blind.
 const { config } = await client.agents.create(appId, {
   handle: "@assistant",
   displayName: "Assistant",
-  model: "@cf/meta/llama-3.1-8b-instruct",
+  model: "meta/llama-3.1-8b-instruct",
   systemPrompt: "You are a concise, friendly teammate in this Space.",
   triggers: [{ type: "mention" }],
 });
@@ -210,6 +218,28 @@ await client.agents.enable(appId, config.agentId, space.id);  // per-Space opt-i
 // list / update / delete / disable also available.
 ```
 
+Give the agent **tools** (a function-calling loop over the app's database,
+functions, and channels) by passing `tools` — requires a function-calling
+`model`. Generate both the prompt and the tool allowlist from decorators:
+
+```typescript
+import { MuhkooAgent, MuhkooSpace, MuhkooDB, ejectAgentPrompt, ejectAgentTools } from "@muhkoo/connect";
+
+@MuhkooAgent({ name: "Assistant", purpose: "A helpful teammate in this chat." })
+class ChatApp {
+  @MuhkooSpace({ description: "Main team discussion." })             general!: string;
+  @MuhkooDB({ access: "read", description: "Chat message history." }) messages!: unknown;
+}
+
+await client.agents.create(appId, {
+  handle: "@assistant",
+  displayName: "Assistant",
+  model: "openai/gpt-oss-120b",            // a function-calling model
+  systemPrompt: ejectAgentPrompt(ChatApp),
+  tools: ejectAgentTools(ChatApp),
+});
+```
+
 **Serverless Functions (`client.functions`).** Deploy your own code that runs on
 the accelerator. A function is an untrusted single-module ES worker
 (`export default { fetch }`) with two triggers: **HTTP** (reachable at its own

package/dist/browser/index.js

@@ -5305,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.
@@ -6865,8 +6951,13 @@ class SpaceNamespace {
  * (viewers can read). Authorization rides the user session token; non-owner
  * editors pass their management Space via `opts.space`.
  *
- * v1 is "prompts + persona": a system prompt, a model, named prompt `skills`,
- * and `triggers` that decide when the agent speaks. No tools, no code.
+ * 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;
@@ -7014,6 +7105,8 @@ 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. */
@@ -7051,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
@@ -7121,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.
  *
@@ -7187,5 +7452,5 @@ var bundledLoader = /*#__PURE__*/Object.freeze({
   default: loadRsWasm
 });
 
-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, 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