fix(headless): missing-key diagnostic recommends an ignored credential store

[coygeek]

Summary

The shipped headless profile correctly ignores saved credentials, but its MISSING_CREDENTIAL diagnostic tells users to store DEEPSEEK_API_KEY through the credentials service or Web Models page. That suggestion cannot fix this profile without restoring the disabled authentication services. A key can already be saved and the diagnostic still recommends saving it. This report concerns the recovery advice, not the intentional credential precedence.

Steps to reproduce

With the released CLI on PATH, run the following from a disposable workspace. All key values below are fake; no external model call is required.

dsh_bin=$(command -v dsh)
probe_root=$(mktemp -d)
mkdir -p "$probe_root/dsh" "$probe_root/work" "$probe_root/agents" "$probe_root/user"
cat > "$probe_root/dsh/.credentials.yaml" <<'YAML'
version: 1
refs:
  DEEPSEEK_API_KEY: fake-stored-key
YAML
chmod 600 "$probe_root/dsh/.credentials.yaml"
cat > "$probe_root/dsh/cordis.patch.yml" <<'YAML'
- id: session-log-deepseek
  config:
    enabled: false
YAML
cd "$probe_root/work"
env -i PATH="$PATH" HOME="$probe_root/user" \
  DSH_HOME="$probe_root/dsh" DSH_AGENTS_HOME="$probe_root/agents" \
  DSH_TELEMETRY_MODE=DISABLED DEEPSEEK_BASE_URL=http://127.0.0.1:1 \
  "$dsh_bin" headless --json 'Reply MOCK_OK. Do not use tools.'

There is no DEEPSEEK_API_KEY in the child environment and neither .env file exists. The credential file has the same version/refs structure used by the local credentials service. The failure occurs before contacting the configured endpoint.

Expected behavior

The missing-key diagnostic should give recovery advice applicable to the active profile. For shipped headless, saving a key in the Web Models page alone cannot authenticate the invocation. The headless Credentials documentation describes launch environment → invocation-directory .env → Harness-home .env, and a three-row patch to restore stored authentication. Recovery advice should remain valid for SDK and ACP, where the store is active.

Actual behavior

The invocation exits 1, with stderr:

dsh: MISSING_CREDENTIAL: llm-deepseek: no API key for provider route "deepseek-official"; store DEEPSEEK_API_KEY through the credentials service (the web Models page writes it), or export DEEPSEEK_API_KEY in the launching environment

Its NDJSON turn_end has reason.kind: "error" and error.code: "MISSING_CREDENTIAL"; the final text is empty. The diagnostic neither qualifies the store suggestion nor mentions the .env fallbacks or restoration option.

In isolated loopback-mock controls, stored-only headless sent no request. Separate headless runs using an exported fake key, an invocation-directory .env, a Harness-home .env, or the documented three-row restoration patch completed with MOCK_OK; the mock received the corresponding fake key. SDK and ACP runs with only the stored fake key also completed. With no stored or launch-time key, SDK and ACP surfaced the same provider message; their store recommendation is applicable because their store is active.

Evidence

• Expected source: The headless Credentials documentation above explicitly says GUI-saved keys are ignored by the shipped profile and identifies the supported alternatives.
• Failure source: Fresh isolated npm installation; executed shipped-profile headless invocation and loopback-mock controls, with exit status, stderr, NDJSON terminal outcome, and received request headers observed.
• Evidence provenance: observed
• Local verification: reproduced
• Reproduction completeness: complete

The headless patch disables credentials, authorization, and deepseek-account. In the API-key provider, resolveApiKey already checks ctx.get('credentials') to choose its lookup path, then throws the same store-oriented message after either path fails. These locators explain the observed scope without prescribing a repair.

Runtime or environment

• npm package: @deepseek-ai/dsh@0.2.1-rc.2, current npm latest and next, installed into an isolated temporary prefix.
• Current default branch: master, commit 687f282e8625c6b8d11ff58211a90524be2e4317, also the release tag's source revision; the diagnostic and shipped-profile configuration remain present there.
• Node.js: v26.12.0.
• Platform: macOS arm64, Darwin 27.0.0.
• Fresh isolated Harness home, agent home, user home, and working directory; no real credentials; telemetry and session-log contribution disabled.

Restoration check

Repeat stored-only shipped headless: it should still refuse authentication, but its error must no longer imply that saving the key alone will fix that invocation. Following a recovery option it advertises must use a credential source active in that composition. Keep a store-enabled SDK or ACP control to confirm that valid store guidance remains available where appropriate, and retain an environment-key headless control so a successful request cannot mask an unintended change to the documented authentication behavior.

Triage assessment

• Impact level: P3
• Assessment status: supported
• Impact basis: The defect is misleading recovery wording. The missing-key failure and headless store exclusion follow the documented behavior; no credential loss or unauthorized access was observed.
• Workaround status: available
• Workaround basis: An exported fake key, each documented .env location, and restoration of the three authentication rows all completed against the loopback mock. The existing export suggestion is usable for shipped headless.

[PerryLink]

The diagnostic already names the remedy that works in this profile, so I would narrow the report to the ordering rather than the missing advice.

// packages/llm/llm-deepseek-api-key/src/index.ts:30-34
throw new LlmError(
  `llm-deepseek: no API key for provider route "${PROVIDER}"; store ${ref} through the credentials`
  + ` service (the web Models page writes it), or export ${ref} in the launching environment`,
  'MISSING_CREDENTIAL',
)

The third clause — export it in the launching environment — is exactly what headless needs, and it is already there. Your summary keeps only the first two, which makes the message look worse than it is.

What is actually wrong is that the message does not depend on which plane it is on. The resolver above already branches on it:

// :22-29
const credentials = ctx.get('credentials')
if (credentials !== undefined) {
  const hit = await credentials.resolve(ref)
  if (hit !== undefined) return assertUsableApiKey(hit.value, 'llm-deepseek', ref)
} else {
  const ambient = launchEnvironmentOf(ctx).get(ref)
  if (ambient !== undefined && ambient.value.length > 0) return assertUsableApiKey(ambient.value, 'llm-deepseek', ref)
}

So the code knows whether the credentials service exists; the error text does not. In headless it leads with a service that is not mounted, and a user follows the first instruction into the same failure.

The fix is to build the text from that same fact: when ctx.get('credentials') is undefined, say "export DEEPSEEK_API_KEY in the launching environment; this profile does not mount the credentials service" and drop the service clause entirely. That keeps one message per situation instead of a menu where one entry is a dead end.

I checked this at 687f282 (0.2.1-rc.2), the same release line your report is against, so this is not a version difference.