@agent-native/core 0.210.0 → 0.210.1-nightly-20261020010058

package/dist/action.js

@@ -1026,7 +1026,22 @@ function zodDefToJsonSchema(def) {
         return result;
     }
     if (type === "literal") {
-        return { type: typeof def.value, enum: [def.value] };
+        const values = Array.isArray(def.values)
+            ? def.values
+            : def.values instanceof Set
+                ? [...def.values]
+                : [def.value];
+        const jsonTypeOf = (value) => value === null ? "null" : typeof value;
+        const uniqueTypes = [...new Set(values.map(jsonTypeOf))];
+        if (uniqueTypes.length === 1) {
+            return { type: uniqueTypes[0], enum: values };
+        }
+        return {
+            anyOf: values.map((value) => ({
+                type: jsonTypeOf(value),
+                enum: [value],
+            })),
+        };
     }
     if (type === "array") {
         const result = { type: "array" };

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

@@ -631,6 +631,7 @@ export interface ExecuteAgentToolCallOptions {
     onApprovalRequired?: (binding: AgentApprovalBinding) => Promise<string | void>;
     consumeApproval?: (binding: AgentApprovalBinding) => Promise<boolean>;
     isToolAlwaysAllowed?: (binding: AgentApprovalBinding) => Promise<boolean>;
+    beforeWrite?: () => Promise<void>;
     send?: (event: AgentChatEvent) => void;
 }
 export interface AgentApprovalBinding {

package/dist/agent/production-agent.js

@@ -3427,6 +3427,7 @@ export async function executeAgentToolCall(options) {
             onApprovalRequired: options.onApprovalRequired,
             consumeApproval: options.consumeApproval,
             isToolAlwaysAllowed: options.isToolAlwaysAllowed,
+            beforeWrite: options.beforeWrite,
         });
     }
     catch (error) {
@@ -11050,6 +11051,7 @@ export function createProductionAgentHandler(options) {
                         onApprovalRequired: approvalHooks.onApprovalRequired,
                         consumeApproval: approvalHooks.consumeApproval,
                         isToolAlwaysAllowed: approvalHooks.isToolAlwaysAllowed,
+                        beforeWrite: agentLoopOpts.beforeWrite,
                         send,
                     });
                     if (approvedExecution.status === "approval_required" ||

package/dist/agent/reaped-run-thread.d.ts

@@ -13,4 +13,4 @@
 export declare function foldReapedRunIntoThread(runId: string, terminalError?: {
     error: string;
     errorCode: string;
-}): Promise<void>;
+}): Promise<"projected" | "superseded" | "retry">;

package/dist/agent/reaped-run-thread.js

@@ -1,4 +1,5 @@
 import { getThread, updateThreadData, withThreadDataLock, } from "../chat-threads/store.js";
+import { RUN_NOT_STARTED_METADATA_KEY } from "../shared/agent-chat-run-not-started.js";
 import { readStoppedRunForThreadFold } from "./run-store.js";
 import { buildAssistantMessage, extractThreadMeta, foldAssistantTurn, isRunPrompt, normalizeThreadRepository, } from "./thread-data-builder.js";
 /**
@@ -16,7 +17,7 @@ import { buildAssistantMessage, extractThreadMeta, foldAssistantTurn, isRunPromp
 export async function foldReapedRunIntoThread(runId, terminalError) {
     const run = await readStoppedRunForThreadFold(runId);
     if (!run || run.laterTurnStarted)
-        return;
+        return "superseded";
     const events = [...run.events];
     if (terminalError) {
         const last = events.at(-1);
@@ -45,18 +46,19 @@ export async function foldReapedRunIntoThread(runId, terminalError) {
         suppressInternalContinuation: run.continuedInTurn,
     });
     if (!assistant)
-        return;
-    await withThreadDataLock(run.threadId, async () => {
+        return "projected";
+    return withThreadDataLock(run.threadId, async () => {
         const thread = await getThread(run.threadId);
         if (!thread)
-            return;
+            return "superseded";
         const repo = normalizeThreadRepository(JSON.parse(thread.threadData || "{}"));
         const folded = foldAssistantTurn(repo, assistant, {
             runId,
             turnId: run.turnId,
         });
         const meta = extractThreadMeta(folded);
-        await updateThreadData(run.threadId, JSON.stringify(folded), thread.title, meta.preview || thread.preview, folded.messages.length, {
+        let rejectedDisposition = "superseded";
+        const updated = await updateThreadData(run.threadId, JSON.stringify(folded), thread.title, meta.preview || thread.preview, folded.messages.length, {
             beforeUpdate: async (tx) => {
                 await tx.execute({
                     sql: "SELECT pg_advisory_xact_lock(hashtextextended(?, 0::bigint))",
@@ -88,11 +90,24 @@ export async function foldReapedRunIntoThread(runId, terminalError) {
                     return false;
                 const currentRepo = normalizeThreadRepository(JSON.parse(currentThreadData || "{}"));
                 const last = currentRepo.messages.at(-1)?.message ?? currentRepo.messages.at(-1);
-                return last?.role === "user"
+                const ownsPrompt = last?.role === "user"
                     ? isRunPrompt(last, { runId, ...run })
                     : last?.role === "assistant" &&
                         last.metadata?.custom?.turnId === run.turnId;
+                const unstartedTurnId = last?.role === "user"
+                    ? last.metadata?.custom?.submittedTurnId
+                    : last?.role === "assistant"
+                        ? last.metadata?.custom?.turnId
+                        : undefined;
+                const isRefusedNewerTurn = last?.metadata?.custom?.[RUN_NOT_STARTED_METADATA_KEY] === true &&
+                    typeof unstartedTurnId === "string" &&
+                    unstartedTurnId !== run.turnId;
+                if (!ownsPrompt && !isRefusedNewerTurn) {
+                    rejectedDisposition = "retry";
+                }
+                return ownsPrompt;
             },
         });
+        return updated ? "projected" : rejectedDisposition;
     });
 }

package/dist/agent/run-store.fencing.worker.js

@@ -1,9 +1,11 @@
 import { writeSync } from "node:fs";
 import postgres from "postgres";
+import { ensureChatThreadTables, getThread, markQueuedSubmissionSubmitted, updateThreadData, } from "../chat-threads/store.js";
 import { toPostgresParams, withDbExec } from "../db/client.js";
 import { withMigrationRuntime } from "../db/migration-runtime.js";
 import { withExecutionFence } from "./execution-fence.js";
 import { beginAgentExecutionStep, claimTurnExecutionLease, completeAgentExecutionStep, ensureRunTables, insertRun, insertRunEvent, markAgentExecutionStepDispatched, } from "./run-store.js";
+import { applySubmittedUserMessage, buildUserMessage, extractThreadMeta, } from "./thread-data-builder.js";
 function executor(sql) {
     return {
         async execute(statement) {
@@ -54,6 +56,62 @@ async function main() {
                 process.stdout.write(JSON.stringify({ status: "unexpected-write" }));
                 return;
             }
+            if (mode === "queue-submit") {
+                await withMigrationRuntime(() => ensureChatThreadTables());
+                const input = JSON.parse(extra ?? "null");
+                const thread = await getThread(threadId);
+                if (!thread)
+                    throw new Error(`Missing queued-message thread ${threadId}`);
+                const userMessage = buildUserMessage({
+                    text: input.message.text,
+                    runId,
+                    queuedMessageId: input.message.id,
+                });
+                let submissionFailure;
+                let pauseBeforeWrite = true;
+                const updated = await updateThreadData(threadId, "{}", thread.title, thread.preview, thread.messageCount, {
+                    transformThreadData: (threadData) => {
+                        const result = applySubmittedUserMessage(JSON.parse(threadData || "{}"), userMessage, {
+                            id: input.message.id,
+                            claimId: input.claimId,
+                            now: Date.now(),
+                        });
+                        if (!("repo" in result)) {
+                            submissionFailure = result.status;
+                            return threadData;
+                        }
+                        const meta = extractThreadMeta(result.repo);
+                        return {
+                            threadData: JSON.stringify(result.repo),
+                            preview: meta.preview || thread.preview,
+                        };
+                    },
+                    beforeUpdate: async () => {
+                        if (pauseBeforeWrite) {
+                            pauseBeforeWrite = false;
+                            writeSync(1, `${JSON.stringify({ ready: true })}\n`);
+                            await waitForContinue();
+                        }
+                        return !submissionFailure;
+                    },
+                    afterUpdate: async (tx) => {
+                        if (submissionFailure)
+                            return;
+                        await markQueuedSubmissionSubmitted(tx, {
+                            threadId,
+                            messageId: input.message.id,
+                            runId,
+                            actor: input.actor,
+                            message: input.message,
+                        });
+                    },
+                });
+                writeSync(1, JSON.stringify({
+                    status: submissionFailure ?? "submitted",
+                    updated,
+                }));
+                return;
+            }
             await insertRun(runId, threadId, turnId);
             const fence = await claimTurnExecutionLease(threadId, turnId, runId);
             if (mode === "claim") {

package/dist/agent/run-store.js

@@ -2123,10 +2123,10 @@ async function reapSingleStaleRun(runId, source, maxStaleMs) {
                     args: [runScope.thread_id, runScope.turn_id, runId, lease.generation],
                 });
             }
-            outcome =
-                lease && !generationMatches
-                    ? { outcome: "execution_lease_changed" }
-                    : await attemptStaleRunRecovery(tx, runId);
+            const executionLeaseChanged = !generationMatches && (lease !== null || run.worker_generation != null);
+            outcome = executionLeaseChanged
+                ? { outcome: "execution_lease_changed" }
+                : await attemptStaleRunRecovery(tx, runId);
             await appendTerminalRunEventInTransaction(tx, runId, STALE_RUN_ERROR_EVENT);
             if (outcome.outcome !== "execution_lease_changed") {
                 const projection = await tx.execute({
@@ -3555,7 +3555,9 @@ async function finalizeStaleRun(runId, source, projectThread = true) {
         return true;
     try {
         const { foldReapedRunIntoThread } = await import("./reaped-run-thread.js");
-        await foldReapedRunIntoThread(runId);
+        const disposition = await foldReapedRunIntoThread(runId);
+        if (disposition === "retry")
+            return false;
         await getDbExec().execute({
             sql: `UPDATE agent_runs
             SET thread_projection_pending = FALSE

package/dist/agent/run-thread-projector.d.ts

@@ -0,0 +1,27 @@
+import { buildAssistantMessage } from "./thread-data-builder.js";
+import type { RunEvent } from "./types.js";
+interface BuildJournalAssistantMessageOptions {
+    suppressInternalContinuation?: boolean;
+    preserveUnknownToolOutcomes?: boolean;
+    scope?: {
+        type: string;
+        id: string;
+    } | null;
+    runDurationMs?: number;
+}
+export declare class RunTranscriptJournalGapError extends Error {
+    readonly runId: string;
+    readonly missingSequences: number[];
+    constructor(runId: string, missingSequences: number[]);
+}
+/** Builds assistant content from the durable event journal and verifies that
+ * every published nonterminal event reached that journal before projection.
+ */
+export declare function buildAssistantMessageFromRunJournal(input: {
+    threadId: string;
+    turnId: string;
+    runId: string;
+    runEvents: readonly RunEvent[];
+    options?: BuildJournalAssistantMessageOptions;
+}): Promise<ReturnType<typeof buildAssistantMessage>>;
+export {};

package/dist/agent/run-thread-projector.js

@@ -0,0 +1,79 @@
+import { CHECKPOINT_TERMINAL_EVENT_SEQ, getCurrentTurnRunEventsForThread, } from "./run-store.js";
+import { buildAssistantMessage, foldAssistantTurn, } from "./thread-data-builder.js";
+export class RunTranscriptJournalGapError extends Error {
+    runId;
+    missingSequences;
+    constructor(runId, missingSequences) {
+        super(`Run transcript journal is missing events for ${runId}: ${missingSequences.join(", ")}`);
+        this.runId = runId;
+        this.missingSequences = missingSequences;
+        this.name = "RunTranscriptJournalGapError";
+    }
+}
+function isTerminalProjectionEvent(event) {
+    return (event.type === "done" ||
+        event.type === "error" ||
+        event.type === "missing_api_key" ||
+        event.type === "loop_limit" ||
+        event.type === "auto_continue");
+}
+/** Builds assistant content from the durable event journal and verifies that
+ * every published nonterminal event reached that journal before projection.
+ */
+export async function buildAssistantMessageFromRunJournal(input) {
+    const turnJournal = await getCurrentTurnRunEventsForThread(input.threadId, input.turnId);
+    const currentRunPersisted = turnJournal.filter((event) => event.runId === input.runId && event.seq < CHECKPOINT_TERMINAL_EVENT_SEQ);
+    const persistedSequences = new Set(currentRunPersisted.map(({ seq }) => seq));
+    const missingSequences = input.runEvents
+        .filter(({ seq, event }) => !isTerminalProjectionEvent(event) && !persistedSequences.has(seq))
+        .map(({ seq }) => seq);
+    if (missingSequences.length > 0) {
+        throw new RunTranscriptJournalGapError(input.runId, missingSequences);
+    }
+    const currentRunEndIndex = turnJournal.reduce((lastIndex, { runId }, index) => runId === input.runId ? index : lastIndex, -1);
+    const relevantJournal = currentRunEndIndex === -1
+        ? []
+        : turnJournal
+            .slice(0, currentRunEndIndex + 1)
+            .filter(({ runId, seq }) => runId !== input.runId || seq < CHECKPOINT_TERMINAL_EVENT_SEQ);
+    const runGroups = new Map();
+    for (const { runId, seq, event } of relevantJournal) {
+        const events = runGroups.get(runId) ?? [];
+        events.push({ seq, event });
+        runGroups.set(runId, events);
+    }
+    if (!runGroups.has(input.runId))
+        runGroups.set(input.runId, []);
+    let repo = { messages: [] };
+    for (const [runId, persistedRunEvents] of runGroups) {
+        const runEvents = persistedRunEvents.sort((left, right) => left.seq - right.seq);
+        if (runId === input.runId) {
+            for (const event of input.runEvents) {
+                if (isTerminalProjectionEvent(event.event) &&
+                    !persistedSequences.has(event.seq)) {
+                    runEvents.push(event);
+                }
+            }
+            runEvents.sort((left, right) => left.seq - right.seq);
+        }
+        const assistant = buildAssistantMessage(runEvents, runId, runId === input.runId
+            ? { ...input.options, turnId: input.turnId }
+            : {
+                suppressInternalContinuation: input.options?.suppressInternalContinuation,
+                preserveUnknownToolOutcomes: input.options?.preserveUnknownToolOutcomes,
+                scope: input.options?.scope,
+                turnId: input.turnId,
+            });
+        if (!assistant)
+            continue;
+        repo = foldAssistantTurn(repo, assistant, {
+            runId,
+            turnId: input.turnId,
+        });
+    }
+    const entry = repo.messages.at(-1);
+    const message = entry && typeof entry === "object" && "message" in entry
+        ? entry.message
+        : entry;
+    return (message ?? null);
+}

package/dist/agent/thread-data-builder.js

@@ -3415,7 +3415,7 @@ function assistantContentWeight(content) {
     }
     return weight;
 }
-function appendFoldedContent(existing, incoming) {
+function appendFoldedContent(existing, incoming, separateRunBoundary = false) {
     const merged = existing.map((p) => ({ ...p }));
     for (const part of incoming) {
         if (part?.type === "tool-call" && part.result !== undefined) {
@@ -3441,11 +3441,12 @@ function appendFoldedContent(existing, incoming) {
             typeof part.text === "string" &&
             last?.type === "text" &&
             typeof last.text === "string") {
-            last.text = `${last.text}${part.text}`;
+            last.text = `${last.text}${separateRunBoundary ? "\n\n" : ""}${part.text}`;
         }
         else {
             merged.push({ ...part });
         }
+        separateRunBoundary = false;
     }
     return normalizeAssistantToolCallIds({
         role: "assistant",
@@ -3476,15 +3477,34 @@ export function foldAssistantTurn(repo, assistantMsg, options) {
         ? assistantMsg.content
         : [];
     const existingFolded = foldedRunIdsOf(lastMsg);
+    const incomingFolded = foldedRunIdsOf(assistantMsg);
     const runAlreadyFolded = !!runId &&
         (existingFolded.includes(runId) || getMessageRunId(lastMsg) === runId);
-    const mergedContent = runAlreadyFolded
-        ? assistantContentWeight(incomingContent) >
-            assistantContentWeight(existingContent)
-            ? incomingContent
-            : existingContent
-        : appendFoldedContent(existingContent, incomingContent);
-    const mergedFolded = Array.from(new Set([...existingFolded, ...(runId ? [runId] : [])]));
+    const supersededRunReplay = runAlreadyFolded && !!runId && getMessageRunId(lastMsg) !== runId;
+    const incomingCoversExistingRuns = existingFolded.length > 0 &&
+        !!runId &&
+        incomingFolded.includes(runId) &&
+        existingFolded.every((foldedRunId) => incomingFolded.includes(foldedRunId));
+    let mergedContent = existingContent;
+    if (!supersededRunReplay) {
+        if (incomingCoversExistingRuns) {
+            mergedContent = incomingContent;
+        }
+        else if (runAlreadyFolded) {
+            if (assistantContentWeight(incomingContent) >
+                assistantContentWeight(existingContent)) {
+                mergedContent = incomingContent;
+            }
+        }
+        else {
+            mergedContent = appendFoldedContent(existingContent, incomingContent, lastMsg.status?.type === "incomplete");
+        }
+    }
+    const mergedFolded = Array.from(new Set([
+        ...existingFolded,
+        ...(supersededRunReplay ? [] : incomingFolded),
+        ...(runId ? [runId] : []),
+    ]));
     const existingCustom = lastMsg.metadata?.custom && typeof lastMsg.metadata.custom === "object"
         ? lastMsg.metadata.custom
         : {};
@@ -3494,7 +3514,7 @@ export function foldAssistantTurn(repo, assistantMsg, options) {
         : {};
     const mergedCustom = {
         ...existingCustom,
-        ...incomingCustom,
+        ...(supersededRunReplay ? {} : incomingCustom),
         turnId,
         foldedRunIds: mergedFolded,
     };
@@ -3512,8 +3532,9 @@ export function foldAssistantTurn(repo, assistantMsg, options) {
     if (mergedDurationMs != null) {
         mergedCustom[ASSISTANT_RUN_DURATION_METADATA_KEY] = mergedDurationMs;
     }
-    if (incomingCustom.continued !== true)
+    if (!supersededRunReplay && incomingCustom.continued !== true) {
         delete mergedCustom.continued;
+    }
     // A turn's failure is its newest run's: a run that continued past an
     // earlier stop clears the stop's error instead of inheriting it.
     if (!runAlreadyFolded && incomingCustom.runError === undefined) {
@@ -3525,10 +3546,14 @@ export function foldAssistantTurn(repo, assistantMsg, options) {
             role: "assistant",
             content: mergedContent,
         }).content,
-        status: assistantMsg.status ?? lastMsg.status,
+        status: supersededRunReplay
+            ? lastMsg.status
+            : (assistantMsg.status ?? lastMsg.status),
         metadata: {
             ...lastMsg.metadata,
-            runId: runId ?? lastMsg.metadata?.runId,
+            runId: supersededRunReplay
+                ? lastMsg.metadata?.runId
+                : (runId ?? lastMsg.metadata?.runId),
             custom: mergedCustom,
         },
     };

package/dist/automation/index.d.ts

@@ -139,8 +139,8 @@ export declare function createAutomationCallbackHandler(runtime: AutomationRunti
     duplicate?: undefined;
     eventId?: undefined;
 } | {
-    error?: undefined;
     accepted: boolean;
     duplicate: boolean;
     eventId: string;
+    error?: undefined;
 }>;

package/dist/cli/create.d.ts

@@ -183,5 +183,5 @@ declare function replacePlaceholders(dir: string, appName: string, appTitle: str
 declare function copyDir(src: string, dest: string, root?: string, opts?: {
     skipExisting?: boolean;
     materializeSymlinks?: boolean;
-}): void;
+}, destinationRoot?: string): void;
 declare function shouldSkipScaffoldEntry(name: string, srcPath?: string): boolean;

package/dist/cli/create.js

@@ -5,7 +5,8 @@ import path from "path";
 import { fileURLToPath, pathToFileURL } from "url";
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 import { DISPATCH_WORKSPACE_ROOT_REDIRECTS, getWorkspaceAppIdValidationError, } from "../shared/workspace-app-id.js";
-import { setupAgentSymlinks } from "./setup-agents.js";
+import { createAgentSymlink, prepareAgentSymlink, rebaseAgentSymlinkTarget, setupAgentSymlinks, } from "./setup-agents.js";
+import { resolveTarExecutable } from "./tar-command.js";
 import { applyTemplateLayer, readTemplateLayer } from "./template-layer.js";
 import { coreTemplates, getTemplate, allTemplateNames, } from "./templates-meta.js";
 import { addConfiguredMigrationDependencies, readUpgradeEnvironment, } from "./upgrade.js";
@@ -674,22 +675,11 @@ function linkWorkspaceRootSkills(targetDir) {
     const linkPath = path.join(agentsDir, "skills");
     const target = "../packages/shared/.agents/skills";
     fs.mkdirSync(agentsDir, { recursive: true });
+    const state = prepareAgentSymlink(linkPath, target, "dir");
+    if (state !== "create")
+        return;
     try {
-        const stat = fs.lstatSync(linkPath);
-        if (stat.isSymbolicLink()) {
-            if (fs.readlinkSync(linkPath) === target)
-                return;
-            fs.unlinkSync(linkPath);
-        }
-        else {
-            return;
-        }
-    }
-    catch {
-        // Missing link; create below.
-    }
-    try {
-        fs.symlinkSync(target, linkPath, process.platform === "win32" ? "junction" : "dir");
+        createAgentSymlink(target, linkPath, "dir");
     }
     catch {
         try {
@@ -1338,7 +1328,7 @@ function localPackageTarball(packageDir) {
     }
     const rawTarball = path.join(packDir, tarballs[0]);
     const unpackDir = fs.mkdtempSync(path.join(os.tmpdir(), "agent-native-local-package-unpack-"));
-    execFileSync("tar", ["-xzf", rawTarball, "-C", unpackDir], {
+    execFileSync(resolveTarExecutable(), ["-xzf", rawTarball, "-C", unpackDir], {
         stdio: "pipe",
     });
     rewritePublishedPackageManifest(path.join(unpackDir, "package", "package.json"));
@@ -1948,7 +1938,7 @@ function tarExtractArgs(tarPath, destDir, options = {}) {
     ];
 }
 function archiveSymlinksForExtraction(tarPath) {
-    const listing = execFileSync("tar", ["tvzf", tarPath], {
+    const listing = execFileSync(resolveTarExecutable(), ["tvzf", tarPath], {
         encoding: "utf-8",
         stdio: ["ignore", "pipe", "pipe"],
         maxBuffer: TAR_LISTING_MAX_BUFFER,
@@ -2037,7 +2027,7 @@ function extractTarball(tarPath, destDir, options = {}) {
     const symlinks = options.skipAgentSymlinks || options.untrustedCommunityArchive
         ? archiveSymlinksForExtraction(tarPath)
         : [];
-    execFileSync("tar", tarExtractArgs(tarPath, destDir, {
+    execFileSync(resolveTarExecutable(), tarExtractArgs(tarPath, destDir, {
         ...options,
         additionalExcludes: symlinks.map((link) => link.archivePath),
     }), {
@@ -2071,7 +2061,7 @@ async function downloadAndExtract(url, destDir, options = {}) {
     }
 }
 function validateCommunityArchive(tarPath) {
-    const listing = execFileSync("tar", ["tvzf", tarPath], {
+    const listing = execFileSync(resolveTarExecutable(), ["tvzf", tarPath], {
         encoding: "utf-8",
         stdio: ["ignore", "pipe", "pipe"],
         maxBuffer: TAR_LISTING_MAX_BUFFER,
@@ -3451,8 +3441,9 @@ function replacePlaceholders(dir, appName, appTitle, workspaceName) {
         fs.writeFileSync(p, next);
     }
 }
-function copyDir(src, dest, root, opts) {
+function copyDir(src, dest, root, opts, destinationRoot) {
     const resolvedRoot = root ?? path.resolve(src);
+    const resolvedDestinationRoot = destinationRoot ?? path.resolve(dest);
     const skipExisting = opts?.skipExisting ?? false;
     fs.mkdirSync(dest, { recursive: true });
     for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
@@ -3465,16 +3456,28 @@ function copyDir(src, dest, root, opts) {
         }
         if (entry.isSymbolicLink()) {
             const target = fs.readlinkSync(srcPath);
-            const resolvedTarget = path.resolve(path.dirname(srcPath), target);
-            if (!opts?.materializeSymlinks &&
-                isPathWithin(resolvedRoot, resolvedTarget)) {
-                fs.symlinkSync(target, destPath);
+            const copiedTarget = rebaseAgentSymlinkTarget(resolvedRoot, resolvedDestinationRoot, srcPath, destPath, target);
+            if (!opts?.materializeSymlinks && copiedTarget !== undefined) {
+                let stat;
+                try {
+                    stat = fs.statSync(srcPath);
+                }
+                catch (error) {
+                    if (error.code !== "ENOENT")
+                        throw error;
+                    if (process.platform === "win32") {
+                        throw new Error(`Cannot copy dangling symlink at "${srcPath}" on Windows because its target type is unknown.`);
+                    }
+                    fs.symlinkSync(copiedTarget, destPath);
+                    continue;
+                }
+                createAgentSymlink(copiedTarget, destPath, stat.isDirectory() ? "dir" : "file");
             }
             else {
                 try {
                     const stat = fs.statSync(srcPath);
                     if (stat.isDirectory()) {
-                        copyDir(srcPath, destPath, resolvedRoot, opts);
+                        copyDir(srcPath, destPath, resolvedRoot, opts, resolvedDestinationRoot);
                     }
                     else {
                         fs.copyFileSync(srcPath, destPath);
@@ -3486,7 +3489,7 @@ function copyDir(src, dest, root, opts) {
             }
         }
         else if (entry.isDirectory()) {
-            copyDir(srcPath, destPath, resolvedRoot, opts);
+            copyDir(srcPath, destPath, resolvedRoot, opts, resolvedDestinationRoot);
         }
         else {
             fs.copyFileSync(srcPath, destPath);

package/dist/cli/package-lifecycle.js

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { assertAgentNativePackageManifest, } from "../package-lifecycle/manifest.js";
+import { resolveTarExecutable } from "./tar-command.js";
 const defaultIO = {
     out: (message) => console.log(message),
     err: (message) => console.error(message),
@@ -96,7 +97,7 @@ export async function loadLifecyclePackage(name, cwd, spawn = spawnSync) {
             throw new Error(`npm pack returned an invalid archive name for '${name}'`);
         }
         const archive = path.join(stage, filename);
-        const listed = spawn("tar", ["-tzf", archive], {
+        const listed = spawn(resolveTarExecutable(), ["-tzf", archive], {
             cwd,
             encoding: "utf8",
             stdio: "pipe",
@@ -114,7 +115,7 @@ export async function loadLifecyclePackage(name, cwd, spawn = spawnSync) {
                 entry.split("/").includes(".."))) {
             throw new Error(`Package archive for '${name}' contains an unsafe path`);
         }
-        const extracted = spawn("tar", [
+        const extracted = spawn(resolveTarExecutable(), [
             "-xzf",
             archive,
             "-C",

package/dist/cli/setup-agents.d.ts

@@ -1,2 +1,7 @@
+type SymlinkState = "create" | "matches" | "occupied";
+export declare function prepareAgentSymlink(linkPath: string, target: string, type: "file" | "dir"): SymlinkState;
+export declare function createAgentSymlink(target: string, linkPath: string, type: "file" | "dir"): void;
+export declare function rebaseAgentSymlinkTarget(sourceRoot: string, destinationRoot: string, sourceLinkPath: string, destinationLinkPath: string, target: string): string | undefined;
 export declare function setupAgentSymlinks(targetDir: string): void;
 export declare function runSetupAgents(): void;
+export {};