@cjhyy/code-shell-core 0.7.1 → 0.8.0

package/README.md

@@ -17,10 +17,7 @@ Requires Node ≥ 20.10 and an ESM-capable runtime.
 ## Quickstart
 
 ```ts
-import {
-  Engine,
-  HeadlessApprovalBackend,
-} from "@cjhyy/code-shell-core";
+import { Engine, HeadlessApprovalBackend } from "@cjhyy/code-shell-core";
 
 const engine = new Engine({
   llm: {
@@ -37,9 +34,7 @@ const engine = new Engine({
   headless: true,
 });
 
-const result = await engine.run(
-  "list files in this directory and summarise their purpose",
-);
+const result = await engine.run("list files in this directory and summarise their purpose");
 
 console.log(result.text);
 console.log("turns:", result.turnCount, "reason:", result.reason);
@@ -60,7 +55,9 @@ Restrict the tool set:
 
 ```ts
 new Engine({
-  llm: { /* … */ },
+  llm: {
+    /* … */
+  },
   // Whitelist — only these built-in tools are registered.
   enabledBuiltinTools: ["Read", "Glob", "Grep", "WebFetch"],
   // Or blacklist — registers every built-in except these.
@@ -93,11 +90,7 @@ Direct `new Engine(...)` still works for advanced cases — but the
 protocol-mediated path is what we test, document, and avoid breaking.
 
 ```ts
-import {
-  createServer,
-  createClient,
-  createInProcessTransport,
-} from "@cjhyy/code-shell-core";
+import { createServer, createClient, createInProcessTransport } from "@cjhyy/code-shell-core";
 
 const [serverT, clientT] = createInProcessTransport();
 const handle = createServer({
@@ -123,6 +116,16 @@ For an out-of-process worker, swap `createInProcessTransport()` for a
 `StdioTransport` pair. The factory accepts any `Transport`, so a future
 `IpcAdapter` will compose without changing the call shape.
 
+Browser UI hosts that only need the trusted Panel App lifecycle coordinator should
+use the audited browser-safe subpath:
+
+```ts
+import { PanelAppLifecycleRuntime } from "@cjhyy/code-shell-core/browser/panel-app-runtime";
+```
+
+This entry contains no Engine, filesystem, process or Electron dependency.
+The non-browser alias is `@cjhyy/code-shell-core/panel-app-runtime`.
+
 `StreamEvent` includes `background_agent_completed` (B2.2) so embedders
 that don't poll `notificationQueue` still observe sub-agent finish/fail
 results. `client.onBackgroundAgentCompleted((sessionId, event) => …)` is
@@ -133,16 +136,16 @@ the typed entry point; events also flow through the catch-all
 
 These exports are covered by the stability promise:
 
-| Area | Stable exports |
-| --- | --- |
-| Factories | `createServer`, `createClient`, `createInProcessTransport`, `StdioTransport` |
-| Server/client | `AgentServer`, `AgentClient` (direct use is supported but `createServer/Client` preferred) |
-| Engine | `Engine`, `EngineConfig`, `EngineRuntime`, `ChatSessionManager` |
-| Protocol types | `Methods`, `ErrorCodes`, `RpcMessage`, `RunResult`, `StreamEvent`, `StreamCallback`, `BackgroundAgentCompletedEvent` |
-| LLM | `LLMConfig`, `LLMResponse`, `ModelPool`, `createLLMClient`, `registerProvider` |
-| Tool authoring | `ToolDefinition`, `ToolCall`, `ToolResult`, `RegisteredTool`, `BUILTIN_TOOLS`, `HookContext`, `HookResult` |
-| Permissions | `PermissionClassifier`, `HeadlessApprovalBackend`, `AutoApprovalBackend`, `ApprovalBackend`, `PermissionMode`, `PermissionRule` |
-| Errors | `FrameworkError` + subclasses (`LLMError`, `ToolError`, `PermissionDeniedError`, …) |
+| Area           | Stable exports                                                                                                                  |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| Factories      | `createServer`, `createClient`, `createInProcessTransport`, `StdioTransport`                                                    |
+| Server/client  | `AgentServer`, `AgentClient` (direct use is supported but `createServer/Client` preferred)                                      |
+| Engine         | `Engine`, `EngineConfig`, `EngineRuntime`, `ChatSessionManager`                                                                 |
+| Protocol types | `Methods`, `ErrorCodes`, `RpcMessage`, `RunResult`, `StreamEvent`, `StreamCallback`, `BackgroundAgentCompletedEvent`            |
+| LLM            | `LLMConfig`, `LLMResponse`, `ModelPool`, `createLLMClient`, `registerProvider`                                                  |
+| Tool authoring | `ToolDefinition`, `ToolCall`, `ToolResult`, `RegisteredTool`, `BUILTIN_TOOLS`, `HookContext`, `HookResult`                      |
+| Permissions    | `PermissionClassifier`, `HeadlessApprovalBackend`, `AutoApprovalBackend`, `ApprovalBackend`, `PermissionMode`, `PermissionRule` |
+| Errors         | `FrameworkError` + subclasses (`LLMError`, `ToolError`, `PermissionDeniedError`, …)                                             |
 
 ### Treat as internal
 
@@ -153,11 +156,21 @@ experimental/internal unless explicitly documented otherwise, and may
 change between minor versions without notice. Plan to migrate via the
 protocol surface instead of deep-importing.
 
+In 0.8 the plugin installer / marketplace / onboarding / self-updater exports
+(`installPluginFromPath`, `installPlugin`, `addMarketplace`, `resolveApiKey`,
+`checkForUpdate`, …) moved off this root entry to
+`@cjhyy/code-shell-core/internal` — they are host-assembly surfaces for the
+in-repo TUI/desktop apps, not part of the embeddable agent SDK.
+
 ## Stability
 
 Pre-1.0 — APIs may change between minor versions. The "stable surface"
 table above is the contract; everything else is mobile.
 
+**Breaking in 0.8:** host-assembly exports (installer/marketplace/onboarding/
+updater) left the root entry; import them from
+`@cjhyy/code-shell-core/internal` if you must (no stability promise there).
+
 See [CHANGELOG.md](https://github.com/cjhyy/codeshell/blob/main/CHANGELOG.md) in the monorepo.
 
 ## License

package/dist/agent/agent-definition-registry.d.ts

@@ -7,8 +7,8 @@ export interface AgentSourceDir {
     pluginName?: string;
 }
 /**
- * Loads reusable sub-agent role definitions from one or more directories
- * of `*.md` files. Non-recursive. Malformed files are skipped with a
+ * Loads reusable sub-agent role definitions recursively from one or more
+ * directories. Malformed `.md` files are skipped with a
  * warning rather than failing the whole load — one bad role file must
  * not break the agent system.
  *

package/dist/agent/agent-definition-registry.js

@@ -1,9 +1,9 @@
-import { readdirSync, readFileSync, existsSync, statSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, sep } from "node:path";
 import { parseAgentDefinition } from "./agent-definition.js";
 /**
- * Loads reusable sub-agent role definitions from one or more directories
- * of `*.md` files. Non-recursive. Malformed files are skipped with a
+ * Loads reusable sub-agent role definitions recursively from one or more
+ * directories. Malformed `.md` files are skipped with a
  * warning rather than failing the whole load — one bad role file must
  * not break the agent system.
  *
@@ -27,14 +27,14 @@ export class AgentDefinitionRegistry {
         for (const { dir, source, pluginName } of dirs) {
             if (!existsSync(dir) || !statSync(dir).isDirectory())
                 continue;
-            for (const entry of readdirSync(dir).sort()) {
-                if (!entry.endsWith(".md"))
-                    continue;
-                const full = join(dir, entry);
+            const pluginRoot = source === "plugin" ? safeRealpath(dir) : null;
+            if (source === "plugin" && !pluginRoot)
+                continue;
+            for (const { full, sourceName } of collectAgentMarkdownFiles(dir, pluginRoot)) {
                 try {
                     if (!statSync(full).isFile())
                         continue;
-                    const def = parseAgentDefinition(readFileSync(full, "utf8"), entry);
+                    const def = parseAgentDefinition(readFileSync(full, "utf8"), sourceName);
                     def.source = source;
                     if (pluginName)
                         def.pluginName = pluginName;
@@ -54,7 +54,7 @@ export class AgentDefinitionRegistry {
                     reg.defs.set(def.name, def);
                 }
                 catch (err) {
-                    reg.warnings.push(`${entry}: ${err.message}`);
+                    reg.warnings.push(`${sourceName}: ${err.message}`);
                 }
             }
         }
@@ -74,3 +74,40 @@ export class AgentDefinitionRegistry {
         return [...this.defs.values()];
     }
 }
+function safeRealpath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return null;
+    }
+}
+function resolveContainedPluginAgent(root, candidate) {
+    const target = safeRealpath(candidate);
+    if (!target)
+        return null;
+    const rel = relative(root, target);
+    if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+        return null;
+    return target;
+}
+function collectAgentMarkdownFiles(root, pluginRoot) {
+    const files = [];
+    const walk = (dir) => {
+        for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            const candidate = join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walk(candidate);
+                continue;
+            }
+            if (!entry.name.endsWith(".md"))
+                continue;
+            const full = pluginRoot === null ? candidate : resolveContainedPluginAgent(pluginRoot, candidate);
+            if (!full)
+                continue;
+            files.push({ full, sourceName: relative(root, candidate) });
+        }
+    };
+    walk(root);
+    return files;
+}

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

@@ -1,3 +1,4 @@
+import type { SandboxMode } from "../tool-system/sandbox/index.js";
 /** A reusable sub-agent role, loaded from a Markdown file. */
 export interface AgentDefinition {
     /** Unique role key, e.g. "researcher". Matched against Agent({ agent_type }). */
@@ -17,6 +18,10 @@ export interface AgentDefinition {
      * system prompt and the only ones it may invoke. Empty array → no skills.
      */
     skills?: string[];
+    /** Optional OS shell sandbox mode. Undefined → inherit the parent sandbox. */
+    sandbox?: SandboxMode;
+    /** Optional MCP server allowlist. Undefined → inherit all; [] → no MCP. */
+    mcp?: string[];
     /** Markdown body — becomes the child Engine's appendSystemPrompt. */
     systemPrompt: string;
     /** Where this def was loaded from. Runtime-only; never serialized. */

package/dist/agent/agent-definition.js

@@ -1,4 +1,8 @@
 import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+const SANDBOX_MODES = new Set(["off", "auto", "seatbelt", "bwrap"]);
+function normalizeSandboxMode(value) {
+    return typeof value === "string" && SANDBOX_MODES.has(value) ? value : undefined;
+}
 /**
  * Normalize a frontmatter `tools:` / `skills:` value into a string[].
  * Accepts both a YAML list (`[a, b]`) and a comma/whitespace-separated
@@ -56,6 +60,12 @@ export function parseAgentDefinition(raw, sourceName) {
     const skills = normalizeNameList(fm.skills);
     if (skills !== undefined)
         def.skills = skills;
+    const sandbox = normalizeSandboxMode(fm.sandbox);
+    if (sandbox !== undefined)
+        def.sandbox = sandbox;
+    const mcp = normalizeNameList(fm.mcp);
+    if (mcp !== undefined)
+        def.mcp = mcp;
     return def;
 }
 /**
@@ -78,6 +88,10 @@ export function serializeAgentDefinition(def) {
         fm.tools = def.tools;
     if (def.skills !== undefined)
         fm.skills = def.skills;
+    if (def.sandbox !== undefined)
+        fm.sandbox = def.sandbox;
+    if (def.mcp !== undefined)
+        fm.mcp = def.mcp;
     const yaml = stringifyYaml(fm).trimEnd();
     return `---\n${yaml}\n---\n${def.systemPrompt}\n`;
 }

package/dist/automation/index.d.ts

@@ -6,7 +6,7 @@
  * no GUI/TTY assumptions, so the same code runs in any host
  * (docs/automation-plan-2026-05-31.md, D1).
  */
-import { CronScheduler } from "./scheduler.js";
+import { CronScheduler, type CronJobLifecycleEvent } from "./scheduler.js";
 import { type CronRunner, type RunSubmitter } from "./runner.js";
 import type { CronStore } from "./store.js";
 export interface StartAutomationDeps {
@@ -20,6 +20,8 @@ export interface StartAutomationDeps {
      */
     runner?: CronRunner;
     runManager?: RunSubmitter;
+    /** Installed before persisted jobs are restored and their timers are armed. */
+    onJobEvent?: (event: CronJobLifecycleEvent) => void;
 }
 export interface AutomationHandle {
     scheduler: CronScheduler;
@@ -32,10 +34,11 @@ export interface AutomationHandle {
  * `runManager` when both are supplied (it gives run history).
  */
 export declare function startAutomation(deps: StartAutomationDeps): AutomationHandle;
-export { CronScheduler, cronScheduler, type CronJob } from "./scheduler.js";
+export { CronScheduler, cronScheduler, type CronExecutionOutcome, type CronJob, type CronJobLifecycleEvent, } from "./scheduler.js";
 export { CronStore, defaultCronStorePath } from "./store.js";
 export { bindCronToEngine, bindCronToRunManager, type CronRunner, type CronRunRequest, type CronRunResult, type RunSubmitter, } from "./runner.js";
 export { isCronExpression, parseCronExpression, nextCronTime, type ParsedCron, } from "./cron-expr.js";
-export type { CronPermissionLevel, CreateJobOptions, UpdateJobPatch } from "./scheduler.js";
-export { resolveWritePolicy, wrapUntrustedInput, type WritePolicy, } from "./write-policy.js";
+export { validateSchedule } from "./scheduler.js";
+export type { CronPermissionLevel, CronTemplateSource, CreateJobOptions, UpdateJobPatch, } from "./scheduler.js";
+export { resolveWritePolicy, wrapUntrustedInput, type WritePolicy } from "./write-policy.js";
 export { runWriteJobInWorktree, type WriteJobGitOps, type RunWriteJobInput, type RunWriteJobResult, } from "./write-run.js";

package/dist/automation/index.js

@@ -24,6 +24,7 @@ export function startAutomation(deps) {
     else {
         throw new Error("startAutomation requires either a runner or a runManager");
     }
+    scheduler.setJobEventListener(deps.onJobEvent);
     scheduler.loadJobs();
     return {
         scheduler,
@@ -31,9 +32,10 @@ export function startAutomation(deps) {
     };
 }
 // Re-export the building blocks so hosts import everything from one place.
-export { CronScheduler, cronScheduler } from "./scheduler.js";
+export { CronScheduler, cronScheduler, } from "./scheduler.js";
 export { CronStore, defaultCronStorePath } from "./store.js";
 export { bindCronToEngine, bindCronToRunManager, } from "./runner.js";
 export { isCronExpression, parseCronExpression, nextCronTime, } from "./cron-expr.js";
-export { resolveWritePolicy, wrapUntrustedInput, } from "./write-policy.js";
+export { validateSchedule } from "./scheduler.js";
+export { resolveWritePolicy, wrapUntrustedInput } from "./write-policy.js";
 export { runWriteJobInWorktree, } from "./write-run.js";

package/dist/automation/runner.js

@@ -58,10 +58,12 @@ export function bindCronToEngine(scheduler, runner) {
             // was deleted) auto-disables the job so it stops silently retrying.
             if (result?.stop) {
                 scheduler.disableWithReason(job.id, result.stop.reason);
+                return { stoppedReason: result.stop.reason };
             }
         }
         catch (err) {
-            logCronFailure(job, err);
+            if (!signal.aborted)
+                logCronFailure(job, err);
             throw err; // let the scheduler's catch record stats + keep ticking
         }
     });

package/dist/automation/scheduler.d.ts

@@ -13,6 +13,13 @@ import type { CronStore } from "./store.js";
 export declare function isCronMisfire(scheduledFor: number, now: number): boolean;
 /** Permission tier a scheduled job runs under (Phase 5 enforces write tiers). */
 export type CronPermissionLevel = "read-only" | "workspace-write" | "full";
+/** Non-executable provenance for a job explicitly created from a plugin template. */
+export interface CronTemplateSource {
+    installKey: string;
+    templateId: string;
+    revision: string;
+    pluginVersion?: string;
+}
 export interface CronJob {
     id: string;
     name: string;
@@ -44,6 +51,27 @@ export interface CronJob {
      *  target whose session no longer exists. Surfaced in the UI so a silently
      *  stopped job is explainable; cleared when the job is re-enabled. */
     disabledReason?: string;
+    /**
+     * Immutable provenance copied when a user instantiates a plugin template.
+     * The job remains standalone if the plugin is later updated or uninstalled.
+     */
+    templateSource?: CronTemplateSource;
+}
+/**
+ * Job execution lifecycle event (see CronScheduler.setJobEventListener).
+ * job_error carries the message `fire()` would otherwise swallow.
+ */
+export interface CronJobLifecycleEvent {
+    type: "job_start" | "job_end" | "job_stopped" | "job_cancelled" | "job_error";
+    job: CronJob;
+    durationMs?: number;
+    reason?: string;
+    error?: string;
+}
+/** Optional semantic outcome returned by an executor after a non-throwing run. */
+export interface CronExecutionOutcome {
+    /** The run permanently disabled itself and should not be reported as success. */
+    stoppedReason?: string;
 }
 /** Optional metadata accepted by create(). */
 export interface CreateJobOptions {
@@ -52,6 +80,7 @@ export interface CreateJobOptions {
     permissionLevel?: CronPermissionLevel;
     once?: boolean;
     resumeSessionId?: string;
+    templateSource?: CronTemplateSource;
 }
 /** Fields editable via update(). Any omitted field is left unchanged. */
 export interface UpdateJobPatch {
@@ -79,6 +108,7 @@ export declare class CronScheduler {
     private runningControllers;
     private nextId;
     private onExecute?;
+    private onJobEvent?;
     /** Optional persistence backend. When set, every create/delete/pause/resume
      *  writes the full job set to disk so jobs survive a restart. */
     private store?;
@@ -96,7 +126,16 @@ export declare class CronScheduler {
     /** Attach (or replace) the persistence backend. Used to give the shared
      *  singleton a store at runtime startup without changing its identity. */
     setStore(store: CronStore): void;
-    setExecutor(fn: (job: CronJob, signal: AbortSignal) => Promise<void>): void;
+    setExecutor(fn: (job: CronJob, signal: AbortSignal) => Promise<void | CronExecutionOutcome>): void;
+    /**
+     * Observe job execution lifecycle
+     * (job_start → job_end | job_stopped | job_cancelled | job_error). Hosts
+     * wire this to their notification surface so scheduled runs — especially
+     * failures, which `fire()` otherwise swallows — are no longer silent.
+     * Listener errors are swallowed; observation never affects scheduling.
+     */
+    setJobEventListener(listener: ((event: CronJobLifecycleEvent) => void) | undefined): void;
+    private emitJobEvent;
     /**
      * Abort the in-flight run of `jobId`, if any. Aborts the AbortSignal handed
      * to the executor (which Engine.run cooperates with — it resolves with
@@ -175,6 +214,21 @@ export declare class CronScheduler {
      * calling arm() repeatedly.
      */
     private arm;
+    /**
+     * Wait until an ABSOLUTE instant, in `setTimeout`-safe chunks.
+     *
+     * Node/Electron timers take a 32-bit signed delay: anything above
+     * 2,147,483,647ms (~24.8 days) does NOT wait longer — it emits
+     * `TimeoutOverflowWarning` and is coerced to **1ms**. A `30d` interval or a
+     * monthly cron therefore fired almost immediately and then kept re-firing,
+     * because the next absolute target was still out of range.
+     *
+     * So never hand a raw long delay to setTimeout. Sleep at most
+     * MAX_TIMER_DELAY_MS at a time and re-check the clock; only run `onDue` once
+     * the real instant has arrived. Chunked waiting also self-corrects for clock
+     * drift and sleep/wake, since each hop recomputes from `Date.now()`.
+     */
+    private armAt;
     private armInterval;
     private nextIntervalRunAfter;
     private armCron;
@@ -188,6 +242,8 @@ export declare class CronScheduler {
      */
     private fire;
 }
+/** Validate a schedule string (interval or cron expr) without scheduling. Throws on invalid. */
+export declare function validateSchedule(schedule: string, timezone?: string): void;
 /**
  * Parse a schedule string into milliseconds.
  * Supports: "30s", "5m", "1h", "1d", or raw (all-digit) milliseconds.