Skip to content

[FEATURE]: support delivery: "queue" for session.shell #52274

Open

Description

@remorses

Feature hasn't been suggested before.

  • I have verified this feature I'm about to request hasn't been suggested before.

Describe the enhancement you want to request

In v2, session.prompt, session.command and session.compact accept delivery: "steer" | "queue", but session.shell does not. A user shell command always runs immediately, in parallel with the active execution.

await client.session.prompt({ sessionID, text: 'fix the test', delivery: 'queue' }) // waits for the current turn
await client.session.shell({ sessionID, command: 'git commit -am wip' })             // runs now, no delivery option

Why it matters

I build a Discord client on top of the v2 server (kimaki). Users can type !cmd to run a shell command in the session, and !cmd. queue to run it after the current turn. Common case:

  • agent is still editing files
  • user queues !git commit -am wip or !pnpm test
  • running it now commits or tests half-done work

Today the client has to keep its own queue and call session.shell on session.execution.succeeded. That queue can't be ordered against the native inbox: with prompt A (queue), !test (queue), prompt B (queue), opencode starts B right after A, before the client runs !test.

Proposal

Add an optional delivery to session.shell, same semantics as prompts:

POST /api/session/:sessionID/shell
{ id?: string, command: string, delivery?: "steer" | "queue" }
  • steer (default): current behavior, run now
  • queue: admit a durable inbox item, run it at the next queue boundary in order with other queued items, then continue with the next item
  • the shell result still becomes the resume: false synthetic message, so it lands in context without waking the agent
  • session.inbox.enqueued / delivered / cancelled events cover it, so clients can show and cancel queued shells like queued prompts

Session.shell already routes the result through synthetic(...) (packages/core/src/session/session.ts), so this is mostly about admitting it through the inbox instead of running it immediately.

Activity

  1. opencodejr commented on Oct 28, 2026

    @opencodejr
    Contributor

    Thanks for the detailed request and the use case!

    To restate it: you'd like session.shell to accept delivery: "steer" | "queue" like session.prompt, session.command and session.compact do. With queue, the shell command would go through the session inbox: it would run at the next queue boundary, in order with other queued items, and could be shown and cancelled through the session.inbox.* events.

    I checked the current code. Session.shell runs the command right away and records the result as a synthetic message, and the inbox has no shell item type. So this would be new behaviour rather than a bug fix. A plugin can't do it either: like your current client-side queue, it could only start the shell after the turn ends, so it couldn't keep the shell in order with natively queued prompts.

    The maintainers will consider it. Related issues:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions