@agent-native/core 0.152.1 → 0.153.1

package/dist/agent/engine/registry.js

@@ -574,9 +574,14 @@ async function apiKeyBelongsToDifferentProvider(apiKey, selectedEntry) {
     }
     return false;
 }
-async function engineCreateConfigForEntry(entry, apiKey, extra, preferResolvedCredential = false, apiKeyEnvVar, credentialIdentity) {
+async function engineCreateConfigForEntry(entry, apiKey, extra, credentialResolution = "explicit", apiKeyEnvVar, credentialIdentity) {
     const safeExtra = { ...(extra ?? {}) };
     let matchingApiKey = apiKey;
+    if (matchingApiKey === undefined &&
+        typeof safeExtra.apiKey === "string" &&
+        safeExtra.apiKey.trim()) {
+        matchingApiKey = safeExtra.apiKey;
+    }
     // A declared provenance settles the question without inspecting values: a
     // credential issued for another provider's env var is never this entry's
     // key, so drop it on explicit branches too. Value comparison below cannot
@@ -586,14 +591,14 @@ async function engineCreateConfigForEntry(entry, apiKey, extra, preferResolvedCr
         !entry.requiredEnvVars.includes(apiKeyEnvVar)) {
         matchingApiKey = undefined;
     }
-    // Automatic engine selection must also select that engine's credential.
-    // Callers historically passed one untagged "active" key before the registry
-    // chose an engine, which could hand an Anthropic key to an app-default
-    // OpenAI engine (or vice versa). Explicit engineOption branches retain their
-    // paired key. Automatic branches replace only a key proven to belong to a
-    // different configured provider; opaque caller-supplied keys keep the public
-    // `ResolveEngineConfig.apiKey` contract.
-    if (preferResolvedCredential &&
+    // Engine selection must also select that engine's credential. Callers
+    // historically passed one untagged "active" key before the registry chose
+    // an engine, which could hand an Anthropic key to an OpenAI engine (or vice
+    // versa). Explicit engine options can also arrive without a key when the
+    // owner resolver missed a shared vault row, so resolve those missing keys at
+    // this construction boundary too. Opaque caller-supplied keys remain intact
+    // unless they are proven to belong to another configured provider.
+    if ((credentialResolution === "automatic" || matchingApiKey === undefined) &&
         entry.name !== "builder" &&
         entry.requiredEnvVars.length > 0) {
         let resolvedMatchingCredential;
@@ -616,8 +621,8 @@ async function engineCreateConfigForEntry(entry, apiKey, extra, preferResolvedCr
         if (matchingApiKey === undefined || suppliedKeyBelongsElsewhere) {
             // Keep deploy-only credentials implicit so provider SDKs retain their
             // established env-fallback behavior. Scoped credentials must be passed
-            // explicitly. A proven different-provider key is replaced or cleared;
-            // an opaque caller-supplied key is preserved by the branch above.
+            // explicitly. Automatic selection replaces a proven
+            // different-provider key; an opaque explicit key is left untouched.
             matchingApiKey =
                 resolvedMatchingCredential && !matchingCredentialUsesDeployFallback
                     ? resolvedMatchingCredential
@@ -820,7 +825,7 @@ export async function resolveEngine(config) {
         if (!entry)
             throw new Error(`[agent-engine] Unknown engine: "${name}". Registered: ${[..._registry.keys()].join(", ")}`);
         assertAgentEnginePackageInstalled(entry);
-        return entry.create(await engineCreateConfigForEntry(entry, apiKey, engineConfig, false, apiKeyEnvVar, credentialIdentity));
+        return entry.create(await engineCreateConfigForEntry(entry, apiKey, engineConfig, "explicit", apiKeyEnvVar, credentialIdentity));
     }
     // 3. Explicit string name from options
     if (typeof engineOption === "string") {
@@ -828,7 +833,7 @@ export async function resolveEngine(config) {
         if (!entry)
             throw new Error(`[agent-engine] Unknown engine: "${engineOption}". Registered: ${[..._registry.keys()].join(", ")}`);
         assertAgentEnginePackageInstalled(entry);
-        return entry.create(await engineCreateConfigForEntry(entry, apiKey, undefined, false, apiKeyEnvVar, credentialIdentity));
+        return entry.create(await engineCreateConfigForEntry(entry, apiKey, undefined, "explicit", apiKeyEnvVar, credentialIdentity));
     }
     // 4. Env var — explicit engine name override
     const envEngine = process.env.AGENT_ENGINE;
@@ -836,7 +841,7 @@ export async function resolveEngine(config) {
         const entry = _registry.get(envEngine);
         if (entry) {
             assertAgentEnginePackageInstalled(entry);
-            return entry.create(await engineCreateConfigForEntry(entry, apiKey, undefined, true, apiKeyEnvVar, credentialIdentity));
+            return entry.create(await engineCreateConfigForEntry(entry, apiKey, undefined, "automatic", apiKeyEnvVar, credentialIdentity));
         }
     }
     const appDefault = await getAgentAppModelDefaultForCurrentRequest(appId);
@@ -846,7 +851,7 @@ export async function resolveEngine(config) {
             (await isStoredEngineUsableForRequest(appDefault, entry, {
                 credentialIdentity,
             }))) {
-            return entry.create(await engineCreateConfigForEntry(entry, apiKey, undefined, true, apiKeyEnvVar, credentialIdentity));
+            return entry.create(await engineCreateConfigForEntry(entry, apiKey, undefined, "automatic", apiKeyEnvVar, credentialIdentity));
         }
     }
     let stored = null;
@@ -873,25 +878,25 @@ export async function resolveEngine(config) {
             (await isStoredEngineUsableForRequest(storedRaw, entry, {
                 credentialIdentity,
             }))) {
-            return entry.create(await engineCreateConfigForEntry(entry, apiKey, stripInlineApiKeyConfig(storedConfig), true, apiKeyEnvVar, credentialIdentity));
+            return entry.create(await engineCreateConfigForEntry(entry, apiKey, stripInlineApiKeyConfig(storedConfig), "automatic", apiKeyEnvVar, credentialIdentity));
         }
     }
     if (detectedFromUser) {
-        return detectedFromUser.create(await engineCreateConfigForEntry(detectedFromUser, apiKey, undefined, true, apiKeyEnvVar, credentialIdentity));
+        return detectedFromUser.create(await engineCreateConfigForEntry(detectedFromUser, apiKey, undefined, "automatic", apiKeyEnvVar, credentialIdentity));
     }
     // 8. Auto-detect from any provider env var — so just dropping a key in
     // .env works without also setting AGENT_ENGINE. Skip keys with active
     // auth-failure markers so a rejected deploy key cannot permanently win.
     const detected = await detectEngineFromEnvForRequest();
     if (detected) {
-        return detected.create(await engineCreateConfigForEntry(detected, apiKey, undefined, true, apiKeyEnvVar, credentialIdentity));
+        return detected.create(await engineCreateConfigForEntry(detected, apiKey, undefined, "automatic", apiKeyEnvVar, credentialIdentity));
     }
     // 9. Default: anthropic
     const anthropicEntry = _registry.get("anthropic");
     if (!anthropicEntry) {
         throw new Error("[agent-engine] Default Anthropic engine is not registered. Did builtin.ts fail to load?");
     }
-    return anthropicEntry.create(await engineCreateConfigForEntry(anthropicEntry, apiKey, undefined, true, apiKeyEnvVar, credentialIdentity));
+    return anthropicEntry.create(await engineCreateConfigForEntry(anthropicEntry, apiKey, undefined, "automatic", apiKeyEnvVar, credentialIdentity));
 }
 /**
  * Read the user-selected model for an engine from the `agent-engine` setting.

package/dist/agent/engine/translate-anthropic.js

@@ -503,7 +503,19 @@ export function observeStreamedToolInput(state, event) {
         state.byId.set(id, { name: event.name ?? "", text, delivered: false });
         return;
     }
-    if (event.type === "tool-call" || event.type === "tool-call-error") {
+    if (event.type === "tool-call") {
+        // Non-empty terminal input remains authoritative. Some gateways emit the
+        // complete argument JSON as deltas but follow it with an empty terminal
+        // input, so recover the already-complete stream in that case.
+        if (isEmptyToolInput(event.input)) {
+            const streamedInput = parseStreamedToolInput(state.byId.get(event.id)?.text ?? "");
+            if (streamedInput !== undefined)
+                event.input = streamedInput;
+        }
+        markStreamedToolInputDelivered(state, event.id);
+        return;
+    }
+    if (event.type === "tool-call-error") {
         markStreamedToolInputDelivered(state, event.id);
     }
 }
@@ -555,6 +567,9 @@ function parseStreamedToolInput(text) {
         return undefined;
     }
 }
+function isEmptyToolInput(input) {
+    return input == null || (isRecord(input) && Object.keys(input).length === 0);
+}
 // ---------------------------------------------------------------------------
 // Build tool_result blocks to append to messages after tool dispatch
 // ---------------------------------------------------------------------------

package/dist/agent/production-agent.d.ts

@@ -373,6 +373,14 @@ export interface ProductionAgentOptions {
     };
 }
 export declare function resolveAgentOwnerEmail(options: Pick<ProductionAgentOptions, "resolveOwnerEmail">, event: any): Promise<string | null>;
+/**
+ * A transient database failure in the completion callback used to prevent a
+ * background continuation from ever being handed off. Keep the retry bounded
+ * and database-only so a permanent persistence error still fails loudly.
+ */
+export declare function runCompletionCallbackWithDatabaseRetry(callback: () => void | Promise<void>, options?: {
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<void>;
 declare function generateRunId(): string;
 /** Check if an error is transient and should be retried
  * @internal exported for unit tests only

package/dist/agent/production-agent.js

@@ -5,7 +5,7 @@ import { parseA2AAgentActivityPart } from "../a2a/activity.js";
 import { describeToolParameterSignature, isAgentActionStopError, } from "../action.js";
 import { readAppState } from "../application-state/script-helpers.js";
 import { isReadOnlyShellCommand } from "../coding-tools/index.js";
-import { getDbExec } from "../db/client.js";
+import { getDbExec, isTransientDatabaseError } from "../db/client.js";
 import { extensionIdFromPathname } from "../extensions/path.js";
 import { preUploadAttachments } from "../file-upload/pre-upload-attachments.js";
 import { isMcpActionResult } from "../mcp-client/app-result.js";
@@ -620,6 +620,29 @@ export async function resolveAgentOwnerEmail(options, event) {
     return ownerEmail ?? getRequestUserEmail() ?? null;
 }
 const MAX_RETRIES = 3;
+const COMPLETION_DATABASE_RETRY_DELAYS_MS = [250, 750, 1_500];
+/**
+ * A transient database failure in the completion callback used to prevent a
+ * background continuation from ever being handed off. Keep the retry bounded
+ * and database-only so a permanent persistence error still fails loudly.
+ */
+export async function runCompletionCallbackWithDatabaseRetry(callback, options) {
+    const sleep = options?.sleep ??
+        ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    for (let attempt = 0;; attempt += 1) {
+        try {
+            await callback();
+            return;
+        }
+        catch (error) {
+            const retryDelay = COMPLETION_DATABASE_RETRY_DELAYS_MS[attempt];
+            if (!isTransientDatabaseError(error) || retryDelay === undefined) {
+                throw error;
+            }
+            await sleep(retryDelay);
+        }
+    }
+}
 /**
  * Retry budget override for `builder_gateway_error` — the no-detail Builder
  * gateway fallback. Production data shows this code is almost never
@@ -6981,7 +7004,7 @@ export function createProductionAgentHandler(options) {
         const baseHandleRunComplete = options.onRunComplete || trackedProgressRunId
             ? async (run) => {
                 try {
-                    await options.onRunComplete?.(run, threadId);
+                    await runCompletionCallbackWithDatabaseRetry(() => options.onRunComplete?.(run, threadId));
                 }
                 catch (err) {
                     await completeTrackedProgressRun(run, err);

package/dist/agent/run-manager.js

@@ -448,6 +448,11 @@ function terminalEventForcesErroredStatus(event) {
     return event?.type === "error" || event?.type === "missing_api_key";
 }
 function terminalReasonForRun(finalStatus, terminalEvent, abortReason, completionError) {
+    if (finalStatus !== "aborted" &&
+        completionError &&
+        terminalEvent?.type === "auto_continue") {
+        return "completion_error";
+    }
     if (terminalEvent?.type === "auto_continue") {
         return terminalEvent.reason || "auto_continue";
     }
@@ -1295,13 +1300,18 @@ export function startRun(runId, threadId, runFn, onComplete, options) {
                 : terminalEventForCompletion?.event.type === "error" ||
                     terminalEventForCompletion?.event.type === "missing_api_key"
                     ? terminalEventForCompletion.event
-                    : terminalEventForCompletion?.event.type === "auto_continue"
+                    : terminalEventForCompletion?.event.type === "auto_continue" &&
+                        run.continuationTerminalEvent
                         ? // The run was checkpointed at a soft-timeout/loop boundary and
                             // is recoverable: the partial turn is in agent_run_events and
-                            // the continuation run will re-attempt the thread_data save.
+                            // the handed-off continuation run will re-attempt the
+                            // thread_data save.
                             // Even though the completion save failed (finalStatus stays
                             // "errored" for SQL/diagnostics), re-emit the auto_continue so
-                            // the client resumes instead of seeing a dead chat.
+                            // the client resumes instead of seeing a dead chat. A
+                            // pending auto_continue without this handoff marker is not
+                            // recoverable: advertising it makes the client poll a dead
+                            // run until it reports background_run_lost.
                             terminalEventForCompletion.event
                         : {
                             type: "error",

package/dist/automations/service.d.ts

@@ -1,6 +1,8 @@
 import { type JobFrontmatter } from "../jobs/frontmatter.js";
 import { type Resource } from "../resources/store.js";
 export type AutomationScope = "personal" | "organization";
+/** Conservative default for new scheduled automations when no cadence is given. */
+export declare const DEFAULT_AUTOMATION_SCHEDULE = "0 * * * *";
 export interface AutomationActor {
     userEmail: string;
     orgId?: string | null;

package/dist/automations/service.js

@@ -4,6 +4,8 @@ import { buildJobResourceContent, jobBelongsToApp, normalizeJobMcpTools, parseJo
 import { deleteAutomationRuns } from "../jobs/run-history.js";
 import { resolveUserSchedulingTimezone } from "../localization/user-timezone.js";
 import { organizationIdFromResourceOwner, organizationResourceOwner, resourceDelete, resourceGetByPath, resourceList, resourcePut, } from "../resources/store.js";
+/** Conservative default for new scheduled automations when no cadence is given. */
+export const DEFAULT_AUTOMATION_SCHEDULE = "0 * * * *";
 function httpError(message, statusCode) {
     return Object.assign(new Error(message), { statusCode });
 }
@@ -181,7 +183,9 @@ export async function defineAutomation(actorInput, input) {
     const body = input.body.trim();
     if (!body)
         throw httpError("body is required.", 400);
-    const schedule = input.schedule?.trim() ?? "";
+    const schedule = input.triggerType === "schedule"
+        ? input.schedule?.trim() || DEFAULT_AUTOMATION_SCHEDULE
+        : "";
     const event = input.event?.trim() ?? "";
     if (input.triggerType === "schedule" && !isValidCron(schedule)) {
         throw httpError(schedule

package/dist/chat-threads/schema.d.ts

@@ -441,14 +441,14 @@ export declare const chatThreadShares: import("drizzle-orm/sqlite-core").SQLiteT
             tableName: string;
             dataType: "string";
             columnType: "SQLiteText";
-            data: "admin" | "editor" | "viewer";
+            data: "admin" | "commenter" | "editor" | "viewer";
             driverParam: string;
             notNull: true;
             hasDefault: true;
             isPrimaryKey: false;
             isAutoincrement: false;
             hasRuntimeDefault: false;
-            enumValues: ["viewer", "editor", "admin"];
+            enumValues: ["viewer", "commenter", "editor", "admin"];
             baseColumn: never;
             identity: undefined;
             generated: undefined;

package/dist/cli/changelog.js

@@ -15,6 +15,7 @@
 import fs from "fs";
 import path from "path";
 import { parsePendingEntry, parseChangelog, rollupChangelog, changelogSlug, CHANGELOG_HEADER, } from "../changelog/parse.js";
+import { createAgentNativeConfigContext, loadResolvedAgentNativeConfig, } from "../vite/agent-native-config-loader.js";
 const CHANGELOG_FILE = "CHANGELOG.md";
 const PENDING_DIR = "changelog";
 function todayIso() {
@@ -61,9 +62,23 @@ function printUsage() {
         "",
         "Entries are user-facing notes. `add` writes a pending file under",
         `  ${PENDING_DIR}/; \`release\` rolls all pending files into ${CHANGELOG_FILE}.`,
+        "Generation requires changelog.enabled: true in agent-native.config.ts.",
     ].join("\n"));
 }
-function cmdAdd(args) {
+async function changelogGenerationEnabled() {
+    const config = await loadResolvedAgentNativeConfig(process.cwd(), createAgentNativeConfigContext("serve", "cli"));
+    return config.changelog?.enabled === true;
+}
+async function requireChangelogGeneration(operation) {
+    if (await changelogGenerationEnabled())
+        return true;
+    console.error(`Changelog ${operation} is disabled by default. Set ` +
+        `changelog: { enabled: true } in agent-native.config.ts to enable it.`);
+    return false;
+}
+async function cmdAdd(args) {
+    if (!(await requireChangelogGeneration("add")))
+        return 1;
     const { flags, rest } = parseFlags(args);
     const summary = rest.join(" ").trim();
     if (!summary) {
@@ -101,7 +116,9 @@ function readPending() {
         content: fs.readFileSync(path.join(dir, f), "utf-8"),
     }));
 }
-function cmdRelease(args) {
+async function cmdRelease(args) {
+    if (!(await requireChangelogGeneration("release")))
+        return 1;
     const { flags } = parseFlags(args);
     const date = flags.date?.match(/\d{4}-\d{2}-\d{2}/)?.[0] ?? todayIso();
     const pendingFiles = readPending();
@@ -144,9 +161,9 @@ export async function runChangelog(args) {
     const rest = args.slice(1);
     switch (sub) {
         case "add":
-            return cmdAdd(rest);
+            return await cmdAdd(rest);
         case "release":
-            return cmdRelease(rest);
+            return await cmdRelease(rest);
         case "list":
             return cmdList();
         case undefined:

package/dist/cli/create.d.ts

@@ -156,11 +156,21 @@ export declare function detectWorkspace(startDir: string): {
 } | null;
 export { parseWorkspaceScope };
 /** @internal — exported for E2E tests */
-export { scaffoldWorkspaceRoot as _scaffoldWorkspaceRoot, ensureGuardedScaffold as _ensureGuardedScaffold, scaffoldAppTemplate as _scaffoldAppTemplate, scaffoldRequiredPackages as _scaffoldRequiredPackages, postProcessStandalone as _postProcessStandalone, loadCatalog as _loadCatalog, fixPackageJsonName as _fixPackageJsonName, renameGitignore as _renameGitignore, rewriteNetlifyToml as _rewriteNetlifyToml, getCoreDependencyVersion as _getCoreDependencyVersion, getDispatchDependencyVersion as _getDispatchDependencyVersion, getToolkitDependencyVersion as _getToolkitDependencyVersion, getCorePackageVersion as _getCorePackageVersion, getGitHubTemplateRef as _getGitHubTemplateRef, getGitHubTemplateRefCandidates as _getGitHubTemplateRefCandidates, githubTarballUrl as _githubTarballUrl, findLocalTemplateFrom as _findLocalTemplateFrom, workspaceAppNameForTemplateSelection as _workspaceAppNameForTemplateSelection, startShapePromptOptions as _startShapePromptOptions, standaloneTemplatePromptOptions as _standaloneTemplatePromptOptions, parseCommunityTemplateSelection as _parseCommunityTemplateSelection, communityTemplateTrustMessage as _communityTemplateTrustMessage, communityTemplateTarballUrl as _communityTemplateTarballUrl, assertCommunityTemplateRoot as _assertCommunityTemplateRoot, assertSafeCommunityArchiveListing as _assertSafeCommunityArchiveListing, validateCommunityArchive as _validateCommunityArchive, resolveCommunityTemplateSource as _resolveCommunityTemplateSource, discoverCommunityWorkspaceApps as _discoverCommunityWorkspaceApps, normalizeCommunityWorkspaceAppDependencies as _normalizeCommunityWorkspaceAppDependencies, shouldSkipScaffoldEntry as _shouldSkipScaffoldEntry, tarExtractArgs as _tarExtractArgs, downloadGitHubSubdir as _downloadGitHubSubdir, findLocalTemplate as _findLocalTemplate, templateSourceName as _templateSourceName, normalizeTemplateName as _normalizeTemplateName, appTitleForScaffold as _appTitleForScaffold, replacePlaceholders as _replacePlaceholders, rewriteTrackingAppId as _rewriteTrackingAppId, rewriteAgentChatAppId as _rewriteAgentChatAppId, applyScaffoldIdentity as _applyScaffoldIdentity, fixWebManifestName as _fixWebManifestName, copyDir as _copyDir, localTemplateSourceKind as _localTemplateSourceKind, REPO as _REPO, TEMPLATES_DIR as _TEMPLATES_DIR, };
+export { scaffoldWorkspaceRoot as _scaffoldWorkspaceRoot, ensureGuardedScaffold as _ensureGuardedScaffold, scaffoldAppTemplate as _scaffoldAppTemplate, scaffoldRequiredPackages as _scaffoldRequiredPackages, postProcessStandalone as _postProcessStandalone, loadCatalog as _loadCatalog, fixPackageJsonName as _fixPackageJsonName, renameGitignore as _renameGitignore, rewriteNetlifyToml as _rewriteNetlifyToml, getCoreDependencyVersion as _getCoreDependencyVersion, getDispatchDependencyVersion as _getDispatchDependencyVersion, getToolkitDependencyVersion as _getToolkitDependencyVersion, getCorePackageVersion as _getCorePackageVersion, getGitHubTemplateRef as _getGitHubTemplateRef, getGitHubTemplateRefCandidates as _getGitHubTemplateRefCandidates, githubTarballUrl as _githubTarballUrl, findLocalTemplateFrom as _findLocalTemplateFrom, workspaceAppNameForTemplateSelection as _workspaceAppNameForTemplateSelection, startShapePromptOptions as _startShapePromptOptions, standaloneTemplatePromptOptions as _standaloneTemplatePromptOptions, parseCommunityTemplateSelection as _parseCommunityTemplateSelection, communityTemplateTrustMessage as _communityTemplateTrustMessage, communityTemplateTarballUrl as _communityTemplateTarballUrl, assertCommunityTemplateRoot as _assertCommunityTemplateRoot, assertSafeCommunityArchiveListing as _assertSafeCommunityArchiveListing, validateCommunityArchive as _validateCommunityArchive, resolveCommunityTemplateSource as _resolveCommunityTemplateSource, discoverCommunityWorkspaceApps as _discoverCommunityWorkspaceApps, normalizeCommunityWorkspaceAppDependencies as _normalizeCommunityWorkspaceAppDependencies, shouldSkipScaffoldEntry as _shouldSkipScaffoldEntry, tarExtractArgs as _tarExtractArgs, extractTarball as _extractTarball, materializeArchiveSymlinks as _materializeArchiveSymlinks, downloadGitHubSubdir as _downloadGitHubSubdir, findLocalTemplate as _findLocalTemplate, templateSourceName as _templateSourceName, normalizeTemplateName as _normalizeTemplateName, appTitleForScaffold as _appTitleForScaffold, replacePlaceholders as _replacePlaceholders, rewriteTrackingAppId as _rewriteTrackingAppId, rewriteAgentChatAppId as _rewriteAgentChatAppId, applyScaffoldIdentity as _applyScaffoldIdentity, fixWebManifestName as _fixWebManifestName, copyDir as _copyDir, localTemplateSourceKind as _localTemplateSourceKind, REPO as _REPO, TEMPLATES_DIR as _TEMPLATES_DIR, };
 declare function tarExtractArgs(tarPath: string, destDir: string, options?: {
     skipAgentSymlinks?: boolean;
     untrustedCommunityArchive?: boolean;
+    additionalExcludes?: string[];
 }): string[];
+interface ArchiveSymlink {
+    archivePath: string;
+    target: string;
+}
+declare function materializeArchiveSymlinks(destDir: string, symlinks: ArchiveSymlink[]): void;
+declare function extractTarball(tarPath: string, destDir: string, options?: {
+    skipAgentSymlinks?: boolean;
+    untrustedCommunityArchive?: boolean;
+}): void;
 declare function validateCommunityArchive(tarPath: string): void;
 declare function assertSafeCommunityArchiveListing(listing: string): void;
 /** Resolves to the ref that actually succeeded so callers can record it. */
@@ -227,5 +237,6 @@ declare function renameGitignore(dir: string): void;
 declare function replacePlaceholders(dir: string, appName: string, appTitle: string, workspaceName?: string): void;
 declare function copyDir(src: string, dest: string, root?: string, opts?: {
     skipExisting?: boolean;
+    materializeSymlinks?: boolean;
 }): void;
 declare function shouldSkipScaffoldEntry(name: string, srcPath?: string): boolean;

package/dist/cli/create.js

@@ -1700,7 +1700,7 @@ export function detectWorkspace(startDir) {
 }
 export { parseWorkspaceScope };
 /** @internal — exported for E2E tests */
-export { scaffoldWorkspaceRoot as _scaffoldWorkspaceRoot, ensureGuardedScaffold as _ensureGuardedScaffold, scaffoldAppTemplate as _scaffoldAppTemplate, scaffoldRequiredPackages as _scaffoldRequiredPackages, postProcessStandalone as _postProcessStandalone, loadCatalog as _loadCatalog, fixPackageJsonName as _fixPackageJsonName, renameGitignore as _renameGitignore, rewriteNetlifyToml as _rewriteNetlifyToml, getCoreDependencyVersion as _getCoreDependencyVersion, getDispatchDependencyVersion as _getDispatchDependencyVersion, getToolkitDependencyVersion as _getToolkitDependencyVersion, getCorePackageVersion as _getCorePackageVersion, getGitHubTemplateRef as _getGitHubTemplateRef, getGitHubTemplateRefCandidates as _getGitHubTemplateRefCandidates, githubTarballUrl as _githubTarballUrl, findLocalTemplateFrom as _findLocalTemplateFrom, workspaceAppNameForTemplateSelection as _workspaceAppNameForTemplateSelection, startShapePromptOptions as _startShapePromptOptions, standaloneTemplatePromptOptions as _standaloneTemplatePromptOptions, parseCommunityTemplateSelection as _parseCommunityTemplateSelection, communityTemplateTrustMessage as _communityTemplateTrustMessage, communityTemplateTarballUrl as _communityTemplateTarballUrl, assertCommunityTemplateRoot as _assertCommunityTemplateRoot, assertSafeCommunityArchiveListing as _assertSafeCommunityArchiveListing, validateCommunityArchive as _validateCommunityArchive, resolveCommunityTemplateSource as _resolveCommunityTemplateSource, discoverCommunityWorkspaceApps as _discoverCommunityWorkspaceApps, normalizeCommunityWorkspaceAppDependencies as _normalizeCommunityWorkspaceAppDependencies, shouldSkipScaffoldEntry as _shouldSkipScaffoldEntry, tarExtractArgs as _tarExtractArgs, downloadGitHubSubdir as _downloadGitHubSubdir, findLocalTemplate as _findLocalTemplate, templateSourceName as _templateSourceName, normalizeTemplateName as _normalizeTemplateName, appTitleForScaffold as _appTitleForScaffold, replacePlaceholders as _replacePlaceholders, rewriteTrackingAppId as _rewriteTrackingAppId, rewriteAgentChatAppId as _rewriteAgentChatAppId, applyScaffoldIdentity as _applyScaffoldIdentity, fixWebManifestName as _fixWebManifestName, copyDir as _copyDir, localTemplateSourceKind as _localTemplateSourceKind, REPO as _REPO, TEMPLATES_DIR as _TEMPLATES_DIR, };
+export { scaffoldWorkspaceRoot as _scaffoldWorkspaceRoot, ensureGuardedScaffold as _ensureGuardedScaffold, scaffoldAppTemplate as _scaffoldAppTemplate, scaffoldRequiredPackages as _scaffoldRequiredPackages, postProcessStandalone as _postProcessStandalone, loadCatalog as _loadCatalog, fixPackageJsonName as _fixPackageJsonName, renameGitignore as _renameGitignore, rewriteNetlifyToml as _rewriteNetlifyToml, getCoreDependencyVersion as _getCoreDependencyVersion, getDispatchDependencyVersion as _getDispatchDependencyVersion, getToolkitDependencyVersion as _getToolkitDependencyVersion, getCorePackageVersion as _getCorePackageVersion, getGitHubTemplateRef as _getGitHubTemplateRef, getGitHubTemplateRefCandidates as _getGitHubTemplateRefCandidates, githubTarballUrl as _githubTarballUrl, findLocalTemplateFrom as _findLocalTemplateFrom, workspaceAppNameForTemplateSelection as _workspaceAppNameForTemplateSelection, startShapePromptOptions as _startShapePromptOptions, standaloneTemplatePromptOptions as _standaloneTemplatePromptOptions, parseCommunityTemplateSelection as _parseCommunityTemplateSelection, communityTemplateTrustMessage as _communityTemplateTrustMessage, communityTemplateTarballUrl as _communityTemplateTarballUrl, assertCommunityTemplateRoot as _assertCommunityTemplateRoot, assertSafeCommunityArchiveListing as _assertSafeCommunityArchiveListing, validateCommunityArchive as _validateCommunityArchive, resolveCommunityTemplateSource as _resolveCommunityTemplateSource, discoverCommunityWorkspaceApps as _discoverCommunityWorkspaceApps, normalizeCommunityWorkspaceAppDependencies as _normalizeCommunityWorkspaceAppDependencies, shouldSkipScaffoldEntry as _shouldSkipScaffoldEntry, tarExtractArgs as _tarExtractArgs, extractTarball as _extractTarball, materializeArchiveSymlinks as _materializeArchiveSymlinks, downloadGitHubSubdir as _downloadGitHubSubdir, findLocalTemplate as _findLocalTemplate, templateSourceName as _templateSourceName, normalizeTemplateName as _normalizeTemplateName, appTitleForScaffold as _appTitleForScaffold, replacePlaceholders as _replacePlaceholders, rewriteTrackingAppId as _rewriteTrackingAppId, rewriteAgentChatAppId as _rewriteAgentChatAppId, applyScaffoldIdentity as _applyScaffoldIdentity, fixWebManifestName as _fixWebManifestName, copyDir as _copyDir, localTemplateSourceKind as _localTemplateSourceKind, REPO as _REPO, TEMPLATES_DIR as _TEMPLATES_DIR, };
 /* ─────────────────────────────────────────────────────────────────────────
  * Download / copy helpers
  * ───────────────────────────────────────────────────────────────────────── */
@@ -1712,12 +1712,14 @@ function validateRepoName(repo) {
     }
 }
 function tarExtractArgs(tarPath, destDir, options = {}) {
-    const excludes = options.skipAgentSymlinks
-        ? FIRST_PARTY_TARBALL_SYMLINK_EXCLUDES.flatMap((pattern) => [
-            "--exclude",
-            pattern,
-        ])
-        : [];
+    const excludePatterns = [
+        ...(options.skipAgentSymlinks ? FIRST_PARTY_TARBALL_SYMLINK_EXCLUDES : []),
+        ...(options.additionalExcludes ?? []),
+    ];
+    const excludes = [...new Set(excludePatterns)].flatMap((pattern) => [
+        "--exclude",
+        pattern,
+    ]);
     const safeOwnership = options.untrustedCommunityArchive
         ? ["--no-same-owner", "--no-same-permissions"]
         : [];
@@ -1731,6 +1733,79 @@ function tarExtractArgs(tarPath, destDir, options = {}) {
         destDir,
     ];
 }
+function archiveSymlinksForExtraction(tarPath) {
+    const listing = execFileSync("tar", ["tvzf", tarPath], {
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    return listing.split(/\r?\n/).flatMap((line) => {
+        if (!line.startsWith("l"))
+            return [];
+        const match = line.match(/\s(\S+)\s+->\s+(\S+)\s*$/);
+        return match ? [{ archivePath: match[1], target: match[2] }] : [];
+    });
+}
+function archivePathAfterStrip(archivePath) {
+    const parts = archivePath.split("/");
+    return parts.length > 1 ? parts.slice(1).join("/") : archivePath;
+}
+function isPathWithin(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return (relative === "" ||
+        (!relative.startsWith(`..${path.sep}`) &&
+            relative !== ".." &&
+            !path.isAbsolute(relative)));
+}
+function materializeArchiveSymlinks(destDir, symlinks) {
+    const links = new Map(symlinks.map((link) => [archivePathAfterStrip(link.archivePath), link]));
+    const active = new Set();
+    const materialize = (relativeLinkPath) => {
+        const link = links.get(relativeLinkPath);
+        if (!link)
+            return;
+        if (active.has(relativeLinkPath)) {
+            throw new Error(`Cannot materialize cyclic archive symlink "${relativeLinkPath}".`);
+        }
+        const linkPath = path.resolve(destDir, relativeLinkPath);
+        if (!isPathWithin(path.resolve(destDir), linkPath)) {
+            throw new Error(`Cannot materialize archive symlink outside the extraction directory: "${relativeLinkPath}".`);
+        }
+        if (fs.existsSync(linkPath))
+            return;
+        const resolvedTarget = path.resolve(path.dirname(linkPath), link.target);
+        if (!isPathWithin(path.resolve(destDir), resolvedTarget)) {
+            throw new Error(`Archive symlink "${relativeLinkPath}" points outside the extraction directory.`);
+        }
+        active.add(relativeLinkPath);
+        try {
+            const targetRelativePath = path.relative(path.resolve(destDir), resolvedTarget);
+            if (links.has(targetRelativePath) && !fs.existsSync(resolvedTarget)) {
+                materialize(targetRelativePath);
+            }
+            if (!fs.existsSync(resolvedTarget)) {
+                throw new Error(`Archive symlink "${relativeLinkPath}" points to a missing target.`);
+            }
+            fs.mkdirSync(path.dirname(linkPath), { recursive: true });
+            const targetStat = fs.statSync(resolvedTarget);
+            if (targetStat.isDirectory()) {
+                copyDir(resolvedTarget, linkPath, undefined, {
+                    materializeSymlinks: true,
+                });
+            }
+            else {
+                fs.copyFileSync(resolvedTarget, linkPath);
+            }
+        }
+        finally {
+            active.delete(relativeLinkPath);
+        }
+    };
+    // Resolve deeper links first so links such as `.claude/skills` see the
+    // regularized skill directories they point at.
+    for (const relativeLinkPath of [...links.keys()].sort((a, b) => b.length - a.length)) {
+        materialize(relativeLinkPath);
+    }
+}
 function execFileBuffer(command, args, options) {
     return new Promise((resolve, reject) => {
         execFile(command, args, { ...options, encoding: "buffer" }, (error, stdout, stderr) => {
@@ -1745,6 +1820,20 @@ function execFileBuffer(command, args, options) {
         });
     });
 }
+function extractTarball(tarPath, destDir, options = {}) {
+    const symlinks = options.skipAgentSymlinks || options.untrustedCommunityArchive
+        ? archiveSymlinksForExtraction(tarPath)
+        : [];
+    execFileSync("tar", tarExtractArgs(tarPath, destDir, {
+        ...options,
+        additionalExcludes: symlinks.map((link) => link.archivePath),
+    }), {
+        stdio: "pipe",
+    });
+    if (symlinks.length > 0) {
+        materializeArchiveSymlinks(destDir, symlinks);
+    }
+}
 async function downloadAndExtract(url, destDir, options = {}) {
     fs.mkdirSync(destDir, { recursive: true });
     // --fail-with-body so curl exits non-zero on HTTP 4xx/5xx instead of writing
@@ -1767,9 +1856,7 @@ async function downloadAndExtract(url, destDir, options = {}) {
         if (options.untrustedCommunityArchive) {
             validateCommunityArchive(tarPath);
         }
-        execFileSync("tar", tarExtractArgs(tarPath, destDir, options), {
-            stdio: "pipe",
-        });
+        extractTarball(tarPath, destDir, options);
     }
     finally {
         fs.unlinkSync(tarPath);
@@ -2854,7 +2941,8 @@ function copyDir(src, dest, root, opts) {
         if (entry.isSymbolicLink()) {
             const target = fs.readlinkSync(srcPath);
             const resolvedTarget = path.resolve(path.dirname(srcPath), target);
-            if (resolvedTarget.startsWith(resolvedRoot)) {
+            if (!opts?.materializeSymlinks &&
+                isPathWithin(resolvedRoot, resolvedTarget)) {
                 fs.symlinkSync(target, destPath);
             }
             else {

package/dist/cli/index.js

@@ -7,6 +7,7 @@ import { fileURLToPath } from "url";
 import * as Sentry from "@sentry/node";
 import { clearAgentNativeNitroPresetMarker, resolveAgentNativeNitroPreset, } from "../deploy/nitro-preset.js";
 import { resolveDeployPostBuildInvocation } from "./deploy-build.js";
+import { cliSpawnOptions } from "./process.js";
 import { shouldTrackCliRun } from "./telemetry-routing.js";
 import { createCliTelemetry } from "./telemetry.js";
 // Resolve version once at module scope — used by both --version and --help
@@ -381,11 +382,7 @@ function extractNodeInspectFlag(args) {
     return { inspectFlag, rest };
 }
 function run(cmd, cmdArgs, opts) {
-    const child = spawn(cmd, cmdArgs, {
-        stdio: opts?.stdio ?? "inherit",
-        shell: process.platform === "win32",
-        env: opts?.env ?? process.env,
-    });
+    const child = spawn(cmd, cmdArgs, cliSpawnOptions(opts));
     child.on("exit", (code) => process.exit(code ?? 0));
     // Forward signals to child so Cmd+C doesn't leave zombie processes holding ports
     for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"]) {
@@ -564,7 +561,10 @@ switch (command) {
             NITRO_DEV_RUNNER: process.env.NITRO_DEV_RUNNER ?? "node-process",
         };
         console.log(`[agent-native] API server debugger listening on ${target}`);
-        run(process.execPath, ["--import", preload, viteJsEntry, ...rest], { env });
+        run(process.execPath, ["--import", preload, viteJsEntry, ...rest], {
+            env,
+            shell: false,
+        });
         break;
     }
     case "workspace-dev": {

package/dist/cli/process.d.ts

@@ -0,0 +1,7 @@
+import type { SpawnOptions } from "node:child_process";
+/**
+ * Keep Windows command-name launches compatible with `.cmd` shims while
+ * allowing callers that already have a real executable path to opt out of the
+ * shell. The latter is important for paths such as `C:\\Program Files\\nodejs\\node.exe`.
+ */
+export declare function cliSpawnOptions(options?: Pick<SpawnOptions, "env" | "shell" | "stdio">, platform?: NodeJS.Platform): Pick<SpawnOptions, "env" | "shell" | "stdio">;

package/dist/cli/process.js

@@ -0,0 +1,12 @@
+/**
+ * Keep Windows command-name launches compatible with `.cmd` shims while
+ * allowing callers that already have a real executable path to opt out of the
+ * shell. The latter is important for paths such as `C:\\Program Files\\nodejs\\node.exe`.
+ */
+export function cliSpawnOptions(options = {}, platform = process.platform) {
+    return {
+        stdio: options.stdio ?? "inherit",
+        shell: options.shell ?? platform === "win32",
+        env: options.env ?? process.env,
+    };
+}

package/dist/cli/workspace-skill-policy.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Skills every generated workspace app can use without an app-local copy.
+ *
+ * Keep this list deliberately small. Skills outside this list remain available
+ * in the framework source and can be opted into by adding them to the
+ * workspace core or to the app that actually needs them.
+ */
+export declare const DEFAULT_WORKSPACE_SKILLS: readonly ["actions", "adding-a-feature", "agent-native-docs", "agent-native-toolkit", "context-awareness", "customizing-agent-native", "delegate-to-agent", "frontend-design", "turn-into-app", "turn-into-skill", "real-time-sync", "secrets", "security", "self-modifying-code", "shadcn-ui", "sharing", "storing-data", "portability", "workspace-conventions"];
+/**
+ * Framework skills that templates may carry before they are transformed into
+ * workspace apps. Workspacify removes these copies because the workspace core
+ * owns the inherited skill surface. App-specific skill names are intentionally
+ * not listed here and remain local.
+ */
+export declare const FRAMEWORK_TEMPLATE_SHARED_SKILLS: readonly ["actions", "agent-native-docs", "agent-native-toolkit", "adding-a-feature", "capture-learnings", "client-methods", "create-skill", "customizing-agent-native", "delegate-to-agent", "frontend-design", "feature-flags", "integration-webhooks", "internationalization", "onboarding", "performance", "real-time-collab", "real-time-sync", "security", "self-modifying-code", "shadcn-ui", "secrets", "storing-data", "sharing", "turn-into-app", "turn-into-skill", "upgrade-agent-native"];