@nseng-ai/kernel 0.1.2

package/src/sdk/execution.ts

@@ -0,0 +1,67 @@
+import type { ExplicitUndefined } from "@nseng-ai/foundation/primitives";
+
+import type { ClinkrFormat, RenderCapabilities } from "./command.ts";
+import type { NsCommandIo, NsProgress } from "./services.ts";
+import type { TextGenerator } from "./text-generation.ts";
+
+export interface ExecResult {
+	stdout: string;
+	stderr: string;
+	code: number;
+	killed: boolean;
+	startupError?: string;
+}
+
+export interface NsExecOptions {
+	timeoutMs?: number;
+	stdin?: ExplicitUndefined<"public-api-compatibility", string>;
+	onStdout?: ExplicitUndefined<"public-api-compatibility", (text: string) => void>;
+	onStderr?: ExplicitUndefined<"public-api-compatibility", (text: string) => void>;
+}
+
+export type NsOutputStream = "stdout" | "stderr";
+export interface NsConfirmOptions {
+	defaultAnswer?: "yes" | "no";
+}
+
+export type NsConfirmPrompt = (
+	title: string,
+	message: string,
+	options?: NsConfirmOptions,
+) => Promise<boolean> | boolean;
+
+export interface NsExtensionApi {
+	/** Current repository working directory for command-entry execution. */
+	cwd: string;
+	/** Environment visible to ns commands and shell execution. */
+	env: Record<string, string | undefined>;
+	/** Kernel-resolved user home directory for user-scope operations, when available. */
+	homeDir?: string;
+	/** Low-level argv execution hook. Project commands own the exact commands they run. */
+	exec(command: string, args: string[], options?: NsExecOptions): Promise<ExecResult>;
+	/** Text-generation capability; ns commands own prompts, validation, and repair policy. */
+	textGenerator: TextGenerator;
+	/** Higher-level human command-output service provided by the host/kernel. */
+	commandIo: NsCommandIo;
+	/** Structured phase progress sink provided by the host/kernel. */
+	progress: NsProgress;
+	/** Host terminal rendering capabilities for human output and previews. */
+	renderCapabilities: RenderCapabilities;
+	/** Host-selected command output format. Useful only for commands streaming durable output before returning. */
+	outputFormat?: ClinkrFormat;
+	/** Durable output for commands that need to stream multiple chunks before returning. */
+	stdout?: ExplicitUndefined<"public-api-compatibility", (text: string) => void>;
+	/** Durable error output for commands that need to stream multiple chunks before returning. */
+	stderr?: ExplicitUndefined<"public-api-compatibility", (text: string) => void>;
+	/** Optional full stdin reader for commands that consume a finite payload. */
+	stdin?: ExplicitUndefined<"public-api-compatibility", () => Promise<string>>;
+	/** Transient live-progress output for UI bridges. */
+	onOutput?: ExplicitUndefined<
+		"public-api-compatibility",
+		(stream: NsOutputStream, text: string) => void
+	>;
+	/** Optional UI confirmation hook for interactive ns commands. */
+	confirm?: ExplicitUndefined<"public-api-compatibility", NsConfirmPrompt>;
+	/** Project-local extension bag. ns commands own any values they read from it. */
+	extensions?: ExplicitUndefined<"public-api-compatibility", Readonly<Record<string, unknown>>>;
+}

package/src/sdk/extension-manifest.ts

@@ -0,0 +1,38 @@
+import { z } from "./schema.ts";
+
+export const nsExtensionPointAcceptsValues = ["hook", "prompt"] as const;
+export const nsExtensionPointSemanticsValues = ["additive", "override"] as const;
+
+export const nsExtensionManifestCommandSchema = z.looseObject({
+	name: z.string().optional(),
+	path: z.array(z.string()).optional(),
+	group: z.string().optional(),
+	description: z.string().optional(),
+	fullDescription: z.string().optional(),
+	entry: z.string().optional(),
+});
+
+export const nsExtensionManifestPointSchema = z.looseObject({
+	path: z.array(z.string()).optional(),
+	accepts: z.enum(nsExtensionPointAcceptsValues).optional(),
+	semantics: z.enum(nsExtensionPointSemanticsValues).optional(),
+	default: z.string().optional(),
+	description: z.string().optional(),
+});
+
+export const nsExtensionManifestSchema = z.looseObject({
+	description: z.string().optional(),
+	group: z.string().optional(),
+	commands: z.array(z.unknown()).optional(),
+	points: z.array(z.unknown()).optional(),
+});
+
+export const nsExtensionPackageManifestSchema = z.looseObject({
+	description: z.string().optional(),
+	ns: nsExtensionManifestSchema.optional(),
+});
+
+export type NsExtensionManifestCommand = z.infer<typeof nsExtensionManifestCommandSchema>;
+export type NsExtensionManifestPoint = z.infer<typeof nsExtensionManifestPointSchema>;
+export type NsExtensionManifest = z.infer<typeof nsExtensionManifestSchema>;
+export type NsExtensionPackageManifest = z.infer<typeof nsExtensionPackageManifestSchema>;

package/src/sdk/index.ts

@@ -0,0 +1,73 @@
+// Public author API for ns extensions.
+// Keep ts/packages/kernel/docs/sdk-reference.md in sync when changing these exports.
+export { defineExtension } from "./command.ts";
+export {
+	defineRepoLocalNsExtensionDescriptor,
+	repoLocalNsCommandDescriptor,
+} from "./repo-local-ns-extension.ts";
+export {
+	nsExtensionManifestCommandSchema,
+	nsExtensionManifestSchema,
+	nsExtensionPackageManifestSchema,
+} from "./extension-manifest.ts";
+export type {
+	NsExtensionManifest,
+	NsExtensionManifestCommand,
+	NsExtensionPackageManifest,
+} from "./extension-manifest.ts";
+export type {
+	ClinkrCompletionCandidate,
+	ClinkrCompletionResult,
+	ClinkrDynamicCompletionRequest,
+	ClinkrExit,
+	ClinkrFormat,
+	PositionalSpec,
+	RenderCapabilities,
+	NsCommand,
+	NsCommandCompletionProvider,
+	NsCommandRequest,
+	NsCommandSchema,
+	NsExtension,
+} from "./command.ts";
+export type {
+	RepoLocalNsCommandDescriptorOptions,
+	RepoLocalNsExtensionCommandDescriptor,
+	RepoLocalNsExtensionDescriptor,
+} from "./repo-local-ns-extension.ts";
+export type {
+	ExecResult,
+	NsConfirmOptions,
+	NsConfirmPrompt,
+	NsExecOptions,
+	NsExtensionApi,
+	NsOutputStream,
+} from "./execution.ts";
+export {
+	normalizeTextOutput,
+	stripOuterCodeFence,
+	trimOuterBlankLines,
+} from "@nseng-ai/foundation/text-normalization";
+export { truncateTextHead, truncateTextHeadTail } from "@nseng-ai/foundation/text-truncation";
+export type {
+	HeadTailTextTruncationOptions,
+	HeadTextTruncationOptions,
+} from "@nseng-ai/foundation/text-truncation";
+export { failed, ok } from "./result.ts";
+export type { NsResult } from "./result.ts";
+export { noopNsCommandIo, noopNsProgress } from "./services.ts";
+export type {
+	NsCommandIo,
+	NsCommandMessageOptions,
+	NsNotifyLevel,
+	NsProgress,
+	NsProgressPhaseEvent,
+	NsProgressPhaseInfo,
+	NsProgressPhaseListener,
+} from "./services.ts";
+export { z } from "./schema.ts";
+export type {
+	TextGenerationRequest,
+	TextGenerationResult,
+	TextGenerationUsage,
+	TextGenerator,
+} from "./text-generation.ts";

package/src/sdk/progress-phase-state.ts

@@ -0,0 +1,352 @@
+import type { NsProgressPhaseEvent, NsProgressPhaseInfo } from "./services.ts";
+
+export type ProgressPhaseState = "pending" | "active" | "done" | "skipped" | "failed";
+
+export interface ProgressPhaseSpec extends NsProgressPhaseInfo {
+	readonly substeps?: readonly ProgressPhaseSpec[];
+}
+
+export interface ProgressPhaseView {
+	readonly key: string;
+	readonly name: string;
+	readonly detail?: string;
+	readonly state: ProgressPhaseState;
+	readonly label: string | undefined;
+	readonly history: readonly string[];
+	readonly substeps: readonly ProgressPhaseView[];
+}
+
+export type ProgressPhaseUnknownKeyPolicy = "ignore" | "append";
+
+export interface ProgressPhaseStateStoreOptions {
+	readonly phases?: readonly ProgressPhaseSpec[];
+	readonly unknownKeyPolicy?: ProgressPhaseUnknownKeyPolicy;
+}
+
+export interface ProgressPhaseStateStore {
+	views(): readonly ProgressPhaseView[];
+	title(): string | undefined;
+	apply(event: NsProgressPhaseEvent): ProgressPhaseView | undefined;
+	failActive(): void;
+	settleOpenPhases(): void;
+}
+
+interface PhaseRecord {
+	spec: ProgressPhaseSpec;
+	runtimeDetail: string | undefined;
+	state: ProgressPhaseState;
+	label: string | undefined;
+	history: string[];
+	substeps: PhaseRecord[];
+}
+
+type PhaseLocation =
+	| { type: "top"; index: number }
+	| { type: "substep"; parentIndex: number; index: number };
+
+export function createProgressPhaseStateStore(
+	options: ProgressPhaseStateStoreOptions = {},
+): ProgressPhaseStateStore {
+	const unknownKeyPolicy = options.unknownKeyPolicy ?? "ignore";
+	let records = (options.phases ?? []).map(createRecord);
+	let indexByKey = indexRecords(records);
+	let activeLocation: PhaseLocation | undefined;
+	let currentTitle: string | undefined;
+
+	function views(): readonly ProgressPhaseView[] {
+		return records.map(viewForRecord);
+	}
+
+	function title(): string | undefined {
+		return currentTitle;
+	}
+
+	function apply(event: NsProgressPhaseEvent): ProgressPhaseView | undefined {
+		switch (event.type) {
+			case "phases-declared":
+				currentTitle = event.title;
+				records = event.phases.map(createRecord);
+				indexByKey = indexRecords(records);
+				activeLocation = undefined;
+				return undefined;
+			case "title-changed":
+				currentTitle = event.title;
+				return undefined;
+			case "phase-started":
+				return applyStarted(event.phaseKey, event.label);
+			case "phase-progress":
+				return applyProgress(event.phaseKey, event.label);
+			case "phase-done":
+				return applyDone(event.phaseKey, event.detail);
+			case "phase-failed":
+				return applyFailed(event.phaseKey, event.detail);
+		}
+	}
+
+	function applyStarted(
+		phaseKey: string,
+		label: string | undefined,
+	): ProgressPhaseView | undefined {
+		return updateRecord(phaseKey, {
+			prepare: setActive,
+			update: (record) => withLabel(record, label ?? record.spec.label),
+		});
+	}
+
+	function applyProgress(phaseKey: string, label: string): ProgressPhaseView | undefined {
+		return updateRecord(phaseKey, {
+			prepare: ensureProgressTargetActive,
+			update: (record) => withLabel(record, label),
+		});
+	}
+
+	function applyDone(phaseKey: string, detail: string | undefined): ProgressPhaseView | undefined {
+		return updateRecord(phaseKey, { update: (record) => completeRecord(record, detail) });
+	}
+
+	function applyFailed(phaseKey: string, detail: string): ProgressPhaseView | undefined {
+		return updateRecord(phaseKey, {
+			update: (record) => withLabel(record, detail, { state: "failed" }),
+			after: failParentForSubstep,
+		});
+	}
+
+	function updateRecord(
+		phaseKey: string,
+		options: {
+			prepare?(location: PhaseLocation): void;
+			update(record: PhaseRecord): PhaseRecord;
+			after?(location: PhaseLocation): void;
+		},
+	): ProgressPhaseView | undefined {
+		const location = ensureLocation(phaseKey);
+		if (location === undefined) return undefined;
+		options.prepare?.(location);
+		const record = recordAt(location);
+		if (record === undefined) return undefined;
+		const nextRecord = options.update(record);
+		replaceRecord(location, nextRecord);
+		options.after?.(location);
+		return viewForRecord(nextRecord);
+	}
+
+	function ensureLocation(phaseKey: string): PhaseLocation | undefined {
+		const existing = indexByKey.get(phaseKey);
+		if (existing !== undefined) return existing;
+		if (unknownKeyPolicy === "ignore") return undefined;
+		const record = createRecord({ key: phaseKey, name: phaseKey });
+		records = [...records, record];
+		const location = { type: "top", index: records.length - 1 } satisfies PhaseLocation;
+		indexByKey = indexRecords(records);
+		return location;
+	}
+
+	function recordAt(location: PhaseLocation): PhaseRecord | undefined {
+		if (location.type === "top") return records[location.index];
+		return records[location.parentIndex]?.substeps[location.index];
+	}
+
+	function replaceRecord(location: PhaseLocation, record: PhaseRecord): void {
+		if (location.type === "top") {
+			records = replaceAt(records, location.index, record);
+			return;
+		}
+		const parent = records[location.parentIndex];
+		if (parent === undefined) return;
+		records = replaceAt(records, location.parentIndex, {
+			...parent,
+			substeps: replaceAt(parent.substeps, location.index, record),
+		});
+	}
+
+	function setActive(location: PhaseLocation): void {
+		if (location.type === "top") {
+			records = markEarlierDone(records, location.index);
+			const record = recordAt(location);
+			if (record !== undefined) replaceRecord(location, { ...record, state: "active" });
+		} else {
+			activateSubstep(location);
+		}
+		activeLocation = location;
+	}
+
+	function activateSubstep(location: Extract<PhaseLocation, { type: "substep" }>): void {
+		const parent = activateParentForSubstep(location);
+		if (parent === undefined) return;
+		const substeps = markEarlierDone(parent.substeps, location.index);
+		const substep = substeps[location.index];
+		const nextSubsteps =
+			substep === undefined
+				? substeps
+				: replaceAt(substeps, location.index, {
+						...substep,
+						state: "active",
+					} satisfies PhaseRecord);
+		records = replaceAt(records, location.parentIndex, {
+			...parent,
+			substeps: nextSubsteps,
+		} satisfies PhaseRecord);
+	}
+
+	function activateParentForSubstep(
+		location: Extract<PhaseLocation, { type: "substep" }>,
+	): PhaseRecord | undefined {
+		records = markEarlierDone(records, location.parentIndex);
+		const parent = records[location.parentIndex];
+		if (parent === undefined) return undefined;
+		const activeParent = { ...parent, state: "active" } satisfies PhaseRecord;
+		records = replaceAt(records, location.parentIndex, activeParent);
+		return activeParent;
+	}
+
+	function ensureProgressTargetActive(location: PhaseLocation): void {
+		const record = recordAt(location);
+		if (record?.state === "pending") {
+			setActive(location);
+			return;
+		}
+		if (location.type === "top") return;
+		if (record?.state === "active") {
+			activateParentForSubstep(location);
+			activeLocation = location;
+		}
+	}
+
+	function failActive(): void {
+		if (activeLocation === undefined) return;
+		const record = recordAt(activeLocation);
+		if (record === undefined) return;
+		replaceRecord(activeLocation, { ...record, state: "failed" });
+		failParentForSubstep(activeLocation);
+	}
+
+	function settleOpenPhases(): void {
+		const hasFailure = records.some(
+			(record) =>
+				record.state === "failed" || record.substeps.some((substep) => substep.state === "failed"),
+		);
+		if (hasFailure) return;
+		records = records.map((record) => {
+			if (record.state === "pending" || record.state === "active") return setDone(record);
+			return record;
+		});
+	}
+
+	function failParentForSubstep(location: PhaseLocation): void {
+		if (location.type === "top") return;
+		const parent = records[location.parentIndex];
+		if (parent !== undefined) {
+			records = replaceAt(records, location.parentIndex, { ...parent, state: "failed" });
+		}
+	}
+
+	return { views, title, apply, failActive, settleOpenPhases };
+}
+
+function createRecord(spec: ProgressPhaseSpec): PhaseRecord {
+	return {
+		spec: copySpec(spec),
+		runtimeDetail: undefined,
+		state: "pending",
+		label: spec.label,
+		history: [],
+		substeps: spec.substeps?.map(createRecord) ?? [],
+	};
+}
+
+function copySpec(spec: ProgressPhaseSpec): ProgressPhaseSpec {
+	return {
+		key: spec.key,
+		name: spec.name,
+		...(spec.label === undefined ? {} : { label: spec.label }),
+		...(spec.detail === undefined ? {} : { detail: spec.detail }),
+		...(spec.substeps === undefined ? {} : { substeps: spec.substeps.map(copySpec) }),
+	};
+}
+
+function viewForRecord(record: PhaseRecord): ProgressPhaseView {
+	const detail = detailForRecord(record);
+	return {
+		key: record.spec.key,
+		name: record.spec.name,
+		...(detail === undefined ? {} : { detail }),
+		state: record.state,
+		label: record.label,
+		history: record.history.slice(),
+		substeps: record.substeps.map(viewForRecord),
+	};
+}
+
+function indexRecords(records: readonly PhaseRecord[]): Map<string, PhaseLocation> {
+	const indexByKey = new Map<string, PhaseLocation>();
+	records.forEach((record, index) => {
+		indexByKey.set(record.spec.key, { type: "top", index });
+		record.substeps.forEach((substep, substepIndex) => {
+			indexByKey.set(substep.spec.key, {
+				type: "substep",
+				parentIndex: index,
+				index: substepIndex,
+			});
+		});
+	});
+	return indexByKey;
+}
+
+function replaceAt<T>(items: readonly T[], index: number, item: T): T[] {
+	return items.map((current, currentIndex) => (currentIndex === index ? item : current));
+}
+
+function withLabel(
+	record: PhaseRecord,
+	nextLabel: string | undefined,
+	extra: Partial<PhaseRecord> = {},
+): PhaseRecord {
+	return { ...withSupersededLabel(record, nextLabel), label: nextLabel, ...extra };
+}
+
+function withSupersededLabel(record: PhaseRecord, nextLabel: string | undefined): PhaseRecord {
+	const previous = record.label;
+	if (previous === undefined || previous === nextLabel) return record;
+	return { ...record, history: [...record.history, previous] };
+}
+
+function detailForRecord(record: PhaseRecord): string | undefined {
+	return record.runtimeDetail ?? record.spec.detail;
+}
+
+function settleSubstepsDone(parent: PhaseRecord): PhaseRecord {
+	return {
+		...parent,
+		substeps: parent.substeps.map((substep) => {
+			if (substep.state === "active") {
+				return { ...withSupersededLabel(substep, detailForRecord(substep)), state: "done" };
+			}
+			if (substep.state === "pending") return { ...substep, state: "skipped" };
+			return substep;
+		}),
+	};
+}
+
+function setDone(record: PhaseRecord): PhaseRecord {
+	const labeled =
+		record.state === "active" ? withSupersededLabel(record, detailForRecord(record)) : record;
+	return settleSubstepsDone({ ...labeled, state: "done" });
+}
+
+function completeRecord(record: PhaseRecord, detail: string | undefined): PhaseRecord {
+	const settledDetail = detail ?? detailForRecord(record);
+	return settleSubstepsDone({
+		...withSupersededLabel(record, settledDetail),
+		runtimeDetail: detail ?? record.runtimeDetail,
+		state: "done",
+		label: settledDetail ?? record.label,
+	});
+}
+
+function markEarlierDone(items: readonly PhaseRecord[], index: number): PhaseRecord[] {
+	return items.map((record, itemIndex) => {
+		if (itemIndex >= index) return record;
+		if (record.state === "pending" || record.state === "active") return setDone(record);
+		return record;
+	});
+}

package/src/sdk/repo-local-ns-extension.ts

@@ -0,0 +1,41 @@
+import type { NsCommand } from "./command.ts";
+
+export interface RepoLocalNsExtensionCommandDescriptor {
+	readonly command: NsCommand;
+	readonly manifestEntry: string;
+	readonly packageExport: string;
+	readonly manifestPath?: readonly string[];
+	readonly manifestName?: string;
+}
+
+export interface RepoLocalNsExtensionDescriptor {
+	readonly group: string;
+	readonly description: string;
+	readonly commands: readonly RepoLocalNsExtensionCommandDescriptor[];
+}
+
+export interface RepoLocalNsCommandDescriptorOptions {
+	readonly command: NsCommand;
+	readonly packageExportPrefix: string;
+	readonly manifestPath?: readonly string[];
+	readonly manifestName?: string;
+}
+
+export function repoLocalNsCommandDescriptor(
+	options: RepoLocalNsCommandDescriptorOptions,
+): RepoLocalNsExtensionCommandDescriptor {
+	const manifestName = options.manifestName ?? options.command.name;
+	return {
+		command: options.command,
+		...(options.manifestName === undefined ? {} : { manifestName }),
+		...(options.manifestPath === undefined ? {} : { manifestPath: options.manifestPath }),
+		manifestEntry: `./src/commands/${manifestName}.ts`,
+		packageExport: `${options.packageExportPrefix}/${manifestName}`,
+	};
+}
+
+export function defineRepoLocalNsExtensionDescriptor(
+	descriptor: RepoLocalNsExtensionDescriptor,
+): RepoLocalNsExtensionDescriptor {
+	return descriptor;
+}

package/src/sdk/result.ts

@@ -0,0 +1,11 @@
+export type NsResult =
+	| { ok: true; message: string }
+	| { ok: false; exitCode: number; message: string };
+
+export function ok(message: string): NsResult {
+	return { ok: true, message };
+}
+
+export function failed(message: string, exitCode = 1): NsResult {
+	return { ok: false, exitCode, message };
+}

package/src/sdk/schema.ts

@@ -0,0 +1,3 @@
+import { z } from "zod";
+
+export { z };

package/src/sdk/services.ts

@@ -0,0 +1,68 @@
+export type NsNotifyLevel = "info" | "warning" | "error";
+
+export interface NsCommandMessageOptions {
+	/** Notification level for text-only fallback sinks. Defaults to "info". */
+	level?: NsNotifyLevel;
+	/**
+	 * Opaque structured presentation payload for rich sinks (e.g. a Pi custom
+	 * scrollback message's `details`). The SDK never inspects this value.
+	 */
+	details?: unknown;
+	/**
+	 * When true, emit only to a rich sink. Text-only sinks drop the message.
+	 * Use for content already delivered through another durable channel (e.g. a
+	 * CLI summary printed via notify) so it is not duplicated in fallback output.
+	 */
+	isRichOnly?: boolean;
+}
+
+export interface NsCommandIo {
+	/** Transient, human-facing phase text. Non-contractual wording; never stdout in machine mode. */
+	phase(message: string): void;
+	/** Terminal human notification (success/warning/error). */
+	notify(message: string, level?: NsNotifyLevel): void;
+	/**
+	 * Durable, human-facing scrollback message. Rich sinks (e.g. Pi custom
+	 * messages) receive `details`; text-only sinks render the message as transient
+	 * phase text, or drop it entirely when `isRichOnly` is set.
+	 */
+	message(message: string, options?: NsCommandMessageOptions): void;
+	/** Clears any sticky transient phase (no-op for append-only sinks). */
+	clearPhase(): void;
+}
+
+export const noopNsCommandIo: NsCommandIo = {
+	phase: () => {},
+	notify: () => {},
+	message: () => {},
+	clearPhase: () => {},
+};
+
+/** Presentation metadata for a declared phase checklist. */
+export interface NsProgressPhaseInfo {
+	key: string;
+	name: string;
+	label?: string;
+	detail?: string;
+}
+
+export type NsProgressPhaseEvent =
+	| { type: "phases-declared"; title: string; phases: readonly NsProgressPhaseInfo[] }
+	| { type: "title-changed"; title: string }
+	| { type: "phase-started"; phaseKey: string; label?: string }
+	| { type: "phase-progress"; phaseKey: string; label: string }
+	| { type: "phase-done"; phaseKey: string; detail?: string }
+	| { type: "phase-failed"; phaseKey: string; detail: string };
+
+export type NsProgressPhaseListener = (event: NsProgressPhaseEvent) => void;
+
+export interface NsProgress {
+	/** True when a host listener consumes phase events; false for the noop sink. */
+	readonly isLive: boolean;
+	phase(event: NsProgressPhaseEvent): void;
+}
+
+export const noopNsProgress: NsProgress = {
+	isLive: false,
+	phase: () => {},
+};

package/src/sdk/text-generation.ts

@@ -0,0 +1,21 @@
+export interface TextGenerationRequest {
+	modelRef: string;
+	system: string;
+	prompt: string;
+	maxTokens?: number;
+	reasoning?: "minimal" | "low";
+	operation?: string;
+}
+
+export interface TextGenerationUsage {
+	inputTokens: number;
+	outputTokens: number;
+}
+
+export type TextGenerationResult =
+	| { ok: true; text: string; usage?: TextGenerationUsage }
+	| { ok: false; error: string };
+
+export interface TextGenerator {
+	generateText(request: TextGenerationRequest): Promise<TextGenerationResult>;
+}