Skip to content

feat(core): background slow Code Mode scripts behind full_codemode - #64343

Merged
jlongster merged 5 commits into
devfrom
codemode-background
Nov 17, 2026
Merged

jlongster merged 5 commits into
devfrom
codemode-background

Conversation

@jlongster

@jlongster jlongster commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

With full_codemode on, a Code Mode execute script that hasn't finished after 10 seconds becomes a background job and keeps running. A fast script returns its result as today. A slow one returns Script cm_… is still running; its result will arrive in this session., and the same VM continues from where it was. When it finishes, its result reaches the session the same way background shells and subagents report back: a synthetic inbox message that wakes the session.

  • packages/core/src/codemode/job.ts (new): runs execute under Job.Service, waits up to 10s, then hands off and delivers the bounded result later.
  • packages/core/src/tool.ts, session/execution.ts: route execute through it when a session provides it.
  • packages/core/src/session/synthetic.ts (new, moved out of session.ts): shared synthetic-message admission used by the job.
  • job.ts, job/list.ts, job/recovery.ts, schema/src/job.ts, protocol/client: new codemode job kind. On restart, a finished result is still delivered; a still-running script is reported as interrupted and never rerun.
  • job.ts (BlockingParent): Ctrl+B releases the outer script; shells it awaits keep their own waits.
  • A backgrounded script’s permission prompts stay pending and can be answered like a subagent’s. The script’s awaited tool call waits for the reply. The app shows the ordinary permission dock; the TUI gives it precedence over an open composer and shows it in the owning child session as well.
  • cli/src/run/noninteractive.ts, plugin/goal.ts, plugin session types: know about the new kind.

Esc before the handoff cancels the script; after it, the script keeps running. Deleting the session cancels it.

🚩 Flag: full_codemode (opt-in only). With it off, execute is unchanged.

Not in this PR (tracked for later): pausing and resuming scripts across restarts, model-facing status/wait/cancel APIs, and dedicated client display for running scripts.

📊 Proof

  • New tests in subagent-idle-e2e.test.ts (TestClock): a fast script returns normally; with the flag off a slow script stays in the foreground; a slow script hands off and its final value appears in the woken session's next model request.
  • Permission follow-up: 271 core tests and 2 TUI permission tests passed. Core and TUI passed typecheck:tsc.
  • 356 core tests pass across the job, shell, Code Mode and session suites; typecheck:tsc passes in core, schema, protocol, client, plugin and cli; check:generated passes in client and protocol.

Added by the opencode bot (AI-generated).

Related: #54221

Public API: adds the codemode job kind (Job.Kind, Job.Info / OpenAPI, plugin SessionIdleBackground); additive, backwards compatible

@jlongster
jlongster marked this pull request as ready for review November 17, 2026 02:18

@opencodejr opencodejr Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I reviewed the code and ran the core tests: the new end-to-end tests in subagent-idle-e2e.test.ts and the job, permission and Code Mode suites all pass, and typecheck:tsc passes in core. I couldn't see it working end to end in the TUI. My drive script never got the simulated execute call to reach the held tool, so the handoff isn't checked by hand. The wait-then-handoff logic, the restart path (a finished result is still delivered, a running script is reported as interrupted) and rejecting a pending approval at handoff all look sound to me.

Public API (additive):

  • Job.Kind (schema, OpenAPI, client): shell | subagent | image → shell | subagent | image | codemode.
  • New Job.CodeMode variant in Job.Info, so GET /api/experimental/job can return kind: "codemode" items.
  • The plugin's SessionIdleBackground (effect and promise versions) gains { kind: "codemode", sessionID, jobID }.

Existing callers keep working, but clients or plugins that handle every job kind explicitly need a new case. In practice these items only appear with full_codemode on.

Non-blocking: after the handoff, Esc no longer stops the script, and neither the user nor the model can cancel it. Only deleting the session or restarting the server stops it. That's acceptable behind an opt-in flag and listed as later work, but a script stuck in a loop will keep running until then.

Related: #54221

@opencodejr opencodejr Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new commit looks sound. The checks pass: 192 core tests (the end-to-end, job, permission and Code Mode suites), 21 nearby TUI tests, and typecheck:tsc in core and TUI. I couldn't drive the new permission flow end to end.

There were no open threads from my earlier review. Changes in this commit:

  • A backgrounded script's approval prompt now stays pending and can be answered, like a subagent's, instead of being rejected at handoff.
  • Shell calls nested inside a script no longer add or remove the session's tracked wait.
  • When a session runner doesn't provide the tool services, scripts aren't backgrounded.

I found nothing new that blocks.

Public API: this commit doesn't change it. The codemode job kind added earlier is still the only API change and is backwards compatible.

The TUI change is visible to users: a pending approval now takes precedence over an open composer, and approvals show inside child sessions too. I couldn't capture it, so could you add before/after screenshots or a short video of the permission dock in a child session and over an open composer?

@opencodejr opencodejr Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new commit looks right. Rejecting a prompt still rejects the other pending prompts in that session from the same step, and now leaves prompts from other steps (such as one from a script still running in the background) pending. Requests with no source attached still count as one step, so nothing changes for them. The new permission test and the end-to-end Code Mode tests pass, and typecheck:tsc passes in core. I didn't run this by hand in the TUI.

This commit doesn't change the public API. My earlier request for before/after screenshots of the TUI permission dock still stands. Nothing new blocks.

Comment thread packages/core/src/tool.ts
if (name === "execute" && codeModeTool) {
const run = (ctx: Tool.Context) => executeTool(codeModeTool, name, event.input, ctx)
const background = yield* CodeModeJob.Current
return yield* background ? background(context, run) : run(context)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

opencode bot explain these changes

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The change in tool.ts decides who runs Code Mode's execute call. Before, it was always called inline. Now it's wrapped in a function, run(ctx), and passed to an optional hook if one exists.

What the lines do (tool.ts 329–333)

  • run is the same executeTool(codeModeTool, ...) call as before. The only difference is that it takes the Tool.Context as an argument, so the hook can pass in a modified one.
  • CodeModeJob.Current (codemode/job.ts) is a Context.Reference that defaults to undefined. With no hook, the code calls run(context) and behaves exactly as before.
  • Only the session drain sets the hook: session/execution.ts:93 builds it with CodeModeJob.make(jobs, SessionSynthetic.make(...), scope), and :124 installs it with Effect.provideServiceEffect. Any other caller of Tool.execute, such as a custom runner or a test, gets the old inline path. make also returns undefined when Flag.Service or ToolOutput.Service is missing, so a runner without those services also falls back to inline.

What the hook does (CodeModeJob.make)

  1. If full_codemode is off, it just calls execute(context), so the behaviour doesn't change.
  2. Otherwise it starts a codemode job (cm_…) under Job.Service. The job runs execute with Job.BlockingParent set to the job id, which is how Ctrl+B releases the outer script. It also wraps progress so that progress updates stop reaching the tool row once the script has been handed off.
  3. It waits on jobs.block for up to 10 seconds:
    • Finishes in time: it returns the real result from the result Deferred, the same as before.
    • Interrupted while waiting (Esc): onInterrupt cancels the job.
    • Times out or is backgrounded: it calls jobs.background(id) and returns a placeholder result, Script cm_… is still running; …, with metadata.jobID.
  4. After a handoff, a fiber forked into the session scope waits for the job to finish. It truncates the output and saves any base64 file parts to disk as paths. It then posts a <codemode id state> synthetic message through synthetic, which wakes the session, and calls completeBackground. If the session was deleted, the job ends up cancelled and nothing is sent.
  5. On a server restart, restart.ts:121 uses CodeModeJob.notice. A script that was still running is reported as cancelled ("Interrupted by server restart.") and is never rerun.

Why it's done through a callback
Putting the hook in context keeps tool.ts independent of sessions, the inbox and synthetic messages. That logic lives in codemode/job.ts, which tool.ts only uses as a context reference and never calls directly.

I only read the code for this. I didn't run the tests.

@opencodejr opencodejr Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These commits only list the job kinds explicitly in the Ctrl+C path of opencode run and in the goal plugin. With the current kinds they behave exactly as before: on Ctrl+C the run exits without waiting when only image or Code Mode jobs are left, a normal run still waits for background scripts, and the goal plugin still stays put for the session's own subagent, image or Code Mode jobs. typecheck:tsc passes in cli and core. They don't change the public API. My earlier request for before/after screenshots of the TUI permission dock still stands. Nothing new blocks.

User decisions:
- Background a Code Mode script as a job after about 10 seconds
- Not durable across restarts yet
- Deliver its result the same way background subagents and shells do
- No status, wait or cancel APIs yet
- Leave permission prompts and client display for later
User decisions:
- Let a backgrounded Code Mode script ask for permission like a subagent does
- Drop the foreground-only permission cutoff
- Show the permission prompt on screen and pause the script until answered
User decisions:
- Rejecting a prompt only cancels other prompts from the same step, like subagents
User decisions:
- Keep run's original background-job wait logic instead of an allowlist
User decisions:
- On Ctrl+C, don't wait for background Code Mode scripts, like image jobs
- A normal run still waits for them

@opencodejr opencodejr Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This push only rebases the PR onto a newer dev: git range-diff shows all five commits as identical patches. On the new base, which includes #64335, the end-to-end, job, permission and Code Mode suites in core still pass, and typecheck:tsc passes in core, cli and tui. The push doesn't change the public API. My earlier request for before/after screenshots of the TUI permission dock still stands. Nothing new blocks.

@jlongster
jlongster merged commit 30654da into dev Nov 17, 2026
11 checks passed
@jlongster
jlongster deleted the codemode-background branch November 17, 2026 16:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant