Expose backend discovery/capabilities for workspace.runtime.exec

[yulinlina]

I was reading through the README and trying to think about how an agent would safely choose between registered backends. workspace.runtime.exec(source, { backend }) is a nice single entry point, but the README notes that the selected backend determines whether source is a shell command or an ECMAScript module.

From the caller's perspective, it looks like you need to already know that one backend ID is shell-like and another is JS-like. If a Workspace has multiple backends registered, there doesn't seem to be a documented way to ask the runtime what backends exist, whether they're connected/lazy, or what kind of source/result they accept.

This becomes a papercut when the caller is an agent or a generic UI: it can easily pick a backend ID and pass the wrong source type, then fail only when the backend connects/executes. A small introspection API would make this much easier to use, something like:

const backends = await workspace.runtime.listBackends();
// [{ id: 'container', kind: 'shell', ready: false }, { id: 'js', kind: 'module', ready: true }]

or even just:

const info = await workspace.runtime.describeBackend('container');
if (info.source === 'shell') { ... }

That would also give a natural place to expose backend-specific limits later, such as network access, filesystem write access, or allowed imports, without changing exec itself. If this already exists somewhere, it might be worth calling it out in the README because it's key to using multiple backends safely.

[yulinlina]

I agree this is mostly plumbing existing state rather than introducing new lifecycle data. One naming tweak: I’d use sourceKind rather than source to avoid confusion with the source argument passed to exec().

For agent safety, I’d also avoid making protocol authoritative. It can inform a fallback, but third-party backends should not be silently guessed.

Proposed shape:

export type BackendSourceKind = "shell" | "module" | "unknown";

export interface RuntimeBackendInfo {
  id: string;
  type?: string;
  sourceKind: BackendSourceKind;
  sourceInferred: boolean;
  callable: boolean;
  default: boolean;
  ready: boolean;
}

unknown is important: if a custom backend does not declare its input contract, the API should expose that ambiguity instead of pretending to know.

The source kind should come from an explicit backend capability:

interface BackendCapabilities {
  sourceKind?: "shell" | "module";
}

interface Backend {
  type?: string;
  capabilities?: BackendCapabilities;
}

First-party backends can declare it directly:

• worker-shell → sourceKind: "shell"
• cloudflare-container → sourceKind: "shell"
• module backend → sourceKind: "module"

For compatibility, we can infer from known protocols for existing built-ins, but set sourceInferred: true. Unknown protocols should default to "unknown" rather than guessing.

Implementation-wise:

• The Workspace constructor already has the registered IDs, callable set, and default ID.
• It can build a Map<string, RuntimeBackendInfo> during registration.
• ready should initially reflect already-established connectivity without forcing a lazy backend to connect.
• WorkspaceRuntime can receive that map read-only and expose:

listBackends(): Promise<RuntimeBackendInfo[]>;
describeBackend(id: string): Promise<RuntimeBackendInfo | undefined>;

Keeping the methods async leaves room for future readiness probes or remote backend discovery.

This also gives a stable place to add future capability metadata later — sandboxing, streaming, supported shells, resource limits, etc. — without changing the exec() surface.

A patch with the descriptor type, built-in capability declarations, and the runtime passthrough seems like a clean first iteration.

[yulinlina]

如果这里指的是通过某个 backend 跑模型推理时 GPU 显存不足，量化确实是主要缓解方案，但它属于 backend / 推理服务层能力，不应该让 exec(source, { backend }) 的调用端盲猜。

常见可行方案：

1. 权重量化：INT8 / INT4，例如 AWQ、GPTQ、GGUF。显存占用下降明显，但精度、延迟和吞吐取决于后端实现。
2. KV cache 量化 / paged attention：长上下文场景下，OOM 往往不是模型权重本身，而是 KV cache，这类方案通常比单纯量化权重更有效。
3. 运行参数降级：降低 batch size、max tokens / context length，必要时启用 CPU offload 或多卡分片。

对当前 issue，我建议先把 sourceKind 做稳；GPU / 显存 / 量化可以作为后续 optional capabilities，不阻塞这个 API：

interface BackendCapabilities {
  sourceKind?: "shell" | "module";
  accelerator?: {
    kind: "gpu" | "cpu";
    vramRequiredMb?: number;
    quantization?: Array<"int8" | "int4" | "awq" | "gptq" | "gguf">;
  };
}

这样 agent 可以优先选择声明了低显存或量化能力的 backend，而不是执行后才 OOM。

如果你能说明具体 backend、模型规模和可用显存，我可以给更具体的量化选择。

[Leo-Ayh-Oday]

I’ve been reading through the runtime and workspace design, and I think this capability-discovery direction is especially important for agent callers.

One thing I like about the current design is that authority is fixed when a backend is constructed rather than being requested dynamically through exec(). That seems like a good security boundary.

Because of that, I wonder if backend discovery could expose more than just the source kind — perhaps a small, stable capability descriptor such as:

{
id: "worker-javascript-readonly",
kind: "module",
input: "structured",
access: "read",
network: false,
resumable: true,
cancellable: true
}

Then an agent/harness could route execution based on capabilities without treating the backend ID itself as semantic configuration.

I’m particularly interested in agent runtime / execution-layer design, so I’d be happy to experiment with routing policies or test cases around this if that would be useful.

[yulinlina]

I like this direction. Since authority is fixed when the backend is constructed, discovery should expose a frozen snapshot of construction-time capabilities, not dynamically negotiated permissions. That keeps the security boundary intact while giving agents enough information to route fail-closed.

I’d split the descriptor into two layers:

export type BackendSourceKind = "shell" | "module" | "unknown";

export interface BackendExecutionCapabilities {
  resumable?: boolean;
  cancellable?: boolean;
  streaming?: boolean;
}

export interface BackendSecurityProfile {
  access?: "none" | "read" | "write" | "full";
  network?: boolean;
  filesystem?: boolean;
}

export interface BackendCapabilities {
  sourceKind?: "shell" | "module";
  execution?: BackendExecutionCapabilities;
  security?: BackendSecurityProfile;
}

export interface RuntimeBackendInfo {
  id: string;
  type?: string;
  sourceKind: BackendSourceKind;
  sourceInferred: boolean;
  callable: boolean;
  default: boolean;
  ready: boolean;
  capabilities?: BackendCapabilities;
}

For v1, sourceKind is the critical piece because it directly affects whether exec(source, { backend }) receives shell text or module code. The broader execution/security capabilities can live under capabilities without forcing every backend to define them immediately.

A few routing rules that seem important for agent callers:

• sourceKind mismatch should be a hard client-side rejection.
• sourceKind: "unknown" should not be auto-routed; it should only be used when the caller explicitly selects that backend ID.
• Missing security capabilities should be treated as unknown, not as false.
• Capability data should be advisory for routing; enforcement still belongs to the backend/runtime.

For built-ins, first-party backends should declare capabilities explicitly:

// worker-shell / cloudflare-container
capabilities: { sourceKind: "shell" }

// module backend
capabilities: { sourceKind: "module" }

// read-only JS sandbox example
capabilities: {
  sourceKind: "module",
  security: { access: "read", network: false, filesystem: false },
  execution: { cancellable: true, resumable: false }
}

A useful first PR would be:

1. Add optional capabilities to the backend interface.
2. Plumb registered/callable/default/ready state through WorkspaceRuntime.
3. Add listBackends() and describeBackend(id).
4. Return sourceKind: "unknown" when no explicit capability is declared.
5. Add tests for built-in backends and for unknown third-party backends.

I can open that PR and keep the broader security / execution fields optional so we can iterate without blocking the initial discovery API.

[calhounbrian82]

📌✨💡 跨平台兼容性测过 Windows 吗

[wilsondonna51]

告警阈值是怎么调出来的 ✨😄⭐

[medinakenneth6634]

🧪🚀🤝 安全方面有没有默认开启的校验