Agent created via ctx.agents.create({ setup }) fails every model call with TRANSPORT; the real cause is a PlatformAuthError that TRANSPORT masks

[zshqzcn]

Summary

An agent created programmatically through
ctx.agents.create({ sessionId, agentOptions, setup }) publishes successfully, dispatches its
turn, assembles a complete and apparently correct request, and then every model attempt fails
with:

DeepSeek Messages transport failed (TRANSPORT)

All 5 retries fail identically. assistant/message and usage are never emitted; the turn ends
with turn/end reason = { kind: 'error', error: { code: 'TRANSPORT' } }.

An agent created by the built-in subagent tool in the same process, on the same provider and
model, works normally. So does the operator's own agent, at the same moment.

I believe I have traced the mechanism, and it has two parts: a diagnosability problem
(a non-LlmError is silently rewritten as TRANSPORT) and a behavioural problem (the
credential record is not resolved the same way for a dynamically created agent).

Environment

• DSH: 0.2.0-rc.2
• @deepseek-ai/dsh-agent-loop: 0.2.0-rc.2
• @deepseek-ai/dsh-llm-deepseek: 0.2.0-rc.2
• @deepseek-ai/dsh-deepseek-account-platform: 0.2.0-rc.2
• Node: v24.21.0
• OS: Windows 10 (10.0.19045)
• Provider route: deepseek-account / deepseek-flash

The mechanism

PlatformAuthError is declared as:

// dsh-deepseek-account-platform/lib/index.js:13
var PlatformAuthError = class extends Error {

It extends Error, not LlmError. The account provider's resolveAuth therefore lets it
propagate untouched, and dsh-llm-deepseek's request wrapper rewrites it:

// dsh-llm-deepseek/lib/index.js:2149-2132
async *request(options, connection, signal, activity) {
  signal.throwIfAborted();
  const { messages, versions } = await prepareImages(...);
  const auth = await this.dependencies.resolveAuth(connection);   // PlatformAuthError escapes here
  try {
    ...
    const response = await fetch(`${messagesApiRoot(connection.baseURL)}/messages`, { ... });
  } catch (error) {
    if (timeoutOf(watchdog.signal, "MESSAGES_IDLE") !== void 0) throw new LlmError("...idle timeout", "TIMEOUT", ...);
    if (options.signal?.aborted) throw new LlmError("...request aborted", "ABORTED", ...);
    if (error instanceof LlmError) throw error;
    throw new LlmError("DeepSeek Messages transport failed", "TRANSPORT", { cause: error });
  }
}

So a PlatformAuthError("storage") becomes a bare TRANSPORT whose cause is never logged.

resolveToken has exactly three outcomes, and only one of them produces TRANSPORT:

// dsh-deepseek-account-platform/lib/index.js:786
async resolveToken(url) {
  if (this.closed || this.removing !== void 0) return void 0;
  const destination = new URL(url);
  if (destination.origin !== this.inferenceOrigin || destination.username || destination.password) return void 0;
  const record = await this.ctx.credentials.readRecord(KEY);
  if (record === void 0) return void 0;
  if (record.kind !== "grant") throw new PlatformAuthError("storage");   // (A) throws
  const result = grant.safeParse(record.payload);
  if (!result.success) throw new PlatformAuthError("storage");           // (B) throws
  ...
  return result.data.token;                                              // (C) success
}

• returning undefined → ACCOUNT_SIGN_IN_REQUIRED (a clear, actionable error)
• returning a token → success
• throwing → silently becomes TRANSPORT

We observe TRANSPORT, not ACCOUNT_SIGN_IN_REQUIRED, so the credential record is being read
or parsed as the wrong kind for this agent: (A) record.kind !== "grant", or (B)
grant.safeParse(record.payload) fails.

That also explains the timing: step/start → first failure is ~105 ms, far too fast for a
network round trip. Nothing is ever sent.

Why this looks agent-scoped rather than global

The same credentials work for other agents at the same moment:

Agent	How created	Model call	Evidence
Operator's own agent	at startup	✅ works	it performs tool calls and replies in the same process
subagent tool child	via the subagent service	✅ works	replied PONG on the same route
Plugin-made agent (setup only)	ctx.agents.create	❌ TRANSPORT	this report
Plugin-made agent (restrict + guard)	ctx.agents.create	❌ TRANSPORT	same failure

A global credential-store failure would break all four rows. It breaks only the last two.

Reproduction

A host plugin that creates an agent in the agent scope. No tools are registered and no tool
restriction is applied — deliberately minimal.

export const name = 'repro'
export const inject = ['agents']

export function apply(ctx) {
  ctx.effect(() => {
    void (async () => {
      const handle = await ctx.agents.create({
        sessionId: 'repro-session-1',
        agentOptions: { provider: 'deepseek-account', model: 'deepseek-flash' },
        setup: (agentCtx) => {
          agentCtx.on('session/event', () => {})   // nothing here touches tools or credentials
        },
      })
      handle.agent.followup({
        content: [{ type: 'text', text: 'Reply with exactly: PING' }],
        source: { kind: 'user' },
      })
      await handle.agent.whenIdle()
    })()
    return () => {}
  })
}

Result: the session log contains turn/start, step/start, system/message, user/message,
request/header, request/context, then 6 × assistant/attempt with a TRANSPORT finish,
5 × llm/retry, and turn/end reason=error. No assistant/message.

A one-step experiment that would settle it

On one machine, at one moment:

1. Have the operator's agent answer a normal question (proves the credential is good right then).
2. Immediately afterwards, run the reproduction above.

If (1) succeeds and (2) fails, then the same credential resolves for one agent and not for the
other inside a single process, and the problem is unambiguously in agent-scoped credential
resolution.

Raw log evidence

{"type":"request/header","data":{"header":{"config":{"provider":"deepseek-account","model":"deepseek-flash","maxTokens":256000,"reasoningEffort":"high"},"adapterDefaults":{"maxTokens":true},"tools":[{"name":"load_workspace_dependencies","...":"..."}]},"reason":"initial"}}
{"type":"request/context","data":{"provider":"deepseek-account","model":"deepseek-flash","contextWindow":1000000,"systemPromptUpdate":"in-history"}}
{"type":"assistant/attempt","data":{"turn":1,"step":1,"stream":[{"type":"chunk","time":1792164009576,"chunk":{"type":"finish","reason":{"kind":"error","failure":{"message":"DeepSeek Messages transport failed","code":"TRANSPORT"}}}}]}}
{"type":"turn/end","data":{"turn":1,"reason":{"kind":"error","error":{"message":"DeepSeek Messages transport failed","code":"TRANSPORT"}}}}

policyKey ["normal",5,["EMPTY_RESPONSE","RATE_LIMIT","SERVER","TIMEOUT","TRANSPORT"],500,10000,0.1]
retry 1..5 -> identical TRANSPORT, delayMs 476 / 1089 / 2004 / 4161 / 7672
step/start 1792164009471 -> first failure 1792164009576   (~105 ms)

What I already ruled out (each with a run experiment)

Hypothesis	Experiment	Result
Provider/credentials broken	Ran the subagent tool on the same route	✅ succeeded → ruled out
ctx.agents-created agents broken in general	Same subagent run	✅ succeeded → ruled out
Missing provider/model route	Supplied them; the earlier {{model}} prompt-variable error disappeared	partially fixed, TRANSPORT remains
Extra reasoningEffort/maxTokens in agentOptions	Passed only provider+model	❌ unchanged. Note maxTokens: 256000 comes from adapterDefaults, not agentOptions, so this experiment could not have altered anything — reported for completeness
cwd value	Explicit cwd written into the session header	❌ unchanged (session id changed, outcome did not)
Tool restriction side effect	preset: full (no restriction at all)	❌ unchanged → ruled out
Stale session id collision	Fresh deterministic id	Symptom disappeared, root cause unchanged

Requests

1. Please confirm the mechanism: is a PlatformAuthError from resolveToken the expected
   source of a TRANSPORT for a dynamically created agent? If so, why would
   credentials.readRecord(KEY) return a non-grant record — or a payload that fails
   grant.safeParse — for that agent but not for the operator's own agent in the same process?
2. Please surface TRANSPORT's cause in the session log. It is currently discarded, so
   error.code is the only clue available and this entire class of failure is undiagnosable from
   outside. Logging the cause's name and message would be enough.
3. Is there anything an agent created through ctx.agents.create({ setup }) lacks that a
   subagent child has — an attachment resolver, a launch-environment snapshot, or a credential
   scope acquired at creation rather than at request time?

Notes

• Reproducible in both directions across two machines with an identical plugin, so it does not
  look host-specific.
• Happy to provide the full plugin source, complete session logs, and detail on any ruled-out
  experiment.
  ``

---

Update: still present in 0.2.1-rc.2

Re-checked after upgrading to �.2.1-rc.2. All three parts of the mechanism are unchanged:

• PlatformAuthError still declares class extends Error (not LlmError)
  — dsh-deepseek-account-platform/lib/index.js:16.

esolveAuth is still awaited outside the ry that guards the request
— dsh-llm-deepseek/lib/index.js:2175, with the ry opening at 2176.

• The stream's catch still rewrites any non-LlmError as

ew LlmError("DeepSeek Messages transport failed", "TRANSPORT", { cause: error })
— dsh-llm-deepseek/lib/index.js:2158-2159.

One related observation that may be the simplest fix: this build already ships an
errorChain() helper in @deepseek-ai/dsh-llm whose documented purpose is exactly to
"surface the underlying failure instead of masking it". It is used at the request-extension
seam (dsh-llm-deepseek/lib/index.js:1369) but not at the Messages transport seam above,
so an auth failure reached through
esolveAuth still arrives as a bare TRANSPORT.

``

[argszero]

Both source claims check out on 687f282e86, and the mechanism is slightly worse than the version in the report. Four things, in order of how much they change the diagnosis.

1. Two calls sit outside the guarded block, not one. In packages/llm/llm-deepseek/src/adapter.ts:

:91   private async * request(...)
:95     const { messages, versions } = await prepareImages(...)      // unguarded
:98     const auth = await this.dependencies.resolveAuth(connection) // unguarded
:99     try {

So a throw from either prepareImages or resolveAuth escapes request() entirely. If your instrumentation put a cause on the error you saw, that narrows it to resolveAuth; if it did not, prepareImages is still in play, and it is the one call in this file that can fail for an agent-scoped reason without any credential being involved — attachment resolution is a per-agent surface (this.dependencies.resolveAttachments?.()), and it is optional, so its absence is silent rather than an error of its own.

2. TRANSPORT is produced one level up, in generate(), not in request(). adapter.ts:76 catches, :77 and :78 re-label the idle-timeout and user-abort cases, :79 passes an LlmError through unchanged, :80 rewrites everything else. Since PlatformAuthError extends Error and not LlmError (packages/credentials/deepseek-account-platform/src/protocol.ts:6), a credential failure reaching this point is indistinguishable from a socket reset. That is the whole of the "masking" you describe, and it is one line.

3. errorChain() exists and is unused here — but it cannot carry what you asked for. packages/llm/llm/src/error.ts:117 renders the outermost message first and appends each cause, and its docstring says exactly this: surface the underlying failure instead of masking it. It is used at the request-extension seam (llm-deepseek/src/request-extensions.ts:32) and not at :80. One correction to request 2 though: the code cannot be improved by it. LlmError.failure (llm/src/index.ts:96, assigned at :122) is a frozen serialized projection of {message, code, status, providerRetryAfterMs, requestId, offloadImages} — deliberately closed, and the session log writes that projection, not the live error. The cause survives on the instance as error.cause but never reaches the log. So the fix you want is in the message, not the code: new LlmError(\DeepSeek Messages transport failed: ${errorChain(error)}`, 'TRANSPORT', { cause: error })` keeps the taxonomy stable and makes the log readable. That is a real trade-off someone will argue about (messages are UI text), and it is worth saying in the report which side you are asking for.

4. 'storage' cannot identify its own throw site. PlatformAuthError carries code: SignInErrorCode and renders account: ${code} (protocol.ts:6-9), and the account package throws PlatformAuthError('storage') from ten places with that identical string — index.ts:170, :172, :180, :376, :378, :390, :392, :468, :470, :581. Two are excluded by your own evidence: [Service.init] (:167-174) runs once at load, so had it thrown, the account service would be FAILED and your operator's agent would not be working. getState() (:376-378) serves UI state, not a model call. That leaves the two inside resolveToken (:390 record is not a grant, :392 payload fails grant.safeParse) — and nothing available outside the process can tell those apart, which is why your request 1 has no answer from the log alone. A detail argument on that error ('kind-mismatch' vs 'payload-invalid') would cost one line and settle it permanently.

On request 3, the honest answer is that I did not find the agent-scoped difference in the credential path — readRecord(KEY) is read through this.ctx.credentials on the account service, which is not an agent-scoped service, so a per-agent record is hard to explain from this side alone. That is a reason to check the other unguarded call first, not a reason to rule yours out.

One thing that is worth having either way: the cause is reachable on the live error instance, so a plugin can surface it without waiting for core — wrap the response side of llm/stream, and on a thrown LlmError read error.cause, then rethrow the same code with the chain appended to the message. It would not fix the behaviour, only make the next occurrence say what happened; given how much of this report is deducible only from timing (105 ms) and elimination, that seems worth more than it sounds.

[zshqzcn]

Thanks — this is a better reading of the code than the one in my report, and it made me re-verify everything against the released 0.2.1-rc.2 build rather than the tree at 687f282e8. Line numbers below are from the packaged lib/*.js, so they drift from your src/*.ts references, but the structure is the same.

Confirmed on the released build

• PlatformAuthError is still class extends Error (account: ${code}), so it is not an LlmError.
• In dsh-llm-deepseek: prepareImages and resolveAuth are both before the try (lib/index.js:2174, :2175, try at :2176); generate() re-labels idle-timeout and abort, passes LlmError through, and rewrites everything else to TRANSPORT (:2156–:2159).
• errorChain() exists (dsh-llm:199) and is used only at the request-extension seam (dsh-llm-deepseek:1369), not at the TRANSPORT site.
• LlmError.failure is the frozen {message, code, status?, providerRetryAfterMs?, requestId?, offloadImages?} projection, and dsh-agent-loop writes error.failure into turn/end (:1024), so cause never reaches the session log. Your point 3 is right on released code, not just in theory.
• One version delta on point 4: the released account package has 11 PlatformAuthError("storage") sites, not 10 — the device flow adds two (:1057, :1094). Applying your exclusions still leaves resolveToken's two (:813 record is not a grant, :815 grant.safeParse fails), so the conclusion is unchanged.

One correction to point 1, which turns out to matter

The reproduction in my report sends content: [{ type: 'text', text: 'Reply with exactly: PING' }], and the logged request/header / request/context contain no image blocks. prepareImages returns at :1425 (if (!messages.some((m) => contentHasImage(m.content))) return …) before it touches attachments. Its failure modes are either LlmError("UNSUPPORTED_CONTENT") — which generate() passes through unchanged, so it would not read as TRANSPORT — or an attachment-read error, which needs an image in the history to reach.

So for this reproduction prepareImages cannot be the thrower, and resolveAuth is the only unguarded call left. That answers your open question as far as it can be answered: I did not capture cause in-process (only the failure projection was logged), but the request shape plus the two unguarded calls leave resolveAuth → resolveToken → one of the two storage throws. It also fits the 105 ms timing and the absence of ACCOUNT_SIGN_IN_REQUIRED (returning undefined would have produced that code, not TRANSPORT).

On the fixes

• Putting errorChain(error) into the TRANSPORT message: agreed, and I would take the trade-off you flag. Message text is UI text, but "transport failed: PlatformAuthError: account: storage" is strictly better than six identical TRANSPORT retries with no cause anywhere in the log.
• Stronger, if you are willing to change behaviour rather than only the message: map PlatformAuthError to an LlmError inside resolveAuth (the account analogue of the existing INVALID_CREDENTIAL for API keys, or a new ACCOUNT_CREDENTIAL_*). Then the adapter never sees a non-LlmError, the retry policy stops spending five retries on a credential-store problem that cannot heal, and the turn fails with an actionable code.
• Splitting storage into kind-mismatch / payload-invalid at the two resolveToken sites: also agreed, one line each, and it would settle "which throw" permanently without needing cause capture.

If it helps, I can run your llm/stream wrapper suggestion and post a before/after of error.cause on the current build — or test a patch if you have one in mind.

[zshqzcn]

Follow-up after instrumenting the boot path instead of only reading it. I built a temporary host plugin that reproduces the original conditions as closely as 0.2.1-rc.2 allows, ran it, then removed it and restored the profile byte-for-byte.

What the probe did: inject only agents (same as the repro plugin), poll for the agent factory, create the agent the moment it appears, wrap credentials.readRecord and deepseekAccount.resolveToken from the instant those services become reachable, run two turns (immediately and +12 s), and write a JSON report.

Results on the released 0.2.1-rc.2 build:

• At plugin apply, neither the agent factory nor the credential/account services exist yet; first availability is ~0.74 s after apply.
• The agent was created ~1.03 s after apply. At creation the credential provider was already present and its in-memory record map was loaded (recordsDefined: true).
• Both turns completed normally (phase idle, no TRANSPORT), and neither readRecord nor resolveToken was observed failing.
• The stored credential is a valid grant (version 1, issuer platform.deepseek.com), resolveToken returns a token, and the credentials document has not been rewritten since 2026-09-27 — so a flat-layout migration during boot cannot be the trigger.

So the original failure does not reproduce on 0.2.1-rc.2 even when the agent is created at the earliest possible moment. That is a correction to my earlier reply, and probably to my own report's claim that the bug was still present on this build.

One second candidate mechanism is now demonstrated rather than inferred: LocalCredentialProvider.readRecord is Promise.resolve(this.records.get(key)), and this.records is only assigned inside loadInitial() during [Service.init]. Reading before that assignment throws a plain TypeError: Cannot read properties of undefined (reading 'get') — not an LlmError — which generate() rewrites as TRANSPORT. I reproduced exactly that error by reading from a deliberately uninitialized provider instance. I could not make the real boot path hit it (service readiness appears to gate consumers), but it is a second concrete way this masking can fire, with no credential-content problem involved.

On your open questions:

• Did the error carry a cause? No. The only surviving evidence was turn/end's error.failure projection, not the live instance, so my original report could not distinguish resolveAuth from prepareImages. The text-only request still rules out prepareImages for that repro; beyond that, the throw site is unproven.
• I would now treat PlatformAuthError("storage") as one candidate, not the conclusion.

Fix-wise this makes the diagnostics changes more valuable than picking a behaviour side: (1) append errorChain(error) to the TRANSPORT message; (2) convert non-LlmError throws in resolveAuth — and readRecord in particular — into an LlmError with a stable code and an actionable "credential store not ready / unreadable" message, so the failure is not retried five times as if it were transport; (3) splitting the two storage throw sites remains useful for the other branch.

If it helps, I can attach the probe source and the full report, or run the same probe against 0.2.0-rc.2 if a build is available, to find where the behaviour diverges.