framer-dalton 0.0.28 → 0.0.30

package/README.md

@@ -7,7 +7,7 @@ CLI and agent skills for interacting with Framer projects via the Framer Server
 Install or refresh the globally available skills:
 
 ```bash
-npx framer-dalton@latest setup
+npx @framer/agent@latest setup
 ```
 
 That installs skills into `~/.agents/skills` and `~/.claude/skills`.
@@ -20,9 +20,9 @@ The CLI and the installed skills are meant to work together. There are three ski
 - `framer-code-components` - explains specific prompts for how to write code components and provides examples.
 - `framer-project-<project id>` - a dynamically-created skill for interacting with a specific project.
 
-1. Running `npx framer-dalton@latest setup` will install the base `framer` and `framer-code-components` skills.
+1. Running `npx @framer/agent@latest setup` will install the base `framer` and `framer-code-components` skills.
 2. The frontmatter of `framer-code-components` tells agents to always load `framer` and the generated project skill first.
-3. The frontmatter of `framer` tells agents to run `npx framer-dalton@latest setup` BEFORE loading the skill. This command will auto-update the cli and update the skill files.
+3. The frontmatter of `framer` tells agents to run `npx @framer/agent@latest setup` BEFORE loading the skill. This command will auto-update the cli and update the skill files.
 4. Creating a new session for a project will create a `framer-project-<project id>` file. This file contains the latest agent system prompt from `framer.agent.getSystemPrompt` and the latest project context from `framer.agent.getContext`. Agents must load this project-specific skill immediately after creating a session before doing any connected-project work.
 
 ## Local Development

package/dist/cli.js

@@ -12,12 +12,12 @@ import net from 'net';
 import { fileURLToPath } from 'url';
 import { createTRPCClient, httpLink } from '@trpc/client';
 
-/* @framer/ai CLI v0.0.28 */
+/* @framer/ai CLI v0.0.30 */
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
 // package.json
-var name = "framer-dalton";
+var name = "@framer/agent";
 
 // src/check-node-version.ts
 var MINIMUM_NODE_VERSION = 22;
@@ -375,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.28" 
+  "0.0.30" 
 );
 var trackingEndpoint = "https://events.framer.com/track";
 var inProgressTrackings = /* @__PURE__ */ new Set();
@@ -592,7 +592,7 @@ function formatErrorForUser(error, opts) {
   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.";
+    return "Connection to the Framer server was lost. Run `npx @framer/agent@latest session new` to reconnect.";
   const ref = getErrorRef(error);
   return ref ? `${error.message} [ref: ${ref}]` : error.message;
 }
@@ -855,7 +855,7 @@ function runBrowserAuthFlow(options) {
       printError(`  1. Open Site Settings \u2192 General: ${settingsUrl}`);
       printError("  2. Scroll to API Keys and create a new key");
       printError(
-        `  3. In another terminal, run: framer project auth ${pollProjectId} <your-api-key>`
+        `  3. In another terminal, run: npx @framer/agent@latest project auth ${pollProjectId} <your-api-key>`
       );
       print("");
       print("Waiting for authorization in browser...");
@@ -869,7 +869,7 @@ function runBrowserAuthFlow(options) {
         });
         reject(
           new Error(
-            pollProjectId ? "Browser authorization timed out. Use `framer project auth <projectUrlOrId> <apiKey>` instead." : "Browser authorization timed out."
+            pollProjectId ? "Browser authorization timed out. Use `npx @framer/agent@latest project auth <projectUrlOrId> <apiKey>` instead." : "Browser authorization timed out."
           )
         );
       });
@@ -1070,6 +1070,114 @@ var types = {
       }
     ]
   },
+  agentbranch: {
+    name: "AgentBranch",
+    description: "",
+    kind: "interface",
+    references: [],
+    members: [
+      {
+        name: "id",
+        type: "string",
+        description: "",
+        optional: false
+      },
+      {
+        name: "title",
+        type: "string",
+        description: "",
+        optional: false
+      },
+      {
+        name: "url",
+        type: "string",
+        description: "",
+        optional: false
+      },
+      {
+        name: "baseId",
+        type: "string",
+        description: "",
+        optional: true
+      },
+      {
+        name: "joined",
+        type: "boolean",
+        description: "",
+        optional: false
+      }
+    ]
+  },
+  agentbranchchange: {
+    name: "AgentBranchChange",
+    description: "",
+    kind: "interface",
+    references: ["AgentBranchCollectionItemChange"],
+    members: [
+      {
+        name: "type",
+        type: '"page" | "collection" | "designPage" | "siteSettings" | "component" | "layoutTemplate"',
+        description: "",
+        optional: false
+      },
+      {
+        name: "nodeId",
+        type: "string",
+        description: "",
+        optional: false
+      },
+      {
+        name: "name",
+        type: "string",
+        description: "",
+        optional: false
+      },
+      {
+        name: "isRemoved",
+        type: "boolean",
+        description: "",
+        optional: false
+      },
+      {
+        name: "items",
+        type: "AgentBranchCollectionItemChange[]",
+        description: "",
+        optional: true
+      },
+      {
+        name: "settingsTab",
+        type: '"general" | "redirects"',
+        description: "",
+        optional: true
+      }
+    ]
+  },
+  agentbranchcollectionitemchange: {
+    name: "AgentBranchCollectionItemChange",
+    description: "",
+    kind: "interface",
+    references: [],
+    members: [
+      {
+        name: "nodeId",
+        type: "string",
+        description: "",
+        optional: false
+      },
+      {
+        name: "name",
+        type: "string",
+        description: "",
+        optional: false
+      },
+      {
+        name: "isRemoved",
+        type: "boolean",
+        description: "",
+        optional: false
+      }
+    ]
+  },
   agentclarificationanswer: {
     name: "AgentClarificationAnswer",
     description: "",
@@ -4374,6 +4482,20 @@ var types = {
     alias: "PixelNumber | `${PixelNumber} ${PixelNumber} ${PixelNumber} ${PixelNumber}`",
     references: ["PixelNumber"]
   },
+  framerreconnectoptions: {
+    name: "FramerReconnectOptions",
+    description: "",
+    kind: "interface",
+    references: [],
+    members: [
+      {
+        name: "expectedInitialBranchId",
+        type: "string",
+        description: "",
+        optional: true
+      }
+    ]
+  },
   fusednumber: {
     name: "FusedNumber",
     description: "",
@@ -7338,6 +7460,66 @@ var types = {
         description: "@alpha",
         optional: false
       },
+      {
+        name: "getActiveBranchForAgent",
+        type: "() => Promise<AgentBranch>",
+        description: "@alpha",
+        optional: false
+      },
+      {
+        name: "getBranchesForAgent",
+        type: "() => Promise<AgentBranch[]>",
+        description: "@alpha",
+        optional: false
+      },
+      {
+        name: "getBranchChangesForAgent",
+        type: "(branchId: string) => Promise<AgentBranchChange[]>",
+        description: "@alpha",
+        optional: false
+      },
+      {
+        name: "switchBranchForAgent",
+        type: "(branchId: string) => Promise<void>",
+        description: "@alpha",
+        optional: false
+      },
+      {
+        name: "createBranchForAgent",
+        type: "(title?: string) => Promise<AgentBranch>",
+        description: "@alpha",
+        optional: false
+      },
+      {
+        name: "mergeBranchForAgent",
+        type: "(targetBranchId?: string) => Promise<void>",
+        description: "@alpha",
+        optional: false
+      },
+      {
+        name: "joinBranchForAgent",
+        type: "(branchId: string) => Promise<void>",
+        description: "@alpha",
+        optional: false
+      },
+      {
+        name: "leaveBranchForAgent",
+        type: "(branchId: string) => Promise<void>",
+        description: "@alpha",
+        optional: false
+      },
+      {
+        name: "renameBranchForAgent",
+        type: "(branchId: string, title: string) => Promise<void>",
+        description: "@alpha",
+        optional: false
+      },
+      {
+        name: "deleteBranchForAgent",
+        type: "(branchId: string) => Promise<void>",
+        description: "@alpha",
+        optional: false
+      },
       {
         name: "readProjectForAgent",
         type: "(queries: Record<string, unknown>[], options?: {\n        pagePath?: string;\n    }) => Promise<{\n        results: unknown[];\n    }>",
@@ -7941,9 +8123,9 @@ var types = {
         optional: false
       },
       {
-        name: "userAgentModel",
+        name: "framerAgentModel",
         type: "string",
-        description: "Inner Framer Agent model override. Defaults to `model` when omitted. Supports the same `model=effort` syntax.",
+        description: "Inner Framer Agent model override. Defaults to `model` when omitted.\n\nSupports the same `model=effort` syntax. Omitting effort is equivalent to `none`.",
         optional: true
       },
       {
@@ -7996,6 +8178,18 @@ var types = {
         description: "JSONL string with one training row per inner-agent step, present when `captureTrainingData` was set.",
         optional: true
       },
+      {
+        name: "traceFilename",
+        type: "string",
+        description: "Replay trace filename, present when the inner agent produced at least one model step.",
+        optional: true
+      },
+      {
+        name: "traceJson",
+        type: "string",
+        description: "Replay trace JSON with system, tools, and final ModelMessage conversation.",
+        optional: true
+      },
       {
         name: "fixtureFilename",
         type: "string",
@@ -13933,6 +14127,20 @@ var methodsByCategory = {
       description: 'Applies commands to the canvas to create, update, remove, move, or duplicate nodes.\n\nThe command syntax is documented in the string returned by {@link getSystemPrompt}.\nEach call is scoped to a single page.\n\n@param dsl - A string of commands separated by `;`. See {@link getSystemPrompt} for syntax.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.',
       references: []
     },
+    {
+      name: "createBranch",
+      category: "FramerAgentAPI",
+      signature: "createBranch(title?: string): Promise<AgentBranch>",
+      description: "Creates a branch and switches to it.\n\n@param title - Optional branch title. The new branch is created from the active branch.\n@returns The created branch.",
+      references: ["AgentBranch"]
+    },
+    {
+      name: "deleteBranch",
+      category: "FramerAgentAPI",
+      signature: "deleteBranch(branchId: string): Promise<void>",
+      description: "Deletes a branch.\n\n@param branchId - Branch id to delete.",
+      references: []
+    },
     {
       name: "flattenComponentInstance",
       category: "FramerAgentAPI",
@@ -13940,6 +14148,13 @@ var methodsByCategory = {
       description: 'Flattens a local component instance into raw editable layers.\n\n@param input - `{ id }`: the id of the component instance to flatten.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns The flatten result \u2014 `success` with a `replacementId`, or `blocked` with a reason.',
       references: []
     },
+    {
+      name: "getActiveBranch",
+      category: "FramerAgentAPI",
+      signature: "getActiveBranch(): Promise<AgentBranch>",
+      description: "Returns the active project branch.\n\n@returns Branch metadata for the active branch.",
+      references: ["AgentBranch"]
+    },
     {
       name: "getAncestors",
       category: "FramerAgentAPI",
@@ -13947,11 +14162,25 @@ var methodsByCategory = {
       description: 'Get every ancestor of a node, from the direct parent up to the page root.\n\n@param input - `{ id }`: the id of the node to start from.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns The ancestors ordered from closest parent to the page root.',
       references: []
     },
+    {
+      name: "getBranchChanges",
+      category: "FramerAgentAPI",
+      signature: "getBranchChanges(branchId: string): Promise<AgentBranchChange[]>",
+      description: "Returns a summarized changelog for a branch.\n\n@param branchId - Branch id.",
+      references: ["AgentBranchChange"]
+    },
+    {
+      name: "getBranches",
+      category: "FramerAgentAPI",
+      signature: "getBranches(): Promise<AgentBranch[]>",
+      description: "Returns the project branches.\n\n@returns Branch metadata for each available branch.",
+      references: ["AgentBranch"]
+    },
     {
       name: "getContext",
       category: "FramerAgentAPI",
-      signature: "getContext(options?: { pagePath?: string; }): Promise<string>",
-      description: 'Returns the dynamic project context as a string.\n\nThe context includes project-specific data:\n- **Available fonts** \u2014 font families loaded in the project.\n- **Components** \u2014 component names and their controls.\n- **Design tokens** \u2014 color tokens defined in the project.\n- **Style presets** \u2014 text style presets defined in the project.\n- **Icon sets** \u2014 available icon sets and their definitions.\n\nThis data changes per project and page. Pair with the static prompt\nfrom {@link getSystemPrompt} for complete agent context.\n\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns A string containing the project context.',
+      signature: "getContext(): Promise<string>",
+      description: "Returns the dynamic project context as a string.\n\nThe context includes project-specific data:\n- **Available fonts** \u2014 font families loaded in the project.\n- **Components** \u2014 component names and their controls.\n- **Design tokens** \u2014 color tokens defined in the project.\n- **Style presets** \u2014 text style presets defined in the project.\n- **Icon sets** \u2014 available icon sets and their definitions.\n\nThis data changes per project. Pair with the static prompt\nfrom {@link getSystemPrompt} for complete agent context.\n\n@returns A string containing the project context.",
       references: []
     },
     {
@@ -14003,6 +14232,20 @@ var methodsByCategory = {
       description: "Returns the static agent system prompt as a string.\n\nThe prompt includes:\n- **Command reference** \u2014 syntax for adding, updating, removing, moving, and duplicating nodes.\n- **Design rules** \u2014 spacing, layout, typography, and responsive design guidance.\n- **Examples** \u2014 common UI patterns expressed as commands.\n- **`readProject` query reference** \u2014 available query types and their parameters.\n\nThis is the sole documentation for the command syntax used by {@link applyChanges}\nand the query types used by {@link readProject}.\n\nThe prompt is static and does not depend on any specific project.\nCall {@link getContext} to get the project-specific context.\n\n@returns A string containing the agent system prompt.",
       references: []
     },
+    {
+      name: "joinBranch",
+      category: "FramerAgentAPI",
+      signature: "joinBranch(branchId: string): Promise<void>",
+      description: "Joins a branch as a contributor so the current user can edit it when permissions allow.\n\n@param branchId - Branch id to join.",
+      references: []
+    },
+    {
+      name: "leaveBranch",
+      category: "FramerAgentAPI",
+      signature: "leaveBranch(branchId: string): Promise<void>",
+      description: "Leaves a branch as a contributor.\n\n@param branchId - Branch id to leave.",
+      references: []
+    },
     {
       name: "makeExternalComponentLocal",
       category: "FramerAgentAPI",
@@ -14010,6 +14253,13 @@ var methodsByCategory = {
       description: 'Converts an external component into a local project component.\n\n@param input - `{ id, replaceAll? }`: the id of the external instance, and whether to replace all instances.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns `success` (with the local component name), `needs_confirmation` (retry with `replaceAll`), or `blocked` with a reason.',
       references: []
     },
+    {
+      name: "mergeBranch",
+      category: "FramerAgentAPI",
+      signature: "mergeBranch(targetBranchId?: string): Promise<void>",
+      description: 'Merges the active branch into its base or a target branch and switches to the target.\n\n@param targetBranchId - Optional target branch id. Use `"main"` for the main branch.',
+      references: []
+    },
     {
       name: "paginate",
       category: "FramerAgentAPI",
@@ -14034,29 +14284,29 @@ var methodsByCategory = {
     {
       name: "readComponentControls",
       category: "FramerAgentAPI",
-      signature: "readComponentControls(input: { componentIds: readonly string[]; }, options?: { pagePath?: string; }): Promise<unknown>",
-      description: 'Reads control definitions for project components.\n\n@param input - `{ componentIds }`: component ids from project context or previous reads.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns The matching component control definitions.',
+      signature: "readComponentControls(input: { componentIds: readonly string[]; }): Promise<unknown>",
+      description: "Reads control definitions for project components.\n\n@param input - `{ componentIds }`: component ids from project context or previous reads.\n@returns The matching component control definitions.",
       references: []
     },
     {
       name: "readIcons",
       category: "FramerAgentAPI",
-      signature: "readIcons(input: { iconSetName: string; }, options?: { pagePath?: string; }): Promise<string[]>",
-      description: 'Reads exact icon names for an icon set.\n\n@param input - `{ iconSetName }`: icon set name from project context or previous reads.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns The available icon names in that set.',
+      signature: "readIcons(input: { iconSetName: string; }): Promise<string[]>",
+      description: "Reads exact icon names for an icon set.\n\n@param input - `{ iconSetName }`: icon set name from project context or previous reads.\n@returns The available icon names in that set.",
       references: []
     },
     {
       name: "readIconSetControls",
       category: "FramerAgentAPI",
-      signature: "readIconSetControls(input: { iconSetNames: readonly string[]; }, options?: { pagePath?: string; }): Promise<unknown>",
-      description: 'Reads icon-set control definitions.\n\n@param input - `{ iconSetNames }`: icon set names from project context or previous reads.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns The matching icon-set control definitions.',
+      signature: "readIconSetControls(input: { iconSetNames: readonly string[]; }): Promise<unknown>",
+      description: "Reads icon-set control definitions.\n\n@param input - `{ iconSetNames }`: icon set names from project context or previous reads.\n@returns The matching icon-set control definitions.",
       references: []
     },
     {
       name: "readLayoutTemplateControls",
       category: "FramerAgentAPI",
-      signature: "readLayoutTemplateControls(input: { layoutTemplateIds: readonly string[]; }, options?: { pagePath?: string; }): Promise<unknown>",
-      description: 'Reads layout-template control definitions.\n\n@param input - `{ layoutTemplateIds }`: layout template ids from project context or previous reads.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns The matching layout-template control definitions.',
+      signature: "readLayoutTemplateControls(input: { layoutTemplateIds: readonly string[]; }): Promise<unknown>",
+      description: "Reads layout-template control definitions.\n\n@param input - `{ layoutTemplateIds }`: layout template ids from project context or previous reads.\n@returns The matching layout-template control definitions.",
       references: []
     },
     {
@@ -14069,15 +14319,22 @@ var methodsByCategory = {
     {
       name: "readShaderControls",
       category: "FramerAgentAPI",
-      signature: "readShaderControls(input: { shaderNames: readonly string[]; }, options?: { pagePath?: string; }): Promise<unknown>",
-      description: 'Reads shader control definitions.\n\n@param input - `{ shaderNames }`: shader names from project context or previous reads.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns The matching shader control definitions.',
+      signature: "readShaderControls(input: { shaderNames: readonly string[]; }): Promise<unknown>",
+      description: "Reads shader control definitions.\n\n@param input - `{ shaderNames }`: shader names from project context or previous reads.\n@returns The matching shader control definitions.",
+      references: []
+    },
+    {
+      name: "renameBranch",
+      category: "FramerAgentAPI",
+      signature: "renameBranch(branchId: string, title: string): Promise<void>",
+      description: "Renames a branch.\n\n@param branchId - Branch id to rename.\n@param title - New branch title.",
       references: []
     },
     {
       name: "reviewChanges",
       category: "FramerAgentAPI",
-      signature: "reviewChanges(options?: { pagePath?: string; }): Promise<unknown>",
-      description: "Reviews changes made by prior {@link applyChanges} calls in this session.\n\nConsumes accumulated diagnostics from the session's agent context.\n\n@param options.pagePath - Target page path (e.g. `\"/about\"`). Defaults to the active page.\n@returns The session's accumulated changes, errors, warnings, and deferred trait reports.",
+      signature: "reviewChanges(): Promise<unknown>",
+      description: "Reviews changes made by prior {@link applyChanges} calls in this session.\n\nConsumes accumulated diagnostics from the session's agent context.\n\n@returns The session's accumulated changes, errors, warnings, and deferred trait reports.",
       references: []
     },
     {
@@ -14093,6 +14350,13 @@ var methodsByCategory = {
       signature: "serializeNodes(input: { ids: readonly string[]; depth?: number; attributeFilter?: readonly string[]; ancestorPath?: boolean; }, options?: { pagePath?: string; }): Promise<unknown>",
       description: 'Serialize multiple nodes on the page. Ids that don\'t resolve to a node are skipped.\n\n@param input - `{ ids }` plus optional serialization options:\n  - `depth` \u2014 limit how many descendant levels to include.\n  - `attributeFilter` \u2014 only return the listed attributes per node.\n  - `ancestorPath` \u2014 also return the path of ancestors up to the page root.\n@param options.pagePath - Target page path (e.g. `"/about"`). Defaults to the active page.\n@returns The serialized nodes that were found, in input order.',
       references: []
+    },
+    {
+      name: "switchBranch",
+      category: "FramerAgentAPI",
+      signature: "switchBranch(branchId: string): Promise<void>",
+      description: 'Switches the active project branch.\n\n@param branchId - Branch id. Use `"main"` for the main branch.',
+      references: []
     }
   ],
   framerapierror: [
@@ -16197,7 +16461,7 @@ function renderDocs(queries) {
         const suggestion = findClosestMatch(query, methodNames);
         const hint = suggestion ? ` Did you mean '${suggestion}'?` : "";
         errors.push(
-          `Method '${query}' not found.${hint} Use 'framer docs' to list all.`
+          `Method '${query}' not found.${hint} Use 'npx @framer/agent@latest docs' to list all.`
         );
         return { lines, errors };
       }
@@ -16246,7 +16510,7 @@ ${typeDef}`);
           const suggestion = findClosestMatch(query, bareNames);
           const hint = suggestion ? ` Did you mean '${suggestion}'?` : "";
           errors.push(
-            `'${query}' not found.${hint} Use 'framer docs' to list all.`
+            `'${query}' not found.${hint} Use 'npx @framer/agent@latest docs' to list all.`
           );
           return { lines, errors };
         }
@@ -16639,7 +16903,7 @@ function installSkills(options = { type: "base" }) {
 __name(installSkills, "installSkills");
 
 // src/cli.ts
-var PROGRAM_NAME = "framer-dalton";
+var PROGRAM_NAME = "@framer/agent";
 var program = new Command();
 program.name(PROGRAM_NAME).version(VERSION).description("Framer Server API CLI").option("--debug", "Enable debug logging").hook("preAction", (thisCommand) => {
   const opts = thisCommand.opts();
@@ -16814,6 +17078,10 @@ async function execAndPrint(sessionId, code) {
     for (const line of result.output) {
       print(line);
     }
+    if (result.branchChange) {
+      const { title, id, url } = result.branchChange.activeBranch;
+      print(`[FRAMER_BRANCH_CHANGE] title="${title}" id="${id}" url="${url}"`);
+    }
     if (result.error) {
       printError(
         `Error: ${formatErrorForUser(errorWithRef(result.error, result.errorRef), { fromExecResult: true })}`

package/dist/start-relay-server.js

@@ -1,6 +1,6 @@
 import fs4 from 'fs';
 import os5 from 'os';
-import path from 'path';
+import path5 from 'path';
 import { execFileSync } from 'child_process';
 import 'net';
 import { fileURLToPath } from 'url';
@@ -14,7 +14,7 @@ import { z } from 'zod';
 import { createRequire } from 'module';
 import * as vm from 'vm';
 
-/* @framer/ai relay server v0.0.28 */
+/* @framer/ai relay server v0.0.30 */
 var __defProp = Object.defineProperty;
 var __knownSymbol = (name2, symbol) => (symbol = Symbol[name2]) ? symbol : /* @__PURE__ */ Symbol.for("Symbol." + name2);
 var __typeError = (msg) => {
@@ -60,7 +60,7 @@ var __callDispose = (stack, error, hasError) => {
 };
 
 // package.json
-var name = "framer-dalton";
+var name = "@framer/agent";
 
 // src/check-node-version.ts
 var MINIMUM_NODE_VERSION = 22;
@@ -79,16 +79,16 @@ var maxLogFileBytes = DEFAULT_MAX_LOG_FILE_BYTES;
 var retainedLogFileBytes = DEFAULT_RETAINED_LOG_FILE_BYTES;
 function getLogPath() {
   if (process.env.XDG_STATE_HOME) {
-    return path.join(process.env.XDG_STATE_HOME, "framer", "relay.log");
+    return path5.join(process.env.XDG_STATE_HOME, "framer", "relay.log");
   }
   if (process.platform === "win32") {
-    return path.join(
+    return path5.join(
       process.env.APPDATA || os5.homedir(),
       "framer",
       "relay.log"
     );
   }
-  return path.join(os5.homedir(), ".local", "state", "framer", "relay.log");
+  return path5.join(os5.homedir(), ".local", "state", "framer", "relay.log");
 }
 __name(getLogPath, "getLogPath");
 var logPath = getLogPath();
@@ -96,7 +96,7 @@ var initialized = false;
 var logEntriesSinceTrimCheck = LOG_TRIM_CHECK_INTERVAL - 1;
 function ensureLogDir() {
   if (initialized) return;
-  const dir = path.dirname(logPath);
+  const dir = path5.dirname(logPath);
   fs4.mkdirSync(dir, { recursive: true });
   initialized = true;
 }
@@ -143,12 +143,12 @@ function log(message) {
 __name(log, "log");
 function getConfigDir() {
   if (process.env.XDG_CONFIG_HOME) {
-    return path.join(process.env.XDG_CONFIG_HOME, "framer");
+    return path5.join(process.env.XDG_CONFIG_HOME, "framer");
   }
   if (process.platform === "win32") {
-    return path.join(process.env.APPDATA || os5.homedir(), "framer");
+    return path5.join(process.env.APPDATA || os5.homedir(), "framer");
   }
-  return path.join(os5.homedir(), ".config", "framer");
+  return path5.join(os5.homedir(), ".config", "framer");
 }
 __name(getConfigDir, "getConfigDir");
 function ensureConfigDir() {
@@ -159,7 +159,7 @@ __name(ensureConfigDir, "ensureConfigDir");
 
 // src/config/relay-token.ts
 function getRelayTokenPath() {
-  return path.join(getConfigDir(), "relay-token");
+  return path5.join(getConfigDir(), "relay-token");
 }
 __name(getRelayTokenPath, "getRelayTokenPath");
 function generateRelayToken() {
@@ -199,12 +199,12 @@ __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.28" 
+  "0.0.30" 
 );
 
 // src/relay-client.ts
 var __filename$1 = fileURLToPath(import.meta.url);
-path.dirname(__filename$1);
+path5.dirname(__filename$1);
 var RELAY_PORT = Number(process.env.FRAMER_CLI_PORT) || 19988;
 createTRPCClient({
   links: [
@@ -303,30 +303,74 @@ var ScopedFS = class {
   static {
     __name(this, "ScopedFS");
   }
-  allowedDirs;
+  allowedRoots;
   constructor(allowedDirs) {
     const defaultDirs = [process.cwd(), "/tmp", os5.tmpdir()];
     const dirs = allowedDirs ?? defaultDirs;
-    this.allowedDirs = [...new Set(dirs.map((d) => path.resolve(d)))];
+    this.allowedRoots = [
+      ...new Set(dirs.map((dir) => this.canonicalizePath(dir)))
+    ];
   }
-  isPathAllowed(resolved) {
-    return this.allowedDirs.some((dir) => {
-      return resolved === dir || resolved.startsWith(dir + path.sep);
+  isPathAllowed(candidatePath) {
+    return this.allowedRoots.some((allowedRoot) => {
+      return candidatePath === allowedRoot || candidatePath.startsWith(allowedRoot + path5.sep);
     });
   }
   resolvePath(filePath) {
-    const resolved = path.resolve(filePath);
-    if (!this.isPathAllowed(resolved)) {
-      const error = new Error(
-        `EPERM: operation not permitted, access outside allowed directories: ${filePath}`
-      );
-      error.code = "EPERM";
-      error.errno = -1;
-      error.syscall = "access";
-      error.path = filePath;
+    const resolvedPath = path5.resolve(filePath);
+    const canonicalPath = this.canonicalizePath(resolvedPath);
+    if (!this.isPathAllowed(canonicalPath)) {
+      this.throwOutsideAllowedRoots(filePath);
+    }
+    return resolvedPath;
+  }
+  canonicalizePath(inputPath) {
+    const resolvedPath = path5.resolve(inputPath);
+    const missingSegments = [];
+    let ancestorPath = resolvedPath;
+    while (true) {
+      const realPath = this.resolveRealPath(ancestorPath);
+      if (realPath !== null) {
+        return path5.resolve(realPath, ...missingSegments);
+      }
+      if (this.isSymbolicLink(ancestorPath)) {
+        this.throwOutsideAllowedRoots(inputPath);
+      }
+      const parentPath = path5.dirname(ancestorPath);
+      if (parentPath === ancestorPath) {
+        return resolvedPath;
+      }
+      missingSegments.unshift(path5.basename(ancestorPath));
+      ancestorPath = parentPath;
+    }
+  }
+  resolveRealPath(targetPath) {
+    try {
+      return path5.resolve(fs4.realpathSync.native(targetPath));
+    } catch (error) {
+      const errnoError = error;
+      if (errnoError.code === "ENOENT") {
+        return null;
+      }
       throw error;
     }
-    return resolved;
+  }
+  isSymbolicLink(targetPath) {
+    try {
+      return fs4.lstatSync(targetPath).isSymbolicLink();
+    } catch {
+      return false;
+    }
+  }
+  throwOutsideAllowedRoots(filePath) {
+    const error = new Error(
+      `EPERM: operation not permitted, access outside allowed directories: ${filePath}`
+    );
+    error.code = "EPERM";
+    error.errno = -1;
+    error.syscall = "access";
+    error.path = filePath;
+    throw error;
   }
   // Sync methods
   readFileSync = /* @__PURE__ */ __name((filePath, options) => {
@@ -558,6 +602,7 @@ __name(sandboxedImport, "sandboxedImport");
 async function execute(session, code, options = {}) {
   const { cwd } = options;
   const output = [];
+  const previousBranch = await readActiveBranch(session);
   const customConsole = {
     log: /* @__PURE__ */ __name((...args) => {
       output.push(args.map((arg) => formatValue(arg)).join(" "));
@@ -625,7 +670,8 @@ async function execute(session, code, options = {}) {
     if (result !== void 0) {
       output.push(formatValue(result));
     }
-    return { output };
+    const branchChange = await getBranchChange(session, previousBranch);
+    return { output, branchChange };
   } catch (err) {
     const errorMessage = err instanceof Error ? err.message : String(err);
     const retryable = isRetryableError(err);
@@ -633,17 +679,33 @@ async function execute(session, code, options = {}) {
       session.connection.markDisconnected();
     }
     const errorRef = getErrorRef(err);
-    return {
-      output,
-      error: errorMessage,
-      ...errorRef ? { errorRef } : {},
-      ...retryable ? { retryable: true } : {}
-    };
+    const branchChange = await getBranchChange(session, previousBranch);
+    return { output, error: errorMessage, errorRef, retryable, branchChange };
   } finally {
     if (timeoutId) clearTimeout(timeoutId);
   }
 }
 __name(execute, "execute");
+async function readActiveBranch(session) {
+  try {
+    const branch = await session.connection.framer.agent.getActiveBranch();
+    session.connection.setActiveBranchId(branch.id);
+    return branch;
+  } catch {
+    return void 0;
+  }
+}
+__name(readActiveBranch, "readActiveBranch");
+async function getBranchChange(session, previousBranch) {
+  if (!previousBranch) return void 0;
+  const activeBranch = await readActiveBranch(session);
+  if (!activeBranch || previousBranch.id === activeBranch.id) return void 0;
+  return {
+    previousBranch,
+    activeBranch
+  };
+}
+__name(getBranchChange, "getBranchChange");
 function isReconnectable(err) {
   return isRetryableError(err) || isConnectionError(err instanceof Error ? err.message : String(err));
 }
@@ -699,15 +761,19 @@ async function executeWithReconnect(session, code, options, execId) {
     log(
       `reconnect.failed exec=${execId} session=${session.id} req=${session.connection.framer.requestId} error="${err instanceof Error ? err.message : String(err)}"`
     );
-    return connectionFailureResult(
+    const failureResult = connectionFailureResult(
       "Connection lost and failed to reconnect",
       err
     );
+    failureResult.branchChange = result.branchChange;
+    return failureResult;
   }
   log(
     `reconnect.success exec=${execId} session=${session.id} req=${session.connection.framer.requestId}`
   );
-  return execute(session, code, options);
+  const retryResult = await execute(session, code, options);
+  retryResult.branchChange ??= result.branchChange;
+  return retryResult;
 }
 __name(executeWithReconnect, "executeWithReconnect");
 function formatValue(value) {
@@ -776,7 +842,7 @@ var SettingsFileSchema = z.object({
   telemetryNoticeShown: z.boolean().optional()
 });
 function getSettingsPath() {
-  return path.join(getConfigDir(), "settings.json");
+  return path5.join(getConfigDir(), "settings.json");
 }
 __name(getSettingsPath, "getSettingsPath");
 var settings;
@@ -1049,6 +1115,7 @@ var Connection = class _Connection {
   sessions = [];
   status = "connected";
   pendingReconnect;
+  activeBranchId;
   static async open(projectId, userId, apiKey, headlessServerUrl) {
     const framer = await connect(projectId, apiKey, {
       clientId: `dalton/${VERSION}`,
@@ -1062,6 +1129,9 @@ var Connection = class _Connection {
   markDisconnected() {
     this.status = "disconnected";
   }
+  setActiveBranchId(branchId) {
+    this.activeBranchId = branchId;
+  }
   getServerSessionId() {
     return this.framer.sessionId ?? MISSING_SERVER_SESSION_ID;
   }
@@ -1105,7 +1175,7 @@ var Connection = class _Connection {
       (session) => session.inflight === 0 && now - session.lastActivityAt >= timeoutMs
     );
   }
-  async reconnect() {
+  async reconnect(expectedInitialBranchId = this.activeBranchId) {
     if (this.status === "connected") {
       return;
     }
@@ -1113,7 +1183,7 @@ var Connection = class _Connection {
       return this.pendingReconnect;
     }
     this.status = "reconnecting";
-    this.pendingReconnect = this.framer.reconnect().then(() => {
+    this.pendingReconnect = this.framer.reconnect({ expectedInitialBranchId }).then(() => {
       this.status = "connected";
       trackConnectionReconnect({
         projectId: this.projectId,

package/docs/skills/framer-project.md

@@ -1,7 +1,7 @@
 ---
 name: {{SKILL_NAME}}
 description: "Project-scoped Framer skill for project {{PROJECT_ID}}. Covers project reads, edits, change review, publishing, image sourcing, component operations, and canvas editing. Very important: never load this skill without having already read the `framer` skill and without having already run `session new`, which will dynamically update this skill."
-allowed-tools: ["Bash(npx framer-dalton:*)", "Bash(npx framer-dalton@latest:*)", "Read({{FRAMER_TEMPORARY_DIR}}/*)", "Write({{FRAMER_TEMPORARY_DIR}}/*)"]
+allowed-tools: ["Bash(npx @framer/agent:*)", "Bash(npx @framer/agent@latest:*)", "Read({{FRAMER_TEMPORARY_DIR}}/*)", "Write({{FRAMER_TEMPORARY_DIR}}/*)"]
 ---
 
 ## Project Scope
@@ -15,11 +15,11 @@ Every connected-project task follows these steps:
 
 ### 1. Look up the API (before EVERY new use of an API method)
 
-**You MUST run `npx framer-dalton docs` before writing any code.** Do not guess method names or signatures.
+**You MUST run `npx @framer/agent@latest docs` before writing any code.** Do not guess method names or signatures.
 
 ```bash
-npx framer-dalton docs Collection           # What methods exist?
-npx framer-dalton docs Collection.getItems  # What are the parameters and return type?
+npx @framer/agent@latest docs Collection           # What methods exist?
+npx @framer/agent@latest docs Collection.getItems  # What are the parameters and return type?
 ```
 
 ### 2. Execute code
@@ -27,7 +27,7 @@ npx framer-dalton docs Collection.getItems  # What are the parameters and return
 Only after checking docs, use your write tool to write your code to a unique file under `{{FRAMER_TEMPORARY_DIR}}/`, then execute it with `-f`. Do not create code files with shell heredocs or `cat`. Name each file `<sessionId>-<short-summary>.js` where `<short-summary>` is a brief kebab-case description (e.g., `1-read-collections.js`, `1-add-team-member.js`).
 
 ```bash
-npx framer-dalton exec -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-read-collections.js
+npx @framer/agent@latest exec -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-read-collections.js
 ```
 
 ### 3. Store results in `state`
@@ -36,13 +36,12 @@ Always save results you'll need again. Don't repeat API calls.
 
 ## Method Selection
 
-Choose the highest-priority interface available for the task:
+Prefer the agent-specific methods `framer.agent.*` over regular plugin API methods (`framer.*`).
 
-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
+For `framer.agent.readProject` and `framer.agent.applyChanges` calls, use the `npx @framer/agent@latest read-project` and `npx @framer/agent@latest apply-changes` subcommands when possible. It's still ok to call those methods in exec scripts if you require something more complex than a plain method call.
 
-- 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.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.
+- Do not use `npx @framer/agent@latest read-project` or `framer.agent.readProject` for node tree reads unless you have just checked current docs and confirmed the exact query type. Query shapes such as `{ type: "node-by-id" }` are not valid for the current local API.
 - 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.
@@ -57,6 +56,7 @@ During normal task execution, do not call `framer.agent.getSystemPrompt()` or `f
 
 - Be concise. Don't narrate implementation details like field IDs, escaping, or internal steps. Just do the work and report what was accomplished in user-facing terms.
 - Use `framer.*` for plugin API calls. Top-level methods are not globals.
+- If command output includes `[FRAMER_BRANCH_CHANGE]`, tell the user the active branch changed and include the `url` value.
 - Before making changes that add/update/delete content that the user has not clearly and explicitly requested in this conversation, inform the user of what you plan to do and why, and ask them to confirm.
     - You do not need to ask for confirmation when carrying out a specific add/update/delete change that the user has already clearly requested (this counts as explicit consent).
     - You do not need to explain or ask for confirmation for non-destructive calls like reading project state.
@@ -87,7 +87,7 @@ state.collections = await framer.getCollections();
 ```
 
 ```bash
-npx framer-dalton exec -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-get-collections.js
+npx @framer/agent@latest exec -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-get-collections.js
 ```
 
 ```js
@@ -97,7 +97,7 @@ console.log(state.teamItems.length);
 ```
 
 ```bash
-npx framer-dalton exec -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-get-team-items.js
+npx @framer/agent@latest exec -s 1 -f {{FRAMER_TEMPORARY_DIR}}/1-get-team-items.js
 ```
 
 Store anything you'll reference again.
@@ -141,7 +141,7 @@ Prompting may take a while to complete, so set the command timeout to 10 minutes
 Prefer using your write tool to write code to a unique file under `{{FRAMER_TEMPORARY_DIR}}/` and executing it with `-f`. Do not create code files with shell heredocs or `cat`:
 
 ```bash
-npx framer-dalton exec -s <sessionId> -f {{FRAMER_TEMPORARY_DIR}}/<sessionId>-<short-summary>.js
+npx @framer/agent@latest exec -s <sessionId> -f {{FRAMER_TEMPORARY_DIR}}/<sessionId>-<short-summary>.js
 ```
 
 For short snippets, `exec` also accepts `-e <code>` or code piped on stdin.
@@ -154,24 +154,24 @@ In Windows PowerShell, if an argument contains nested quotes, use a single-quote
 $value = @'
 [{"key":"value","filter":["text","$rect"]}]
 '@
-npx framer-dalton <command> --option $value
+npx @framer/agent@latest <command> --option $value
 ```
 
 ## API Documentation
 
 ```bash
-npx framer-dalton docs                            # List all available methods
-npx framer-dalton docs framer.getCollections      # Show top level method
-npx framer-dalton docs Collection                 # Show class with all method signatures
-npx framer-dalton docs Collection.addItems        # Show method + recursively expand all referenced types
-npx framer-dalton docs ScreenshotOptions          # Show type + recursively expand all referenced types
+npx @framer/agent@latest docs                            # List all available methods
+npx @framer/agent@latest docs framer.getCollections      # Show top level method
+npx @framer/agent@latest docs Collection                 # Show class with all method signatures
+npx @framer/agent@latest docs Collection.addItems        # Show method + recursively expand all referenced types
+npx @framer/agent@latest docs ScreenshotOptions          # Show type + recursively expand all referenced types
 ```
 
 `docs` with no arguments lists available methods. Looking up a class shows its full definition without expanding referenced types. Looking up a specific method or type automatically expands all referenced types recursively.
 
 ## API Examples
 
-**STOP: These are patterns only. Before using any method below, run `npx framer-dalton docs <ClassName>` to verify the current signature.**
+**STOP: These are patterns only. Before using any method below, run `npx @framer/agent@latest docs <ClassName>` to verify the current signature.**
 
 ### Working with Collections (CMS)
 

package/docs/skills/framer.md

@@ -2,13 +2,13 @@
 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'.
-  **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}}/*)"]
+  **Mandatory precondition**: run `npx @framer/agent@latest setup` and let it complete **BEFORE** loading this skill.
+allowed-tools: ["Bash(npx @framer/agent:*)", "Bash(npx @framer/agent@latest:*)", "Read({{FRAMER_TEMPORARY_DIR}}/*)", "Write({{FRAMER_TEMPORARY_DIR}}/*)"]
 ---
 
 If you didn't run this command before loading the skill, run it now:
 ```bash
-npx framer-dalton@latest setup
+npx @framer/agent@latest setup
 ```
 
 ## Capabilities
@@ -29,14 +29,14 @@ What you can do with the Framer CLI:
 
 ### Permissions
 
-The Framer CLI requires network access (to download packages and connect to Framer servers) and file-system access outside the project directory (to install skills into `~/.agents/skills/` and `~/.claude/skills/`). In sandboxed environments, you must execute `npx framer-dalton` commands with elevated permissions from the get-go. Do not try to execute them with the default sandboxed permissions; they will hang or fail.
+The Framer CLI requires network access (to download packages and connect to Framer servers) and file-system access outside the project directory (to install skills into `~/.agents/skills/` and `~/.claude/skills/`). In sandboxed environments, you must execute `npx @framer/agent@latest` commands with elevated permissions from the get-go. Do not try to execute them with the default sandboxed permissions; they will hang or fail.
 
 ### Session Management
 
 If the user refers to a project by name or description rather than giving a URL, first inspect the recent projects:
 
 ```bash
-npx framer-dalton project list
+npx @framer/agent@latest project list
 ```
 
 Use that list to infer the likely project from the names and recency. If the right project is already known, use its project ID with `session new`. If there are multiple possible matches, clarify with the user. Only ask the user for a Project URL if there is no clear match. Avoid talking about the technical contents of returned data like IDs.
@@ -46,7 +46,7 @@ Each session maintains a persistent connection to a Framer project. Use sessions
 Create a session against an existing project:
 
 ```bash
-npx framer-dalton session new "<url or id>"
+npx @framer/agent@latest session new "<url or id>"
 ```
 
 This prints the session ID. You must always use that session ID with `-s <id>` for all subsequent commands. Using the same session preserves your `state` between calls.
@@ -54,15 +54,15 @@ This prints the session ID. You must always use that session ID with `-s <id>` f
 To create a brand new empty project and connect to it:
 
 ```bash
-npx framer-dalton project new
-npx framer-dalton session new "<returned project id>"
+npx @framer/agent@latest project new
+npx @framer/agent@latest session new "<returned project id>"
 ```
 
 To remix (duplicate) an existing project and connect to the copy:
 
 ```bash
-npx framer-dalton project remix "<url, project id, or remix link>"
-npx framer-dalton session new "<returned project id>"
+npx @framer/agent@latest project remix "<url, project id, or remix link>"
+npx @framer/agent@latest session new "<returned project id>"
 ```
 
 Note that during beta, you cannot connect to non-beta projects. If creating a session errors with a message about this, you need to move your project to beta.
@@ -70,7 +70,7 @@ Note that during beta, you cannot connect to non-beta projects. If creating a se
 List active sessions:
 
 ```bash
-npx framer-dalton session list
+npx @framer/agent@latest session list
 ```
 
 ## Project-scoped skill

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "framer-dalton",
-  "version": "0.0.28",
+  "version": "0.0.30",
   "type": "module",
   "bin": "./dist/cli.js",
   "main": "./dist/cli.js",
@@ -24,7 +24,7 @@
     "@trpc/client": "^11.17.0",
     "@trpc/server": "^11.17.0",
     "commander": "^12.1.0",
-    "framer-api": "0.1.14",
+    "framer-api": "^0.1.16",
     "zod": "^4.4.3"
   },
   "devDependencies": {