client.config

Typed reads of dynamic per-agent configuration. Operators tweak values in the dashboard (feature flags, thresholds, JSON snippets); agents read them at runtime through client.config and the value propagates without a redeploy.

Mental model

client.config mirrors client.secrets but for non-secret operational config. Values can be any JSON-serialisable shape — pass a generic to get / getMany to type the return value at the call site. The facade does not cache — every call hits the control plane — so dashboard edits propagate on the next read.

Required capability: config.read_write. Both get and getMany await the contract handshake before dispatching.

Read a single key

import { createClient } from '@stackbone/sdk';

const client = createClient();

interface RefundConfig {
  thresholdCents: number;
  approverEmail: string;
}

const result = await client.config.get<RefundConfig>('refund.policy');
if (result.error) throw new Error(result.error.code);

const { thresholdCents, approverEmail } = result.data;

get rejects empty keys with config_invalid_request. A key that the agent does not have set surfaces config_not_found (mapped from the underlying HTTP 404).

Read many at once

interface AgentConfig {
  greeting: string;
  retries: number;
  features: { betaInbox: boolean };
}

const result = await client.config.getMany<AgentConfig>(['greeting', 'retries', 'features']);
if (result.error) throw new Error(result.error.code);

console.log(result.data.greeting); // string | undefined

Keys absent from the agent's config come back as omissions in the returned Partial<T> — getMany never fails just because one key is unset. Access fields with ?. and provide defaults at the call site.

Errors

Code	When
config_invalid_request	Empty key, empty array, or array with empty strings.
config_not_found	get(key) and the agent has no value for that key.
config_invalid_response	Control plane returned a payload missing the expected fields.
HTTP errors (http_*)	Network / 5xx / unexpected status.

The contract gate adds contract_version_unsupported, capability_unavailable, contract_unreachable and contract_malformed — see overview.

Where to go next

• client.secrets — same pattern, but for encrypted credentials.
• client.approval — combine with client.config to surface "this action needs approval" thresholds without redeploying.