framer-dalton 0.0.25 → 0.0.26

package/dist/cli.js

@@ -12,7 +12,7 @@ import net from 'net';
 import { fileURLToPath } from 'url';
 import { createTRPCClient, httpLink } from '@trpc/client';
 
-/* @framer/ai CLI v0.0.25 */
+/* @framer/ai CLI v0.0.26 */
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
@@ -29,6 +29,51 @@ Please upgrade: https://nodejs.org/`
   );
   process.exit(1);
 }
+
+// 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._:-]+$/;
+var providerEnvVars = [
+  { provider: "codex", envVar: "CODEX_THREAD_ID" },
+  { provider: "claude", envVar: "CLAUDE_CODE_SESSION_ID" },
+  { provider: "claude", envVar: "CLAUDE_CODE_REMOTE_SESSION_ID" }
+];
+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");
+function resolveAgentThreadContext(env = process.env) {
+  for (const { provider, envVar } of providerEnvVars) {
+    const agentThreadContext = normalizeAgentThreadContext({
+      agentThreadId: env[envVar],
+      agentProvider: provider
+    });
+    if (agentThreadContext.agentThreadId) return agentThreadContext;
+  }
+  return {};
+}
+__name(resolveAgentThreadContext, "resolveAgentThreadContext");
 function openUrl(url) {
   const platform = process.platform;
   let cmd;
@@ -330,7 +375,7 @@ __name(markTelemetryNoticeShown, "markTelemetryNoticeShown");
 // 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.26" 
 );
 var trackingEndpoint = "https://events.framer.com/track";
 var inProgressTrackings = /* @__PURE__ */ new Set();
@@ -420,6 +465,45 @@ function trackError(payload) {
   });
 }
 __name(trackError, "trackError");
+
+// src/connection-errors.ts
+var RELAY_CONNECTION_LOST_PATTERNS = [
+  "fetch failed",
+  // undici top-level: relay gone / socket closed mid-request
+  "other side closed",
+  // undici SocketError: relay exited mid-request
+  "UND_ERR_SOCKET",
+  // undici socket error code
+  "ECONNREFUSED",
+  // relay not listening
+  "ECONNRESET",
+  // connection reset mid-request
+  "socket hang up"
+];
+function isRelayConnectionLost(err) {
+  const seen = /* @__PURE__ */ new Set();
+  const stack = [err];
+  while (stack.length > 0) {
+    const node = stack.pop();
+    if (node == null || seen.has(node)) continue;
+    seen.add(node);
+    const e = node;
+    const text = `${typeof e.message === "string" ? e.message : ""} ${typeof e.code === "string" ? e.code : ""}`;
+    if (RELAY_CONNECTION_LOST_PATTERNS.some((pattern) => text.includes(pattern)))
+      return true;
+    if (e.cause != null) stack.push(e.cause);
+    if (Array.isArray(e.errors)) stack.push(...e.errors);
+  }
+  return false;
+}
+__name(isRelayConnectionLost, "isRelayConnectionLost");
+var AUTH_ERROR_PATTERNS = ["does not have access", "UNAUTHORIZED"];
+function isAuthError(errorMessage) {
+  return AUTH_ERROR_PATTERNS.some((p) => errorMessage.includes(p));
+}
+__name(isAuthError, "isAuthError");
+
+// src/utils.ts
 function rehydrateFramerAPIError(error) {
   if (!(error instanceof Error)) return null;
   const framerApi = error.data?.framerApi;
@@ -448,10 +532,12 @@ function formatError(error) {
   return String(error);
 }
 __name(formatError, "formatError");
-function formatErrorForUser(error) {
+function formatErrorForUser(error, opts) {
   if (!(error instanceof Error)) return String(error);
   const rehydrated = rehydrateFramerAPIError(error);
   if (rehydrated) return rehydrated.toString();
+  if (!opts?.fromExecResult && isRelayConnectionLost(error))
+    return "Connection to the Framer server was lost. Run `framer session new` to reconnect.";
   const ref = getErrorRef(error);
   return ref ? `${error.message} [ref: ${ref}]` : error.message;
 }
@@ -819,13 +905,6 @@ async function acquireAuthWithRemixProject(sourceProjectUrlOrId) {
 }
 __name(acquireAuthWithRemixProject, "acquireAuthWithRemixProject");
 
-// src/connection-errors.ts
-var AUTH_ERROR_PATTERNS = ["does not have access", "UNAUTHORIZED"];
-function isAuthError(errorMessage) {
-  return AUTH_ERROR_PATTERNS.some((p) => errorMessage.includes(p));
-}
-__name(isAuthError, "isAuthError");
-
 // src/closest-match.ts
 function levenshteinDistance(source, target) {
   const sourceLength = source.length;
@@ -7210,12 +7289,48 @@ var types = {
         description: "@alpha",
         optional: false
       },
+      {
+        name: "readComponentControlsForAgent",
+        type: "(input: {\n        componentIds: readonly string[];\n    }, options?: {\n        pagePath?: string;\n    }) => Promise<unknown>",
+        description: "@alpha",
+        optional: false
+      },
+      {
+        name: "readIconSetControlsForAgent",
+        type: "(input: {\n        iconSetNames: readonly string[];\n    }, options?: {\n        pagePath?: string;\n    }) => Promise<unknown>",
+        description: "@alpha",
+        optional: false
+      },
+      {
+        name: "readIconsForAgent",
+        type: "(input: {\n        iconSetName: string;\n    }, options?: {\n        pagePath?: string;\n    }) => Promise<string[]>",
+        description: "@alpha",
+        optional: false
+      },
+      {
+        name: "readLayoutTemplateControlsForAgent",
+        type: "(input: {\n        layoutTemplateIds: readonly string[];\n    }, options?: {\n        pagePath?: string;\n    }) => Promise<unknown>",
+        description: "@alpha",
+        optional: false
+      },
+      {
+        name: "readShaderControlsForAgent",
+        type: "(input: {\n        shaderNames: readonly string[];\n    }, options?: {\n        pagePath?: string;\n    }) => Promise<unknown>",
+        description: "@alpha",
+        optional: false
+      },
       {
         name: "applyAgentChanges",
         type: "(dsl: string, options?: {\n        pagePath?: string;\n    }) => Promise<void>",
         description: "@alpha",
         optional: false
       },
+      {
+        name: "ping",
+        type: "() => Promise<void>",
+        description: "@alpha Liveness round-trip; resolves when Vekter's plugin handler answers.",
+        optional: false
+      },
       {
         name: "publishForAgent",
         type: "(input?: Record<string, unknown>) => Promise<unknown>",
@@ -7825,6 +7940,18 @@ var types = {
         type: "string",
         description: "JSONL string with one training row per inner-agent step, present when `captureTrainingData` was set.",
         optional: true
+      },
+      {
+        name: "fixtureFilename",
+        type: "string",
+        description: "Document fixture filename, always present after a completed run.",
+        optional: false
+      },
+      {
+        name: "fixtureContent",
+        type: "string",
+        description: "Document fixture JSON content (tree + code files).",
+        optional: false
       }
     ]
   },
@@ -13224,6 +13351,13 @@ var methodsByCategory = {
       description: 'Paginate a large array of values across multiple calls. The cursor is\nopaque and only valid within the same headless session and page.\n\n- First page: pass `{ items }`.\n- Continuation: pass `{ keyName, cursor }` using values returned by a previous call.\n\n@param input - `{ items }` for a fresh array, or `{ keyName, cursor }` for continuation.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns The current page, including `keyName`, `cursor`, `results`, `totalResults`, and (if more pages remain) `nextCursor`.',
       references: []
     },
+    {
+      name: "[$framerApiOnly.ping]",
+      category: "framer",
+      signature: "[$framerApiOnly.ping](): Promise<void>",
+      description: "Liveness round-trip: resolves once Vekter's plugin handler answers. Used by the headless\n backend to verify the transport actually routes, not just that the page is alive.",
+      references: []
+    },
     {
       name: "[$framerApiOnly.publishForAgent]",
       category: "framer",
@@ -13238,6 +13372,34 @@ var methodsByCategory = {
       description: 'Searches for stock images to use on the canvas (e.g. `"FrameNode"` `fill` values). Returns\ncandidate images with preview thumbnails and a `url` field for each. The returned URLs are\nregistered as trusted for this session so they can be applied directly via `fill="<url>"`\nin a subsequent {@link applyAgentChanges} DSL command. Without calling this method first,\nexternal image URLs are rejected at apply time.\n\nThe input schema is documented in the string returned by {@link getAgentSystemPrompt}.\n\n@param input - Search input object (source / query / count / orientation).\n@returns An object describing the candidates or an error.',
       references: []
     },
+    {
+      name: "[$framerApiOnly.readComponentControlsForAgent]",
+      category: "framer",
+      signature: "[$framerApiOnly.readComponentControlsForAgent](input: { componentIds: readonly string[]; }, options?: { pagePath?: string; }): Promise<unknown>",
+      description: "@alpha",
+      references: []
+    },
+    {
+      name: "[$framerApiOnly.readIconSetControlsForAgent]",
+      category: "framer",
+      signature: "[$framerApiOnly.readIconSetControlsForAgent](input: { iconSetNames: readonly string[]; }, options?: { pagePath?: string; }): Promise<unknown>",
+      description: "@alpha",
+      references: []
+    },
+    {
+      name: "[$framerApiOnly.readIconsForAgent]",
+      category: "framer",
+      signature: "[$framerApiOnly.readIconsForAgent](input: { iconSetName: string; }, options?: { pagePath?: string; }): Promise<string[]>",
+      description: "@alpha",
+      references: []
+    },
+    {
+      name: "[$framerApiOnly.readLayoutTemplateControlsForAgent]",
+      category: "framer",
+      signature: "[$framerApiOnly.readLayoutTemplateControlsForAgent](input: { layoutTemplateIds: readonly string[]; }, options?: { pagePath?: string; }): Promise<unknown>",
+      description: "@alpha",
+      references: []
+    },
     {
       name: "[$framerApiOnly.readProjectForAgent]",
       category: "framer",
@@ -13245,6 +13407,13 @@ var methodsByCategory = {
       description: 'Reads project state by executing an array of queries against the project.\n\nReturns one result per query. Available query types and their parameters\nare documented in the string returned by {@link getAgentSystemPrompt}.\n\n@param queries - Array of query objects. See {@link getAgentSystemPrompt} for available types.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns An object with a `results` array, one entry per query.',
       references: []
     },
+    {
+      name: "[$framerApiOnly.readShaderControlsForAgent]",
+      category: "framer",
+      signature: "[$framerApiOnly.readShaderControlsForAgent](input: { shaderNames: readonly string[]; }, options?: { pagePath?: string; }): Promise<unknown>",
+      description: "@alpha",
+      references: []
+    },
     {
       name: "[$framerApiOnly.reviewChangesForAgent]",
       category: "framer",
@@ -13804,6 +13973,13 @@ var methodsByCategory = {
       description: 'Paginate a large array of values across multiple calls. The cursor is\nopaque and only valid within the same headless session and page.\n\n- First page: pass `{ items }`.\n- Continuation: pass `{ keyName, cursor }` using values returned by a previous call.\n\n@param input - `{ items }` for a fresh array, or `{ keyName, cursor }` for continuation.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns The current page, including `keyName`, `cursor`, `results`, `totalResults`, and (if more pages remain) `nextCursor`.',
       references: []
     },
+    {
+      name: "ping",
+      category: "framer",
+      signature: "ping(): Promise<void>",
+      description: "Liveness round-trip: resolves once Vekter's plugin handler answers. Used by the headless\n backend to verify the transport actually routes, not just that the page is alive.",
+      references: []
+    },
     {
       name: "publish",
       category: "framer",
@@ -13825,6 +14001,34 @@ var methodsByCategory = {
       description: 'Searches for stock images to use on the canvas (e.g. `"FrameNode"` `fill` values). Returns\ncandidate images with preview thumbnails and a `url` field for each. The returned URLs are\nregistered as trusted for this session so they can be applied directly via `fill="<url>"`\nin a subsequent {@link applyAgentChanges} DSL command. Without calling this method first,\nexternal image URLs are rejected at apply time.\n\nThe input schema is documented in the string returned by {@link getAgentSystemPrompt}.\n\n@param input - Search input object (source / query / count / orientation).\n@returns An object describing the candidates or an error.',
       references: []
     },
+    {
+      name: "readComponentControlsForAgent",
+      category: "framer",
+      signature: "readComponentControlsForAgent(input: { componentIds: readonly string[]; }, options?: { pagePath?: string; }): Promise<unknown>",
+      description: "@alpha",
+      references: []
+    },
+    {
+      name: "readIconSetControlsForAgent",
+      category: "framer",
+      signature: "readIconSetControlsForAgent(input: { iconSetNames: readonly string[]; }, options?: { pagePath?: string; }): Promise<unknown>",
+      description: "@alpha",
+      references: []
+    },
+    {
+      name: "readIconsForAgent",
+      category: "framer",
+      signature: "readIconsForAgent(input: { iconSetName: string; }, options?: { pagePath?: string; }): Promise<string[]>",
+      description: "@alpha",
+      references: []
+    },
+    {
+      name: "readLayoutTemplateControlsForAgent",
+      category: "framer",
+      signature: "readLayoutTemplateControlsForAgent(input: { layoutTemplateIds: readonly string[]; }, options?: { pagePath?: string; }): Promise<unknown>",
+      description: "@alpha",
+      references: []
+    },
     {
       name: "readProjectForAgent",
       category: "framer",
@@ -13832,6 +14036,13 @@ var methodsByCategory = {
       description: 'Reads project state by executing an array of queries against the project.\n\nReturns one result per query. Available query types and their parameters\nare documented in the string returned by {@link getAgentSystemPrompt}.\n\n@param queries - Array of query objects. See {@link getAgentSystemPrompt} for available types.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns An object with a `results` array, one entry per query.',
       references: []
     },
+    {
+      name: "readShaderControlsForAgent",
+      category: "framer",
+      signature: "readShaderControlsForAgent(input: { shaderNames: readonly string[]; }, options?: { pagePath?: string; }): Promise<unknown>",
+      description: "@alpha",
+      references: []
+    },
     {
       name: "rejectAllPending",
       category: "framer",
@@ -14024,6 +14235,22 @@ var methodsByCategory = {
       references: ["NamedImageAssetInput", "ImageAsset"]
     }
   ],
+  framerapierror: [
+    {
+      name: "recentMethods",
+      category: "FramerAPIError",
+      signature: "recentMethods: string[]",
+      description: "@see FramerAPIErrorOptions.recentMethods",
+      references: []
+    },
+    {
+      name: "retryable",
+      category: "FramerAPIError",
+      signature: "retryable: boolean",
+      description: "@see FramerAPIErrorOptions.retryable",
+      references: []
+    }
+  ],
   imageasset: [
     {
       name: "altText",
@@ -16729,7 +16956,7 @@ async function execAndPrint(sessionId, code) {
     }
     if (result.error) {
       printError(
-        `Error: ${formatErrorForUser(errorWithRef(result.error, result.errorRef))}`
+        `Error: ${formatErrorForUser(errorWithRef(result.error, result.errorRef), { fromExecResult: true })}`
       );
       await waitForTrackingToFinish();
       process.exit(1);
@@ -16807,6 +17034,7 @@ session.command("new <projectUrlOrId>").description("Create a new session and pr
 ).action(
   async (projectUrlOrId, options) => {
     const projectId = extractProjectId(projectUrlOrId);
+    const agentThreadContext = resolveAgentThreadContext();
     let sessionId;
     let userId;
     try {
@@ -16831,7 +17059,8 @@ session.command("new <projectUrlOrId>").description("Create a new session and pr
         projectId,
         apiKey: credentials.apiKey,
         userId: credentials.userId,
-        headlessServerUrl
+        headlessServerUrl,
+        ...agentThreadContext
       });
       sessionId = result.id;
       debug("session.new", `session created id=${sessionId}`);
@@ -16885,6 +17114,7 @@ session.command("new <projectUrlOrId>").description("Create a new session and pr
         errorType: "session_new_error",
         projectId,
         userId,
+        ...agentThreadContext,
         errorMessage: message
       });
       printError(`Failed to create session: ${formatErrorForUser(err)}`);

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.26 */
 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.26" 
 );
 
 // 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

@@ -39,6 +39,7 @@ Always save results you'll need again. Don't repeat API calls.
 Use agent-specific methods whenever a plugin API method and an agent method overlap:
 
 - Use `readProjectForAgent`, `getNodeForAgent`, `getNodesForAgent`, `getNodesOfTypesForAgent`, `getScopeNodeForAgent`, `getGroundNodeForAgent`, `getParentNodeForAgent`, `getAncestorsForAgent`, `serializeForAgent`, `serializeNodesForAgent`, and `paginateForAgent` for project tree reads.
+- Use `readComponentControlsForAgent`, `readIconSetControlsForAgent`, `readIconsForAgent`, `readLayoutTemplateControlsForAgent`, and `readShaderControlsForAgent` for reading the controls of components, icon sets, icons, layout templates, and shaders.
 - 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.
 
@@ -170,7 +171,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 `readProjectForAgent` and `applyAgentChanges`, not the plugin API. Use the plugin Collection API to read available collections and field schema first, then use `applyAgentChanges` to add the list.
 
 #### Reading Collections
 
@@ -182,10 +183,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 +246,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,7 +275,7 @@ 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 `applyAgentChanges`.
 
 There are three sources you'll typically pull URLs from:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "framer-dalton",
-  "version": "0.0.25",
+  "version": "0.0.26",
   "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-beta",
+    "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": {