@agent-native/core 0.114.6 → 0.114.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.114.6",
+  "version": "0.114.8",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -381,7 +381,7 @@
     "yjs": "^13.6.31",
     "zod": "^4.3.6",
     "@agent-native/recap-cli": "0.4.5",
-    "@agent-native/toolkit": "^0.8.1"
+    "@agent-native/toolkit": "^0.8.2"
   },
   "devDependencies": {
     "@ai-sdk/anthropic": "^3.0.71",

package/src/cli/mcp-config-writers.ts

@@ -123,12 +123,13 @@ export function buildLocalMcpEntryForClient(
   client: ClientId,
   args: string[],
   env?: Record<string, string>,
+  command = "agent-native",
 ): Record<string, unknown> {
   const cleanEnv = env ? Object.fromEntries(Object.entries(env)) : {};
   if (client === "opencode") {
     return {
       type: "local",
-      command: ["agent-native", ...args],
+      command: [command, ...args],
       enabled: true,
       ...(Object.keys(cleanEnv).length ? { environment: cleanEnv } : {}),
     };
@@ -136,13 +137,13 @@ export function buildLocalMcpEntryForClient(
   if (client === "github-copilot") {
     return {
       type: "stdio",
-      command: "agent-native",
+      command,
       args,
       ...(Object.keys(cleanEnv).length ? { env: cleanEnv } : {}),
     };
   }
   return {
-    command: "agent-native",
+    command,
     args,
     ...(Object.keys(cleanEnv).length ? { env: cleanEnv } : {}),
   };
@@ -543,9 +544,10 @@ export function buildCodexLocalBlock(
   name: string,
   args: string[],
   env?: Record<string, string>,
+  command = "agent-native",
 ): string {
   const lines: string[] = [codexMcpHeader(name)];
-  lines.push(`command = "agent-native"`);
+  lines.push(`command = ${tomlQuote(command)}`);
   lines.push(`args = [${args.map(tomlQuote).join(", ")}]`);
   const cleanEnv = env ? Object.fromEntries(Object.entries(env)) : {};
   if (Object.keys(cleanEnv).length) {

package/src/cli/mcp.ts

@@ -15,6 +15,7 @@
 
 import crypto from "node:crypto";
 import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
 
 import { MCP_PUBLIC_ROUTE_PREFIX } from "../mcp/route-paths.js";
@@ -42,6 +43,7 @@ import {
 } from "./mcp-config-writers.js";
 
 const SERVER_NAME_PREFIX = "agent-native";
+const SCREEN_MEMORY_SERVER_NAME = "clips-screen-memory";
 
 interface ParsedArgs {
   _: string[];
@@ -83,6 +85,58 @@ function logOut(msg: string): void {
   process.stdout.write(`${msg}\n`);
 }
 
+export interface ScreenMemoryStoreResolutionOptions {
+  explicitDir?: string;
+  env?: NodeJS.ProcessEnv;
+  platform?: NodeJS.Platform;
+  homeDir?: string;
+}
+
+/**
+ * Resolve the active Clips store without asking people to find an app-data
+ * path. Environment overrides remain the unambiguous escape hatch; otherwise
+ * the most recently touched installed Clips/Clips Alpha store wins.
+ */
+export function resolveScreenMemoryStoreDir(
+  options: ScreenMemoryStoreResolutionOptions = {},
+): string | undefined {
+  if (options.explicitDir) return path.resolve(options.explicitDir);
+  const env = options.env ?? process.env;
+  const override =
+    env.CLIPS_SCREEN_MEMORY_DIR || env.AGENT_NATIVE_SCREEN_MEMORY_DIR;
+  if (override) return path.resolve(override);
+
+  const platform = options.platform ?? process.platform;
+  const home = options.homeDir ?? os.homedir();
+  const appDataRoot =
+    platform === "darwin"
+      ? path.join(home, "Library", "Application Support")
+      : platform === "win32"
+        ? env.APPDATA || path.join(home, "AppData", "Roaming")
+        : env.XDG_DATA_HOME || path.join(home, ".local", "share");
+  return ["com.clips.tray", "com.clips.tray.alpha"]
+    .map((bundleId) => path.join(appDataRoot, bundleId, "screen-memory"))
+    .filter((candidate) => fs.existsSync(candidate))
+    .map((candidate) => ({
+      candidate,
+      modifiedAt: Math.max(
+        fs.statSync(candidate).mtimeMs,
+        ...["feature-config.json", "chapters.json"]
+          .map((name) =>
+            name === "feature-config.json"
+              ? path.join(path.dirname(candidate), name)
+              : path.join(candidate, name),
+          )
+          .filter((file) => fs.existsSync(file))
+          .map((file) => fs.statSync(file).mtimeMs),
+      ),
+    }))
+    .sort(
+      (a, b) =>
+        b.modifiedAt - a.modifiedAt || a.candidate.localeCompare(b.candidate),
+    )[0]?.candidate;
+}
+
 // ---------------------------------------------------------------------------
 // .env token provisioning (local dev) — hand-rolled idempotent upsert
 // ---------------------------------------------------------------------------
@@ -343,6 +397,38 @@ function installForClient(
   return file;
 }
 
+export function installScreenMemoryForClient(
+  client: ClientId,
+  storeDir: string,
+  cwd: string,
+  scope: string | undefined,
+): string {
+  const file = configPathFor(client, cwd, scope);
+  const args = [
+    "-y",
+    "@agent-native/core@latest",
+    "mcp",
+    "screen-memory",
+    "--dir",
+    path.resolve(storeDir),
+  ];
+  if (client === "codex") {
+    writeCodexBlock(
+      file,
+      SCREEN_MEMORY_SERVER_NAME,
+      buildCodexLocalBlock(SCREEN_MEMORY_SERVER_NAME, args, {}, "npx"),
+    );
+  } else {
+    writeJsonMcpEntryForClient(
+      client,
+      file,
+      SCREEN_MEMORY_SERVER_NAME,
+      buildLocalMcpEntryForClient(client, args, {}, "npx"),
+    );
+  }
+  return file;
+}
+
 function uninstallForClient(
   client: ClientId,
   appId: string,
@@ -454,6 +540,36 @@ async function cmdInstall(p: ParsedArgs): Promise<void> {
   logOut(`  Restart ${client} to pick up the new MCP server.`);
 }
 
+function cmdInstallScreenMemory(p: ParsedArgs): void {
+  const client = normalizeClientId(p.client);
+  if (!client) {
+    logErr(
+      `Usage: npx @agent-native/core@latest mcp install-screen-memory --client ${SELECTABLE_CLIENTS.join("|")} [--dir <path>] [--scope user|project]`,
+    );
+    process.exit(1);
+  }
+  const screenMemoryDir = resolveScreenMemoryStoreDir({
+    explicitDir: p.screenMemoryDir,
+  });
+  if (!screenMemoryDir) {
+    logErr(
+      "No local Clips Screen Memory store was found. Turn Rewind on in Clips, or pass --dir <path>.",
+    );
+    process.exit(1);
+  }
+  const file = installScreenMemoryForClient(
+    client,
+    screenMemoryDir,
+    process.cwd(),
+    p.scope,
+  );
+  logOut(`Installed \"${SCREEN_MEMORY_SERVER_NAME}\" for ${client} → ${file}`);
+  logOut("  Store: current local Clips Rewind memory");
+  logOut(
+    `  Restart ${client} to pick up the repaired Screen Memory MCP server.`,
+  );
+}
+
 function cmdUninstall(p: ParsedArgs): void {
   const client = normalizeClientId(p.client);
   if (!client) {
@@ -544,6 +660,11 @@ Usage:
       Run the local Clips Screen Memory stdio server.
       Defaults to the Clips app-data screen-memory folder.
 
+  npx @agent-native/core@latest mcp install-screen-memory --client <c> [--dir <path>] [--scope user|project]
+      Install or repair the dedicated local Screen Memory MCP. The active Clips
+      or Clips Alpha store is discovered automatically; --dir is an override.
+      Clients: claude-code, codex, cowork, cursor, opencode, github-copilot
+
   npx @agent-native/core@latest mcp install --client <c> [--app <id>] [--scope user|project]
       Provision a token and write the client's MCP config (idempotent).
       Clients: claude-code, codex, cowork, cursor, opencode, github-copilot
@@ -571,6 +692,9 @@ export async function runMcp(args: string[]): Promise<void> {
     case "install":
       await cmdInstall(p);
       return;
+    case "install-screen-memory":
+      cmdInstallScreenMemory(p);
+      return;
     case "uninstall":
       cmdUninstall(p);
       return;

package/src/cli/skills-content/help.ts

@@ -2,13 +2,14 @@ export const HELP = `npx @agent-native/core@latest skills
 
 Usage:
   npx @agent-native/core@latest skills list
-  npx @agent-native/core@latest skills status [assets|content|design-exploration|visual-edit|visual-plan|visual-recap|visualize-repo|context-xray|scaffold] [--client codex|claude-code|pi|all] [--scope user|project] [--json]
-  npx @agent-native/core@latest skills update [assets|content|design-exploration|visual-edit|visual-plan|visual-recap|visualize-repo|context-xray|scaffold] [--client codex|claude-code|pi|all] [--scope user|project] [--dry-run] [--json]
-  npx @agent-native/core@latest skills add assets|content|design-exploration|visual-edit|visual-plan|visual-recap|visualize-repo|context-xray [--client codex|claude-code|cowork|cursor|opencode|github-copilot|all] [--scope user|project] [--mode hosted|local-files|self-hosted] [--mcp-url <url>] [--no-connect] [--with-github-action] [--yes] [--dry-run] [--json]
+  npx @agent-native/core@latest skills status [assets|content|rewind|design-exploration|visual-edit|visual-plan|visual-recap|visualize-repo|context-xray|scaffold] [--client codex|claude-code|pi|all] [--scope user|project] [--json]
+  npx @agent-native/core@latest skills update [assets|content|rewind|design-exploration|visual-edit|visual-plan|visual-recap|visualize-repo|context-xray|scaffold] [--client codex|claude-code|pi|all] [--scope user|project] [--dry-run] [--json]
+  npx @agent-native/core@latest skills add assets|content|rewind|design-exploration|visual-edit|visual-plan|visual-recap|visualize-repo|context-xray [--client codex|claude-code|cowork|cursor|opencode|github-copilot|all] [--scope user|project] [--mode hosted|local-files|self-hosted] [--mcp-url <url>] [--no-connect] [--with-github-action] [--yes] [--dry-run] [--json]
   npx @agent-native/core@latest skills add <manifest-or-app-dir|skill-repo> [--skill <name>] [--client ...] [--yes]
 
 Examples:
   npx @agent-native/core@latest skills add assets
+  npx @agent-native/core@latest skills add rewind --client codex --scope user --yes
   npx @agent-native/core@latest skills add content --mode local-files
   npx @agent-native/core@latest skills add design-exploration
   npx @agent-native/core@latest skills add visual-edit

package/src/cli/skills-content/index.ts

@@ -8,6 +8,7 @@
 export * from "./help.js";
 export * from "./assets-skill.js";
 export * from "./content-skill.js";
+export * from "./rewind-skill.js";
 export * from "./design-exploration-skill.js";
 export * from "./design-visual-edit-skill.js";
 export * from "./plan-setup-auth.js";

package/src/cli/skills-content/rewind-skill.ts

@@ -0,0 +1,52 @@
+export const REWIND_SKILL_MD = `---
+name: rewind
+description: >-
+  Retrieve recent local Clips Rewind context when the user says "Look at
+  Rewind," asks what just happened, or refers to something they recently said
+  or saw.
+metadata:
+  visibility: exported
+---
+
+# Rewind
+
+Use Clips Rewind as local screen memory. Start broad enough to find the right
+moment, then read only the smallest relevant range.
+
+## Retrieval Flow
+
+1. Call \`screen_memory_status\` first. If the newest segment is still open,
+   wait for it to finalize rather than substituting an older segment.
+2. Search \`screen_memory_search_chapters\` before requesting raw recent
+   context. Use the user's words, the visible app or project, and the likely
+   time range as clues.
+3. If several chapters plausibly match, show the candidates and ask which one
+   the user means. Do not blend separate workstreams together.
+4. Read the smallest useful range with \`screen_memory_recent_context\`.
+   Restate what you recovered before acting, and flag transcription or coverage
+   uncertainty.
+5. Use \`screen_memory_frame_at\` for one exact visual moment or
+   \`screen_memory_contact_sheet\` to scan a bounded range. Prefer local frames
+   before escalating to cloud processing.
+6. Request the smallest relevant timestamp range through Clips' bounded private
+   Clip handoff only when local text and frames are insufficient, such as
+   garbled speech, important motion, dense analysis, or a Clip the user wants
+   to keep and query later.
+
+## Boundaries
+
+- Rewind recordings, screenshots, audio, transcripts, OCR, and indexes remain
+  local unless the user explicitly asks for a bounded Clip handoff.
+- Do not reveal archive filesystem paths, crawl Clips' app-data folders, or
+  bypass the Screen Memory MCP broker.
+- Do not upload frames returned by local Screen Memory tools.
+- Treat foreground apps and chapter labels as evidence, not proof of intent.
+- If the Screen Memory MCP is missing, explain that the one-time setup needs to
+  be repaired with:
+
+  \`npx -y @agent-native/core@latest skills add rewind --client <client> --scope user --yes\`
+
+  Replace \`<client>\` with the current compatible host: \`codex\`,
+  \`claude-code\`, \`cursor\`, \`opencode\`, \`github-copilot\`, or \`cowork\`.
+  Ask the user to restart the host if it cannot reload MCP servers in place.
+`;

package/src/cli/skills.ts

@@ -33,6 +33,10 @@ import {
   installLocalContextXray,
 } from "./context-xray-local.js";
 import { CLIENTS, type ClientId } from "./mcp-config-writers.js";
+import {
+  installScreenMemoryForClient,
+  resolveScreenMemoryStoreDir,
+} from "./mcp.js";
 import { PR_VISUAL_RECAP_SETUP, writePrVisualRecapWorkflow } from "./recap.js";
 import { setupAgentSymlinks } from "./setup-agents.js";
 import {
@@ -46,6 +50,7 @@ import {
   EXEMPLAR_REFERENCE_MD,
   HELP,
   LOCAL_FILES_REFERENCE_MD,
+  REWIND_SKILL_MD,
   VISUAL_PLANS_SKILL_MD,
   VISUAL_RECAP_SKILL_MD,
   VISUALIZE_REPO_SKILL_MD,
@@ -161,6 +166,40 @@ export const BUILT_IN_APP_SKILLS = {
     }),
     skillMarkdown: CONTENT_SKILL_MD,
   },
+  rewind: {
+    skillName: "rewind",
+    screenMemoryMcp: true,
+    manifest: normalizeAppSkillManifest({
+      schemaVersion: 1,
+      id: "rewind",
+      displayName: "Rewind",
+      description:
+        "Retrieve recent local Clips screen memory, chapters, transcripts, and exact frames through a privacy-preserving agent workflow.",
+      hosted: {
+        url: "https://clips.agent-native.com",
+        mcpUrl: "https://clips.agent-native.com/mcp",
+      },
+      mcp: { serverName: "clips-screen-memory" },
+      auth: { mode: "none" },
+      surfaces: [
+        {
+          id: "rewind-memory",
+          path: "/",
+          description:
+            "Search and inspect the user's local Clips Rewind memory through a bounded local MCP broker.",
+        },
+      ],
+      skills: [
+        {
+          path: "skills/rewind",
+          visibility: "exported",
+          exportAs: "rewind",
+        },
+      ],
+      hostAdapters: ["plain-skill", "claude-skill", "generic-mcp"],
+    }),
+    skillMarkdown: REWIND_SKILL_MD,
+  },
   design: {
     skillName: "design-exploration",
     extraSkills: {
@@ -356,6 +395,7 @@ export const BUILT_IN_APP_SKILLS = {
      */
     extraFiles?: Record<string, Record<string, string>>;
     localOnly?: boolean;
+    screenMemoryMcp?: boolean;
   }
 >;
 
@@ -379,6 +419,10 @@ const BUILT_IN_APP_SKILL_ALIASES = {
   "local-content": "content",
   "content-local-files": "content",
   "agent-native-content": "content",
+  rewind: "rewind",
+  "screen-memory": "rewind",
+  "clips-rewind": "rewind",
+  "agent-native-rewind": "rewind",
   design: "design",
   "ui-design": "design",
   "ux-design": "design",
@@ -421,6 +465,7 @@ const BUILT_IN_APP_SKILL_DISPLAY_ALIASES = {
     "content-local-files",
     "agent-native-content",
   ],
+  rewind: ["screen-memory", "clips-rewind", "agent-native-rewind"],
   design: [
     "design-exploration",
     "visual-edit",
@@ -811,6 +856,12 @@ function isLocalOnlyBuiltInSkill(
   return Boolean(entry && "localOnly" in entry && entry.localOnly);
 }
 
+function isScreenMemoryMcpBuiltInSkill(
+  entry: (typeof BUILT_IN_APP_SKILLS)[BuiltInAppSkillId] | null | undefined,
+): boolean {
+  return Boolean(entry && "screenMemoryMcp" in entry && entry.screenMemoryMcp);
+}
+
 function targetSupportsInstallMode(
   targetId: string | undefined,
 ): targetId is ModeAwareAppSkillId {
@@ -1019,6 +1070,7 @@ function skillFilesForBuiltIn(
       skillName,
       mcpUrl:
         isLocalOnlyBuiltInSkill(entry) ||
+        isScreenMemoryMcpBuiltInSkill(entry) ||
         localFilesModeSkipsMcp(appSkillId, options.planMode)
           ? ""
           : (options.mcpUrl ?? entry.manifest.hosted.mcpUrl),
@@ -1238,9 +1290,10 @@ function builtInSkillsRootForAgent(
 ): string {
   const home = homeDir() ?? baseDir;
   if (scope === "project") {
-    if (agent === "codex") return path.join(baseDir, ".agents", "skills");
-    if (agent === "pi") return path.join(baseDir, ".agents", "skills");
-    return path.join(baseDir, ".claude", "skills");
+    if (agent === "claude-code" || agent === "claude-code-cli") {
+      return path.join(baseDir, ".claude", "skills");
+    }
+    return path.join(baseDir, ".agents", "skills");
   }
   if (agent === "codex") {
     return process.env.CODEX_HOME
@@ -1250,6 +1303,13 @@ function builtInSkillsRootForAgent(
   if (agent === "pi") {
     return path.join(home, ".agents", "skills");
   }
+  if (
+    agent === "cursor" ||
+    agent === "opencode" ||
+    agent === "github-copilot"
+  ) {
+    return path.join(home, ".agents", "skills");
+  }
   return path.join(home, ".claude", "skills");
 }
 
@@ -2128,6 +2188,11 @@ const BUILT_IN_SKILL_PROMPT_OPTIONS: SkillsTargetPromptContext["options"] = [
     label: "content",
     hint: BUILT_IN_APP_SKILLS.content.manifest.description,
   },
+  {
+    value: "rewind",
+    label: "rewind",
+    hint: BUILT_IN_APP_SKILLS.rewind.manifest.description,
+  },
   {
     value: "design-exploration",
     label: "design-exploration",
@@ -3309,7 +3374,13 @@ export async function addAgentNativeSkill(
     );
   }
   const knownBuiltIn = knownTarget ? BUILT_IN_APP_SKILLS[knownTarget] : null;
+  const installsScreenMemoryMcp = isScreenMemoryMcpBuiltInSkill(knownBuiltIn);
   const baseDir = options.baseDir ?? process.cwd();
+  if (installsScreenMemoryMcp && parsed.mcpUrl) {
+    throw new Error(
+      "Rewind uses the local Clips Screen Memory MCP and does not accept --mcp-url.",
+    );
+  }
   if (isLocalOnlyBuiltInSkill(knownBuiltIn)) {
     if (parsed.planMode) {
       throw new Error(
@@ -3415,7 +3486,9 @@ export async function addAgentNativeSkill(
     );
   }
   installTarget = preserveMcpUrlAppPathOverride(installTarget, parsed.mcpUrl);
-  const skillsAgents = skillsAgentsForClients(clients);
+  const skillsAgents = installsScreenMemoryMcp
+    ? clients
+    : skillsAgentsForClients(clients);
   if (parsed.dryRun) {
     try {
       const localManifestPath = shouldWriteContentLocalFilesManifest(
@@ -3443,9 +3516,11 @@ export async function addAgentNativeSkill(
         displayName: installTarget.displayName,
         skillNames: installTarget.skillNames,
         skillsAgents,
-        mcpUrl: localFilesModeSkipsMcp(modeAwareTargetId, planMode)
+        mcpUrl: installsScreenMemoryMcp
           ? ""
-          : installTarget.loaded.manifest.hosted.mcpUrl,
+          : localFilesModeSkipsMcp(modeAwareTargetId, planMode)
+            ? ""
+            : installTarget.loaded.manifest.hosted.mcpUrl,
         mcpClients: shouldRegisterMcp ? mcpClients : [],
         dryRun: true,
         commands: [
@@ -3545,7 +3620,29 @@ export async function addAgentNativeSkill(
       dryRun: Boolean(parsed.dryRun),
     });
 
-    if (shouldRegisterMcp) {
+    if (shouldRegisterMcp && installsScreenMemoryMcp) {
+      const screenMemoryDir = resolveScreenMemoryStoreDir();
+      if (!screenMemoryDir) {
+        throw new Error(
+          "No local Clips Screen Memory store was found. Turn Rewind on in Clips, then run the setup again.",
+        );
+      }
+      registeredMcpClients = mcpClients.map((client) => {
+        commands.push(
+          `npx @agent-native/core@latest mcp install-screen-memory --client ${client} --scope ${parsed.scope}`,
+        );
+        installScreenMemoryForClient(
+          client,
+          screenMemoryDir,
+          baseDir,
+          parsed.scope,
+        );
+        return client;
+      });
+      options.telemetry?.track("skills_cli mcp registered", {
+        skills: installTarget.skillNames.join(","),
+      });
+    } else if (shouldRegisterMcp) {
       commands.push(
         `npx @agent-native/core@latest app-skill ensure --manifest ${installTarget.loaded.file} --client ${parsed.client} --scope ${parsed.scope} --yes`,
       );
@@ -3655,9 +3752,11 @@ export async function addAgentNativeSkill(
       instructionSource,
       skillNames: installTarget.skillNames,
       skillsAgents,
-      mcpUrl: localFilesModeSkipsMcp(modeAwareTargetId, planMode)
+      mcpUrl: installsScreenMemoryMcp
         ? ""
-        : installTarget.loaded.manifest.hosted.mcpUrl,
+        : localFilesModeSkipsMcp(modeAwareTargetId, planMode)
+          ? ""
+          : installTarget.loaded.manifest.hosted.mcpUrl,
       mcpClients: registeredMcpClients,
       dryRun: parsed.dryRun,
       commands,
@@ -3689,10 +3788,13 @@ function listSkills(options: RunSkillsOptions = {}) {
           ] ?? [],
         name: entry.manifest.displayName,
         description: entry.manifest.description,
-        mcpUrl: isLocalOnlyBuiltInSkill(entry)
-          ? ""
-          : entry.manifest.hosted.mcpUrl,
-        local: isLocalOnlyBuiltInSkill(entry),
+        mcpUrl:
+          isLocalOnlyBuiltInSkill(entry) || isScreenMemoryMcpBuiltInSkill(entry)
+            ? ""
+            : entry.manifest.hosted.mcpUrl,
+        local:
+          isLocalOnlyBuiltInSkill(entry) ||
+          isScreenMemoryMcpBuiltInSkill(entry),
         source: "agent-native",
       })),
     ...publicSkillEntries(options).map((entry) => ({