# Agent harness native inventories

> Read-only model and MCP catalogs a harness reports from its own native runtime

- 网址：https://funcoding.ai/agents/openclaw/plugins/sdk-agent-harness/native-inventories/
- 来源：OpenClaw 官方文档原文（英文），MIT 许可，同步于 2026-10-11
- 官方原文：https://docs.openclaw.ai/zh-CN/plugins/sdk-agent-harness/native-inventories

---
The read-only catalogs a harness exposes to OpenClaw control surfaces: native model rows with their readiness, and MCP tool inventory owned outside the in-process MCP runtime. Part of the [Agent harness plugins](https://funcoding.ai/agents/openclaw/plugins/sdk-agent-harness/) reference.

## Native model inventory

`loadModelCatalog(params)` lists models for the supplied agent, workspace, and
config snapshot. Rows owned by native model selection set `nativeRuntime` to
the harness ID and omit host `api` and `baseUrl` claims. Core does not enrich
these rows with transport or capabilities from a host route.

Return `{ entries, outcomes }` to report secret-free discovery outcomes alongside
the rows. Outcomes use the provider catalog statuses `ready`, `auth-rejected`,
and `unavailable`; a catalog-only auth rejection sets `rejectionScope: "catalog"`.
Do not include raw native errors or credential data. Failed providers retain their
previous rows while successful siblings update. An empty successful result,
including a disabled or missing app, clears that runtime's earlier outcomes.
Core retains these facts with the native runtime independently of API-provider
authentication. Plain row arrays remain supported for plugins built against the
2026.9.5 SDK.

Unexpected thrown discovery errors keep the host’s generic partial-failure behavior.
The host does not infer a provider or authentication rejection from a runtime name
or arbitrary exception text; a harness must supply its own known provider outcome.

An optional synchronous `readModelCatalogReadiness(params)` returns only
`{ accountType: string }` for a current native account observation
covering that exact scope and model. Preserve the native account type; it does
not imply a host credential or OAuth refresh lifecycle. Return `undefined` for missing, failed,
superseded, or disposed observations. Readiness must remain with the physical
native owner and be revalidated at use; never serialize it on catalog rows,
perform I/O in this callback, or infer it from a successful earlier turn.
Gateway uses this metadata for native-owned picker rows; authored host routes,
credentials, and profile locks still use host readiness. This is not execution
authorization, and all run-time compatibility and permission checks still apply.

### Service-tier picker policy

An optional synchronous `filterModelServiceTiers` hook narrows the tiers shown for
the harness runtime:

```ts
filterModelServiceTiers(params: {
  config: OpenClawConfig;
  agentId?: string;
  provider: string;
  modelId: string;
  serviceTiers: readonly string[];
}): readonly string[];
```

Gateway calls this hook after resolving account and route service-tier evidence,
for both the selected model row and alternative runtime choices. The supplied
config is the prepared catalog's snapshot. Interpret plugin-specific policy in
the harness; core does not read private plugin config.

Return a subset without mutating the input or doing I/O or discovery. Core
intersects the result with the resolved tiers, preserving their order and
ignoring added tiers. Without the hook, tiers are unchanged. Unknown tier
availability remains unknown and does not invoke the hook. This affects picker
metadata only; the harness must still enforce its policy when executing a turn.

## Native MCP inventory

A harness that owns MCP connections outside OpenClaw's in-process MCP runtime
can implement `loadMcpToolCatalog(params)`. The callback is used by read-only
control surfaces such as the composer Tool access view. It receives the
authoritative session identity, runtime config, workspace, and sparse session
MCP overrides. `mcpServerNames` is the bounded set of OpenClaw-configured
servers whose session policy the harness may represent. Return OpenClaw's
`McpToolCatalog` shape for only that set.

Use only an already-bound native process and thread. Returning `undefined`
means no live catalog is available; do not start a new harness process merely
to answer inventory. Preserve raw server/tool names, assign collision-safe
server names with `assignMcpCatalogSafeServerNames(...)`, and retain tools
hidden only by a session denial in `sessionDeniedTools`. Core still applies the
final OpenClaw tool policy and schema compatibility checks before exposing the
rows.

`SessionMcpRuntime` implementations used by materialized tool views should
provide `joinCleanup()`. It waits for cleanup already requested from that exact
runtime, including unpublished or retiring servers, and rejects if any owned
cleanup failed or could not be confirmed. It must preserve that failure for
later callers without closing transports still leased by another run. A fulfilled
best-effort `dispose()` alone is not cleanup evidence.

The method is optional for existing SDK implementations; automatic one-shot
recovery treats a missing method as uncertain cleanup. A native facade that owns
no transport may resolve immediately when its enclosing runtime separately owns
and verifies the process lifetime.