@agent-native/core 0.131.6 → 0.131.9

package/src/cli/create.ts

@@ -50,6 +50,18 @@ const FIRST_PARTY_TARBALL_SYMLINK_EXCLUDES = [
   "*/.claude/skills",
 ];
 const localPackageTarballs = new Map<string, string>();
+/** VCS/editor files that don't count as "not empty" for an in-place scaffold. */
+const IN_PLACE_ALLOWLIST = new Set([
+  ".git",
+  ".gitignore",
+  ".gitattributes",
+  ".DS_Store",
+  ".idea",
+  ".vscode",
+  "LICENSE",
+  "README.md",
+  "Thumbs.db",
+]);
 
 /**
  * Tagged error for input that fails CLI-level validation (repo names, app
@@ -110,6 +122,11 @@ export interface CreateAppOptions {
    * unconditional workspace scaffold.
    */
   forceWorkspace?: boolean;
+  /**
+   * Internal: scaffold into the current directory instead of a new subfolder.
+   * Set when the name argument is `.`/`./` (see `createApp`).
+   */
+  inPlace?: boolean;
 }
 
 /**
@@ -127,6 +144,13 @@ export async function createApp(
 ): Promise<void> {
   const clack = await import("@clack/prompts");
 
+  // `create .` (or `./`) means "scaffold into the current folder" — derive the
+  // project name from the folder's basename, like create-react-app / npm init.
+  if (name === "." || name === "./") {
+    name = path.basename(process.cwd());
+    opts = { ...opts, inPlace: true };
+  }
+
   // Reject an invalid provided name before any interactive prompt so bad input
   // fails fast instead of blocking on the start-shape picker below.
   if (name !== undefined) {
@@ -335,6 +359,44 @@ function assertValidProjectName(
     process.exit(1);
   }
 }
+/**
+ * Resolve where a scaffold writes and guard the target. A named project writes
+ * to a new sibling subfolder that must not already exist; `create .` writes
+ * into the current directory, which must be empty apart from benign VCS/editor
+ * files (a pre-existing repo is allowed).
+ *
+ * For an in-place scaffold we do NOT return the current directory: we build
+ * into a private staging directory and `finalizeScaffold` copies the result
+ * in afterward. Staging keeps the whole scaffold atomic — a mid-scaffold
+ * failure's cleanup can only ever delete the staging dir, never the user's
+ * current directory (including its `.git`).
+ */
+function resolveScaffoldTarget(
+  name: string,
+  inPlace: boolean | undefined,
+  clack: typeof import("@clack/prompts"),
+): string {
+  if (inPlace) {
+    const conflicting = fs
+      .readdirSync(process.cwd())
+      .filter((entry) => !IN_PLACE_ALLOWLIST.has(entry));
+    if (conflicting.length > 0) {
+      const shown = conflicting.slice(0, 3).join(", ");
+      const more = conflicting.length > 3 ? ", …" : "";
+      clack.cancel(
+        `Current directory is not empty (${shown}${more}). Scaffold into an empty folder, or run \`create <name>\` to make a new one.`,
+      );
+      process.exit(1);
+    }
+    return fs.mkdtempSync(path.join(os.tmpdir(), "agent-native-create-"));
+  }
+  const targetDir = path.resolve(process.cwd(), name);
+  if (fs.existsSync(targetDir)) {
+    clack.cancel(`Directory "${name}" already exists.`);
+    process.exit(1);
+  }
+  return targetDir;
+}
 
 /* ─────────────────────────────────────────────────────────────────────────
  * Workspace creation (new default)
@@ -378,11 +440,7 @@ async function createWorkspaceInteractive(
         });
   const templates = ["dispatch", ...optionalPicks];
 
-  const targetDir = path.resolve(process.cwd(), name);
-  if (fs.existsSync(targetDir)) {
-    clack.cancel(`Directory "${name}" already exists.`);
-    process.exit(1);
-  }
+  const targetDir = resolveScaffoldTarget(name, opts?.inPlace, clack);
 
   const s = clack.spinner();
   for (const template of templates) {
@@ -482,13 +540,15 @@ async function createWorkspaceInteractive(
   } catch (err: any) {
     s.stop("Failed to scaffold workspace.");
     // Remove the partially-scaffolded workspace so a retry of `agent-native
-    // create <name>` doesn't trip the "Directory already exists" guard.
+    // create <name>` doesn't trip the "Directory already exists" guard. For an
+    // in-place scaffold `targetDir` is the private staging dir, so this never
+    // touches the user's current directory.
     cleanupOnFailure(targetDir);
     clack.cancel(err?.message ?? String(err));
     process.exit(1);
   }
 
-  tryGitInit(targetDir);
+  finalizeScaffold(targetDir, opts?.inPlace);
 
   // Show the user the tree we just built so the workspace/app distinction is
   // visible, not just described. First-time users routinely expect their
@@ -845,11 +905,7 @@ async function createStandaloneApp(
 
   name = await promptNameIfMissing(name, clack, "app", "my-app");
 
-  const targetDir = path.resolve(process.cwd(), name);
-  if (fs.existsSync(targetDir)) {
-    clack.cancel(`Directory "${name}" already exists.`);
-    process.exit(1);
-  }
+  const targetDir = resolveScaffoldTarget(name, opts?.inPlace, clack);
 
   // Standalone is single-select — pick one template.
   let template =
@@ -889,12 +945,14 @@ async function createStandaloneApp(
     s.stop("App created!");
   } catch (err: any) {
     s.stop("Failed to create app.");
+    // `targetDir` is the private staging dir for an in-place scaffold, so this
+    // only ever removes the staging copy, never the user's current directory.
     cleanupOnFailure(targetDir);
     clack.cancel(err?.message ?? String(err));
     process.exit(1);
   }
 
-  tryGitInit(targetDir);
+  finalizeScaffold(targetDir, opts?.inPlace);
 
   if (template === "headless") {
     clack.outro(
@@ -954,6 +1012,35 @@ function cleanupOnFailure(targetDir: string): void {
   }
 }
 
+/**
+ * Land a finished scaffold in its final home and initialize git. A named
+ * scaffold is already in place, so this only inits git. An in-place scaffold
+ * (`create .`) was built in `scaffoldDir` (a staging dir); copy only the files
+ * that don't already exist into the current directory so pre-existing files
+ * (`.git`, `README.md`, `.gitignore`, editor configs) are preserved, then drop
+ * the staging dir. Git init/commit is skipped when the current directory is
+ * already a repo so we never write an unexpected commit into the user's
+ * history.
+ */
+function finalizeScaffold(scaffoldDir: string, inPlace?: boolean): void {
+  if (!inPlace) {
+    tryGitInitUnlessRepo(scaffoldDir);
+    return;
+  }
+  const dest = process.cwd();
+  try {
+    copyDir(scaffoldDir, dest, undefined, { skipExisting: true });
+  } finally {
+    cleanupOnFailure(scaffoldDir);
+  }
+  tryGitInitUnlessRepo(dest);
+}
+
+function tryGitInitUnlessRepo(dir: string): void {
+  if (fs.existsSync(path.join(dir, ".git"))) return;
+  tryGitInit(dir);
+}
+
 /* ─────────────────────────────────────────────────────────────────────────
  * Shared scaffolding helpers
  * ───────────────────────────────────────────────────────────────────────── */
@@ -3399,13 +3486,25 @@ function replacePlaceholders(
   }
 }
 
-function copyDir(src: string, dest: string, root?: string): void {
+function copyDir(
+  src: string,
+  dest: string,
+  root?: string,
+  opts?: { skipExisting?: boolean },
+): void {
   const resolvedRoot = root ?? path.resolve(src);
+  const skipExisting = opts?.skipExisting ?? false;
   fs.mkdirSync(dest, { recursive: true });
   for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
     const srcPath = path.join(src, entry.name);
     if (shouldSkipScaffoldEntry(entry.name, srcPath)) continue;
     const destPath = path.join(dest, entry.name);
+    // Preserve anything already at the destination (in-place scaffold merges
+    // into a directory the user may already own). Directories still recurse so
+    // new files land inside a pre-existing folder.
+    if (skipExisting && !entry.isDirectory() && fs.existsSync(destPath)) {
+      continue;
+    }
     if (entry.isSymbolicLink()) {
       const target = fs.readlinkSync(srcPath);
       const resolvedTarget = path.resolve(path.dirname(srcPath), target);
@@ -3415,7 +3514,7 @@ function copyDir(src: string, dest: string, root?: string): void {
         try {
           const stat = fs.statSync(srcPath);
           if (stat.isDirectory()) {
-            copyDir(srcPath, destPath, resolvedRoot);
+            copyDir(srcPath, destPath, resolvedRoot, opts);
           } else {
             fs.copyFileSync(srcPath, destPath);
           }
@@ -3424,7 +3523,7 @@ function copyDir(src: string, dest: string, root?: string): void {
         }
       }
     } else if (entry.isDirectory()) {
-      copyDir(srcPath, destPath, resolvedRoot);
+      copyDir(srcPath, destPath, resolvedRoot, opts);
     } else {
       fs.copyFileSync(srcPath, destPath);
     }

package/src/client/AssistantChat.tsx

@@ -3421,7 +3421,11 @@ const AssistantChatInner = forwardRef<
           }
           window.dispatchEvent(
             new CustomEvent("agentNative.chatRunning", {
-              detail: { isRunning: false, tabId: tabId || threadId },
+              detail: {
+                isRunning: false,
+                tabId: tabId || threadId,
+                reason: "failed",
+              },
             }),
           );
           return;
@@ -4510,7 +4514,11 @@ const AssistantChatInner = forwardRef<
       if (typeof window !== "undefined") {
         window.dispatchEvent(
           new CustomEvent("agentNative.chatRunning", {
-            detail: { isRunning: false, tabId: tabId || threadId },
+            detail: {
+              isRunning: false,
+              tabId: tabId || threadId,
+              reason: "stopped",
+            },
           }),
         );
       }

package/src/client/frame-protocol.ts

@@ -115,7 +115,11 @@ export interface FrameOriginMessage {
 
 export interface ChatRunningMessage {
   type: "agentNative.chatRunning";
-  detail: { isRunning: boolean; tabId?: string };
+  detail: {
+    isRunning: boolean;
+    tabId?: string;
+    reason?: "stopped" | "failed";
+  };
 }
 
 export interface UserInfoMessage {

package/src/guards/no-env-credentials.ts

@@ -65,6 +65,8 @@ const ALLOWLIST_EXACT = new Set([
   "PORT",
   "HOST",
   "SECRETS_ENCRYPTION_KEY",
+  "WORKSPACE_SECRETS_ENCRYPTION_KEY",
+  "WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS",
 ]);
 
 const ALLOWLIST_PREFIX = [

package/src/scripts/call-agent.ts

@@ -464,10 +464,12 @@ export async function run(
   const messageWithHint = taskId
     ? ""
     : `${message}${integrationSourceContextHint(sourceContext)}\n\n` +
-      `[Note: this request comes from another app via A2A. The caller cannot see your local UI, deck list, or navigation — only the literal text you put in your reply. ` +
+      `<a2a-caller-hint>\n` +
+      `This request comes from another app via A2A. The caller cannot see your local UI, deck list, or navigation — only the literal text you put in your reply. ` +
       `If you create or reference a deck/document/design/dashboard, include its FULLY-QUALIFIED URL (e.g. ${agent.url}/deck/<id>) in your reply, not a relative path. ` +
       `Use only artifact IDs and URL paths returned by successful actions — never invent slugs, IDs, or hosts. ` +
-      `Return a concise caller-ready synthesis rather than raw tool output or full transcripts; preserve source counts, IDs, short supporting quotes, and URLs needed to substantiate the answer.]`;
+      `Return a concise caller-ready synthesis rather than raw tool output or full transcripts; preserve source counts, IDs, short supporting quotes, and URLs needed to substantiate the answer.\n` +
+      `</a2a-caller-hint>`;
 
   const invocationId = randomUUID();
   const invocationStartedAt = Date.now();

package/src/secrets/crypto.ts

@@ -13,10 +13,13 @@
  * The generic encryption key is derived from
  * `<APP_NAME>_SECRETS_ENCRYPTION_KEY` when set, then
  * `SECRETS_ENCRYPTION_KEY`, then `BETTER_AUTH_SECRET`. Workspace-shared vault
- * rows use a different precedence: `SECRETS_ENCRYPTION_KEY`, then material
- * derived from the workspace-wide `A2A_SECRET`, then the app-local auth/key
- * fallbacks retained for backward-compatible reads. This keeps sibling apps
- * on one key even when each app correctly has a different auth secret.
+ * rows use a different precedence: `WORKSPACE_SECRETS_ENCRYPTION_KEY`, then
+ * the legacy shared `SECRETS_ENCRYPTION_KEY`, then material derived from the
+ * workspace-wide `A2A_SECRET`, then the app-local auth/key fallbacks retained
+ * for backward-compatible reads. A previous workspace key can be supplied
+ * during rotation with `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS`. This keeps
+ * sibling apps on one stable key even when each app correctly has a different
+ * auth secret, and prevents A2A trust rotation from stranding vault data.
  *
  * In production we refuse to start without configured key material — a
  * CWD-derived fallback would be effectively static (e.g. `/var/task` on
@@ -95,6 +98,18 @@ function genericEncryptionKeyMaterial(): string | undefined {
   );
 }
 
+function workspaceSharedEncryptionKeyMaterial(): string | undefined {
+  if (typeof process === "undefined") return undefined;
+  return process.env.WORKSPACE_SECRETS_ENCRYPTION_KEY?.trim() || undefined;
+}
+
+function previousWorkspaceSharedEncryptionKeyMaterial(): string | undefined {
+  if (typeof process === "undefined") return undefined;
+  return (
+    process.env.WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS?.trim() || undefined
+  );
+}
+
 /**
  * Vault sharing follows configured A2A trust even on independently deployed
  * sibling apps that are not launched by the workspace wrapper. The wrapper's
@@ -116,14 +131,17 @@ function a2aSharedEncryptionKeyMaterial(): string | undefined {
  * Stable materials that may be used for workspace-shared vault rows, ordered
  * from current preference to legacy compatibility fallbacks.
  *
- * `BETTER_AUTH_SECRET` deliberately comes after the A2A-derived material:
- * sibling apps normally have different auth secrets but share A2A trust.
+ * `BETTER_AUTH_SECRET` deliberately comes after the workspace and A2A-derived
+ * materials: sibling apps normally have different auth secrets but share
+ * workspace trust.
  */
 function sharedEncryptionKeyMaterials(): string[] {
   if (typeof process === "undefined") return [];
   const candidates = [
+    workspaceSharedEncryptionKeyMaterial(),
     process.env.SECRETS_ENCRYPTION_KEY,
     a2aSharedEncryptionKeyMaterial(),
+    previousWorkspaceSharedEncryptionKeyMaterial(),
     process.env.BETTER_AUTH_SECRET,
     appScopedEncryptionKey(),
   ].filter((value): value is string => Boolean(value));
@@ -131,7 +149,14 @@ function sharedEncryptionKeyMaterials(): string[] {
 }
 
 function preferredSharedEncryptionKeyMaterial(): string | undefined {
-  return sharedEncryptionKeyMaterials()[0];
+  if (typeof process === "undefined") return undefined;
+  return (
+    workspaceSharedEncryptionKeyMaterial() ||
+    process.env.SECRETS_ENCRYPTION_KEY ||
+    a2aSharedEncryptionKeyMaterial() ||
+    process.env.BETTER_AUTH_SECRET ||
+    appScopedEncryptionKey()
+  );
 }
 
 function hashSecretEncryptionKey(material: string): Buffer {
@@ -187,20 +212,23 @@ export function getSecretEncryptionKey(): Buffer {
 /**
  * Derive the preferred workspace-shared key used by `app_secrets` rows.
  * Unlike generic column-level encryption, workspace vault data must decrypt
- * in sibling apps. An explicit `SECRETS_ENCRYPTION_KEY` wins; hosted
- * workspaces otherwise derive stable material from their shared `A2A_SECRET`
- * before considering app-local `BETTER_AUTH_SECRET` or app-scoped key
- * fallbacks. Reads try every configured legacy candidate and report when the
- * ciphertext should be refreshed under the preferred key.
+ * in sibling apps. An explicit `WORKSPACE_SECRETS_ENCRYPTION_KEY` wins without
+ * changing the key for app-local OAuth and credential ciphertext. The legacy
+ * shared `SECRETS_ENCRYPTION_KEY` remains supported; hosted workspaces
+ * otherwise derive material from their shared `A2A_SECRET` before considering
+ * app-local `BETTER_AUTH_SECRET` or app-scoped key fallbacks. Reads try every
+ * configured legacy/previous candidate and report when the ciphertext should
+ * be refreshed under the preferred key.
  */
 export function getSharedSecretEncryptionKey(): Buffer {
   return deriveSecretEncryptionKey(
     preferredSharedEncryptionKeyMaterial(),
     "[agent-native/secrets] Refusing to start in production without encryption key material for workspace secrets. " +
-      "Set SECRETS_ENCRYPTION_KEY, ensure a hosted workspace has A2A_SECRET, or set BETTER_AUTH_SECRET / an app-scoped " +
+      "Set WORKSPACE_SECRETS_ENCRYPTION_KEY (preferred), SECRETS_ENCRYPTION_KEY, ensure a hosted workspace has A2A_SECRET, " +
+      "or set BETTER_AUTH_SECRET / an app-scoped " +
       "*_SECRETS_ENCRYPTION_KEY compatibility fallback in the deploy environment.",
-    "[agent-native/secrets] SECRETS_ENCRYPTION_KEY not set — using app-scoped or machine-local fallback for workspace secrets. " +
-      "Set SECRETS_ENCRYPTION_KEY or rely on A2A_SECRET-derived material on hosted workspace deploys so sibling apps share vault rows.",
+    "[agent-native/secrets] Workspace encryption key not set — using app-scoped or machine-local fallback for workspace secrets. " +
+      "Set WORKSPACE_SECRETS_ENCRYPTION_KEY or rely on A2A_SECRET-derived material on hosted workspace deploys so sibling apps share vault rows.",
   );
 }
 
@@ -208,6 +236,7 @@ export function getSharedSecretEncryptionKey(): Buffer {
 export function hasSharedSecretEncryptionKeyMaterial(): boolean {
   if (typeof process === "undefined") return false;
   return Boolean(
+    workspaceSharedEncryptionKeyMaterial() ||
     process.env.SECRETS_ENCRYPTION_KEY ||
     a2aSharedEncryptionKeyMaterial() ||
     process.env.BETTER_AUTH_SECRET,

package/src/secrets/storage.ts

@@ -2,10 +2,12 @@
  * Storage layer for the framework secrets registry.
  *
  * Values are encrypted at rest with AES-256-GCM. The workspace-shared
- * encryption key is derived from `SECRETS_ENCRYPTION_KEY` (preferred) or the
- * workspace-wide `A2A_SECRET`. `BETTER_AUTH_SECRET` and app-scoped keys remain
- * read fallbacks for rows written before sibling apps converged on the shared
- * key. Successful fallback reads race-safely refresh the shared ciphertext.
+ * encryption key prefers `WORKSPACE_SECRETS_ENCRYPTION_KEY`, then the legacy
+ * combined `SECRETS_ENCRYPTION_KEY`, then the workspace-wide `A2A_SECRET`.
+ * A configured previous workspace key, `BETTER_AUTH_SECRET`, and app-scoped
+ * keys remain read fallbacks for rows written before sibling apps converged on
+ * the shared key. Successful fallback reads race-safely refresh the shared
+ * ciphertext.
  *
  * Secret values are NEVER logged and NEVER returned from any route handler.
  */

package/src/server/agent-chat/action-filters-a2a.ts

@@ -360,6 +360,8 @@ export const DELEGATED_AGENT_EXECUTION_CONTRACT = `
 <delegated-agent-contract>
 This request was delegated by another app. You are the specialist owner of the work.
 - Interpret the caller's natural-language objective using your own instructions, skills, data dictionary, credentials, and tools. Choose providers, schemas, queries, and joins here; never ask the caller to invent SQL or source-specific implementation details for you.
+- Finish the objective autonomously in this delegated turn whenever a safe, reasonable default exists. Do not bounce the work back with UI-navigation requests, implementation questions, or intermediate status. Ask for input only when authorization, missing credentials, or a consequential user choice truly blocks progress.
+- When evidence is incomplete, return the best grounded partial answer with explicit coverage gaps instead of refusing or asking the caller to choose your source, filter, dashboard, or workflow.
 - Minimize round trips. Filter, join, aggregate, paginate, stage, and reduce large datasets inside your own tools rather than returning raw records or transcripts.
 - Return a concise caller-ready result with the answer, source and coverage details, relevant counts or IDs, caveats/partial gaps, and exact artifact URLs. Do not return tool transcripts or large raw payloads.
 </delegated-agent-contract>`;

package/src/templates/default/.agents/skills/secrets/SKILL.md

@@ -227,15 +227,20 @@ Core routes plugin mounts these under `/_agent-native/secrets/` automatically:
   prefer `<APP_NAME>_SECRETS_ENCRYPTION_KEY` (for example,
   `ANALYTICS_SECRETS_ENCRYPTION_KEY`), then `SECRETS_ENCRYPTION_KEY`, then
   `BETTER_AUTH_SECRET`.
-- Workspace-shared `app_secrets` prefer `SECRETS_ENCRYPTION_KEY`, then a
-  purpose-derived key from `A2A_SECRET`. Better Auth and app-scoped keys remain
-  legacy read candidates; a successful legacy decrypt is compare-and-swap
-  migrated to the preferred shared key without changing the row timestamp.
-- Set the same stable `SECRETS_ENCRYPTION_KEY` in every app that reads a shared
-  vault. If the vault relies on `A2A_SECRET`, rotating A2A material also rotates
-  its encryption key. Before rotating A2A, add the stable vault key everywhere
-  and read/migrate every existing row while the old A2A material is still
-  available.
+- Workspace-shared `app_secrets` prefer
+  `WORKSPACE_SECRETS_ENCRYPTION_KEY`, then the legacy shared
+  `SECRETS_ENCRYPTION_KEY`, then a purpose-derived key from `A2A_SECRET`.
+  Better Auth and app-scoped keys remain legacy read candidates; a successful
+  legacy decrypt is compare-and-swap migrated to the preferred shared key
+  without changing the row timestamp.
+- Set the same stable `WORKSPACE_SECRETS_ENCRYPTION_KEY` in every app that
+  reads a shared vault. It is intentionally separate from app-local OAuth
+  encryption. If the vault still relies on `A2A_SECRET`, rotating A2A material
+  also rotates its encryption key. Add the stable vault key everywhere and
+  read/migrate existing rows before rotating A2A.
+- To rotate the dedicated workspace key itself, deploy the new value together
+  with `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS=<old value>`, let reads
+  migrate ciphertext, then remove the previous key after the migration window.
 - If no configured key material exists, development uses a machine-local
   fallback and logs a one-time warning. Production fails closed.
 

package/src/templates/headless/.agents/skills/secrets/SKILL.md

@@ -227,15 +227,20 @@ Core routes plugin mounts these under `/_agent-native/secrets/` automatically:
   prefer `<APP_NAME>_SECRETS_ENCRYPTION_KEY` (for example,
   `ANALYTICS_SECRETS_ENCRYPTION_KEY`), then `SECRETS_ENCRYPTION_KEY`, then
   `BETTER_AUTH_SECRET`.
-- Workspace-shared `app_secrets` prefer `SECRETS_ENCRYPTION_KEY`, then a
-  purpose-derived key from `A2A_SECRET`. Better Auth and app-scoped keys remain
-  legacy read candidates; a successful legacy decrypt is compare-and-swap
-  migrated to the preferred shared key without changing the row timestamp.
-- Set the same stable `SECRETS_ENCRYPTION_KEY` in every app that reads a shared
-  vault. If the vault relies on `A2A_SECRET`, rotating A2A material also rotates
-  its encryption key. Before rotating A2A, add the stable vault key everywhere
-  and read/migrate every existing row while the old A2A material is still
-  available.
+- Workspace-shared `app_secrets` prefer
+  `WORKSPACE_SECRETS_ENCRYPTION_KEY`, then the legacy shared
+  `SECRETS_ENCRYPTION_KEY`, then a purpose-derived key from `A2A_SECRET`.
+  Better Auth and app-scoped keys remain legacy read candidates; a successful
+  legacy decrypt is compare-and-swap migrated to the preferred shared key
+  without changing the row timestamp.
+- Set the same stable `WORKSPACE_SECRETS_ENCRYPTION_KEY` in every app that
+  reads a shared vault. It is intentionally separate from app-local OAuth
+  encryption. If the vault still relies on `A2A_SECRET`, rotating A2A material
+  also rotates its encryption key. Add the stable vault key everywhere and
+  read/migrate existing rows before rotating A2A.
+- To rotate the dedicated workspace key itself, deploy the new value together
+  with `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS=<old value>`, let reads
+  migrate ciphertext, then remove the previous key after the migration window.
 - If no configured key material exists, development uses a machine-local
   fallback and logs a one-time warning. Production fails closed.
 

package/src/templates/workspace-core/.agents/skills/secrets/SKILL.md

@@ -227,15 +227,20 @@ Core routes plugin mounts these under `/_agent-native/secrets/` automatically:
   prefer `<APP_NAME>_SECRETS_ENCRYPTION_KEY` (for example,
   `ANALYTICS_SECRETS_ENCRYPTION_KEY`), then `SECRETS_ENCRYPTION_KEY`, then
   `BETTER_AUTH_SECRET`.
-- Workspace-shared `app_secrets` prefer `SECRETS_ENCRYPTION_KEY`, then a
-  purpose-derived key from `A2A_SECRET`. Better Auth and app-scoped keys remain
-  legacy read candidates; a successful legacy decrypt is compare-and-swap
-  migrated to the preferred shared key without changing the row timestamp.
-- Set the same stable `SECRETS_ENCRYPTION_KEY` in every app that reads a shared
-  vault. If the vault relies on `A2A_SECRET`, rotating A2A material also rotates
-  its encryption key. Before rotating A2A, add the stable vault key everywhere
-  and read/migrate every existing row while the old A2A material is still
-  available.
+- Workspace-shared `app_secrets` prefer
+  `WORKSPACE_SECRETS_ENCRYPTION_KEY`, then the legacy shared
+  `SECRETS_ENCRYPTION_KEY`, then a purpose-derived key from `A2A_SECRET`.
+  Better Auth and app-scoped keys remain legacy read candidates; a successful
+  legacy decrypt is compare-and-swap migrated to the preferred shared key
+  without changing the row timestamp.
+- Set the same stable `WORKSPACE_SECRETS_ENCRYPTION_KEY` in every app that
+  reads a shared vault. It is intentionally separate from app-local OAuth
+  encryption. If the vault still relies on `A2A_SECRET`, rotating A2A material
+  also rotates its encryption key. Add the stable vault key everywhere and
+  read/migrate existing rows before rotating A2A.
+- To rotate the dedicated workspace key itself, deploy the new value together
+  with `WORKSPACE_SECRETS_ENCRYPTION_KEY_PREVIOUS=<old value>`, let reads
+  migrate ciphertext, then remove the previous key after the migration window.
 - If no configured key material exists, development uses a machine-local
   fallback and logs a one-time warning. Production fails closed.
 

package/src/workspace-files/tool.ts

@@ -86,13 +86,16 @@ export function createWorkspaceFilesTool(): Record<string, ActionEntry> {
                 'MIME type for new files. Default: "text/plain". Use "application/json" for JSON, "text/markdown" for Markdown.',
             },
             offset: {
-              type: "number",
+              type: "integer",
+              minimum: 0,
               description:
-                "Character offset to start reading from (for paging large files). Default: 0.",
+                "Non-negative character offset to start reading from (for paging large files). Default: 0.",
             },
             maxChars: {
-              type: "number",
-              description: `Maximum characters to return when reading. Default: ${DEFAULT_READ_CHARS}. Max: ${MAX_READ_CHARS}.`,
+              type: "integer",
+              minimum: 1,
+              maximum: MAX_READ_CHARS,
+              description: `Positive maximum characters to return when reading. Default: ${DEFAULT_READ_CHARS}. Max: ${MAX_READ_CHARS}.`,
             },
             pattern: {
               type: "string",
@@ -168,16 +171,19 @@ export function createWorkspaceFilesTool(): Record<string, ActionEntry> {
               if (!path) return "Error: path is required for read.";
               const rawOffset = Number(args.offset);
               const offset =
-                Number.isFinite(rawOffset) && rawOffset > 0 ? rawOffset : 0;
+                Number.isFinite(rawOffset) && rawOffset > 0
+                  ? Math.floor(rawOffset)
+                  : 0;
               const rawMax = Number(args.maxChars);
               const maxChars =
                 Number.isFinite(rawMax) && rawMax > 0
-                  ? Math.min(rawMax, MAX_READ_CHARS)
+                  ? Math.min(Math.max(1, Math.floor(rawMax)), MAX_READ_CHARS)
                   : DEFAULT_READ_CHARS;
 
+              // The sentinel character distinguishes an exact page from a truncated one.
               const file = await readWorkspaceFile(scope, path, {
                 offset,
-                maxChars,
+                maxChars: maxChars + 1,
               });
               if (!file) {
                 return JSON.stringify({
@@ -186,19 +192,20 @@ export function createWorkspaceFilesTool(): Record<string, ActionEntry> {
                 });
               }
 
-              const truncated = file.content.length >= maxChars;
+              const truncated = file.content.length > maxChars;
+              const content = file.content.slice(0, maxChars);
               return JSON.stringify({
                 ok: true,
                 path: file.path,
                 contentType: file.contentType,
                 sizeBytes: file.sizeBytes,
                 updatedAt: file.updatedAt,
-                content: file.content,
+                content,
                 ...(truncated
                   ? {
                       truncated: true,
-                      nextOffset: offset + file.content.length,
-                      hint: `File has more content. Call again with offset: ${offset + file.content.length}`,
+                      nextOffset: offset + content.length,
+                      hint: `File has more content. Call again with offset: ${offset + content.length}`,
                     }
                   : {}),
               });