dsh-opencode-go 0.1.0

package/lib/types/adapter.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The OpenCode Go adapter: one route, one catalog, per-request routing header.
+ *
+ * Every request to the gateway carries two Harness-owned headers: the
+ * attribution User-Agent (`deepseek-harness/<version>`), which pi-ai's client
+ * lets request headers override, and `x-opencode-session`, which the gateway
+ * requires and uses to route a conversation and share its prompt cache. The
+ * header value is the request's session id — stable per conversation, so
+ * caching and billing attribution stay correct; a request arriving with no
+ * session id gets a fresh random value rather than a shared constant, because
+ * a constant would merge unrelated traffic into one cache bucket.
+ *
+ * Multi-turn correctness rides on the shared pi-ai conversion machinery
+ * (`toPiContext` reconstructs provider-native replay state from the session
+ * log; `toStreamChunks` maps events to seam chunks), so assistant history,
+ * tool calls, and usage land in the session log exactly as the generic pi-ai
+ * adapter records them. Image content rides the same machinery: models whose
+ * catalog entry declares the image modality convert attachments through the
+ * durable attachment service, and every other model refuses image content
+ * before any provider I/O.
+ *
+ * @module dsh-llm-opencode-go/adapter
+ */
+import { LlmAdapter } from '@deepseek-ai/dsh-llm';
+import type { GenerateOptions, ImageAttachmentAccess, LlmModelInfo, LlmResolvedModelInfo, StreamChunk } from '@deepseek-ai/dsh-llm';
+import type { AttachmentStore, ImageAttachmentRef } from '@deepseek-ai/dsh-attachment';
+import { OpencodeGoCatalog } from './catalog.ts';
+import type { OpencodeGoConfig } from './config.ts';
+/**
+ * The attachment-service bridges one image request reads. Construction-time
+ * (context-dependent); the config-dependent policy numbers are merged per
+ * request from the current configuration.
+ */
+export interface OpencodeGoImageAccess {
+    /** Resolve the optional durable attachment service at request time. */
+    resolveAttachments: () => AttachmentStore | undefined;
+    /** Bridge one attachment reference into the current model-tool execution world. */
+    resolveImageAccess: (attachments: AttachmentStore, ref: ImageAttachmentRef) => ImageAttachmentAccess | undefined;
+}
+/** Constructor inputs for {@link OpencodeGoAdapter}. */
+export interface OpencodeGoAdapterOptions {
+    /**
+     * The current configuration, re-read at every operation: a settings write
+     * reaches the next request without a restart, and one operation never mixes
+     * two configuration generations.
+     */
+    config: () => OpencodeGoConfig;
+    /** Resolve the route's credential per call; missing must fail loud. */
+    resolveApiKey: () => Promise<string | undefined>;
+    /**
+     * Image input machinery; absent refuses image content, which is the posture
+     * for direct construction without a durable attachment service behind it.
+     */
+    imageAccess?: OpencodeGoImageAccess;
+    /** Observe the catalog falling back to the curated table. */
+    onFallback?: (detail: {
+        url: string;
+        error: unknown;
+        kept: number;
+    }) => void;
+    /** Observe live ids the curated table cannot route. */
+    onOmitted?: (ids: readonly string[]) => void;
+    /** Observe assistant history degrading to provider-neutral conversion. */
+    onReplayDegrade?: (reason: string) => void;
+}
+/**
+ * The single route's adapter. The catalog snapshot freezes at each operation,
+ * so a refresh between two requests never mixes model generations inside one
+ * call.
+ */
+export declare class OpencodeGoAdapter extends LlmAdapter {
+    private readonly options;
+    /**
+     * One catalog instance per endpoint/refresh pair. A settings write that
+     * changes either gets a fresh resolver (and a fresh live-listing fetch) on
+     * the next operation; an unchanged configuration keeps its cached snapshot
+     * for the whole refresh interval.
+     */
+    private catalogCache;
+    constructor(options: OpencodeGoAdapterOptions);
+    /**
+     * The catalog resolver for one configuration, rebuilding on the facts it
+     * owns. Public for the plugin's discovery registration, which resolves the
+     * current configuration the same way the adapter does.
+     * @param config - the configuration whose endpoint and refresh interval the
+     *   resolver serves; a change to either yields a fresh resolver.
+     * @returns the resolver caching one snapshot per endpoint/refresh pair.
+     */
+    catalogOf(config: OpencodeGoConfig): OpencodeGoCatalog;
+    providerInfo(provider: string): {
+        id: string;
+        name: string;
+    };
+    listModels(_provider: string): Promise<readonly LlmModelInfo[]>;
+    resolveModel(_provider: string, model: string, _signal?: AbortSignal): Promise<LlmResolvedModelInfo>;
+    /** Describe one model: capacities plus the reasoning levels it actually offers. */
+    private modelInfo;
+    /** Validate an explicit effort against the model's own levels, without clamping. */
+    private resolveReasoningLevel;
+    stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+}

package/lib/types/catalog.d.ts

@@ -0,0 +1,95 @@
+/**
+ * The OpenCode Go model catalog: a curated table intersected with the gateway's
+ * live model list.
+ *
+ * The curated table is seeded from pi-ai's installed `opencode-go` catalog —
+ * its entries carry the wire protocol, compat quirks, thinking-level spellings,
+ * and capacities that the gateway's own listing endpoint does not disclose —
+ * plus this package's additions for models the installed catalog has not
+ * caught up with. The gateway rotates its list faster than either pi-ai or
+ * this package releases, so the served catalog is the curated table **minus**
+ * models the live listing no longer advertises: a model the gateway retired
+ * must disappear rather than error mid-session. Live ids the curated table
+ * does not describe are omitted too, because without a protocol mapping they
+ * cannot be routed correctly.
+ *
+ * The live listing at `{baseURL}/models` is public and answers ids only. A
+ * fetch failure never takes the route down: the curated table is served as-is
+ * and the failure is reported, on the grounds that a network blip should not
+ * deny service, while model discovery — whose whole purpose is the live
+ * answer — fails loud instead.
+ *
+ * @module dsh-llm-opencode-go/catalog
+ */
+import type { Api, Model, Provider } from '@earendil-works/pi-ai';
+import type { LlmDiscoveredModel } from '@deepseek-ai/dsh-llm';
+/** Provider route key this plugin registers and every materialized model carries. */
+export declare const PROVIDER_ID = "opencode-go";
+/** Display name for selectors and status labels. */
+export declare const DISPLAY_NAME = "OpenCode Go";
+/** Endpoint serving both model requests and the model listing. */
+export declare const DEFAULT_BASE_URL = "https://opencode.ai/zen/go/v1";
+/** One immutable resolution of the served catalog. */
+export interface CatalogSnapshot {
+    /** Served models by id: the curated table minus models absent from the live listing. */
+    readonly models: ReadonlyMap<string, Model<Api>>;
+    /** The provider serving exactly these models. */
+    readonly provider: Provider;
+    /** Whether the live listing answered this resolution; `false` on the fallback path. */
+    readonly live: boolean;
+    /** When this resolution completed, for the refresh interval. */
+    readonly fetchedAtMs: number;
+}
+/**
+ * Read one live listing reply. The endpoint answers the standard OpenAI
+ * `data` array with entries carrying ids only; anything else is a fault the
+ * caller treats as "live unavailable" and falls back. An honest empty array
+ * is a valid answer: the gateway says it serves nothing.
+ * @param body - the decoded JSON reply.
+ * @returns the non-empty ids it advertises, in reply order.
+ * @throws {Error} when the reply carries no `data` array.
+ */
+export declare function readLiveModelIds(body: unknown): readonly string[];
+/**
+ * TTL-cached resolution of the served catalog. Concurrent callers share one
+ * in-flight fetch; a completed snapshot serves unchanged until the refresh
+ * interval elapses, so one stream call never observes two catalog generations.
+ */
+export declare class OpencodeGoCatalog {
+    private readonly baseURL;
+    private readonly refreshMs;
+    private readonly onFallback;
+    private readonly onOmitted;
+    private served;
+    private pending;
+    /**
+     * @param baseURL - The endpoint the gateway serves; also the listing base.
+     * @param refreshMs - How long one live resolution stays authoritative.
+     * @param onFallback - Observes a failed live listing and how many curated
+     *   models kept serving because of it.
+     * @param onOmitted - Observes live ids the curated table cannot route.
+     */
+    constructor(baseURL: string, refreshMs: number, onFallback: (detail: {
+        url: string;
+        error: unknown;
+        kept: number;
+    }) => void, onOmitted: (ids: readonly string[]) => void);
+    /**
+     * The current catalog, fetching when expired or never fetched.
+     * @returns the snapshot now serving, shared by concurrent callers.
+     */
+    snapshot(): Promise<CatalogSnapshot>;
+    /** One resolution: intersect the curated table with the live listing. */
+    private build;
+}
+/**
+ * Candidate models for the configuration surface's "fetch available models"
+ * action: the same live intersection the route would serve, with the curated
+ * capacities the listing endpoint does not disclose. Unlike route resolution,
+ * discovery fails when the live listing is unreachable: its whole purpose is
+ * the live answer, and a stale answer would offer models the gateway retired.
+ * @param catalog - The route's catalog resolver.
+ * @returns the served models in curated order.
+ * @throws LlmError `DISCOVERY_FAILED` when the live listing is unreachable.
+ */
+export declare function discoverCatalogModels(catalog: OpencodeGoCatalog): Promise<readonly LlmDiscoveredModel[]>;

package/lib/types/client/Section.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The OpenCode Go settings section. It leads with the one value a user has to
+ * supply — the API key, stored write-only through the credentials domain — and
+ * the models the gateway currently serves, then keeps the credential
+ * reference, the endpoint, and the adapter tuning fields in the
+ * `llm-opencode-go` namespace behind a collapsed disclosure.
+ */
+import type { InjectFace } from '@deepseek-ai/dsh-client-ui-slots';
+import type { OpencodeGoSectionFace } from './section-controller.ts';
+import type { en } from './locales.ts';
+export type { OpencodeGoSectionState } from './section-controller.ts';
+/** Section copy lookup, including the optional `{name}` template params. */
+type SectionTranslate = (key: keyof typeof en, params?: Record<string, unknown>) => string;
+/** Injected dependencies of {@link OpencodeGoSection} (slot `inject`). */
+export interface OpencodeGoSectionInjected extends OpencodeGoSectionFace {
+    /** Section copy. */
+    t: SectionTranslate;
+}
+/** Props delivered by the slot outlet: the inject face spread flat. */
+export type OpencodeGoSectionProps = Partial<InjectFace<OpencodeGoSectionInjected>>;
+/**
+ * Render the OpenCode Go settings page.
+ * @param props - locale copy, the page snapshot, and its form actions.
+ * @returns the section.
+ */
+export declare function OpencodeGoSection(props: OpencodeGoSectionProps): import("react").JSX.Element | null;

package/lib/types/client/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * OpenCode Go settings plugin, browser half. Registers the "OpenCode Go"
+ * settings page over the `llm-opencode-go` namespace: the API key (stored
+ * write-only through the credentials domain), the gateway's current model
+ * listing, and the adapter knobs behind the page's advanced disclosure. The
+ * Host settings and credential contracts stay behind their existing wire APIs.
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import { en } from './locales.ts';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** The OpenCode Go settings page copy. */
+        'settings.opencode-go': keyof typeof en;
+    }
+}
+export type { OpencodeGoSectionProps } from './Section.tsx';
+export type { OpencodeGoSectionState, OpencodeGoSettings } from './section-controller.ts';
+export { OPENCODE_GO_NS } from './section-controller.ts';
+export type { OpencodeGoKey } from './locales.ts';
+/**
+ * Required services (cordis fiber inject). The target slot is declared by
+ * ui-settings' apply, whose activation order relative to this one is NOT
+ * constrained; registration depends on each slot through `slots.inject()`.
+ * `remote.llm` is the discovery namespace the page reads the model listing
+ * through.
+ */
+export declare const inject: string[];
+/**
+ * Register the section once the `settings.section` declaration is on the
+ * ledger, and keep the credential badge fresh on Host-reported key changes
+ * written from any surface.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;

package/lib/types/client/locales.d.ts

@@ -0,0 +1,50 @@
+/** Copy dictionaries for the OpenCode Go settings page. English is the key-set source of truth. */
+export declare const en: {
+    nav: string;
+    title: string;
+    intro: string;
+    enabledLabel: string;
+    enabledHint: string;
+    enabledOff: string;
+    enabledUnavailable: string;
+    keyLabel: string;
+    keyHint: string;
+    keyConfigured: string;
+    keyMissing: string;
+    keyNotWritable: string;
+    modelsLabel: string;
+    modelsRefresh: string;
+    modelsLoading: string;
+    modelsFailed: string;
+    modelsEmpty: string;
+    modelsCount: string;
+    advancedLabel: string;
+    advancedHint: string;
+    apiKeyEnvLabel: string;
+    apiKeyEnvHint: string;
+    baseURLLabel: string;
+    baseURLHint: string;
+    refreshMinutesLabel: string;
+    refreshMinutesHint: string;
+    streamIdleTimeoutMsLabel: string;
+    streamIdleTimeoutMsHint: string;
+    maxRequestImageBytesLabel: string;
+    maxRequestImageBytesHint: string;
+    requestImagePixelBudgetLabel: string;
+    requestImagePixelBudgetHint: string;
+    requestImageMaxBytesLabel: string;
+    requestImageMaxBytesHint: string;
+    overridden: string;
+    reset: string;
+    invalidValue: string;
+    save: string;
+    discard: string;
+    saving: string;
+    savedFailed: string;
+    readOnly: string;
+    unavailable: string;
+};
+/** Chinese copy; the key set mirrors {@link en}. */
+export declare const zh: typeof en;
+/** Every copy key this page's dictionaries must supply. */
+export type OpencodeGoKey = keyof typeof en;

package/lib/types/client/section-controller.d.ts

@@ -0,0 +1,175 @@
+/**
+ * The OpenCode Go settings page's staged form over the `llm-opencode-go`
+ * settings namespace, plus the gateway model listing the page reports.
+ *
+ * The key is the one control that does not live in the section: its literal
+ * never rides a response, so the page learns only whether one is configured
+ * and writes it through the credentials domain, addressed by the reference the
+ * section names. It is still staged with the rest of the form, so one save
+ * covers everything the page shows.
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis';
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
+import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client';
+import { type FieldState, type FormActions, type FormShell } from './staged-form.ts';
+/** Namespace of the OpenCode Go adapter. Spelled here rather than imported: a client package must not depend on a Host package. */
+export declare const OPENCODE_GO_NS = "llm-opencode-go";
+/** The adapter fields this page edits. */
+export interface OpencodeGoSettings {
+    /** Whether the adapter serves its route; false withdraws it from every picker. */
+    enabled?: boolean;
+    /** Credential reference naming the environment key. */
+    apiKeyEnv?: string;
+    /** The gateway endpoint; also the live listing base. */
+    baseURL?: string;
+    /** Live catalog re-resolution interval, in minutes. */
+    refreshMinutes?: number;
+    /** Largest idle gap between stream events, in milliseconds. */
+    streamIdleTimeoutMs?: number;
+    /** Accumulated base64 image payload bound for one request. */
+    maxRequestImageBytes?: number;
+    /** Total-pixel budget for one request image. */
+    requestImagePixelBudget?: number;
+    /** Raw encoded-byte target for one request image. */
+    requestImageMaxBytes?: number;
+}
+/** The gateway's model listing as the page reports it. */
+export type OpencodeGoModels = 
+/** Not asked for yet; the page asks once it mounts. */
+{
+    readonly status: 'idle';
+}
+/** A listing request is outstanding. */
+ | {
+    readonly status: 'loading';
+}
+/** The gateway answered: how many models it serves, and a preview of their names. */
+ | {
+    readonly status: 'ready';
+    readonly count: number;
+    readonly preview: readonly string[];
+}
+/** The listing could not be read; `message` is the Host's own diagnostic. */
+ | {
+    readonly status: 'failed';
+    readonly message: string;
+};
+/** What the settings page renders. */
+export interface OpencodeGoSectionState extends FormShell {
+    /**
+     * Whether the adapter currently serves its route. Resolved from the section
+     * rather than staged: the switch writes on the click that flips it, because
+     * a withdrawn route is what the user is trying to observe.
+     */
+    enabled: boolean;
+    /** Credential reference naming the environment key. */
+    apiKeyEnv: FieldState;
+    /** The gateway endpoint. */
+    baseURL: FieldState;
+    /** Live catalog re-resolution interval, in minutes. */
+    refreshMinutes: FieldState;
+    /** Largest idle gap between stream events, in milliseconds. */
+    streamIdleTimeoutMs: FieldState;
+    /** Accumulated base64 image payload bound for one request. */
+    maxRequestImageBytes: FieldState;
+    /** Total-pixel budget for one request image. */
+    requestImagePixelBudget: FieldState;
+    /** Raw encoded-byte target for one request image. */
+    requestImageMaxBytes: FieldState;
+    /** The staged credential, which starts blank on every load. */
+    apiKey: FieldState;
+    /** Whether the Host reports a credential configured for the referenced key. */
+    apiKeyConfigured: boolean;
+    /** Whether the credentials domain accepts a write for it; false disables the control. */
+    apiKeyWritable: boolean;
+    /** The gateway's current model listing. */
+    models: OpencodeGoModels;
+}
+/** The registration-side face the page's slot entry injects. */
+export interface OpencodeGoSectionFace extends FormActions {
+    hooks: {
+        /** Page snapshot bound by the UI renderer as useOpencodeGo. */
+        opencodeGo: SnapshotStore<OpencodeGoSectionState>;
+    };
+    /** Read the gateway's model listing, now or again after a failure. */
+    loadModels: () => void;
+    /**
+     * Turn the adapter's route on or off, writing immediately.
+     * @param next - the state the switch asks for.
+     */
+    setEnabled: (next: boolean) => void;
+}
+/** Bridges the `llm-opencode-go` scope and the credentials domain onto the page. */
+export declare class OpencodeGoSectionController {
+    private readonly scope;
+    private readonly ctx;
+    private readonly form;
+    private readonly store;
+    private credential;
+    private models;
+    private modelsRequest;
+    private face;
+    /**
+     * @param scope - the bound settings scope for the `llm-opencode-go` namespace.
+     * @param ctx - the page plugin's context, whose `remote.credentials` namespace
+     *   answers for the credential the section references.
+     */
+    constructor(scope: SettingsScope<OpencodeGoSettings>, ctx: ClientContext);
+    private projection;
+    /**
+     * The adapter's effective switch state: the resolved section's value, over
+     * the Host's own default when the section carries none.
+     * @returns whether the route is currently served.
+     */
+    private enabled;
+    /**
+     * Flip the switch by writing the field on the click itself.
+     *
+     * This is the one control on the page that does not wait for Save: the point
+     * of turning it off is to watch the models leave the pickers, and the point
+     * of turning it back on is to use the route again — staging either behind a
+     * second gesture would report a state the Host does not hold. The write is
+     * revision-fenced by the scope like every other, and a refusal surfaces as a
+     * failed save through the shared shell rather than a silent revert.
+     * @param next - the state the switch asks for.
+     */
+    setEnabled(next: boolean): void;
+    /**
+     * Read the gateway's model listing through the Host's discovery for this
+     * adapter. Called when the page mounts and again from its refresh control.
+     * A rejection settles as a failure too: the refresh control is disabled
+     * while loading and the next read starts only from `idle`, so leaving the
+     * state loading would strand the page with no way to ask the gateway again.
+     */
+    loadModels(): void;
+    /**
+     * Ask the credentials domain about the reference the section currently names.
+     *
+     * The answer is stored with the reference it describes: `apiKeyEnv` can
+     * change between the request and its response, and two reads can settle out
+     * of order, so a response is published only while it still answers for the
+     * reference in force.
+     */
+    private readCredential;
+    /**
+     * Re-read after the Host reports a change to the reference this page watches.
+     *
+     * A key can be written from somewhere else — the Models page addresses the
+     * same reference — and the settings section does not change when it is, so
+     * without this the badge keeps reporting a state the Host already replaced.
+     * @param ref - the reference the Host reports as changed.
+     */
+    refreshCredential(ref: string): void;
+    /**
+     * Build the face the page's slot registration injects. Built once: the store
+     * is what changes, and the renderer binds the same callbacks across renders.
+     * @returns the page snapshot and its form actions.
+     */
+    inject(): OpencodeGoSectionFace;
+    /**
+     * Write the staged key, then re-read whether the Host now holds one.
+     * @param value - the staged credential literal.
+     * @returns whether the Host reports a configured credential afterwards.
+     */
+    private writeKey;
+}

package/lib/types/client/staged-form.d.ts

@@ -0,0 +1,184 @@
+/**
+ * The staged form behind the OpenCode Go settings page.
+ *
+ * The page stages what the user types and writes it only when they save. Each
+ * settings write is a durable, revision-fenced document mutation, so a control
+ * that committed as it settled turned one edit into a write the user never
+ * asked for and could not preview; staged text makes what is on screen exactly
+ * what a save would store.
+ *
+ * A field shows its effective value — the user layer over the composition
+ * layer over the schema default — and whether the user layer carries it. That
+ * presence, not a value comparison, is what marks a field overridden: an
+ * override equal to the composition default is still an override.
+ *
+ * Copied from the plugin-configuration card form (`ui-settings-plugins`): the
+ * client bundle purity gate forbids importing it across packages, and the two
+ * forms evolve independently anyway.
+ */
+import { type SnapshotStore } from '@deepseek-ai/dsh-client-store';
+import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client';
+/** The write one field's staged text performs when the page is saved. */
+export type FieldWrite = {
+    kind: 'set';
+    value: unknown;
+} | {
+    kind: 'clear';
+};
+/** How one section field converts between its stored value and its draft text. */
+export interface FieldSpec {
+    /** Field name inside the namespace section. */
+    field: string;
+    /** Render a stored value as draft text; the empty string when the section carries none. */
+    format: (value: unknown) => string;
+    /**
+     * The write this draft text stages, or undefined when the text is not a
+     * value this field accepts — which blocks the save rather than discarding it.
+     */
+    parse: (text: string) => FieldWrite | undefined;
+}
+/**
+ * A control whose value is written outside the settings section. A credential
+ * literal never rides a response, so its draft has nothing to seed from: it is
+ * blank until typed, and a blank draft writes nothing.
+ */
+export interface SecretSpec {
+    /** Field name addressing this control inside the page's form. */
+    field: string;
+    /** Write the staged text; resolves to whether the Host accepted it. */
+    write: (text: string) => Promise<boolean>;
+}
+/** One field as the page's control renders it. */
+export interface FieldState {
+    /** Draft text the control renders. */
+    text: string;
+    /**
+     * Whether saving would leave a user-layer entry for this field. A staged
+     * edit answers for itself, so the badge previews the save rather than
+     * reporting a state the pending edit already contradicts.
+     */
+    overridden: boolean;
+    /** Whether the draft is not a value this field accepts, which blocks saving. */
+    invalid: boolean;
+}
+/** Form state the page shell shares across its controls. */
+export interface FormShell {
+    /** False while the namespace is not served to this client; the page renders nothing. */
+    available: boolean;
+    /** Whether the Host document accepts writes. */
+    writable: boolean;
+    /** Whether the form holds edits that a save would write. */
+    dirty: boolean;
+    /** Whether any staged draft is invalid, which blocks the save. */
+    invalid: boolean;
+    /** Whether a save is crossing the wire. */
+    saving: boolean;
+    /** Whether the last save did not land as staged; cleared by the next edit or save. */
+    failed: boolean;
+}
+/** The write actions the page's slot entry injects. */
+export interface FormActions {
+    /** Stage draft text for one field. */
+    edit: (field: string, text: string) => void;
+    /** Stage a clear, so saving lets the field re-inherit the composition layer. */
+    resetField: (field: string) => void;
+    /** Write every staged edit, then re-seed from what the Host accepted. */
+    save: () => void;
+    /** Drop every staged edit. */
+    discard: () => void;
+}
+/**
+ * A whole-number field. An empty draft clears the field; any other draft that
+ * is not a finite number blocks the save.
+ * @param field - field name inside the namespace section.
+ * @returns the field's conversion spec.
+ */
+export declare function numberField(field: string): FieldSpec;
+/**
+ * A two-state field. Unlike the text fields, the draft is the boolean itself
+ * rather than text: the control that renders it reports the state the user
+ * asked for, and an unset section resolves to the composition default the
+ * schema supplied. Its draft text is the state's string form so the shared
+ * override and invalid tracking needs no second branch.
+ * @param field - field name inside the namespace section.
+ * @returns the field's conversion spec.
+ */
+export declare function booleanField(field: string): FieldSpec;
+/**
+ * A free-text field. An empty draft clears the field, so emptying the control
+ * and saving is the same gesture as resetting it.
+ * @param field - field name inside the namespace section.
+ * @returns the field's conversion spec.
+ */
+export declare function textField(field: string): FieldSpec;
+/**
+ * Stages the page's edits over the `llm-opencode-go` namespace and writes them
+ * on save.
+ *
+ * The form publishes through a snapshot store because the slot component reads
+ * through a snapshot selector, while both the scope and the local drafts
+ * change underneath; every projection is rebuilt from the two together.
+ */
+export declare class StagedForm {
+    private readonly scope;
+    private readonly specs;
+    private readonly secretSpecs;
+    private readonly staged;
+    private readonly listeners;
+    private saving;
+    private failed;
+    /**
+     * @param scope - the bound settings scope for this page's namespace.
+     * @param specs - the section fields this page edits.
+     * @param secrets - the page's write-only controls, written outside the section.
+     */
+    constructor(scope: SettingsScope<Record<string, unknown>>, specs: FieldSpec[], secrets?: SecretSpec[]);
+    /**
+     * Publish a projection of this form, rebuilt whenever the scope or a draft changes.
+     * @param project - build the page state from the form's current reads.
+     * @returns the store the component reads through its bound selector.
+     */
+    bind<S>(project: () => S): SnapshotStore<S>;
+    /**
+     * Read the page-level state: what the Host serves, and what a save would do.
+     * @returns the form state the page shell shares.
+     */
+    shell(): FormShell;
+    /**
+     * Read one control's state.
+     * @param field - field name of a section field or of a write-only control.
+     * @returns the draft text, whether a save would leave an override, and whether it is invalid.
+     */
+    field(field: string): FieldState;
+    /**
+     * Build the edit, reset, save, and discard actions bound to this form.
+     * @returns the actions the page's slot entry injects.
+     */
+    actions(): FormActions;
+    /**
+     * Write every staged edit, then re-seed from what the Host accepted.
+     *
+     * The Host is the only authority on whether a value was accepted — its
+     * validators own the constraints no schema can express — so the outcome is
+     * read back from the section rather than predicted here. A save that did not
+     * land keeps its drafts, so the user can correct them instead of retyping.
+     */
+    save(): Promise<void>;
+    /**
+     * Every staged edit a save would write. An entry whose draft is not a value
+     * its field accepts carries no write: the form is still dirty, and the save
+     * refuses rather than dropping the edit.
+     * @returns the planned writes, in the order the fields were staged.
+     */
+    private plan;
+    private clear;
+    private store;
+    private stage;
+    private spec;
+    private snapshotOf;
+    private sectionValue;
+    private baseValue;
+    private userLayer;
+    private stored;
+    private publish;
+}