feat(code): make /offload server-owned

[Mason Daugherty (mdrxy)]

/offload now runs only as a server-owned operation on built-in dcode servers. Local and ACP agents no longer support it, and custom or older servers without the route are unsupported.

---

The graph-operation prototype coupled the TUI to LangGraph run routing and lifecycle behavior. This revision puts the ownership boundary in dcode's server backend: the built-in LangGraph deployment registers a custom HTTP app that resolves the same cached runtime, compaction policy, hooks, model configuration, and CompositeBackend as the interactive agent.

flowchart LR
    user["User runs /offload"] --> tui["TUI"]

    subgraph client["Client"]
        tui --> remote["RemoteAgent"]
        hookexec["Configured hook executor"]
        remote <--> hookexec
    end

    subgraph server["Built-in dcode LangGraph server"]
        api["Offload HTTP boundary"]
        runtime["Shared server runtime"]
        operation["OffloadOperation"]
        hooks["PreCompact + PreToolUse"]
        compact["Agent compaction service"]
        state[("Thread checkpoint")]
        backend["Agent CompositeBackend"]
        cost["Cost recorder"]

        api -->|"resolve"| runtime
        runtime --> operation
        operation --> hooks --> compact
        api -->|"read + validate"| state
        compact -->|"plan archive"| backend
        cost -->|"priced delta"| api
        api -->|"summary event + cost"| state
        api -->|"then append archive"| backend
    end

    remote -->|"thread ID + runtime context"| api
    api -->|"typed result or hook request"| remote
    compact -->|"summarize"| model["Configured model provider"]

    style api fill:#dcfce7,stroke:#16a34a
    style operation fill:#dcfce7,stroke:#16a34a
    style state fill:#dcfce7,stroke:#16a34a

Loading

The server operation:

• reads and hydrates checkpoint state itself; the request contains no graph name, checkpoint, or conversation messages;
• refuses a thread that holds work in flight — active, interrupted, carrying pending graph tasks, or advanced past the checkpoint it read. A thread whose last run failed is still offloadable: LangGraph leaves that thread on error until the next run completes, which is exactly when a user reaches for /offload to recover from an overflow;
• commits only the channels OffloadStateUpdate declares. The runtime guard is an allowlist derived from that type, so a future merge adding any other channel is refused, not just messages. No synthetic assistant or tool message is persisted, and the operation cannot replace conversation history;
• resolves the summarizer's model and transport from the checkpoint, not from the request. A client cannot point the server's credentialed provider calls at an endpoint of its choosing;
• runs the agent's PreCompact and PreToolUse hooks, transporting interrupt/resume payloads opaquely through the client and returning denials as typed results. The session's approval mode is carried across, so a configured hook sees the same mode it sees on an interactive turn;
• reserves the summary in the checkpoint before appending the archive, and rolls the append back if the link cannot be committed. A per-session lock serializes an archive's read/write cycle against concurrent compactions;
• records priceable model cost in the same checkpoint update. Every prepared charge is explicitly committed or rolled back, and an abandoned one warns rather than vanishing;
• uses the agent's existing compaction backend/policy and archive guard, so server-side archives remain readable by the agent;
• accepts an explicit cancellation for an in-flight operation and confirms the outcome, so a client that gives up learns whether the operation finished or was cancelled.

The client calls the server route directly. There is no capability probe and no seeded tool-call fallback. A local in-process or ACP agent gets a short unsupported message. A server that does not register the route gets a message naming that cause instead of a bare transport error.

Careful review is warranted around the custom-route/thread-state boundary, the archive reserve-then-append ordering, and hook replay identity. The real integration test launches the production server configuration, checks message preservation around /offload, verifies route authentication, and reads the archive back through the running agent.

User-visible output

Success is unchanged in shape:

Offloaded 6 older messages, freeing up context window space.
Conversation: ~1.0K → ~250 tokens (75% decrease), 4 messages kept.

Three failure paths now say something actionable:

Situation	Before	Now
Last turn failed (thread on error)	Offload failed: Cannot offload while the thread has an active or interrupted run. — and no way out until a turn succeeds	Offloads normally
Server does not register the route	Offload failed: 404 Not Found	Offload failed: This server does not provide dcode's /offload operation. Use the built-in dcode server, or upgrade the server to a version that registers it.
Reporting fails after the server committed	Offload failed: <exception> — prompting a second offload of an already compacted conversation	The conversation was offloaded, but the result could not be displayed. Check logs for details.

A dropped endpoint override is now logged with the key names, so a user whose gateway configuration is being ignored has something to find.

Test plan

• Full make test: 14,199 passed, 2 skipped.
• Real-server integration: 3 passed.
• make format and make lint: passed, including Ruff, ty, and command-catalog validation.
• Three added tests were mutation-verified: re-keying the per-thread lock on operation_id, renaming the route's path converter, and deleting the hook round-limit break each fail the new test and passed before it.

Made by Open SWE

[open-swe]

Open SWE Review found 2 potential issues.

Open in Web • View Open SWE trace

[open-swe]

Open SWE Review found 3 potential issues.

Open in Web • View Open SWE trace

[open-swe]

Open SWE Review found 1 potential issue.

Open in Web • View Open SWE trace