@cjhyy/code-shell-core 0.6.0-rc.9 → 0.7.0

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,206 @@
+# Third-party notices
+
+This package includes code derived from third-party open source projects.
+
+## OpenAI Codex apply-patch
+
+Files under `src/tool-system/builtin/apply-patch/` contain TypeScript code
+adapted from OpenAI Codex `codex-rs/apply-patch`.
+
+- Source: https://github.com/openai/codex/tree/main/codex-rs/apply-patch
+- License: Apache License 2.0
+- Copyright: Copyright 2025 OpenAI
+
+The CodeShell implementation includes modifications, including a two-phase
+commit/rollback behavior for failed patches.
+
+### Adapted files
+
+| Source (Rust)                      | Target (TypeScript)           | Notes                                               |
+| ---------------------------------- | ----------------------------- | --------------------------------------------------- |
+| `src/seek_sequence.rs`             | `seek-sequence.ts`            | Direct port; same four-pass strategy                |
+| `src/parser.rs`                    | `parser.ts`                   | Direct port of the V4A grammar parser               |
+| `src/lib.rs`                       | `applier.ts`                  | `compute_replacements` algorithm port               |
+| `apply_patch_tool_instructions.md` | tool description (`index.ts`) | Patch-format instructions adapted from the original |
+| `tests/fixtures/scenarios/`        | `tests/fixtures/apply-patch/` | Golden scenarios used for conformance               |
+
+### Apache License 2.0
+
+```
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+```

package/dist/automation/scheduler.d.ts

@@ -120,7 +120,8 @@ export declare class CronScheduler {
      * created/deleted/changed jobs through the same store. Reconciliation:
      *   - jobs on disk but not in memory  → added (and armed if enabled)
      *   - jobs in memory but not on disk  → removed + timer cleared
-     *   - jobs whose schedule/enabled differ → re-armed to match disk
+     *   - jobs whose schedule/enabled/timezone differ → re-armed to match disk
+     *   - unchanged enabled jobs with live timers → kept as-is, preserving nextRun
      *
      * Pass `{ arm: false }` in a host that must NOT execute jobs (the worker —
      * separate process from the one that owns execution); it still tracks +
@@ -130,6 +131,8 @@ export declare class CronScheduler {
         arm?: boolean;
     }): void;
     private reconcileJobs;
+    private jobDefinitionChanged;
+    private mergeJobFromDisk;
     private nextPersistedId;
     /** Recompute nextRun without arming a timer (for display in disabled/no-arm hosts). */
     private refreshNextRunForDisplay;
@@ -166,19 +169,22 @@ export declare class CronScheduler {
      */
     runNow(id: string): boolean;
     /**
-     * Arm a job's timer. Interval schedules ("5m") use setInterval; cron-
-     * expression schedules ("0 9 * * 1-5") compute the next trigger in the
-     * job's timezone and use setTimeout, re-arming after each fire. nextRun is
-     * updated to reflect the scheduled instant.
+     * Arm a job's timer from its current definition. This intentionally resets
+     * the absolute phase (interval: now+interval; cron: next matching wall-clock
+     * instant), so reconcileJobs preserves unchanged live timers instead of
+     * calling arm() repeatedly.
      */
     private arm;
-    private refreshIntervalNextRun;
+    private armInterval;
+    private nextIntervalRunAfter;
     private armCron;
     private clearTimer;
     /**
      * Shared fire path for both schedule kinds. Re-entrancy guard, run-stat
      * bookkeeping, persistence, then the executor. `afterStats` updates nextRun
-     * for the next occurrence (interval: now+interval; cron: re-armed inside).
+     * for the next occurrence. Returns false when the run was skipped by enabled
+     * state or the re-entrancy guard, so one-shot timers can still schedule the
+     * next absolute slot without starting overlapping executions.
      */
     private fire;
 }

package/dist/automation/scheduler.js

@@ -102,7 +102,8 @@ export class CronScheduler {
      * created/deleted/changed jobs through the same store. Reconciliation:
      *   - jobs on disk but not in memory  → added (and armed if enabled)
      *   - jobs in memory but not on disk  → removed + timer cleared
-     *   - jobs whose schedule/enabled differ → re-armed to match disk
+     *   - jobs whose schedule/enabled/timezone differ → re-armed to match disk
+     *   - unchanged enabled jobs with live timers → kept as-is, preserving nextRun
      *
      * Pass `{ arm: false }` in a host that must NOT execute jobs (the worker —
      * separate process from the one that owns execution); it still tracks +
@@ -127,28 +128,67 @@ export class CronScheduler {
         let maxId = 0;
         for (const job of persisted) {
             const prev = this.jobs.get(job.id);
-            this.jobs.set(job.id, job);
             const n = parseInt(job.id, 10);
             if (Number.isFinite(n) && n > maxId)
                 maxId = n;
-            // (Re)arm when execution is on. arm() is idempotent (clears any prior
-            // timer first), so calling it for unchanged jobs is harmless; it also
-            // refreshes nextRun for display.
-            if (arm && job.enabled) {
-                this.arm(job);
+            if (!prev) {
+                this.jobs.set(job.id, job);
+                if (arm && job.enabled) {
+                    this.arm(job);
+                }
+                else {
+                    this.refreshNextRunForDisplay(job);
+                }
+                continue;
             }
-            else {
-                // Disabled (or arm suppressed): ensure no stale timer survives a
-                // prior enabled state.
-                if (prev && this.timers.has(job.id))
+            const definitionChanged = this.jobDefinitionChanged(prev, job);
+            const hasTimer = this.timers.has(job.id);
+            if (!arm || !job.enabled) {
+                // Disabled (or arm suppressed): ensure no stale timer survives a prior
+                // enabled state. Keep the existing object identity so any in-flight
+                // executor bookkeeping still points at the scheduler-visible job.
+                this.mergeJobFromDisk(prev, job);
+                if (hasTimer)
                     this.clearTimer(job.id);
-                // Still refresh nextRun for display even when not arming.
-                if (!arm || !job.enabled)
-                    this.refreshNextRunForDisplay(job);
+                this.refreshNextRunForDisplay(prev);
+            }
+            else if (definitionChanged || !hasTimer) {
+                // New scheduling definition, or this process has no live timer (e.g.
+                // after stopAll or when taking over from an arm:false worker): reset the
+                // absolute phase from now and arm.
+                this.mergeJobFromDisk(prev, job);
+                this.arm(prev);
+            }
+            else {
+                // Unchanged enabled job with a live timer: preserve the timer and the
+                // absolute nextRun. Merge user-editable fields into the same object so
+                // the existing timeout closure and scheduler.get(id) never diverge.
+                this.mergeJobFromDisk(prev, job, { preserveNextRun: true });
             }
         }
         this.nextId = Math.max(this.nextId, maxId + 1);
     }
+    jobDefinitionChanged(prev, next) {
+        return (prev.schedule !== next.schedule ||
+            prev.enabled !== next.enabled ||
+            prev.timezone !== next.timezone);
+    }
+    mergeJobFromDisk(target, source, opts) {
+        const preservedNextRun = target.nextRun;
+        for (const key of Object.keys(target)) {
+            if (!(key in source))
+                delete target[key];
+        }
+        Object.assign(target, source);
+        if (opts?.preserveNextRun) {
+            if (preservedNextRun === undefined) {
+                delete target.nextRun;
+            }
+            else {
+                target.nextRun = preservedNextRun;
+            }
+        }
+    }
     nextPersistedId(jobs) {
         let maxId = 0;
         for (const job of jobs) {
@@ -377,6 +417,8 @@ export class CronScheduler {
                     if (patch.schedule !== undefined || patch.timezone !== undefined) {
                         validateSchedule(nextSchedule, nextTimezone);
                     }
+                    const scheduleChanged = (patch.schedule !== undefined && patch.schedule !== job.schedule) ||
+                        (patch.timezone !== undefined && patch.timezone !== job.timezone);
                     if (patch.name !== undefined)
                         job.name = patch.name;
                     if (patch.prompt !== undefined)
@@ -389,14 +431,15 @@ export class CronScheduler {
                         job.cwd = patch.cwd;
                     if (patch.permissionLevel !== undefined)
                         job.permissionLevel = patch.permissionLevel;
-                    this.refreshNextRunForDisplay(job);
+                    if (scheduleChanged)
+                        this.refreshNextRunForDisplay(job);
                     updated = job;
                     return job;
                 });
                 return { jobs: next, result: updated };
             });
             this.reconcileJobs(tx.jobs);
-            return tx.result ? this.jobs.get(id) ?? tx.result : null;
+            return tx.result ? (this.jobs.get(id) ?? tx.result) : null;
         }
         const job = this.jobs.get(id);
         if (!job)
@@ -407,6 +450,8 @@ export class CronScheduler {
         if (patch.schedule !== undefined || patch.timezone !== undefined) {
             validateSchedule(nextSchedule, nextTimezone);
         }
+        const scheduleChanged = (patch.schedule !== undefined && patch.schedule !== job.schedule) ||
+            (patch.timezone !== undefined && patch.timezone !== job.timezone);
         if (patch.name !== undefined)
             job.name = patch.name;
         if (patch.prompt !== undefined)
@@ -419,11 +464,12 @@ export class CronScheduler {
             job.cwd = patch.cwd;
         if (patch.permissionLevel !== undefined)
             job.permissionLevel = patch.permissionLevel;
-        // Re-arm so a schedule/timezone change drives execution now. arm() is
-        // idempotent and respects enabled + executionEnabled (paused → no timer,
-        // but nextRun still refreshed for display).
+        // Re-arm only when the schedule definition changed, or when an enabled job
+        // has no live timer to preserve. Ordinary field edits keep the absolute
+        // nextRun so they do not push an interval job back.
         if (job.enabled) {
-            this.arm(job);
+            if (scheduleChanged || !this.timers.has(id))
+                this.arm(job);
         }
         else {
             this.clearTimer(id);
@@ -454,10 +500,10 @@ export class CronScheduler {
         return true;
     }
     /**
-     * Arm a job's timer. Interval schedules ("5m") use setInterval; cron-
-     * expression schedules ("0 9 * * 1-5") compute the next trigger in the
-     * job's timezone and use setTimeout, re-arming after each fire. nextRun is
-     * updated to reflect the scheduled instant.
+     * Arm a job's timer from its current definition. This intentionally resets
+     * the absolute phase (interval: now+interval; cron: next matching wall-clock
+     * instant), so reconcileJobs preserves unchanged live timers instead of
+     * calling arm() repeatedly.
      */
     arm(job) {
         this.clearTimer(job.id);
@@ -472,15 +518,36 @@ export class CronScheduler {
         }
         else {
             const intervalMs = parseSchedule(job.schedule);
-            job.nextRun = Date.now() + intervalMs;
+            const nextRun = Date.now() + intervalMs;
+            job.nextRun = nextRun;
             if (!this.executionEnabled)
                 return;
-            const timer = setInterval(() => void this.fire(job, () => this.refreshIntervalNextRun(job, intervalMs)), intervalMs);
-            this.timers.set(job.id, timer);
+            this.armInterval(job, intervalMs, nextRun);
         }
     }
-    refreshIntervalNextRun(job, intervalMs) {
-        job.nextRun = Date.now() + intervalMs;
+    armInterval(job, intervalMs, scheduledFor) {
+        job.nextRun = scheduledFor;
+        const delay = Math.max(0, scheduledFor - Date.now());
+        const timer = setTimeout(() => {
+            this.timers.delete(job.id);
+            const rearm = () => {
+                if (!this.executionEnabled || !job.enabled || !this.jobs.has(job.id))
+                    return;
+                this.armInterval(job, intervalMs, this.nextIntervalRunAfter(scheduledFor, intervalMs, Date.now()));
+            };
+            void this.fire(job, rearm).then((ran) => {
+                if (!ran)
+                    rearm();
+            });
+        }, delay);
+        this.timers.set(job.id, timer);
+    }
+    nextIntervalRunAfter(scheduledFor, intervalMs, now) {
+        let next = scheduledFor + intervalMs;
+        if (next <= now) {
+            next += (Math.floor((now - next) / intervalMs) + 1) * intervalMs;
+        }
+        return next;
     }
     armCron(job) {
         const cron = parseCronExpression(job.schedule);
@@ -495,6 +562,7 @@ export class CronScheduler {
         const scheduledFor = next;
         const delay = Math.max(0, next - Date.now());
         const timer = setTimeout(() => {
+            this.timers.delete(job.id);
             // Misfire guard for sleep/wake drift. A setTimeout pauses while the host
             // sleeps, then fires the instant the machine wakes — which can be hours
             // off the scheduled wall-clock (observed: a `0 9 * * *` job running at
@@ -507,12 +575,16 @@ export class CronScheduler {
                     this.armCron(job);
                 return;
             }
-            void this.fire(job, () => {
+            const rearm = () => {
                 // Re-arm for the following occurrence — but only if the job still
                 // exists. A one-shot (once) job deletes itself in fire()'s finally,
                 // so this closure must not resurrect it via a stale reference.
                 if (job.enabled && this.jobs.has(job.id))
                     this.armCron(job);
+            };
+            void this.fire(job, rearm).then((ran) => {
+                if (!ran)
+                    rearm();
             });
         }, delay);
         this.timers.set(job.id, timer);
@@ -527,16 +599,18 @@ export class CronScheduler {
     /**
      * Shared fire path for both schedule kinds. Re-entrancy guard, run-stat
      * bookkeeping, persistence, then the executor. `afterStats` updates nextRun
-     * for the next occurrence (interval: now+interval; cron: re-armed inside).
+     * for the next occurrence. Returns false when the run was skipped by enabled
+     * state or the re-entrancy guard, so one-shot timers can still schedule the
+     * next absolute slot without starting overlapping executions.
      */
     async fire(job, afterStats, force = false) {
         if (!job.enabled && !force)
-            return;
+            return false;
         // Re-entrancy guard: if this job's previous run is still in flight
         // (onExecute slower than the interval), skip rather than stacking
         // overlapping executions that double-count runCount.
         if (this.running.has(job.id))
-            return;
+            return false;
         this.running.add(job.id);
         // One in-flight entry per job. abort(jobId) trips `controller` (Engine.run
         // cooperates and resolves early) and awaits `done`, which we resolve in the
@@ -573,6 +647,7 @@ export class CronScheduler {
             // Unblock any abort() awaiting this run's teardown.
             resolveDone();
         }
+        return true;
     }
 }
 /** Validate a schedule string (interval or cron expr) without scheduling. Throws on invalid. */
@@ -604,10 +679,14 @@ export function parseSchedule(schedule) {
         // path's `> 0` guard and the "throw on bad input" contract.
         if (value > 0) {
             switch (match[2]) {
-                case "s": return value * 1000;
-                case "m": return value * 60 * 1000;
-                case "h": return value * 60 * 60 * 1000;
-                case "d": return value * 24 * 60 * 60 * 1000;
+                case "s":
+                    return value * 1000;
+                case "m":
+                    return value * 60 * 1000;
+                case "h":
+                    return value * 60 * 60 * 1000;
+                case "d":
+                    return value * 24 * 60 * 60 * 1000;
             }
         }
     }

package/dist/capability-control/service.d.ts

@@ -31,9 +31,11 @@ export interface CapabilityServiceDeps {
     readInstalledPlugins: () => InstalledPluginsV2;
     resolveBuiltinToolNames: (o?: {
         preset?: string;
+        host?: "desktop";
         enabledBuiltinTools?: string[];
         disabledBuiltinTools?: string[];
     }) => string[];
+    builtinToolHost?: "desktop";
 }
 export declare class CapabilityService {
     private readonly deps;

package/dist/capability-control/service.js

@@ -13,7 +13,7 @@
  */
 import { CapabilityNotFoundError } from "./types.js";
 import { projectBuiltin, projectMcp, projectSkills, projectPlugins, projectAgents, } from "./project.js";
-import { applyOverride, bucketForKind, overrideTokenForId, overrideFor, } from "./overlay.js";
+import { applyOverride, bucketForKind, overrideTokenForId, overrideFor } from "./overlay.js";
 export class CapabilityService {
     deps;
     constructor(deps) {
@@ -30,12 +30,14 @@ export class CapabilityService {
         const agent = (s.agent ?? {});
         const tools = this.deps.registry.listToolsDetailed();
         const preset = agent.preset;
+        const host = this.deps.builtinToolHost;
         const base = [
             ...projectBuiltin({
                 tools: tools.filter((t) => t.source === "builtin"),
-                presetDefaults: this.deps.resolveBuiltinToolNames({ preset }),
+                presetDefaults: this.deps.resolveBuiltinToolNames({ preset, host }),
                 effective: this.deps.resolveBuiltinToolNames({
                     preset,
+                    host,
                     enabledBuiltinTools: agent.enabledBuiltinTools ?? [],
                     disabledBuiltinTools: agent.disabledBuiltinTools ?? [],
                 }),

package/dist/cc-orchestrator/agent-adapter.d.ts

@@ -2,8 +2,12 @@ export type PermissionMode = "default" | "acceptEdits" | "bypassPermissions";
 export interface BuildArgsOpts {
     prompt: string;
     resumeSessionId?: string;
+    /** Optional caller-specified model override. Passed through without validation; the CLI reports unknown models. */
+    model?: string;
     permissionMode: PermissionMode;
     cwd: string;
+    imagePaths?: string[];
+    codexImageInputSupported?: boolean;
 }
 export interface ParsedResult {
     sessionId: string;

package/dist/cc-orchestrator/agent-adapter.js

@@ -14,6 +14,8 @@ export const claudeAdapter = {
     buildArgs(opts) {
         // -p (print/headless) + stream-json REQUIRES --verbose (verified).
         const args = ["-p", opts.prompt, "--output-format", "stream-json", "--verbose"];
+        if (opts.model)
+            args.push("--model", opts.model);
         if (opts.resumeSessionId)
             args.push("--resume", opts.resumeSessionId);
         // Hard-disallow Workflow: driving CC unattended (esp. bypassPermissions),
@@ -82,6 +84,12 @@ export const codexAdapter = {
         else {
             args.push("--sandbox", opts.permissionMode === "acceptEdits" ? "workspace-write" : "read-only");
         }
+        if (opts.model)
+            args.push("--model", opts.model);
+        if (opts.codexImageInputSupported) {
+            for (const imagePath of opts.imagePaths ?? [])
+                args.push("-i", imagePath);
+        }
         // `resume <thread_id>` continues a prior codex session; the trailing `-`
         // tells codex exec to read the prompt from stdin (we feed it there).
         if (opts.resumeSessionId)
@@ -108,7 +116,9 @@ export const codexAdapter = {
             }
             if (d.type === "thread.started" && typeof d.thread_id === "string")
                 sessionId = d.thread_id;
-            else if (d.type === "item.completed" && d.item?.type === "agent_message" && typeof d.item.text === "string") {
+            else if (d.type === "item.completed" &&
+                d.item?.type === "agent_message" &&
+                typeof d.item.text === "string") {
                 finalText = d.item.text; // keep the LAST agent_message
             }
             else if (d.type === "turn.failed") {

package/dist/cc-orchestrator/codex-session-history.d.ts

@@ -1,4 +1,4 @@
-import type { HistoryMessage } from "./session-history.js";
+import type { HistoryMessage, SessionTailEvent } from "./session-history.js";
 /**
  * Read the last `limit` user/assistant messages from a codex CLI session,
  * returning the SAME shape as the claude-side `readRecentHistory` so the room
@@ -23,3 +23,16 @@ export declare function readCodexRecentHistory(cwd: string, threadId: string, li
     hasMore: boolean;
     totalCount: number;
 };
+/** Parse a bounded/raw Codex rollout snapshot. Shared with the desktop tail
+ * follower so its initial history and EOF cursor are atomic. */
+export declare function parseCodexRecentHistory(raw: string, limit: number): {
+    messages: HistoryMessage[];
+    hasMore: boolean;
+    totalCount: number;
+};
+/** Parse one newly-appended Codex rollout JSONL line. `response_item` is the
+ * authoritative rendered stream; parallel `event_msg.agent_message` records
+ * are deliberately ignored to avoid duplicate assistant bubbles. */
+export declare function parseCodexTranscriptLine(line: string): SessionTailEvent[];
+/** Find the rollout file whose `session_meta` matches both `threadId` and `cwd`. */
+export declare function findCodexRolloutFile(codexHome: string, cwd: string, threadId: string): string | undefined;