@cjhyy/code-shell-core 0.8.13 → 0.9.0

package/dist/llm/providers/openai.js

@@ -41,6 +41,24 @@ function cachedTokensOf(usage) {
         out.cacheCreationTokens = details.cache_write_tokens;
     return out;
 }
+/** Read the effective output-token ceiling from a built Chat Completions request. */
+function outputTokenLimitOf(requestBody) {
+    const value = requestBody.max_completion_tokens ?? requestBody.max_tokens;
+    return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined;
+}
+/**
+ * Some OpenAI-compatible gateways return finish_reason `tool_calls` when the
+ * output ceiling cuts a function-argument JSON string off. The malformed JSON
+ * plus exact cap usage is the evidence that distinguishes this from an ordinary
+ * completed tool call.
+ */
+function didHitToolArgumentOutputLimit(input) {
+    return (input.finishReason === "tool_calls" &&
+        input.malformedToolArguments &&
+        input.outputTokenLimit !== undefined &&
+        input.completionTokens !== undefined &&
+        input.completionTokens >= input.outputTokenLimit);
+}
 /**
  * Consume an async iterable of stream chunks with an idle watchdog.
  * Returns the accumulated text — either from onChunk return values, or
@@ -193,6 +211,7 @@ function normalizeOpenAIToolMessagePairs(messages) {
 }
 export class OpenAIClient extends LLMClientBase {
     _client = null;
+    dangerouslyAllowBrowser;
     // Sticky override: once the endpoint tells us `max_tokens` is rejected for
     // this model, switch to `max_completion_tokens` for the lifetime of the
     // client. Cheaper and more reliable than re-deriving from the model id when
@@ -205,8 +224,9 @@ export class OpenAIClient extends LLMClientBase {
     // succeed. Omitting the field just means "model default reasoning", which is
     // fine for our background/aux calls.
     _dropReasoningEffort = false;
-    constructor(config, defaults) {
+    constructor(config, defaults, runtimeOptions = {}) {
         super(config, defaults);
+        this.dangerouslyAllowBrowser = runtimeOptions.dangerouslyAllowBrowser === true;
     }
     initClient() {
         // Lazy init — client created on first use
@@ -222,6 +242,8 @@ export class OpenAIClient extends LLMClientBase {
                     (Object.keys(headers).length > 0 ? "x-headers-auth" : undefined),
                 ...(this.config.baseUrl ? { baseURL: this.config.baseUrl } : {}),
                 ...(Object.keys(headers).length > 0 ? { defaultHeaders: headers } : {}),
+                ...(this.fetch ? { fetch: this.fetch } : {}),
+                ...(this.dangerouslyAllowBrowser ? { dangerouslyAllowBrowser: true } : {}),
                 timeout: this.timeout,
             });
         }
@@ -473,7 +495,8 @@ export class OpenAIClient extends LLMClientBase {
     }
     async nonStreamMessage(options, messages, tools, reasoning, requestSignal) {
         try {
-            const response = await this.client.chat.completions.create(this.buildRequestBody(options, messages, tools, reasoning, false), { signal: requestSignal ?? options.signal });
+            const requestBody = this.buildRequestBody(options, messages, tools, reasoning, false);
+            const response = await this.client.chat.completions.create(requestBody, { signal: requestSignal ?? options.signal });
             const choice = response.choices[0];
             if (!choice)
                 throw new LLMError("No response from OpenAI", "openai");
@@ -486,7 +509,7 @@ export class OpenAIClient extends LLMClientBase {
                 ...cachedTokensOf(response.usage),
             };
             this.recordUsage(usage, options);
-            return this.processChoice(choice, usage);
+            return this.processChoice(choice, usage, outputTokenLimitOf(requestBody));
         }
         catch (err) {
             this.handleApiError(err);
@@ -496,7 +519,9 @@ export class OpenAIClient extends LLMClientBase {
     async streamMessage(options, messages, tools, reasoning, requestSignal) {
         const sdkSignal = requestSignal ?? options.signal;
         try {
-            const stream = await this.client.chat.completions.create(this.buildRequestBody(options, messages, tools, reasoning, true), { signal: sdkSignal });
+            const requestBody = this.buildRequestBody(options, messages, tools, reasoning, true);
+            const stream = await this.client.chat.completions.create(requestBody, { signal: sdkSignal });
+            const outputTokenLimit = outputTokenLimitOf(requestBody);
             let text = "";
             let reasoningContent = "";
             const toolCallsMap = new Map();
@@ -605,6 +630,7 @@ export class OpenAIClient extends LLMClientBase {
                 signal: sdkSignal,
             });
             const toolCalls = [];
+            let malformedToolArguments = false;
             for (const [, tc] of toolCallsMap) {
                 // Drop incomplete tool calls: an empty id or name (the fallbacks set
                 // when a delta never delivered them) would become a malformed call
@@ -621,9 +647,16 @@ export class OpenAIClient extends LLMClientBase {
                     args = JSON.parse(tc.args || "{}");
                 }
                 catch {
-                    /* intentional: model emitted malformed tool-call JSON — fall back to
-                       empty args rather than crashing the stream; the tool layer reports
-                       the resulting validation error back to the model. */
+                    malformedToolArguments = true;
+                    // Keep the historical empty-args fallback for genuinely malformed
+                    // model output. If usage also proves the configured output ceiling was
+                    // reached, the stop reason is normalized to "length" below so the turn
+                    // loop retries instead of executing this misleading empty call.
+                    logger.warn("openai.malformed_tool_arguments", {
+                        id: tc.id,
+                        name: tc.name,
+                        argumentChars: tc.args.length,
+                    });
                 }
                 toolCalls.push({ id: tc.id, toolName: tc.name, args });
             }
@@ -634,11 +667,31 @@ export class OpenAIClient extends LLMClientBase {
                 ...cachedTokensOf(streamUsage),
             };
             this.recordUsage(usage, options);
+            const inferredToolArgumentTruncation = didHitToolArgumentOutputLimit({
+                finishReason,
+                malformedToolArguments,
+                completionTokens: usage.completionTokens,
+                outputTokenLimit,
+            });
+            if (inferredToolArgumentTruncation) {
+                logger.warn("openai.tool_arguments_truncation_inferred", {
+                    provider: this.provider,
+                    model: this.model,
+                    finishReason,
+                    completionTokens: usage.completionTokens,
+                    outputTokenLimit,
+                    toolCount: toolCalls.length,
+                });
+            }
             return {
                 text,
                 toolCalls,
                 usage,
-                stopReason: finishReason ?? "stop",
+                // OpenRouter can report `tool_calls` even when max_tokens cuts a tool's
+                // argument JSON off. Normalize that proven cap hit to the standard
+                // OpenAI `length` spelling so the shared continuation guard can skip
+                // execution and ask the model to retry with a smaller call.
+                stopReason: inferredToolArgumentTruncation ? "length" : (finishReason ?? "stop"),
                 ...(reasoningContent ? { reasoningContent } : {}),
             };
         }
@@ -647,9 +700,10 @@ export class OpenAIClient extends LLMClientBase {
             throw err;
         }
     }
-    processChoice(choice, usage) {
+    processChoice(choice, usage, outputTokenLimit) {
         const text = choice.message.content ?? "";
         const toolCalls = [];
+        let malformedToolArguments = false;
         if (choice.message.tool_calls) {
             for (const tc of choice.message.tool_calls) {
                 let args = {};
@@ -657,9 +711,12 @@ export class OpenAIClient extends LLMClientBase {
                     args = JSON.parse(tc.function.arguments || "{}");
                 }
                 catch {
-                    /* intentional: model emitted malformed tool-call JSON — fall back to
-                       empty args rather than crashing; the tool layer reports the
-                       resulting validation error back to the model. */
+                    malformedToolArguments = true;
+                    logger.warn("openai.malformed_tool_arguments", {
+                        id: tc.id,
+                        name: tc.function.name,
+                        argumentChars: tc.function.arguments?.length ?? 0,
+                    });
                 }
                 toolCalls.push({
                     id: tc.id,
@@ -669,11 +726,17 @@ export class OpenAIClient extends LLMClientBase {
             }
         }
         const reasoningContent = extractReasoningContent(choice.message);
+        const inferredToolArgumentTruncation = didHitToolArgumentOutputLimit({
+            finishReason: choice.finish_reason ?? undefined,
+            malformedToolArguments,
+            completionTokens: usage.completionTokens,
+            outputTokenLimit,
+        });
         return {
             text,
             toolCalls,
             usage,
-            stopReason: choice.finish_reason ?? undefined,
+            stopReason: inferredToolArgumentTruncation ? "length" : (choice.finish_reason ?? undefined),
             ...(reasoningContent ? { reasoningContent } : {}),
         };
     }

package/dist/panel-apps/index.d.ts

@@ -1,4 +1,4 @@
 export { PANEL_APP_ICONS, PANEL_APP_MANIFEST_FILE, PANEL_APP_PERMISSIONS, PanelAppAgentContribution, PanelAppAgentTool, PanelAppManifest, type PanelAppAgentContribution as PanelAppAgentContributionData, type PanelAppAgentTool as PanelAppAgentToolData, type PanelAppManifest as PanelAppManifestData, } from "./manifest.js";
 export { PanelAppAlreadyInstalledError, PanelAppInstallError, PanelAppReviewChangedError, assertSafePanelAppId, panelAppInstallDir, panelAppsRegistryPath, panelAppsRoot, } from "./paths.js";
-export { installReviewedLocalPanelApp, installReviewedPanelAppUpdate, listInstalledPanelApps, previewInstalledPanelAppUpdate, previewLocalPanelApp, uninstallPanelApp, type InstalledPanelApp, type InstalledPanelAppSource, type GitPanelAppSourceInput, type LocalPanelAppSourceInput, type PanelAppSourceInput, type PanelAppPreview, } from "./installer.js";
+export { discoverGitPanelApps, installReviewedLocalPanelApp, installReviewedPanelAppUpdate, listInstalledPanelApps, previewInstalledPanelAppUpdate, previewLocalPanelApp, uninstallPanelApp, type InstalledPanelApp, type InstalledPanelAppSource, type GitPanelAppSourceInput, type GitPanelAppDiscovery, type GitPanelAppDiscoveryCandidate, type GitPanelAppDiscoveryIssue, type LocalPanelAppSourceInput, type PanelAppSourceInput, type PanelAppPreview, } from "./installer.js";
 export { isPanelAppBound, resolvePanelAppBindingPolicy, resolvePanelAppBindingProjectPath, type PanelAppBindingPolicy, } from "./bindings.js";

package/dist/panel-apps/index.js

@@ -1,4 +1,4 @@
 export { PANEL_APP_ICONS, PANEL_APP_MANIFEST_FILE, PANEL_APP_PERMISSIONS, PanelAppAgentContribution, PanelAppAgentTool, PanelAppManifest, } from "./manifest.js";
 export { PanelAppAlreadyInstalledError, PanelAppInstallError, PanelAppReviewChangedError, assertSafePanelAppId, panelAppInstallDir, panelAppsRegistryPath, panelAppsRoot, } from "./paths.js";
-export { installReviewedLocalPanelApp, installReviewedPanelAppUpdate, listInstalledPanelApps, previewInstalledPanelAppUpdate, previewLocalPanelApp, uninstallPanelApp, } from "./installer.js";
+export { discoverGitPanelApps, installReviewedLocalPanelApp, installReviewedPanelAppUpdate, listInstalledPanelApps, previewInstalledPanelAppUpdate, previewLocalPanelApp, uninstallPanelApp, } from "./installer.js";
 export { isPanelAppBound, resolvePanelAppBindingPolicy, resolvePanelAppBindingProjectPath, } from "./bindings.js";

package/dist/panel-apps/installer.d.ts

@@ -33,6 +33,29 @@ export interface PanelAppPreview {
     };
     warnings: string[];
 }
+export interface GitPanelAppDiscoveryCandidate {
+    /** Repository-relative path, or "." when the repository root is the app. */
+    subdir: string;
+    source: GitPanelAppSourceInput;
+    id: string;
+    version: string;
+    title: {
+        default: string;
+        en?: string;
+        "zh-CN"?: string;
+    };
+    description?: string;
+    icon: PanelAppManifest["icon"];
+}
+export interface GitPanelAppDiscoveryIssue {
+    subdir: string;
+    error: string;
+}
+export interface GitPanelAppDiscovery {
+    source: GitPanelAppSourceInput;
+    panels: GitPanelAppDiscoveryCandidate[];
+    issues: GitPanelAppDiscoveryIssue[];
+}
 export interface InstalledPanelApp {
     id: string;
     version: string;
@@ -52,6 +75,12 @@ export interface InstalledPanelApp {
     installedAt: string;
     lastUpdated: string;
 }
+/**
+ * Download a public GitHub repository once and enumerate every independently
+ * installable Panel App beneath it. Discovery is read-only: selecting a result
+ * still runs the normal full review and digest-bound install flow.
+ */
+export declare function discoverGitPanelApps(input: GitPanelAppSourceInput): Promise<GitPanelAppDiscovery>;
 export declare function previewLocalPanelApp(input: PanelAppSourceInput): Promise<PanelAppPreview>;
 /**
  * Re-open the original folder, archive, or GitHub source through the same

package/dist/panel-apps/installer.js

@@ -16,6 +16,9 @@ const MAX_FILE_BYTES = 16 * 1024 * 1024;
 const MAX_DEPTH = 16;
 const MAX_MANIFEST_BYTES = 1024 * 1024;
 const MAX_AGENT_SKILL_BYTES = 256 * 1024;
+const MAX_PANEL_DISCOVERY_DEPTH = 4;
+const MAX_PANEL_DISCOVERY_DIRECTORIES = 512;
+const MAX_PANEL_DISCOVERY_RESULTS = 16;
 const REVIEWED_GIT_SNAPSHOT_TTL_MS = 10 * 60 * 1000;
 const MAX_REVIEWED_GIT_SNAPSHOTS = 8;
 const ALLOWED_ASSET_EXTENSIONS = new Set([
@@ -61,9 +64,14 @@ function normalizeGitPanelAppSource(input) {
     if (!raw || raw.length > MAX_SOURCE_PATH || raw.includes("\0")) {
         throw new PanelAppInstallError("GitHub repository URL is invalid");
     }
+    const urlText = /^[A-Za-z0-9_.-]{1,100}\/[A-Za-z0-9_.-]{1,100}(?:\.git)?\/?$/.test(raw)
+        ? `https://github.com/${raw}`
+        : /^github\.com\//i.test(raw)
+            ? `https://${raw}`
+            : raw;
     let parsed;
     try {
-        parsed = new URL(raw);
+        parsed = new URL(urlText);
     }
     catch {
         throw new PanelAppInstallError("GitHub repository URL is invalid");
@@ -135,19 +143,52 @@ function normalizedGitSourceKey(input) {
 function looksLikePanelAppRoot(directory) {
     return existsSync(join(directory, PANEL_APP_MANIFEST_FILE));
 }
+async function discoverPanelAppRoots(directory) {
+    const found = [];
+    const pending = [{ directory, depth: 0 }];
+    let visited = 0;
+    while (pending.length > 0 &&
+        visited < MAX_PANEL_DISCOVERY_DIRECTORIES &&
+        found.length < MAX_PANEL_DISCOVERY_RESULTS) {
+        const current = pending.shift();
+        visited += 1;
+        if (looksLikePanelAppRoot(current.directory)) {
+            found.push(current.directory);
+            continue;
+        }
+        if (current.depth >= MAX_PANEL_DISCOVERY_DEPTH)
+            continue;
+        const entries = await readdir(current.directory, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory() || entry.name.startsWith(".") || entry.name === "node_modules") {
+                continue;
+            }
+            pending.push({ directory: join(current.directory, entry.name), depth: current.depth + 1 });
+        }
+    }
+    return found;
+}
 async function findPanelAppRoot(directory) {
     if (looksLikePanelAppRoot(directory))
         return directory;
-    const entries = await readdir(directory, { withFileTypes: true });
-    const children = entries.filter((entry) => entry.isDirectory() && !entry.name.startsWith("."));
-    if (children.length === 1) {
-        const nested = join(directory, children[0].name);
-        if (looksLikePanelAppRoot(nested))
-            return nested;
-    }
-    throw new PanelAppInstallError(`no Panel App found (expected ${PANEL_APP_MANIFEST_FILE})`);
+    const found = await discoverPanelAppRoots(directory);
+    if (found.length === 1)
+        return found[0];
+    if (found.length > 1) {
+        const candidates = found
+            .map((root) => relative(directory, root).split(sep).join(posix.sep))
+            .sort()
+            .join(", ");
+        throw new PanelAppInstallError(`multiple Panel Apps found; choose an app subdirectory: ${candidates}`);
+    }
+    throw new PanelAppInstallError(`no Panel App found (expected ${PANEL_APP_MANIFEST_FILE}); ` +
+        "for a monorepo, provide the app subdirectory or a GitHub /tree/<ref>/<path> URL");
 }
-async function openGitPanelAppSource(input) {
+function joinedPanelAppSubdirectory(base, nested) {
+    const parts = [base, nested].filter((part) => Boolean(part));
+    return parts.length > 0 ? parts.join("/") : undefined;
+}
+async function openGitPanelAppArchive(input) {
     const source = normalizeGitPanelAppSource(input);
     const temporaryRoot = await mkdtemp(join(tmpdir(), "cs-panel-app-git-"));
     try {
@@ -157,18 +198,86 @@ async function openGitPanelAppSource(input) {
         await downloadGitHubPanelAppArchive(source, archivePath);
         await extractZipSubdirectory(archivePath, extractedRoot, source.subdir);
         await rm(archivePath, { force: true });
+        return { source, extractedRoot, temporaryRoot };
+    }
+    catch (error) {
+        await rm(temporaryRoot, { recursive: true, force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+async function openGitPanelAppSource(input) {
+    const opened = await openGitPanelAppArchive(input);
+    try {
         return {
-            source,
-            sourceKey: JSON.stringify(source),
-            sourceRoot: await findPanelAppRoot(extractedRoot),
-            temporaryRoot,
+            source: opened.source,
+            sourceKey: JSON.stringify(opened.source),
+            sourceRoot: await findPanelAppRoot(opened.extractedRoot),
+            temporaryRoot: opened.temporaryRoot,
         };
     }
     catch (error) {
-        await rm(temporaryRoot, { recursive: true, force: true }).catch(() => undefined);
+        await rm(opened.temporaryRoot, { recursive: true, force: true }).catch(() => undefined);
         throw error;
     }
 }
+/**
+ * Download a public GitHub repository once and enumerate every independently
+ * installable Panel App beneath it. Discovery is read-only: selecting a result
+ * still runs the normal full review and digest-bound install flow.
+ */
+export async function discoverGitPanelApps(input) {
+    const opened = await openGitPanelAppArchive(input);
+    try {
+        const roots = await discoverPanelAppRoots(opened.extractedRoot);
+        if (roots.length === 0) {
+            throw new PanelAppInstallError(`no Panel App found (expected ${PANEL_APP_MANIFEST_FILE}); ` +
+                "check the repository, branch, or optional search subdirectory");
+        }
+        const panels = [];
+        const issues = [];
+        for (const root of roots) {
+            const nested = relative(opened.extractedRoot, root).split(sep).join(posix.sep);
+            const subdir = joinedPanelAppSubdirectory(opened.source.subdir, nested);
+            const label = subdir ?? ".";
+            try {
+                const inspected = await inspectPanelAppSource(root);
+                panels.push({
+                    subdir: label,
+                    source: {
+                        kind: "git",
+                        url: opened.source.url,
+                        ...(opened.source.ref ? { ref: opened.source.ref } : {}),
+                        ...(subdir ? { subdir } : {}),
+                    },
+                    id: inspected.manifest.id,
+                    version: inspected.manifest.version,
+                    title: inspected.manifest.title,
+                    ...(inspected.manifest.description
+                        ? { description: inspected.manifest.description }
+                        : {}),
+                    icon: inspected.manifest.icon,
+                });
+            }
+            catch (error) {
+                issues.push({
+                    subdir: label,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+        panels.sort((left, right) => left.subdir.localeCompare(right.subdir));
+        issues.sort((left, right) => left.subdir.localeCompare(right.subdir));
+        if (panels.length === 0) {
+            throw new PanelAppInstallError(`found ${issues.length} Panel App manifest(s), but none passed validation: ${issues
+                .map((issue) => `${issue.subdir}: ${issue.error}`)
+                .join("; ")}`);
+        }
+        return { source: opened.source, panels, issues };
+    }
+    finally {
+        await rm(opened.temporaryRoot, { recursive: true, force: true }).catch(() => undefined);
+    }
+}
 async function disposeReviewedGitSnapshot(snapshot) {
     clearTimeout(snapshot.expiryTimer);
     await rm(snapshot.temporaryRoot, { recursive: true, force: true }).catch(() => undefined);

package/dist/plugins/pluginAutomationTemplates.d.ts

@@ -6,6 +6,8 @@ export interface InstantiatePluginAutomationTemplateOptions {
     templateId: string;
     expectedRevision: string;
     cwd?: string;
+    projectId?: string;
+    rootId?: string;
     /** Effective project/global disable list computed by the host for this cwd. */
     disabledPluginNames: ReadonlySet<string>;
     maxJobs?: number;

package/dist/plugins/pluginAutomationTemplates.js

@@ -38,6 +38,10 @@ export function instantiatePluginAutomationTemplate(options) {
     const template = contribution.template;
     return options.scheduler.create(template.title.default, template.schedule, template.prompt, {
         ...(template.workspace === "current" && options.cwd ? { cwd: options.cwd } : {}),
+        ...(template.workspace === "current" && options.projectId
+            ? { projectId: options.projectId }
+            : {}),
+        ...(template.workspace === "current" && options.rootId ? { rootId: options.rootId } : {}),
         ...(template.timezone ? { timezone: template.timezone } : {}),
         permissionLevel: template.permissionLevel,
         templateSource: {

package/dist/plugins/pluginCatalog.d.ts

@@ -33,6 +33,12 @@ export interface PluginAutomationTemplateContribution {
  * instantiated later. Install paths and timestamps are intentionally excluded.
  */
 export declare function pluginAutomationTemplateRevision(installKey: string, template: PluginAutomationTemplate): string;
+/**
+ * Read an installed plugin manifest without following links or accepting an
+ * unbounded/non-regular file. Shared by the runtime catalog and UI inventory so
+ * those views cannot disagree about which manifest bytes are trusted.
+ */
+export declare function readCatalogPluginManifest(installPath: string): CanonicalPluginManifestData | null;
 /**
  * Load the installed plugin catalog at the core boundary.
  *

package/dist/plugins/pluginCatalog.js

@@ -19,7 +19,12 @@ export function pluginAutomationTemplateRevision(installKey, template) {
         .update(JSON.stringify(template))
         .digest("hex");
 }
-function readCanonicalManifest(installPath) {
+/**
+ * Read an installed plugin manifest without following links or accepting an
+ * unbounded/non-regular file. Shared by the runtime catalog and UI inventory so
+ * those views cannot disagree about which manifest bytes are trusted.
+ */
+export function readCatalogPluginManifest(installPath) {
     const file = join(installPath, CANONICAL_PLUGIN_MANIFEST_FILE);
     let descriptor;
     try {
@@ -69,7 +74,7 @@ export function loadPluginCatalog(options = {}) {
             const installPath = resolveSafePluginPath(entry.installPath, root);
             if (!installPath)
                 continue;
-            const manifest = readCanonicalManifest(installPath);
+            const manifest = readCatalogPluginManifest(installPath);
             const identity = identityFromInstallKey(installKey, manifest);
             catalog.push({
                 installKey,

package/dist/plugins/pluginContent.d.ts

@@ -7,7 +7,7 @@
  */
 import { type PluginHookEntry } from "./loadPluginHooks.js";
 import { type PluginHookReview } from "./pluginHookApproval.js";
-import { type PluginAutomationTemplate } from "./installer/types.js";
+import type { PluginAutomationTemplate } from "./installer/types.js";
 export type PluginAutomationTemplateDescriptor = PluginAutomationTemplate & {
     revision: string;
 };

package/dist/plugins/pluginContent.js

@@ -11,8 +11,7 @@ import { parseFrontmatter } from "../skills/frontmatter.js";
 import { listPluginHooks } from "./loadPluginHooks.js";
 import { reviewPluginHooks } from "./pluginHookApproval.js";
 import { readPluginMcp } from "./installer/loadPluginMcp.js";
-import { CANONICAL_PLUGIN_MANIFEST_FILE, CanonicalPluginManifest, } from "./installer/types.js";
-import { pluginAutomationTemplateRevision } from "./pluginCatalog.js";
+import { pluginAutomationTemplateRevision, readCatalogPluginManifest } from "./pluginCatalog.js";
 function resolveContainedPath(root, candidate) {
     try {
         const realRoot = realpathSync(root);
@@ -117,14 +116,7 @@ export function describePluginContent(pluginName, installPath, installKey) {
             return undefined;
         }
     })();
-    const manifest = (() => {
-        try {
-            return CanonicalPluginManifest.parse(JSON.parse(readFileSync(join(installPath, CANONICAL_PLUGIN_MANIFEST_FILE), "utf-8")));
-        }
-        catch {
-            return null;
-        }
-    })();
+    const manifest = readCatalogPluginManifest(installPath);
     return {
         skills: listSkills(installPath),
         commands: listMdNames(installPath, "commands"),

package/dist/prompt/composer.d.ts

@@ -10,8 +10,11 @@ import { type ScanOptions } from "./instruction-scanner.js";
 import { type AgentPreset } from "../preset/index.js";
 import type { BuiltinTool } from "../tool-system/builtin/index.js";
 import type { CapabilityDynamicContextProvider } from "../capabilities/index.js";
+import { type WorkspaceContext } from "../workspace/workspace-context.js";
 export interface ComposerOptions {
     cwd: string;
+    /** Run workspace; omitted by legacy callers that only provide cwd. */
+    workspace?: WorkspaceContext;
     model: string;
     instructionOptions?: ScanOptions;
     /** Resolved preset — used to load section-based prompt. */
@@ -106,9 +109,9 @@ export interface ComposerOptions {
     disableSourcesContext?: boolean;
 }
 export declare class PromptComposer {
-    private readonly options;
     private sectionCache;
     private cachedInstructions;
+    private readonly options;
     constructor(options: ComposerOptions);
     /**
      * Build the system prompt from sections.

package/dist/prompt/composer.js

@@ -11,12 +11,18 @@ import { MemoryManager } from "../session/memory.js";
 import { scanSkills } from "../skills/index.js";
 import { buildSkillListing } from "../tool-system/builtin/skill-prompt.js";
 import { resolveAgentPreset, buildPresetSystemPrompt } from "../preset/index.js";
+import { legacySingleRootWorkspace, validateWorkspaceContext, } from "../workspace/workspace-context.js";
 export class PromptComposer {
-    options;
     sectionCache = new SectionCache();
     cachedInstructions = null;
+    options;
     constructor(options) {
-        this.options = options;
+        this.options = {
+            ...options,
+            workspace: options.workspace === undefined
+                ? legacySingleRootWorkspace(options.cwd)
+                : validateWorkspaceContext(options.workspace),
+        };
     }
     /**
      * Build the system prompt from sections.
@@ -58,7 +64,7 @@ export class PromptComposer {
         const preset = this.options.preset ?? resolveAgentPreset();
         const parts = await Promise.all((this.options.dynamicContextProviders ?? []).map(async (provider) => {
             try {
-                return await provider({ cwd: this.options.cwd, preset });
+                return await provider({ cwd: this.options.cwd, workspace: this.options.workspace, preset });
             }
             catch {
                 // A capability's optional context must not make a turn fail.
@@ -164,6 +170,8 @@ export class PromptComposer {
                 const lines = [
                     `You are an AI agent powered by ${this.options.model}.`,
                     `Working directory: ${this.options.cwd}`,
+                    `Workspace roots (${this.options.workspace.roots.length}):`,
+                    ...this.options.workspace.roots.map((root) => `- [${root.role}] ${root.path} (rootId: ${root.id})`),
                     `Platform: ${process.platform}`,
                     `Shell: ${process.env.SHELL ?? "unknown"}`,
                 ];

package/dist/protocol/chat-session-manager.d.ts

@@ -1,9 +1,10 @@
 import { ChatSession } from "./chat-session.js";
 import type { SessionKind } from "../types.js";
+import type { SessionProjectBinding, SessionWorkspace } from "../types.js";
 import type { Engine } from "../engine/engine.js";
 import type { EngineRuntime } from "../engine/runtime.js";
 import type { EngineConfig } from "../engine/types.js";
-export type EngineConfigSlice = Pick<EngineConfig, "permissionMode" | "preset" | "customSystemPrompt" | "appendSystemPrompt" | "goal" | "maxTurns" | "maxContextTokens" | "cwd" | "projectTrusted" | "sessionStorageDir">;
+export type EngineConfigSlice = Pick<EngineConfig, "permissionMode" | "preset" | "customSystemPrompt" | "appendSystemPrompt" | "goal" | "maxTurns" | "maxContextTokens" | "cwd" | "workspaceContext" | "projectTrusted" | "sessionStorageDir">;
 /** Identity scope every ChatSessionManager belongs to when none is injected. */
 export declare const LOCAL_CHAT_IDENTITY = "local";
 export interface ChatSessionManagerOptions {
@@ -48,11 +49,30 @@ export interface LiveChatSessionSnapshot {
     }>;
 }
 export declare const CLOSED_CHAT_SESSION_TOMBSTONE_LIMIT = 4096;
+export interface ResidentSessionMainRootMigration {
+    project: SessionProjectBinding;
+    mainRoot: string;
+    workspaceContext: import("../workspace/workspace-context.js").WorkspaceContext;
+    projectTrusted: boolean;
+}
+export type SessionMigrationOwnership = {
+    status: "resident";
+    session: ChatSession;
+} | {
+    status: "not-resident";
+    ownershipToken: string;
+} | {
+    status: "failed";
+    error: string;
+};
 export declare class ChatSessionManager {
     private readonly sessions;
     private readonly closingSessions;
     private readonly closedSessions;
     private readonly sessionGeneration;
+    private readonly sessionSlices;
+    private readonly migrationClaims;
+    private readonly residentMigrations;
     readonly runtime: EngineRuntime;
     /** Identity scope this manager serves ("local" unless injected). */
     readonly identity: string;
@@ -76,6 +96,26 @@ export declare class ChatSessionManager {
      */
     forIdentity(identity: string): ChatSessionManager;
     getOrCreate(sessionId: string, slice: EngineConfigSlice): Promise<ChatSession>;
+    /**
+     * Prove whether this worker currently owns a resident Engine, or fence the
+     * Session so Main can perform one durable migration without a re-resume race.
+     */
+    beginSessionMigration(sessionId: string, ownershipToken: string): SessionMigrationOwnership;
+    /** Release only the exact claim minted for this Session. */
+    completeSessionMigration(sessionId: string, ownershipToken: string): boolean;
+    /**
+     * Rebuild an idle resident Engine against a new authoritative main root.
+     *
+     * Transaction order is intentional:
+     * 1. construct and restore the candidate while durable state still points at
+     *    the old owner (factory/restore failure is therefore a no-op),
+     * 2. atomically commit durable state through the old owning Engine,
+     * 3. synchronously swap the Engine inside the existing ChatSession,
+     * 4. dispose the unreachable old Engine before reporting success.
+     *
+     * No await occurs between the idle check, durable commit and owner swap.
+     */
+    migrateResidentSessionMainRoot(sessionId: string, target: ResidentSessionMainRootMigration): Promise<SessionWorkspace>;
     /**
      * Cold-resume a persisted session using its own cwd. The first detached
      * Engine is only a storage probe; all actual work runs on the second Engine
@@ -121,6 +161,7 @@ export declare class ChatSessionManager {
     startIdleSweeper(intervalMs?: number): void;
     stopIdleSweeper(): void;
     private unregisterMcpOwner;
+    private disposeEngine;
     private engineSessionManager;
 }
 /**