LAYER 06 · Build and ship extensions

Lab: design a capability seam and provider

Design interface, implementation, and consumer together; an abstract class alone is not a seam

22 min3 source anchorsupstream@47f9438

definition + provider + consumer

The question this chapter resolves

When should you add a provider, and when should you design a new seam?

Build intuition

A socket standard is not one socket shell. It defines the electrical interface, manufacturers producing sockets, and appliances consuming them. Without all roles, it has no product meaning.

MECHANISM

Mechanism

When a service contract exists, a new provider implements its semantics and registers. A new capability requires a service definition, at least one provider, a consumer, and a clear replacement value.

Provider-specific config stays in the implementation package; consumers depend only on the service. Capability catalogs and module graphs verify there are no unnecessary reverse dependencies.

Step 1 of 5

Prove replacement value

Identify two plausible implementations or one clear deployment boundary.

INVARIANTS

What extensions must preserve

Consumers do not import provider packages
Every implementation can honor interface error semantics
Provider disposal fully releases SDK, process, or remote resources

FAILURE MODES

The tempting wrong turns

×Abstracting prematurely for one implementation
×Leaking provider names into agent-loop
×Offering an arbitrary protocol escape hatch

● ● ●h26-build-adapter.ts TypeScript

abstract class WeatherService extends Service {
  abstract lookup(input: WeatherQuery, signal?: AbortSignal): Promise<WeatherSnapshot>
}

class HttpWeatherProvider extends WeatherService {
  async lookup(input: WeatherQuery, signal?: AbortSignal) {
    return normalize(await this.client.fetch(input, { signal }))
  }
}

VERIFY IN SOURCE

Do not trust the conclusion—verify it

These anchors are pinned to official deepseek-harness@47f9438; account for later breaking changes when reading current upstream.

Capability graphdocs/capability-seams.md

Definitions, implementations, consumers, and policy consumers.

Adding an adapterdocs/cookbook/adding-an-llm-adapter.md

A concrete provider-extension example.

Package boundariesdocs/cookbook/adding-a-package.md

Package boundaries, dependencies, and verification.

KNOWLEDGE CHECK

Pause for ten seconds before revealing

Why does the LSP seam not expose sendRawRequest()?

Why the next chapter follows

A capability still needs human and client surfaces. Next: how Web, CLI, ACP, SDK, and Host share one agent.