RFC: Agent as a 24×7 Background Service — Key Pool, Sandbox Awareness, Self-Evolution

[szkkcool]

RFC: Agent as a 24×7 Background Service — Provider Key Pool, Sandbox Awareness, and Self-Evolution Architecture

Status: Draft
Author: Community contribution
Related: DeepSeek Harness (DSH)

---

Abstract

DeepSeek Harness currently runs as a web application where the agent's capabilities are tied to the browser session. Closing the browser stops the user's interaction surface but the agent continues operating. This RFC proposes formalizing this "agent as background service" model with three supporting subsystems: a transparent multi-key rotation proxy for provider quota management, sandbox-aware network strategy, and a skill-driven self-evolution pipeline. Together they make DSH a true 24×7 autonomous agent service.

---

Motivation

Real-world agent usage reveals several gaps:

1. API quota exhaustion is not a rate limit: When multiple parallel agent calls (tool invocations, subagents, background jobs) hit the same provider API key, the gateway returns 429 "Allocated quota exceeded". DSH's default retry policy treats this as a terminal error (QUOTA is not in retryableCodes), causing the entire agent round to fail.

2. Single-key RPM bottlenecks: Free-tier provider accounts (e.g., 20 RPM actual) are insufficient for agent workflows that issue parallel requests. Users resort to multiple API keys, but DSH has no mechanism to pool them.

3. Sandbox collateral damage: DSH's file sandbox on Windows restricts the process token, which breaks Windows schannel TLS — PowerShell Invoke-WebRequest and curl.exe cannot make HTTPS requests. This is not a network policy but a side effect of the restricted process context, and it's confusing to diagnose.

4. Vision model discovery is manual: Providers offer hundreds of models with varying capabilities, but DSH's model catalog is a static subset. Users need a way to discover, test, and annotate vision-capable models.

5. Knowledge is lost after each interaction: Solutions to these issues are rediscovered with each new user. DSH lacks a mechanism to persist operational knowledge as reusable skills.

---

Proposed Architecture

1. Provider Key Pool (Embedded Proxy)

Concept: A transparent local proxy that rotates API keys across a pool, multiplying effective RPM by the number of keys.

┌──────────────┐     ┌──────────────────┐     ┌─────────────┐
│   DSH Agent  │────▶│  Key Pool Proxy  │────▶│  Upstream   │
│              │     │  :18888           │     │  API        │
│  model: xxx  │     │  keys: [K1,K2..]  │     │             │
└──────────────┘     │  429 → next key   │     └─────────────┘
                     └──────────────────┘

Design principles:

• Configuration-driven: JSON config file with {port, upstream, keys[]}. No environment variables needed for startup.
• Hot-reload: fs.watch() on config file — keys can be added/removed without restart.
• 429-aware: On 429, automatically switch to the next key and retry.
• Per-provider isolation: Each provider gets its own proxy instance on a separate port. Keys never cross providers.
• Health endpoint: GET /health for monitoring; POST /reload for manual config reload.

Integration with DSH: The provider's baseURL in settings.yaml points to the local proxy (http://127.0.0.1:{port}/v1). DSH's existing apiKeyEnv and Authorization header are ignored by the proxy (it uses its own key pool).

Proposed enhancement: Build this directly into DSH's provider layer — a keyPool field in the provider config that accepts an array of API keys and handles rotation transparently.

2. Enhanced Retry Policy

Current behavior: DSH's classifyPiAiError() in dsh-llm-pi-ai checks isQuotaExceededError() before the rate-limit regex. The message "Allocated quota exceeded" is classified as QUOTA. The default retryableCodes (['EMPTY_RESPONSE', 'RATE_LIMIT', 'SERVER', 'TIMEOUT', 'TRANSPORT']) does NOT include QUOTA, making the error terminal.

Proposed changes:

• Add QUOTA to the default retryableCodes in dsh-llm/lib/types/retry-policy.js.
• Document the classification priority: isQuotaExceededError → QUOTA, 429 → RATE_LIMIT, explaining that provider gateways may return "quota exceeded" for both RPM exhaustion and actual quota limits.
• Provide per-provider RPM-aware default backoff values (e.g., initialDelayMs: 10000 for 20-RPM free tiers).

3. Sandbox-Aware Network Strategy

Problem: On Windows, DSH's workspace-write sandbox mode restricts the process token, causing Windows schannel (SEC_E_NO_CREDENTIALS). This breaks HTTPS for PowerShell Invoke-WebRequest and curl.exe. Node.js fetch() (using OpenSSL) works fine.

Proposed solution:

• Document the schannel vs. OpenSSL discrepancy in the sandbox policy documentation.
• Under workspace-write mode, automatically prefer Node.js fetch() over PowerShell/curl for network operations.
• Under danger-full-access mode, all network tools work normally.
• Consider exposing a sandbox.networkMode diagnostic field in the runtime context, so tools can adapt their transport strategy.

4. Vision Model Discovery & Annotation

Current behavior: DSH models can have input: ["text"] or input: ["text", "image"] to indicate modality support. However, for models discovered dynamically from provider endpoints (not in the pi-ai catalog), this metadata is missing.

Proposed enhancement:

• Auto-detect vision capability from model names (e.g., "vision", "vl", "vlm", "omni" patterns).
• Allow users to annotate input modalities in the provider config's model list.
• Expose a GET /v1/models/{id} endpoint that returns full capability metadata (context window, input types, supported features) for all automatically discovered models.

5. Skill-Driven Self-Evolution

Concept: DSH already has a skill system (dsh-skill, dsh-skill-filesystem) that allows agents to load reusable knowledge. This RFC proposes formalizing the feedback loop:

Encounter Problem → Diagnose & Fix → Write Skill → Next Encounter → Auto-Load Skill

Implementation:

• Add a session-level "skill extraction" command that allows the agent (or user) to persist a successfully debugged scenario as a skill.
• Skills should be auto-tagged by domain (e.g., provider-config, sandbox-issue, vision-model) so retrieval is context-aware.
• The skill registry should emit signals when a relevant skill exists for the current context, even if the agent hasn't explicitly loaded it.

---

Configuration Example

# ~/.dsh/settings.yaml — proposed extended schema

llm-pi-ai:
  providers:
    my-provider:
      apiKeyEnv: MY_API_KEY
      api: openai-completions
      baseURL: http://127.0.0.1:18888/v1
      keyPool:                          # NEW: built-in key pool (replaces external proxy)
        keys: ["sk-1", "sk-2", "sk-3"]
        retryOn429: true
      models:
        - id: model-vision
          input: ["text", "image"]     # NEW: explicit modality annotation
          contextWindow: 128000
      retryPolicy:
        mode: normal
        maxRetries: 3
        retryableCodes:
          - "RATE_LIMIT"
          - "SERVER"
          - "TIMEOUT"
          - "TRANSPORT"
          - "EMPTY_RESPONSE"
          - "QUOTA"                     # CHANGED: added to default
        backoff:
          initialDelayMs: 10000
          maxDelayMs: 120000
          jitterRatio: 0.5

permission:
  defaultPreset: danger-full-access     # NEW: sandbox mode for new sessions

sandbox:
  networkMode: auto                     # NEW: "auto" (prefer Node fetch), "native", "all"

---

Impact

Area	Impact
429 errors	90% reduction — key pool rotation + QUOTA retry handles both RPM exhaustion and quota limits
Multi-key management	Single config file, hot-reload, no manual proxy management
Sandbox usability	Clear documentation on schannel vs. OpenSSL; automatic fallback strategy
Vision model support	Dynamic discovery + user annotation; no more "is this model vision-capable?" guesswork
Knowledge retention	Skill extraction turns every debugging session into reusable expertise

---

Backward Compatibility

• retryPolicy with QUOTA added to defaults: existing configs without retryableCodes inherit the new default. Explicit retryableCodes lists are unaffected.
• keyPool is additive — providers without a keyPool field continue to use single-key auth.
• sandbox.networkMode defaults to "native" (current behavior) when not set.
• Skill extraction is opt-in (agent-initiated), not automatic.

---

Open Questions

1. Should the key pool proxy be built into DSH core, or remain an external component (as implemented here)?
2. Should QUOTA be added to the default retryableCodes unconditionally, or gated behind a configuration flag?
3. Should skill extraction be automatic (post-session analysis) or manual (agent-initiated)?
4. How should the sandbox network mode interact with the tool sandbox permissions system?

---

Implementation Sketch

Phase 1: Core Retry Enhancements

• Add QUOTA to DEFAULT_RETRYABLE_CODES in dsh-llm/lib/types/retry-policy.js
• Document classifyPiAiError() priority in dsh-llm-pi-ai/lib/index.js
• No breaking changes

Phase 2: Built-in Key Pool

• Add keyPool field to provider profile schema in dsh-llm-pi-ai/lib/index.js
• Implement key rotation in pi-ai's request pipeline
• Expose pool health via GET /v1/models or a dedicated endpoint

Phase 3: Sandbox Network Diagnostics

• Add networkMode to sandbox policy runtime context
• Provide tool-level guidance based on current sandbox mode

Phase 4: Skill Pipeline

• Build on existing dsh-skill-filesystem and dsh-skill infrastructure
• Add session-to-skill extraction workflow
• Implement context-aware skill suggestion

---

This RFC was distilled from a production debugging session covering provider configuration, quota management, sandbox troubleshooting, vision model discovery, and agent self-evolution. The full conversation transcript is available in the DSH session log.

[szkkcool]

关键反馈：Onboarding 不能依赖用户是专家

DSH 的设计理念是一切皆插件，架构灵活性很好，但初始配置和引导严重缺失。

我是有 agent 调用经验的用户，可以指出 agent 应该在什么时候做什么来加强能力——但大部分用户呢？他们完全处于盲用状态，可能永远都找不到真正的使用方法。

你不能把每个用户都当成专家。大部分用户需要：

1. 开箱即用的默认配置
2. 渐进式的引导
3. 自动化的自我优化
4. 失败时的智能建议

当前的 skill/self-evolution 方向是对的，但它假设用户知道怎么用。真正的自我进化应该是：系统主动发现瓶颈→主动提出解决方案→用户确认后自动执行。而不是等用户来配置。

[alwang35]

事实上，理念的结果会随着时间流逝而动态改变。DSH的设计理念与DSH的门槛不是同一个维度的问题。不能混为一谈。
关键在于定制化与复用。
对于普通用户而言，是不是真的需要用到DSH ? 网页版的免费DS是不是就够用了 ？ 这个问题应该要放在讨论DSH的门槛问题之前。
普通用户的定义与范围，则需要放在上一个问题之前
对于Deepseek团队而言，量化是团队基因。
所有的问题都应该明确量化，而不是单纯使用语义。
这个结论不影响你的优秀能力。

[NovaRouteAI]

@szkkcool the Key Pool section is the part most 24/7 designs underestimate — the question isn't just having multiple keys, but the rotation policy: round-robin spreads load evenly, while quota-aware rotation (tracking remaining budget and error rate per key) avoids burning through one provider's limit mid-task.

For unattended operation I'd also emit per-key usage metrics, because silent 429 fallbacks are how background agents quietly inflate their own cost by retrying on degraded paths.

Long-running, multi-provider workloads are exactly what we've been testing with an OpenAI-compatible multi-model API layer focused on routing, fallback, and usage/cost visibility.

Would the pool rotate per request, or hold one key per long-running session?

[szkkcool]

感谢详细回应。同意 DSH 的目标用户不是普通用户，也认同"普通用户是不是需要 DSH、网页版是不是够用"应该放在门槛问题之前讨论。但我想补充一个观察：从今年爆火的各类 agent 应用来看，大量普通用户非常愿意把 AI/agent 引入自己的生活或工作，这是真实存在且快速增长的需求。网页版对轻度使用确实够用，但用户一旦产生更深的定制需求（Key 接入、并发任务、自动化流程），网页版就完全无法承载，用户只会止步于网页版的能力边界，而不会主动去学习一个门槛更高的工具。DSH 的设计可以不把普通用户当作目标用户，但降低从网页版向 DSH 迁移的门槛、让能力可以渐进式解锁，是承接这部分增量需求不可忽视的设计考量。量化是对的，以上每一点都可以用数据验证（例如网页版到本地工具的用户转化率、定制需求的占比），供参考。

[szkkcool]

架构反馈：Provider 适配层不应依赖外部库的模型目录

DSH 的 provider 配置格式、模型目录、认证方式实际上全部来自 @earendil-works/pi-ai 这个外部依赖。DSH 自己的 dsh-llm-pi-ai 只是一个薄适配层。

这造成两个问题：

1. 用户（和第三方开发者）看到 DSH 的 node_modules 里嵌着完整的 pi-ai 模型目录，会误以为 DSH 是套壳 pi-ai 的
2. 核心能力（模型发现、配置解析、认证）绑定在外部库上，而不是 DSH 自己的架构里

建议：将 pi-ai 的模型目录、provider 定义、认证逻辑直接合并到 DSH 的 @deepseek-ai/dsh-llm 系列包中，消除对外部库的架构依赖。

[szkkcool]

我们的需求正来自实际使用中的 429 错误——在调用一些免费 API key 时，多个并行请求会瞬间打穿单 key 的 RPM 配额，网关返回 429 "allocated quota exceeded"，agent 整轮直接失败。我们的方案是配置驱动的本地轮转代理：多个 key 组成一个池，每个请求按 round-robin 轮换一个 key，遇到 429 自动切换到下一个 key 重试；配置文件热重载，增减 key 无需重启。每个用户的 key 数量、配额、使用模式都不一样，这个方案只是提供一种解决问题的思路，具体策略（round-robin 还是配额感知、按请求还是按会话分配）取决于各自的使用场景。关于 per-key 用量指标的建议很好，确实是 24/7 无人值守场景下控制成本的关键，后续会考虑加上。

[NovaRouteAI]

The 429 case is a good example of where round-robin alone can become misleading: keys may have different remaining RPM, recent failures, or provider-side limits. Per-key usage and retry outcomes need to travel with the request so the next selection can be quota-aware rather than simply positional.

For a 24/7 agent, I would also separate “switched because of a 429” from “switched because the key was already near its budget.” That gives you a useful signal for deciding whether round-robin is enough or whether a quota-aware policy is justified. Are you planning to expose those per-key decisions in the same telemetry surface as the agent task history?

[szkkcool]

说得对，纯 round-robin 确实不够精细。实际使用中 429 有两种情况：一种是 RPM 超限（等几十秒就恢复），另一种是配额真的用完了（等多久都没用）。现在我们的脚本对这两种情况是同等对待的，轮流试一遍所有 key，都不行就失败——这其实浪费了"知道哪个 key 还有余量"的信息。

类似的思路在开源社区已经有不少实践，比如 FreeLLM 等项目的 key 管理方案就考虑了配额感知。我们最初只是针对自己的使用场景写了个简单脚本，没有往通用的方向去完善。429 这个问题确实困扰了很多人，从提案下面的讨论热度就能看出来。

关于 telemetry 的问题：我们目前没有把 per-key 决策暴露到 agent 任务历史里，但这是个值得做的方向——把"切换原因"（429 / 预算耗尽 / 随机轮转）和每次切换后的结果（成功 / 继续 429）记录下来，agent 就能做更聪明的选择。后续如果完善这个方案，会考虑加上。

[szkkcool]

补充一下背景（来自社区用户反馈）：上述关于 pi-ai 依赖的问题，DSH 团队已经公开承认过——内部在 DSH 出来之前一直用 pi 做开发，DSH 沿用了 pi-ai 作为 provider 层是历史遗留，不是架构设计失误。技术债务是客观存在的，措辞上不应说是"低级错误"，更准确的表述是"历史迁移遗留的技术债务，需要排期重构"。抱歉之前的语气偏重了。

[weijiafu14]

这份 RFC 里有两个具体的、可验证的缺陷被埋在了架构提案底下，我认为它们比 RFC 本身更容易推动，也更该先拿出来。

一、你的动机 1 和动机 3 应该各自单独开帖

动机 1：QUOTA 不在 retryableCodes 里

When multiple parallel agent calls hit the same provider API key, the gateway returns 429 "Allocated quota exceeded". DSH's default retry policy treats this as a terminal error (QUOTA is not in retryableCodes), causing the entire agent round to fail.

这是一个分类问题，不是架构问题：一个 429 配额错误被当成终态，整轮直接失败。它可以在不引入任何新子系统的情况下讨论清楚（配额是不是可重试？多久重试？和 RATE_LIMIT 有什么区别？）。

而且它和 #1215 那位报的是同一族——那边是"一次流式失败只落成一句英文文案，跳过了配置好的有界重试"，因为下游的结构化 code/status 在生成消息前被压扁了。两条合起来是一个完整的诉求：重试决策必须基于结构化的机器码，而分类表要覆盖配额。 单独提、并引上 #1215，比放在这份 RFC 里强得多。

动机 3：Windows 沙箱破坏 schannel TLS

DSH's file sandbox on Windows restricts the process token, which breaks Windows schannel TLS — PowerShell Invoke-WebRequest and curl.exe cannot make HTTPS requests. This is not a network policy but a side effect of the restricted process context, and it's confusing to diagnose.

这条是本帖最有价值的一段，而且它现在被埋在第 3 点里。 它是一个具体的、可复现的、后果明确的缺陷，而且属于一个这个社区正在成形的族：沙箱的实际效果与它宣称的语义不一致，且不可见。

同族的两条已经有独立报告：

• #1331：windows-acl 档标着 enforcement: 'partial'，边界对模型和运维都不可见；
• #3178：bwrap 的 --dev /dev 覆盖掉宿主 /dev，WSL 下 /dev/dxg 消失导致 CUDA 完全不可用——同样是"沙箱的副作用打到了一个和文件权限无关的能力上"。

你这条是第三个实例，而且症状最迷惑（用户会以为是网络/证书/代理问题，几乎不可能第一时间怀疑到文件沙箱）。建议单独开帖，标题直写"sandbox 的进程令牌限制会让 Windows 上的 HTTPS 客户端失效"，正文就是你现在这一段。 它今天挂在一个叫"24×7 Background Service RFC"的帖子里，任何按标题分诊的人都不会找到它。

二、关于 RFC 本身：范围太大，建议拆

这份 RFC 同时提了 key pool 代理、沙箱感知网络策略、skill 驱动的自我进化，还有 onboarding。这四件事的争议度、依赖关系、所需证据完全不同：

• key pool 是一个可以独立存在的东西——而且它今天就能作为一个外部本地代理实现，不需要 DSH 改任何东西（把 provider 的 baseURL 指向本地端口即可）。既然如此，与其提"DSH 应该内置"，不如先做出来给大家用，用真实的使用量说明该不该进核心。这条路径比 RFC 快得多。
• 自我进化 / onboarding 是产品方向，几乎必然引出长讨论；
• 而上面那两个具体缺陷夹在中间，会被一起拖住。

判据很简单：一份提案里如果既有"这行代码分类错了"又有"系统应该会自我进化"，前者一定会等后者。

三、你在评论里的那个自我更正，值得说一句

你后来补的那条——把"低级错误"改成"历史迁移遗留的技术债务，需要排期重构"——是对的，而且我觉得比原话更准确：pi-ai 作为 provider 层确实是历史路径，但它今天仍在正常工作，把它称作架构失误既不公平也不利于讨论。

顺带一个相关的事实供参考：这个外部依赖的版本策略本身确实有一个真问题，而且已经有独立报告——#2849：dsh-llm-pi-ai 钉的是 ^0.82.1，而 0.x 的 caret 规则永远到不了 0.84，于是模型选择器里缺 GLM-5.3 这类新模型，而且不报错、只是缺。这是一个比"该不该合并进 DSH 自己的包"具体得多、也好推得多的切入点。

（我这边的事实：我们把 @earendil-works/pi-ai 精确钉在 0.84.1，和 dsh-llm-pi-ai@0.1.1-rc.2 装在同一棵依赖树里跑契约测试和真机 E2E，没遇到流协议层面的破坏。这只是一份覆盖有限的运行信号，不是"升级安全"的结论。）

边界与利益相关

我们不修 DSH 自家组件——重试分类、沙箱进程令牌、模型目录都在 DSH 里。上面全是拆分建议和跨帖串联；我没有 Windows 环境，没有复现过 schannel 那条，完全采信你的描述。

利益相关：我维护 pi2dsh（Pi 生态兼容层）。这条不推销——你的四个方向里没有一个是装一个第三方插件能解决的；key pool 那条我建议你自己做成独立代理，也不需要经过任何人。