framer-dalton 0.0.25 → 0.0.27

package/dist/start-relay-server.js

@@ -14,7 +14,7 @@ import { z } from 'zod';
 import { createRequire } from 'module';
 import * as vm from 'vm';
 
-/* @framer/ai relay server v0.0.25 */
+/* @framer/ai relay server v0.0.27 */
 var __defProp = Object.defineProperty;
 var __knownSymbol = (name2, symbol) => (symbol = Symbol[name2]) ? symbol : /* @__PURE__ */ Symbol.for("Symbol." + name2);
 var __typeError = (msg) => {
@@ -160,7 +160,7 @@ __name(debug, "debug");
 // src/version.ts
 var VERSION = (
   // typeof is used to ensure this can be used just via tsx or node etc. without build
-  "0.0.25" 
+  "0.0.27" 
 );
 
 // src/relay-client.ts
@@ -182,6 +182,35 @@ createTRPCClient({
   ]
 });
 
+// src/agent-thread-context.ts
+var MAX_AGENT_THREAD_ID_LENGTH = 256;
+var MAX_AGENT_PROVIDER_LENGTH = 64;
+var SAFE_VALUE_PATTERN = /^[A-Za-z0-9._:-]+$/;
+function normalizeValue(value, maxLength) {
+  const trimmed = value?.trim();
+  if (!trimmed) return void 0;
+  if (trimmed.length > maxLength) return void 0;
+  if (!SAFE_VALUE_PATTERN.test(trimmed)) return void 0;
+  return trimmed;
+}
+__name(normalizeValue, "normalizeValue");
+function normalizeAgentThreadContext(input) {
+  const agentThreadId = normalizeValue(
+    input.agentThreadId,
+    MAX_AGENT_THREAD_ID_LENGTH
+  );
+  if (!agentThreadId) return {};
+  const agentProvider = normalizeValue(
+    input.agentProvider,
+    MAX_AGENT_PROVIDER_LENGTH
+  );
+  return {
+    agentThreadId,
+    ...agentProvider ? { agentProvider } : {}
+  };
+}
+__name(normalizeAgentThreadContext, "normalizeAgentThreadContext");
+
 // src/connection-errors.ts
 var CONNECTION_ERROR_PATTERNS = [
   "Connection closed",
@@ -198,8 +227,15 @@ var CONNECTION_ERROR_PATTERNS = [
   // Our own check in executor.ts
   "Execution timed out after",
   // Likely dead connection
-  "Session expired"
+  "Session expired",
   // Server-side session expiry
+  // Typed page-death (PROJECT_CLOSED) for the string fallback; isRetryableError is the primary path.
+  "Project session crashed",
+  // PageCrashedError (renderer crash / OOM)
+  "Project was closed",
+  // StaleSessionError (page closed/reaped)
+  "Session was recycled"
+  // SessionRecycledError (destroy->respawn reconnect race)
 ];
 function isConnectionError(errorMessage) {
   return CONNECTION_ERROR_PATTERNS.some(
@@ -207,6 +243,18 @@ function isConnectionError(errorMessage) {
   );
 }
 __name(isConnectionError, "isConnectionError");
+function isRetryableError(err) {
+  if (err && typeof err === "object") {
+    const e = err;
+    if (e.retryable === true) return true;
+    if (e.code === "PROJECT_CLOSED") return true;
+    if (typeof e.message === "string" && isConnectionError(e.message))
+      return true;
+    return false;
+  }
+  return typeof err === "string" && isConnectionError(err);
+}
+__name(isRetryableError, "isRetryableError");
 var AUTH_ERROR_PATTERNS = ["does not have access", "UNAUTHORIZED"];
 function isAuthError(errorMessage) {
   return AUTH_ERROR_PATTERNS.some((p) => errorMessage.includes(p));
@@ -541,20 +589,37 @@ async function execute(session, code, options = {}) {
     return { output };
   } catch (err) {
     const errorMessage = err instanceof Error ? err.message : String(err);
-    if (isConnectionError(errorMessage)) {
+    const retryable = isRetryableError(err);
+    if (retryable || isConnectionError(errorMessage)) {
       session.connection.markDisconnected();
     }
     const errorRef = getErrorRef(err);
     return {
       output,
       error: errorMessage,
-      ...errorRef ? { errorRef } : {}
+      ...errorRef ? { errorRef } : {},
+      ...retryable ? { retryable: true } : {}
     };
   } finally {
     if (timeoutId) clearTimeout(timeoutId);
   }
 }
 __name(execute, "execute");
+function isReconnectable(err) {
+  return isRetryableError(err) || isConnectionError(err instanceof Error ? err.message : String(err));
+}
+__name(isReconnectable, "isReconnectable");
+function connectionFailureResult(prefix, err) {
+  const inner = err instanceof Error ? err.message : String(err);
+  const errorRef = getErrorRef(err);
+  return {
+    output: [],
+    error: `${prefix}: ${inner}`,
+    ...errorRef ? { errorRef } : {},
+    ...isRetryableError(err) ? { retryable: true } : {}
+  };
+}
+__name(connectionFailureResult, "connectionFailureResult");
 async function executeWithReconnect(session, code, options, execId) {
   if (!session.connection.isConnected()) {
     log(
@@ -563,17 +628,27 @@ async function executeWithReconnect(session, code, options, execId) {
     try {
       await session.connection.reconnect();
     } catch (err) {
-      const inner = err instanceof Error ? err.message : String(err);
-      const errorRef = getErrorRef(err);
-      return {
-        output: [],
-        error: `Failed to get connection for session: ${inner}`,
-        ...errorRef ? { errorRef } : {}
-      };
+      if (!isReconnectable(err)) {
+        return connectionFailureResult(
+          "Failed to get connection for session",
+          err
+        );
+      }
+      log(
+        `exec.reconnect.retry exec=${execId} session=${session.id} reason="${err instanceof Error ? err.message : String(err)}"`
+      );
+      try {
+        await session.connection.reconnect();
+      } catch (err2) {
+        return connectionFailureResult(
+          "Failed to get connection for session",
+          err2
+        );
+      }
     }
   }
   const result = await execute(session, code, options);
-  if (!result.error || !isConnectionError(result.error)) {
+  if (!result.error || !(result.retryable || isConnectionError(result.error))) {
     return result;
   }
   log(
@@ -582,16 +657,13 @@ async function executeWithReconnect(session, code, options, execId) {
   try {
     await session.connection.reconnect();
   } catch (err) {
-    const inner = err instanceof Error ? err.message : String(err);
-    const errorRef = getErrorRef(err);
     log(
-      `reconnect.failed exec=${execId} session=${session.id} req=${session.connection.framer.requestId} error="${inner}"`
+      `reconnect.failed exec=${execId} session=${session.id} req=${session.connection.framer.requestId} error="${err instanceof Error ? err.message : String(err)}"`
+    );
+    return connectionFailureResult(
+      "Connection lost and failed to reconnect",
+      err
     );
-    return {
-      output: [],
-      error: `Connection lost and failed to reconnect: ${inner}`,
-      ...errorRef ? { errorRef } : {}
-    };
   }
   log(
     `reconnect.success exec=${execId} session=${session.id} req=${session.connection.framer.requestId}`
@@ -897,10 +969,11 @@ var Connection = class _Connection {
       headlessServerUrl: this.headlessServerUrl
     }));
   }
-  createSession(id) {
+  createSession(id, agentThreadContext) {
     const session = {
       id,
       state: {},
+      agentThreadContext,
       lastActivityAt: Date.now(),
       inflight: 0,
       connection: this
@@ -971,14 +1044,17 @@ var SessionManager = class {
   }
   connections = [];
   idleCheck = null;
-  async create(projectId, userId, apiKey, headlessServerUrl) {
+  async create(projectId, userId, apiKey, headlessServerUrl, agentThreadContext = {}) {
     const connection = await this.findOrCreateConnection(
       projectId,
       userId,
       apiKey,
       headlessServerUrl
     );
-    const session = connection.createSession(this.getNextSessionId());
+    const session = connection.createSession(
+      this.getNextSessionId(),
+      agentThreadContext
+    );
     this.startIdleCheck();
     return session;
   }
@@ -1008,6 +1084,7 @@ var SessionManager = class {
         projectId: session.connection.projectId,
         userId: session.connection.userId,
         sessionId: session.connection.getServerSessionId(),
+        ...session.agentThreadContext,
         durationMs,
         hasError: result.error !== void 0,
         ...result.error ? { errorMessage: result.error } : {}
@@ -1048,7 +1125,8 @@ var SessionManager = class {
     trackSessionDestroy({
       projectId: session.connection.projectId,
       userId: session.connection.userId,
-      sessionId: session.connection.getServerSessionId()
+      sessionId: session.connection.getServerSessionId(),
+      ...session.agentThreadContext
     });
     session.connection.removeSession(id);
     if (!session.connection.hasSessions()) {
@@ -1202,16 +1280,20 @@ var appRouter = t.router({
       projectId: z.string(),
       apiKey: z.string(),
       userId: z.string().optional(),
-      headlessServerUrl: z.string()
+      headlessServerUrl: z.string(),
+      agentThreadId: z.string().optional(),
+      agentProvider: z.string().optional()
     })
   ).mutation(async ({ input }) => {
     const start = performance.now();
+    const agentThreadContext = normalizeAgentThreadContext(input);
     try {
       const session = await sessionManager.create(
         input.projectId,
         input.userId,
         input.apiKey,
-        input.headlessServerUrl
+        input.headlessServerUrl,
+        agentThreadContext
       );
       log(
         `session.new id=${session.id} project=${input.projectId} headlessServerUrl=${input.headlessServerUrl}`
@@ -1220,6 +1302,7 @@ var appRouter = t.router({
         projectId: input.projectId,
         userId: session.connection.userId,
         sessionId: session.connection.getServerSessionId(),
+        ...session.agentThreadContext,
         durationMs: Math.round(performance.now() - start)
       });
       return { id: session.id };
@@ -1229,6 +1312,7 @@ var appRouter = t.router({
         errorType: "session_create_error",
         projectId: input.projectId,
         userId: input.userId,
+        ...agentThreadContext,
         errorMessage: message
       });
       throw new TRPCError({

package/docs/skills/framer-project.md

@@ -36,15 +36,20 @@ Always save results you'll need again. Don't repeat API calls.
 
 ## Method Selection
 
-Use agent-specific methods whenever a plugin API method and an agent method overlap:
+Choose the highest-priority interface available for the task:
 
-- Use `readProjectForAgent`, `getNodeForAgent`, `getNodesForAgent`, `getNodesOfTypesForAgent`, `getScopeNodeForAgent`, `getGroundNodeForAgent`, `getParentNodeForAgent`, `getAncestorsForAgent`, `serializeForAgent`, `serializeNodesForAgent`, and `paginateForAgent` for project tree reads.
-- Use `applyAgentChanges` for page and layout edits. Do not use low-level node APIs like `createNode`, `setAttributes`, or `setRect` for design/layout work.
-- Use `publishForAgent` for publishing. Do not use `publish`, `getDeployments`, or `deploy` for normal agent publishing flows.
+1. Subcommands, such as `framer-dalton read-project` and `framer-dalton apply-changes`
+2. Agent-specific methods, such as `framer.agent.readProject`, `framer.agent.applyChanges`, and `framer.agent.publish`
+3. Generic plugin API methods, such as top-level `framer.*` methods
 
-Use the plugin API for capabilities that do not have an agent-specific counterpart, such as code file management, localization, and redirects.
+- Use `framer.agent.readProject`, `framer.agent.getNode`, `framer.agent.getNodes`, `framer.agent.getNodesOfTypes`, `framer.agent.getScopeNode`, `framer.agent.getGroundNode`, `framer.agent.getParentNode`, `framer.agent.getAncestors`, `framer.agent.serialize`, `framer.agent.serializeNodes`, and `framer.agent.paginate` for project tree reads.
+- Use `framer.agent.readComponentControls`, `framer.agent.readIconSetControls`, `framer.agent.readIcons`, `framer.agent.readLayoutTemplateControls`, and `framer.agent.readShaderControls` for reading the controls of components, icon sets, icons, layout templates, and shaders.
+- Use `framer.agent.applyChanges` for page and layout edits. Do not use low-level node APIs like `createNode`, `setAttributes`, or `setRect` for design/layout work.
+- Use `framer.agent.publish` for publishing. Do not use `publish`, `getDeployments`, or `deploy` for normal agent publishing flows.
 
-During normal task execution, do not call `framer.getAgentSystemPrompt()` or `framer.getAgentContext()`. This skill already includes their output.
+Use generic plugin API methods only for capabilities that do not have a subcommand or agent-specific counterpart, such as code file management, localization, and redirects.
+
+During normal task execution, do not call `framer.agent.getSystemPrompt()` or `framer.agent.getContext()`. This skill already includes their output.
 
 ## Core Usage Principles
 
@@ -99,15 +104,15 @@ Store anything you'll reference again.
 
 Use this approach only if the user asks for it. Do not mention this approach to the user otherwise.
 
-This approach is called “Prompt the Framer agent”. With this approach, use `framer.startAgentConversation()` to start a stateful design subagent. Keep the `conversationId` it returns in `state`, and call `framer.continueAgentConversation()` with it to continue the same design task.
+This approach is called “Prompt the Framer agent”. With this approach, use `framer.agent.startConversation()` to start a stateful design subagent. Keep the `conversationId` it returns in `state`, and call `framer.agent.continueConversation()` with it to continue the same design task.
 
-Do not call `framer.getAgentSystemPrompt()` or `framer.getAgentContext()` or `framer.applyAgentChanges()` with this approach.
+Do not call `framer.agent.getSystemPrompt()` or `framer.agent.getContext()` or `framer.agent.applyChanges()` with this approach.
 
 Example:
 
 ```js
 state.agent ??= {};
-const first = await framer.startAgentConversation(
+const first = await framer.agent.startConversation(
   "Build me a landing page based on the attached screenshot",
   {
     pagePath: "/",
@@ -118,7 +123,7 @@ const first = await framer.startAgentConversation(
 state.agent.conversationId = first.conversationId;
 console.log(first.responseMessages);
 
-const second = await framer.continueAgentConversation("Now make it pink", {
+const second = await framer.agent.continueConversation("Now make it pink", {
   conversationId: state.agent.conversationId,
   selectionNodeIds: ["someNodeId"],
   // imageUrls: [...],
@@ -170,7 +175,7 @@ npx framer-dalton docs ScreenshotOptions          # Show type + recursively expa
 
 Collections are Framer's CMS. Each collection has fields (columns) and items (rows). Use the plugin Collection API (the methods below) for collection schema and item CRUD.
 
-**Exception — CMS Collection Lists.** The in-canvas construct that *renders* a collection as a repeating list of cards (the "Collection List" / repeater) is an agent/page concern. Build and edit those through `readProjectForAgent` and `applyAgentChanges`, not the plugin API. Use the plugin Collection API to read available collections and field schema first, then drive the list through the project-scoped skill.
+**Exception — CMS Collection Lists.** The in-canvas construct that *renders* a collection as a repeating list of cards (the "Collection List" / repeater) is an agent/page concern. Build and edit those through `framer.agent.readProject` and `framer.agent.applyChanges`, not the plugin API. Use the plugin Collection API to read available collections and field schema first, then use `framer.agent.applyChanges` to add the list.
 
 #### Reading Collections
 
@@ -182,10 +187,11 @@ console.log(collections.map((c) => ({ name: c.name, id: c.id })));
 // Get a specific collection by ID
 const collection = await framer.getCollection("collection-id");
 
-// Get fields (columns) - returns array of { id, type, name }
+// Get fields (columns)
 const fields = await collection.getFields();
-console.log(fields);
-// [{ id: "BnNuS2i3o", type: "string", name: "Title" }, ...]
+// Note that a plain console.log will miss getter-backed properties
+console.log(fields.map((f) => ({ id: f.id, name: f.name, type: f.type })));
+// [{ id: "BnNuS2i3o", name: "Title", type: "string" }, ...]
 
 // Get items (rows)
 const items = await collection.getItems();
@@ -244,6 +250,17 @@ const ids = items.map((i) => i.id).reverse();
 await collection.setItemOrder(ids);
 ```
 
+#### Writing enum fields
+
+Enum fields are **write-by-case-id, read-by-name**: a write must pass the case's `id`, but `getItems()` reads the value back as the case name. Writing `{ type: "enum", value: "New" }` (the name) is rejected — look up the id from the field definition first:
+
+```js
+const caseId = field.cases.find((c) => c.name === "New").id;
+await collection.addItems([
+  { slug: "hello-world", fieldData: { [field.id]: { type: "enum", value: caseId } } },
+]);
+```
+
 #### Working with CollectionItem
 
 ```js
@@ -262,14 +279,14 @@ await item.remove();
 
 ### Working with Images
 
-Canvas editing accepts image URLs directly when setting an image fill, so the typical task is to obtain a URL and pass it through to the project-scoped skill.
+Canvas editing accepts image URLs directly when setting an image fill, so the typical task is to obtain a URL and use it directly with `framer.agent.applyChanges`.
 
 There are three sources you'll typically pull URLs from:
 
-**Stock photography.** Use `framer.queryImagesForAgent` to source candidates and stash the URL you want:
+**Stock photography.** Use `framer.agent.queryImages` to source candidates and stash the URL you want:
 
 ```js
-const { results } = await framer.queryImagesForAgent({
+const { results } = await framer.agent.queryImages({
   source: "unsplash",
   query: "snow-capped mountains",
   count: 4,
@@ -290,7 +307,7 @@ state.heroUrl = (await framer.uploadImage({
 **An image already on the canvas.** Read the node and reuse its existing image URL:
 
 ```js
-const node = await framer.getNodeForAgent({ id: "<image-node-id>" });
+const node = await framer.agent.getNode({ id: "<image-node-id>" });
 state.heroUrl = node.attributes.fill;
 ```
 
@@ -330,7 +347,7 @@ console.log(state.diagnostics);
 state.component = state.codeFile.exports.find(
   (exportItem) => exportItem.type === "component" && exportItem.isDefaultExport,
 );
-await framer.applyAgentChanges(
+await framer.agent.applyChanges(
   `+ComponentInstanceNode badge parent="wrapper" component="${state.component.componentId}"; SET badge width=120 height=48;`,
   { pagePath: "/" },
 );

package/docs/skills/framer.md

@@ -1,7 +1,7 @@
 ---
 name: framer
 description: >
-  Use when the user wants to design, edit, or publish a website or web page — creating layouts, editing sections, updating text or images, managing CMS collections and content, syncing external data, creating or modifying code components, managing color and text styles, handling localization, or publishing deployments. Trigger when the user mentions Framer, references their website or web pages, asks to edit designs, update site content, or work with any Framer project — even if they don't explicitly say 'Framer'. 
+  Use when the user wants to design, edit, or publish a website or web page — creating layouts, editing sections, updating text or images, managing CMS collections and content, syncing external data, creating or modifying code components, managing color and text styles, handling localization, or publishing deployments. Trigger when the user mentions Framer, references their website or web pages, asks to edit designs, update site content, or work with any Framer project — even if they don't explicitly say 'Framer'.
   **Mandatory precondition**: run `npx framer-dalton@latest setup` and let it complete **BEFORE** loading this skill.
 allowed-tools: ["Bash(npx framer-dalton:*)", "Bash(npx framer-dalton@latest:*)", "Read({{FRAMER_TEMPORARY_DIR}}/*)", "Write({{FRAMER_TEMPORARY_DIR}}/*)"]
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "framer-dalton",
-  "version": "0.0.25",
+  "version": "0.0.27",
   "type": "module",
   "bin": "./dist/cli.js",
   "main": "./dist/cli.js",
@@ -16,6 +16,7 @@
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist",
     "check": "biome check .",
+    "check:fix": "biome check --write .",
     "format": "biome format --write .",
     "generate-types": "tsx scripts/generate-types.ts"
   },
@@ -23,17 +24,17 @@
     "@trpc/client": "^11.17.0",
     "@trpc/server": "^11.17.0",
     "commander": "^12.1.0",
-    "framer-api": "0.1.11",
-    "zod": "^4.3.6"
+    "framer-api": "0.1.14",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.13",
-    "@framerjs/framer-events": "0.0.175",
-    "@types/node": "24.10.9",
+    "@framerjs/framer-events": "0.0.183",
+    "@types/node": "24.12.4",
     "tsup": "^8.0.2",
-    "tsx": "^4.19.0",
+    "tsx": "^4.22.3",
     "typescript": "^5.9.2",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.7"
   },
   "packageManager": "yarn@4.13.0",
   "engines": {