@cjhyy/code-shell-core 0.5.0-rc.0 → 0.5.0-rc.2

package/dist/settings/schema.js

@@ -2,6 +2,27 @@
  * Settings schema with Zod validation.
  */
 import { z } from "zod";
+import { ReasoningSettingSchema } from "../llm/reasoning-setting.js";
+/**
+ * Tri-state project capability overlay. Lives in PROJECT settings only and
+ * layers over the global baseline (disabledSkills / disabledPlugins /
+ * mcpServers.<name>.enabled / disabledAgents). NOT a second denylist:
+ *   - "on"      → force enabled (even if globally disabled)
+ *   - "off"     → force disabled (even if globally enabled)
+ *   - "inherit" → take the global baseline. We don't persist "inherit"; an
+ *                 absent key means inherit. See the project-scoped
+ *                 capabilities design (spec §4).
+ */
+export const CapabilityOverrideSchema = z.enum(["inherit", "on", "off"]);
+export const CapabilityOverridesSchema = z
+    .object({
+    skills: z.record(CapabilityOverrideSchema).optional(),
+    plugins: z.record(CapabilityOverrideSchema).optional(),
+    agents: z.record(CapabilityOverrideSchema).optional(),
+    mcp: z.record(CapabilityOverrideSchema).optional(),
+    builtin: z.record(CapabilityOverrideSchema).optional(),
+})
+    .optional();
 export const SettingsSchema = z
     .object({
     agent: z
@@ -12,6 +33,14 @@ export const SettingsSchema = z
         disabledBuiltinTools: z.array(z.string()).default([]),
         customSystemPrompt: z.string().optional(),
         appendSystemPrompt: z.string().optional(),
+        responseLanguage: z.string().optional(),
+        userProfile: z.string().optional(),
+        instructions: z
+            .object({
+            compatClaude: z.boolean().default(true),
+            compatCodex: z.boolean().default(true),
+        })
+            .optional(),
     })
         .default({}),
     /**
@@ -22,6 +51,15 @@ export const SettingsSchema = z
      * both — appendOnboardingResult does this in one shot.
      */
     activeKey: z.string().optional(),
+    /**
+     * Auxiliary-task model — points at a models[].key. Background, non-user-
+     * facing LLM calls (memory extraction, the auto-dream loop) use this model
+     * instead of the active one, so per-turn book-keeping doesn't burn the
+     * expensive primary model. Pick something fast/cheap (e.g. a Haiku or
+     * DeepSeek key). When unset, those calls fall back to the active model
+     * (legacy behavior). An invalid/missing key also falls back to active.
+     */
+    auxModelKey: z.string().optional(),
     /**
      * Toggle background auto-update. When true (default), code-shell checks
      * npm for newer versions and — if the npm global prefix is writable —
@@ -62,12 +100,11 @@ export const SettingsSchema = z
         protocol: z.enum(["openai-compat", "anthropic-style"]).optional(),
         modelsPath: z.string().optional(),
         /**
-         * DeepSeek V4 thinking-mode default for this provider. "enabled"
-         * matches endpoint default; "disabled" makes V4 calls run in
-         * non-thinking mode (faster, cheaper). Ignored by every provider
-         * other than DeepSeek V4. Per-call overrides still win.
+         * Default reasoning/thinking setting for this provider's models.
+         * Rich shape: {mode:"off"|"on"} | {mode:"effort",effort} |
+         * {mode:"budget",budgetTokens}. Per-model `reasoning` wins.
          */
-        thinking: z.enum(["enabled", "disabled"]).optional(),
+        reasoning: ReasoningSettingSchema.optional(),
     }))
         .default([]),
     models: z
@@ -90,12 +127,12 @@ export const SettingsSchema = z
         baseUrl: z.string().optional(),
         apiKey: z.string().optional(),
         /**
-         * Per-model thinking override. Wins over the provider-level
-         * setting (settings.providers[].thinking). Use this when
-         * different models under the same provider need different
-         * defaults — e.g. DeepSeek V4 Pro off (faster) but V4 Flash on.
+         * Per-model reasoning override. Wins over the provider-level
+         * `reasoning` setting (settings.providers[].reasoning). Use this
+         * when different models under the same provider need different
+         * defaults — e.g. one model off (faster) and another on.
          */
-        thinking: z.enum(["enabled", "disabled"]).optional(),
+        reasoning: ReasoningSettingSchema.optional(),
     })
         .transform((m) => {
         // Normalize: prefer `protocol`; fall back to legacy `provider`.
@@ -146,6 +183,9 @@ export const SettingsSchema = z
         url: z.string().optional(),
         transport: z.enum(["stdio", "sse", "streamable-http", "inprocess"]).optional(),
         headers: z.record(z.string()).optional(),
+        // Codex-style on/off switch. Absent or true → connected; only
+        // literal false disables. Filtered in MCPManager.connectAll.
+        enabled: z.boolean().optional(),
     }))
         .default({}),
     /**
@@ -155,6 +195,27 @@ export const SettingsSchema = z
      * tool both see the filtered set — see scanSkills(opts).
      */
     disabledSkills: z.array(z.string()).default([]),
+    /**
+     * Plugin-level total switch: every skill whose namespaced name
+     * starts with `${pluginName}:` is filtered. Coarser knob than
+     * disabledSkills; both are honored simultaneously. Bare plugin
+     * names (no colon suffix). See scanSkills(opts.disabledPlugins).
+     */
+    disabledPlugins: z.array(z.string()).default([]),
+    /**
+     * Sub-agent role names (the `name` in .code-shell/agents/*.md) to
+     * hide from the registry. A disabled role is filtered out at load
+     * so it never appears in registry.list()/get() — the Agent tool's
+     * agent_type list won't show it and the LLM can't pick it. Mirrors
+     * disabledSkills / disabledPlugins.
+     */
+    disabledAgents: z.array(z.string()).default([]),
+    /**
+     * Project-scoped tri-state capability overlay. Only meaningful in
+     * ${cwd}/.code-shell/settings.json; layered over the global baseline at
+     * capability-assembly time. Optional — absence === everything inherits.
+     */
+    capabilityOverrides: CapabilityOverridesSchema,
     instructions: z
         .object({
         fileName: z.string().default("CODESHELL.md"),
@@ -197,6 +258,15 @@ export const SettingsSchema = z
             .record(z.enum(["serper", "tavily", "searxng"]), z.object({
             apiKey: z.string().optional(),
             baseUrl: z.string().optional(),
+            lastProbe: z
+                .object({
+                status: z.enum(["ok", "error", "unconfigured"]),
+                sampleTitles: z.array(z.string()).optional(),
+                errorMessage: z.string().optional(),
+                errorDetail: z.string().optional(),
+                lastProbedAt: z.string(),
+            })
+                .optional(),
         }))
             .optional(),
     })
@@ -206,6 +276,24 @@ export const SettingsSchema = z
         format: z.enum(["text", "json", "jsonl", "stream-json"]).default("text"),
     })
         .default({}),
+    /**
+     * Image attachment handling. Sub-fields:
+     *   - detail: OpenAI-style fidelity hint applied to every user-
+     *     attached image. "low" = 85 tokens/image fixed (cheap
+     *     thumbnail), "high" = ~768 px tiles (default), "original" =
+     *     keep client-side dimensions (most expensive). Anthropic
+     *     ignores this field today; that's fine — it just gets
+     *     dropped on the Claude path.
+     *   - mcpImageTokenBudget: per-turn cap on token cost of images
+     *     returned by MCP tools. Codex doesn't enforce this; CC uses
+     *     25 000. Set to 0 to disable.
+     */
+    images: z
+        .object({
+        detail: z.enum(["low", "high", "original"]).optional(),
+        mcpImageTokenBudget: z.number().int().nonnegative().optional(),
+    })
+        .optional(),
     /**
      * OS-level sandbox for shell-tool execution. "auto" picks per platform:
      * Seatbelt on macOS, bubblewrap on Linux when installed, otherwise off.
@@ -220,6 +308,34 @@ export const SettingsSchema = z
         network: z.enum(["allow", "deny"]).optional(),
     })
         .optional(),
+    /**
+     * Project-local environment profile. Mirrors Codex's local-environment
+     * shape at the settings layer: setup/cleanup scripts can be customized per
+     * platform, and env values are stored as KEY=VALUE pairs. Runtime wiring is
+     * intentionally separate from the MCP server env model above.
+     */
+    localEnvironment: z
+        .object({
+        name: z.string().optional(),
+        setupScripts: z
+            .object({
+            default: z.string().optional(),
+            macos: z.string().optional(),
+            linux: z.string().optional(),
+            windows: z.string().optional(),
+        })
+            .optional(),
+        cleanupScripts: z
+            .object({
+            default: z.string().optional(),
+            macos: z.string().optional(),
+            linux: z.string().optional(),
+            windows: z.string().optional(),
+        })
+            .optional(),
+        env: z.record(z.string()).optional(),
+    })
+        .optional(),
     /**
      * Shell-hook configuration. Each entry binds a HookEventName to a
      * shell command; the command receives ctx JSON on stdin and returns

package/dist/skills/scanner.d.ts

@@ -17,15 +17,22 @@ export interface SkillDefinition {
     source: "project" | "user" | "plugin";
 }
 /**
- * Options accepted by scanSkills. The disabled-skill filter is applied
- * after the memoized scan returns so the cache stays warm across
- * different filter values — changing `settings.disabledSkills` should
- * never force a re-scan. Names in `disabledSkills` must match the
- * SkillDefinition.name exactly, including any "<plugin>:" prefix —
- * see scanInstalledPlugins() at line ~168 for namespace construction.
+ * Options accepted by scanSkills. Both filters are applied after the
+ * memoized scan returns so the cache stays warm across different filter
+ * values — changing `settings.disabledSkills` or `settings.disabledPlugins`
+ * should never force a re-scan.
+ *
+ * - `disabledSkills` names must match the SkillDefinition.name exactly,
+ *   including any "<plugin>:" prefix — see scanInstalledPlugins() at
+ *   line ~168 for namespace construction.
+ * - `disabledPlugins` names are bare plugin names (no colon suffix).
+ *   Every skill whose name starts with `${pluginName}:` is filtered.
+ *   This is the coarse "plugin total switch" knob; `disabledSkills` is
+ *   the per-skill knob.
  */
 export interface ScanSkillsOptions {
     disabledSkills?: string[];
+    disabledPlugins?: string[];
 }
 export declare function scanSkills(cwd: string, opts?: ScanSkillsOptions): SkillDefinition[];
 export declare function invalidateSkillCache(): void;

package/dist/skills/scanner.js

@@ -160,11 +160,30 @@ function installedPluginsMtime() {
 const memoized = memoize(scanOnce, (cwd) => `${cwd}\0${userHome()}\0${installedPluginsMtime()}`);
 export function scanSkills(cwd, opts) {
     const all = memoized(cwd);
-    const disabled = opts?.disabledSkills;
-    if (!disabled || disabled.length === 0)
+    const disabledSkills = opts?.disabledSkills;
+    const disabledPlugins = opts?.disabledPlugins;
+    const hasSkillFilter = disabledSkills && disabledSkills.length > 0;
+    const hasPluginFilter = disabledPlugins && disabledPlugins.length > 0;
+    if (!hasSkillFilter && !hasPluginFilter)
         return all;
-    const set = new Set(disabled);
-    return all.filter((s) => !set.has(s.name));
+    const skillSet = hasSkillFilter ? new Set(disabledSkills) : null;
+    const pluginSet = hasPluginFilter ? new Set(disabledPlugins) : null;
+    return all.filter((s) => {
+        if (skillSet && skillSet.has(s.name))
+            return false;
+        if (pluginSet) {
+            // Use indexOf, not split — skill names may theoretically contain
+            // more colons after the first; the namespace boundary is the
+            // first ":" only.
+            const colon = s.name.indexOf(":");
+            if (colon > 0) {
+                const prefix = s.name.slice(0, colon);
+                if (pluginSet.has(prefix))
+                    return false;
+            }
+        }
+        return true;
+    });
 }
 export function invalidateSkillCache() {
     memoized.cache.clear?.();

package/dist/tool-system/builtin/add-marketplace.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Built-in AddMarketplace tool — register a plugin marketplace source so the
+ * user can browse/install plugins from it in the UI. The tool only *adds the
+ * source* (git clone + validate marketplace.json via core's addMarketplace);
+ * which plugin to install is left to the user. Pairs with WebSearch/WebFetch:
+ * the model can discover a marketplace repo, then add it.
+ *
+ * Side effects (network + git clone + disk write) → permissionDefault "ask".
+ */
+import type { ToolDefinition } from "../../types.js";
+export declare const addMarketplaceToolDef: ToolDefinition;
+export declare function addMarketplaceTool(args: Record<string, unknown>): Promise<string>;

package/dist/tool-system/builtin/add-marketplace.js

@@ -0,0 +1,76 @@
+/**
+ * Built-in AddMarketplace tool — register a plugin marketplace source so the
+ * user can browse/install plugins from it in the UI. The tool only *adds the
+ * source* (git clone + validate marketplace.json via core's addMarketplace);
+ * which plugin to install is left to the user. Pairs with WebSearch/WebFetch:
+ * the model can discover a marketplace repo, then add it.
+ *
+ * Side effects (network + git clone + disk write) → permissionDefault "ask".
+ */
+import { addMarketplace } from "../../plugins/marketplaceManager.js";
+export const addMarketplaceToolDef = {
+    name: "AddMarketplace",
+    description: "Register a plugin marketplace source so the user can browse and install " +
+        "plugins from it. Provide a short name and a source: either a GitHub repo " +
+        "(owner/name) or a git URL. This only ADDS the source — it does not install " +
+        "any plugin. Use WebSearch/WebFetch first to find a marketplace repo if you " +
+        "don't already have one.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            name: {
+                type: "string",
+                description: "Short local name for this marketplace (e.g. 'official').",
+            },
+            source_type: {
+                type: "string",
+                enum: ["github", "git"],
+                description: "'github' for an owner/name repo, 'git' for a clone URL.",
+            },
+            repo: {
+                type: "string",
+                description: "GitHub repo in owner/name form (required when source_type='github').",
+            },
+            url: {
+                type: "string",
+                description: "Git clone URL (required when source_type='git').",
+            },
+        },
+        required: ["name", "source_type"],
+    },
+};
+export async function addMarketplaceTool(args) {
+    const name = args.name;
+    if (typeof name !== "string" || !name.trim()) {
+        return "Error: name is required";
+    }
+    const sourceType = args.source_type;
+    let source;
+    if (sourceType === "github") {
+        const repo = args.repo;
+        if (typeof repo !== "string" || !repo.includes("/")) {
+            return "Error: github source requires repo in owner/name form";
+        }
+        source = { source: "github", repo };
+    }
+    else if (sourceType === "git") {
+        const url = args.url;
+        if (typeof url !== "string" || !url.trim()) {
+            return "Error: git source requires a url";
+        }
+        source = { source: "git", url };
+    }
+    else {
+        return "Error: source_type must be 'github' or 'git'";
+    }
+    try {
+        const result = await addMarketplace(name, source);
+        if (!result.ok) {
+            return `Error adding marketplace ${name}: ${result.error}`;
+        }
+        return `Marketplace '${name}' added. The user can now browse and install plugins from it in the Extensions → Market UI.`;
+    }
+    catch (err) {
+        return `Error adding marketplace ${name}: ${err.message}`;
+    }
+}

package/dist/tool-system/builtin/agent-registry.d.ts

@@ -12,6 +12,8 @@
  * RunManager, not here.
  */
 export type AsyncAgentStatus = "running" | "completed" | "failed" | "cancelled";
+/** Process-wide cap on concurrent background sub-agents (aligns with Codex max_threads=6). */
+export declare const MAX_BACKGROUND_AGENTS = 6;
 /**
  * Minimal structural shape for an entry in an agent's transcript. We avoid
  * importing the UI's `ChatEntry` here to prevent a tool-system → ui import
@@ -27,7 +29,15 @@ export interface AsyncAgentEntry {
     agentId: string;
     /** Short kind label shown in the dock (e.g. "Explore", "Plan"). */
     name?: string;
+    /** Dispatched role (e.g. "general-purpose", "explorer"); shown in the dock
+     *  so you can see what kind of agent is running. */
+    agentType?: string;
     description: string;
+    /** Session that spawned this background agent. Lets the spawning
+     *  Engine.run wait only on ITS OWN background agents (hasRunningForSession),
+     *  not every concurrent session's. Undefined only for legacy/ad-hoc callers
+     *  outside Engine.run. */
+    sessionId?: string;
     status: AsyncAgentStatus;
     startedAt: number;
     finishedAt?: number;
@@ -44,6 +54,11 @@ declare class AsyncAgentRegistry {
     subscribe: (cb: () => void) => (() => void);
     getSnapshot: () => AsyncAgentEntry[];
     hasRunning: () => boolean;
+    /** True if any background agent spawned by `sessionId` is still running.
+     *  Drives Engine.run's "wait for my background agents before resolving". */
+    hasRunningForSession: (sessionId: string) => boolean;
+    /** Count of agents currently in the "running" state (cap enforcement). */
+    runningCount(): number;
     private notify;
     register(entry: AsyncAgentEntry): void;
     appendToTranscript(agentId: string, entry: AgentTranscriptEntry): void;

package/dist/tool-system/builtin/agent-registry.js

@@ -11,6 +11,8 @@
  * the right boundary: long-running cross-process work belongs to
  * RunManager, not here.
  */
+/** Process-wide cap on concurrent background sub-agents (aligns with Codex max_threads=6). */
+export const MAX_BACKGROUND_AGENTS = 6;
 class AsyncAgentRegistry {
     agents = new Map();
     listeners = new Set();
@@ -28,6 +30,15 @@ class AsyncAgentRegistry {
     hasRunning = () => {
         return this.snapshot.some((e) => e.status === "running");
     };
+    /** True if any background agent spawned by `sessionId` is still running.
+     *  Drives Engine.run's "wait for my background agents before resolving". */
+    hasRunningForSession = (sessionId) => {
+        return this.snapshot.some((e) => e.status === "running" && e.sessionId === sessionId);
+    };
+    /** Count of agents currently in the "running" state (cap enforcement). */
+    runningCount() {
+        return this.snapshot.filter((e) => e.status === "running").length;
+    }
     notify() {
         this.snapshot = [...this.agents.values()];
         for (const cb of this.listeners) {
@@ -102,10 +113,9 @@ class AsyncAgentRegistry {
         catch {
             // ignore abort errors — we still mark cancelled
         }
-        e.status = "cancelled";
-        e.finishedAt = Date.now();
-        e.finishedFadeAt = e.finishedAt + 30_000;
-        this.notify();
+        // Reuse markFinished for the status/timestamp/notify bookkeeping rather
+        // than duplicating it (the entry is still "running" after abort()).
+        this.markFinished(agentId, "cancelled");
         return true;
     }
     reset() {

package/dist/tool-system/builtin/agent.d.ts

@@ -8,9 +8,64 @@
  */
 import type { ToolDefinition } from "../../types.js";
 import type { ToolContext } from "../context.js";
+import type { AgentDefinitionRegistry } from "../../agent/agent-definition-registry.js";
+import type { HookRegistry } from "../../hooks/registry.js";
+export interface AgentTypeOverrides {
+    resolvedType?: string;
+    model?: string;
+    maxTurns?: number;
+    toolAllowlist?: string[];
+    appendSystemPrompt?: string;
+}
+/**
+ * Resolve an `agent_type` against the role registry into spawn overrides.
+ *
+ * - Omitted type + non-empty registry → fall back to a configured role
+ *   ("general-purpose" if present, else the first available) instead of
+ *   running a nameless ephemeral agent. Relaxed from the earlier "throw when
+ *   agent_type omitted": the model habitually omits it, and a hard error just
+ *   turned every spawn into a failure. Falling back to a real role keeps the
+ *   tool-allowlist / system-prompt benefits without breaking the call.
+ * - Omitted type + empty registry → empty overrides (true ephemeral; nothing
+ *   to fall back to).
+ * - Unknown explicit type → throw, so the LLM gets a clear correction rather
+ *   than silently running a generic agent.
+ */
+export declare function resolveAgentTypeOverrides(agentType: string | undefined, registry: AgentDefinitionRegistry | undefined): AgentTypeOverrides;
+/**
+ * Render the "Available agent types" block injected into the Agent tool's
+ * description, listing the roles defined in .code-shell/agents/*.md so the
+ * model knows it can pass `agent_type` instead of hand-rolling an ad-hoc
+ * agent. Without this the model never sees the registry (it lives per-engine,
+ * not in the static tool def) and falls back to nameless ephemeral agents —
+ * see the Core A/B/C incident. Returns "" when no roles are defined, so the
+ * base description is left untouched.
+ */
+export declare function buildAgentTypesBlock(registry: AgentDefinitionRegistry | undefined): string;
+/**
+ * Produce an Agent tool definition whose description ends with the live
+ * available-agent-types listing. Pure: takes the registry, returns a new def
+ * (the base `agentToolDef` const is never mutated). When no roles exist the
+ * base def is returned unchanged.
+ */
+export declare function agentToolDefWithTypes(registry: AgentDefinitionRegistry | undefined): ToolDefinition;
+type SubAgentLifecycle = "subagent_start" | "subagent_finish" | "subagent_error";
+/**
+ * Emit a sub-agent lifecycle event via the existing `notification` hook,
+ * tagged with a `kind`. No-op when hooks are absent. Fire-and-forget: emit is
+ * async, we deliberately `void` it so bookkeeping never blocks on a handler
+ * (mirrors the background-completion notification below).
+ */
+export declare function emitSubAgentHook(hooks: HookRegistry | undefined, kind: SubAgentLifecycle, payload: {
+    agentId: string;
+    description: string;
+    text?: string;
+    error?: string;
+}): void;
 export declare const agentToolDef: ToolDefinition;
 export declare function agentTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
 export declare const agentStatusToolDef: ToolDefinition;
 export declare function agentStatusTool(args: Record<string, unknown>): Promise<string>;
 export declare const agentCancelToolDef: ToolDefinition;
 export declare function agentCancelTool(args: Record<string, unknown>): Promise<string>;
+export {};