@absolutejs/sync 1.9.2 → 1.10.0

package/dist/codeMode.d.ts

@@ -0,0 +1,130 @@
+/**
+ * `@absolutejs/sync/code-mode` — wraps engine mutations as Code Mode host
+ * tools.
+ *
+ * The Code Mode pattern (Cloudflare Dynamic Workers / Anthropic
+ * programmatic tool calling, both ~2026) replaces "N tool calls per
+ * turn" with "1 tool call whose body is JS that chains the underlying
+ * fns." Sync's contribution: the engine's mutation surface is the
+ * underlying fns. The model writes
+ *
+ * ```js
+ * const c = await runMutation('comments:create', { body: '@bob …', resourceId });
+ * await runMutation('comments:toggleReaction', { commentId: c.id, emoji: '👍' });
+ * return c.id;
+ * ```
+ *
+ * and three would-be tool turns collapse into one — only the final
+ * `return` enters the conversation context.
+ *
+ * The factory here returns a **host-tool map** that's shape-compatible
+ * with `@absolutejs/ai`'s `codeModeTool({ tools })` option. We don't
+ * import `@absolutejs/ai` because the consumer is responsible for
+ * wiring the two; sync stays decoupled from the AI SDK.
+ *
+ * ## v0.1 semantics (read carefully)
+ *
+ * - Each `runMutation` call runs in its own DB transaction (the
+ *   engine's per-call retry/transaction wrapper). If mutation 3/5
+ *   fails, mutations 1–2 are already committed; the model receives
+ *   the error and decides whether to compensate (e.g. by calling a
+ *   delete mutation).
+ * - Cross-mutation atomicity (all-or-nothing across N runMutations) is
+ *   NOT provided here — it would need a new engine batch primitive.
+ *   That's a deliberate v0.2 followup; this v0.1 ships the integration
+ *   without lying about transactional semantics.
+ * - The host-side `ctx` factory runs ONCE per `run_mutations` tool
+ *   call; the same ctx is threaded through every mutation in that
+ *   script. This matches the "one model turn ≈ one user request"
+ *   shape, where the user identity doesn't change mid-script.
+ *
+ * @example
+ * ```ts
+ * import { engineMutationsAsHostTools } from '@absolutejs/sync/code-mode';
+ * import { codeModeTool } from '@absolutejs/ai/tools';
+ *
+ * const sessionCtx = () => ({ userId: currentSessionUserId() });
+ * const hostTools = engineMutationsAsHostTools({
+ *   ctx: sessionCtx,
+ *   engine,
+ *   mutations: [
+ *     {
+ *       description: 'Post a comment on a resource.',
+ *       name: 'comments:create',
+ *       tsSignature:
+ *         '(args: { resourceId: string; body: string }) => ' +
+ *         'Promise<{ id: string; authorId: string; body: string }>',
+ *     },
+ *     {
+ *       description: 'Toggle a reaction emoji on a comment.',
+ *       name: 'comments:toggleReaction',
+ *       tsSignature:
+ *         '(args: { commentId: string; emoji: string }) => ' +
+ *         'Promise<{ added: boolean }>',
+ *     },
+ *   ],
+ * });
+ *
+ * const aiTool = codeModeTool({ tools: hostTools });
+ * ```
+ */
+import type { SyncEngine } from './engine/syncEngine';
+/** One engine mutation surfaced to the model as a host function. */
+export type MutationToolDescriptor = {
+    /** Engine-registered mutation name (e.g. `'comments:create'`). */
+    name: string;
+    /**
+     * One-line description shown to the model in the Code Mode prompt.
+     * Should describe *what the mutation does*, not just its inputs.
+     */
+    description: string;
+    /**
+     * TypeScript signature shown to the model. Default
+     * `'(args: any) => Promise<any>'` — provide a real signature so the
+     * model knows the input shape.
+     */
+    tsSignature?: string;
+    /**
+     * Override the host-fn name surfaced to the model. Default: the
+     * mutation `name` with `:` replaced by `_` (engine names are not
+     * valid JS identifiers). For `'comments:create'` the model sees
+     * `comments_create` by default.
+     */
+    hostFnName?: string;
+};
+/** Options for {@link engineMutationsAsHostTools}. */
+export type EngineMutationsAsHostToolsOptions<Ctx> = {
+    /** The engine whose mutations should be exposed. */
+    engine: SyncEngine;
+    /**
+     * Resolve the per-call ctx — invoked ONCE at the start of each
+     * Code Mode `run_mutations` call and threaded through every
+     * mutation in that script. Typically returns the current
+     * session/user identity. May be sync or async.
+     */
+    ctx: () => Ctx | Promise<Ctx>;
+    /** The mutation set to expose. */
+    mutations: MutationToolDescriptor[];
+};
+/**
+ * Shape of one entry in the host-tool map. Mirrors
+ * `@absolutejs/ai/tools`'s `CodeModeHostTool` exactly — no import
+ * needed; the AI SDK consumes any record with this shape.
+ */
+export type CodeModeHostTool = {
+    description: string;
+    tsSignature: string;
+    handler: (...args: unknown[]) => unknown;
+};
+/** Map of model-visible host-fn name → host tool. */
+export type CodeModeHostToolMap = Record<string, CodeModeHostTool>;
+/**
+ * Build a host-tool map that exposes the engine's mutation surface to a
+ * Code Mode tool. Pass the result to `codeModeTool({ tools })` from
+ * `@absolutejs/ai/tools`.
+ *
+ * The function throws synchronously at build time if any descriptor
+ * names a mutation that isn't registered on the engine, so a typo'd
+ * allowlist surfaces at boot, not at the first model call.
+ */
+export declare const engineMutationsAsHostTools: <Ctx>(options: EngineMutationsAsHostToolsOptions<Ctx>) => CodeModeHostToolMap;

package/dist/codeMode.js

@@ -0,0 +1,52 @@
+// @bun
+var __defProp = Object.defineProperty;
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, {
+      get: all[name],
+      enumerable: true,
+      configurable: true,
+      set: __exportSetter.bind(all, name)
+    });
+};
+var __require = import.meta.require;
+
+// src/codeMode.ts
+var DEFAULT_TS_SIGNATURE = "(args: any) => Promise<any>";
+var defaultHostFnName = (mutationName) => mutationName.replace(/[^A-Za-z0-9_]/g, "_");
+var engineMutationsAsHostTools = (options) => {
+  const { engine, ctx, mutations } = options;
+  const registered = new Set(engine.inspect().mutations);
+  const map = {};
+  const seenHostFnNames = new Set;
+  for (const descriptor of mutations) {
+    if (!registered.has(descriptor.name)) {
+      throw new Error(`engineMutationsAsHostTools: mutation "${descriptor.name}" is not registered on the engine. ` + `Register it first, or remove it from the mutations list.`);
+    }
+    const hostFnName = descriptor.hostFnName ?? defaultHostFnName(descriptor.name);
+    if (seenHostFnNames.has(hostFnName)) {
+      throw new Error(`engineMutationsAsHostTools: duplicate host-fn name "${hostFnName}". ` + `Two mutations map to the same identifier \u2014 set hostFnName explicitly on one of them.`);
+    }
+    seenHostFnNames.add(hostFnName);
+    map[hostFnName] = {
+      description: descriptor.description,
+      handler: async (...args) => {
+        const payload = args[0];
+        const resolvedCtx = await ctx();
+        return engine.runMutation(descriptor.name, payload, resolvedCtx);
+      },
+      tsSignature: descriptor.tsSignature ?? DEFAULT_TS_SIGNATURE
+    };
+  }
+  return map;
+};
+export {
+  engineMutationsAsHostTools
+};
+
+//# debugId=F24C2874EAF571E664756E2164756E21
+//# sourceMappingURL=codeMode.js.map

package/dist/codeMode.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/codeMode.ts"],
+  "sourcesContent": [
+    "/**\n * `@absolutejs/sync/code-mode` — wraps engine mutations as Code Mode host\n * tools.\n *\n * The Code Mode pattern (Cloudflare Dynamic Workers / Anthropic\n * programmatic tool calling, both ~2026) replaces \"N tool calls per\n * turn\" with \"1 tool call whose body is JS that chains the underlying\n * fns.\" Sync's contribution: the engine's mutation surface is the\n * underlying fns. The model writes\n *\n * ```js\n * const c = await runMutation('comments:create', { body: '@bob …', resourceId });\n * await runMutation('comments:toggleReaction', { commentId: c.id, emoji: '👍' });\n * return c.id;\n * ```\n *\n * and three would-be tool turns collapse into one — only the final\n * `return` enters the conversation context.\n *\n * The factory here returns a **host-tool map** that's shape-compatible\n * with `@absolutejs/ai`'s `codeModeTool({ tools })` option. We don't\n * import `@absolutejs/ai` because the consumer is responsible for\n * wiring the two; sync stays decoupled from the AI SDK.\n *\n * ## v0.1 semantics (read carefully)\n *\n * - Each `runMutation` call runs in its own DB transaction (the\n *   engine's per-call retry/transaction wrapper). If mutation 3/5\n *   fails, mutations 1–2 are already committed; the model receives\n *   the error and decides whether to compensate (e.g. by calling a\n *   delete mutation).\n * - Cross-mutation atomicity (all-or-nothing across N runMutations) is\n *   NOT provided here — it would need a new engine batch primitive.\n *   That's a deliberate v0.2 followup; this v0.1 ships the integration\n *   without lying about transactional semantics.\n * - The host-side `ctx` factory runs ONCE per `run_mutations` tool\n *   call; the same ctx is threaded through every mutation in that\n *   script. This matches the \"one model turn ≈ one user request\"\n *   shape, where the user identity doesn't change mid-script.\n *\n * @example\n * ```ts\n * import { engineMutationsAsHostTools } from '@absolutejs/sync/code-mode';\n * import { codeModeTool } from '@absolutejs/ai/tools';\n *\n * const sessionCtx = () => ({ userId: currentSessionUserId() });\n * const hostTools = engineMutationsAsHostTools({\n *   ctx: sessionCtx,\n *   engine,\n *   mutations: [\n *     {\n *       description: 'Post a comment on a resource.',\n *       name: 'comments:create',\n *       tsSignature:\n *         '(args: { resourceId: string; body: string }) => ' +\n *         'Promise<{ id: string; authorId: string; body: string }>',\n *     },\n *     {\n *       description: 'Toggle a reaction emoji on a comment.',\n *       name: 'comments:toggleReaction',\n *       tsSignature:\n *         '(args: { commentId: string; emoji: string }) => ' +\n *         'Promise<{ added: boolean }>',\n *     },\n *   ],\n * });\n *\n * const aiTool = codeModeTool({ tools: hostTools });\n * ```\n */\n\nimport type { SyncEngine } from './engine/syncEngine';\n\n/** One engine mutation surfaced to the model as a host function. */\nexport type MutationToolDescriptor = {\n\t/** Engine-registered mutation name (e.g. `'comments:create'`). */\n\tname: string;\n\t/**\n\t * One-line description shown to the model in the Code Mode prompt.\n\t * Should describe *what the mutation does*, not just its inputs.\n\t */\n\tdescription: string;\n\t/**\n\t * TypeScript signature shown to the model. Default\n\t * `'(args: any) => Promise<any>'` — provide a real signature so the\n\t * model knows the input shape.\n\t */\n\ttsSignature?: string;\n\t/**\n\t * Override the host-fn name surfaced to the model. Default: the\n\t * mutation `name` with `:` replaced by `_` (engine names are not\n\t * valid JS identifiers). For `'comments:create'` the model sees\n\t * `comments_create` by default.\n\t */\n\thostFnName?: string;\n};\n\n/** Options for {@link engineMutationsAsHostTools}. */\nexport type EngineMutationsAsHostToolsOptions<Ctx> = {\n\t/** The engine whose mutations should be exposed. */\n\tengine: SyncEngine;\n\t/**\n\t * Resolve the per-call ctx — invoked ONCE at the start of each\n\t * Code Mode `run_mutations` call and threaded through every\n\t * mutation in that script. Typically returns the current\n\t * session/user identity. May be sync or async.\n\t */\n\tctx: () => Ctx | Promise<Ctx>;\n\t/** The mutation set to expose. */\n\tmutations: MutationToolDescriptor[];\n};\n\n/**\n * Shape of one entry in the host-tool map. Mirrors\n * `@absolutejs/ai/tools`'s `CodeModeHostTool` exactly — no import\n * needed; the AI SDK consumes any record with this shape.\n */\nexport type CodeModeHostTool = {\n\tdescription: string;\n\ttsSignature: string;\n\thandler: (...args: unknown[]) => unknown;\n};\n\n/** Map of model-visible host-fn name → host tool. */\nexport type CodeModeHostToolMap = Record<string, CodeModeHostTool>;\n\nconst DEFAULT_TS_SIGNATURE = '(args: any) => Promise<any>';\n\nconst defaultHostFnName = (mutationName: string): string =>\n\tmutationName.replace(/[^A-Za-z0-9_]/g, '_');\n\n/**\n * Build a host-tool map that exposes the engine's mutation surface to a\n * Code Mode tool. Pass the result to `codeModeTool({ tools })` from\n * `@absolutejs/ai/tools`.\n *\n * The function throws synchronously at build time if any descriptor\n * names a mutation that isn't registered on the engine, so a typo'd\n * allowlist surfaces at boot, not at the first model call.\n */\nexport const engineMutationsAsHostTools = <Ctx>(\n\toptions: EngineMutationsAsHostToolsOptions<Ctx>\n): CodeModeHostToolMap => {\n\tconst { engine, ctx, mutations } = options;\n\tconst registered = new Set(engine.inspect().mutations);\n\tconst map: CodeModeHostToolMap = {};\n\tconst seenHostFnNames = new Set<string>();\n\n\tfor (const descriptor of mutations) {\n\t\tif (!registered.has(descriptor.name)) {\n\t\t\tthrow new Error(\n\t\t\t\t`engineMutationsAsHostTools: mutation \"${descriptor.name}\" is not registered on the engine. ` +\n\t\t\t\t\t`Register it first, or remove it from the mutations list.`\n\t\t\t);\n\t\t}\n\t\tconst hostFnName =\n\t\t\tdescriptor.hostFnName ?? defaultHostFnName(descriptor.name);\n\t\tif (seenHostFnNames.has(hostFnName)) {\n\t\t\tthrow new Error(\n\t\t\t\t`engineMutationsAsHostTools: duplicate host-fn name \"${hostFnName}\". ` +\n\t\t\t\t\t`Two mutations map to the same identifier — set hostFnName explicitly on one of them.`\n\t\t\t);\n\t\t}\n\t\tseenHostFnNames.add(hostFnName);\n\n\t\tmap[hostFnName] = {\n\t\t\tdescription: descriptor.description,\n\t\t\thandler: async (...args: unknown[]): Promise<unknown> => {\n\t\t\t\t// Code Mode passes positional args from the model's JS call.\n\t\t\t\t// Engine mutations take a single `args` value — first\n\t\t\t\t// positional arg is the mutation payload.\n\t\t\t\tconst payload = args[0];\n\t\t\t\tconst resolvedCtx = await ctx();\n\t\t\t\treturn engine.runMutation(\n\t\t\t\t\tdescriptor.name,\n\t\t\t\t\tpayload,\n\t\t\t\t\tresolvedCtx\n\t\t\t\t);\n\t\t\t},\n\t\t\ttsSignature: descriptor.tsSignature ?? DEFAULT_TS_SIGNATURE\n\t\t};\n\t}\n\n\treturn map;\n};\n"
+  ],
+  "mappings": ";;;;;;;;;;;;;;;;;;AA8HA,IAAM,uBAAuB;AAE7B,IAAM,oBAAoB,CAAC,iBAC1B,aAAa,QAAQ,kBAAkB,GAAG;AAWpC,IAAM,6BAA6B,CACzC,YACyB;AAAA,EACzB,QAAQ,QAAQ,KAAK,cAAc;AAAA,EACnC,MAAM,aAAa,IAAI,IAAI,OAAO,QAAQ,EAAE,SAAS;AAAA,EACrD,MAAM,MAA2B,CAAC;AAAA,EAClC,MAAM,kBAAkB,IAAI;AAAA,EAE5B,WAAW,cAAc,WAAW;AAAA,IACnC,IAAI,CAAC,WAAW,IAAI,WAAW,IAAI,GAAG;AAAA,MACrC,MAAM,IAAI,MACT,yCAAyC,WAAW,4CACnD,0DACF;AAAA,IACD;AAAA,IACA,MAAM,aACL,WAAW,cAAc,kBAAkB,WAAW,IAAI;AAAA,IAC3D,IAAI,gBAAgB,IAAI,UAAU,GAAG;AAAA,MACpC,MAAM,IAAI,MACT,uDAAuD,kBACtD,2FACF;AAAA,IACD;AAAA,IACA,gBAAgB,IAAI,UAAU;AAAA,IAE9B,IAAI,cAAc;AAAA,MACjB,aAAa,WAAW;AAAA,MACxB,SAAS,UAAU,SAAsC;AAAA,QAIxD,MAAM,UAAU,KAAK;AAAA,QACrB,MAAM,cAAc,MAAM,IAAI;AAAA,QAC9B,OAAO,OAAO,YACb,WAAW,MACX,SACA,WACD;AAAA;AAAA,MAED,aAAa,WAAW,eAAe;AAAA,IACxC;AAAA,EACD;AAAA,EAEA,OAAO;AAAA;",
+  "debugId": "F24C2874EAF571E664756E2164756E21",
+  "names": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@absolutejs/sync",
-	"version": "1.9.2",
+	"version": "1.10.0",
 	"description": "Lightweight reactive-push and write-behind-cache primitives for Elysia and the AbsoluteJS ecosystem — kill polling and keep a remote store off your hot path, without adopting a whole sync-engine backend.",
 	"repository": {
 		"type": "git",
@@ -28,6 +28,11 @@
 			"import": "./dist/testing.js",
 			"default": "./dist/testing.js"
 		},
+		"./code-mode": {
+			"types": "./dist/codeMode.d.ts",
+			"import": "./dist/codeMode.js",
+			"default": "./dist/codeMode.js"
+		},
 		"./mcp": {
 			"types": "./dist/mcp/index.d.ts",
 			"import": "./dist/mcp/index.js",