@nseng-ai/kernel 0.1.2

package/src/runtime/command-io.ts

@@ -0,0 +1,149 @@
+import { optionalEntries, optionalEntry } from "@nseng-ai/foundation/primitives";
+import type {
+	NsCommandIo,
+	NsCommandMessageOptions,
+	NsExtensionApi,
+	NsNotifyLevel,
+	NsOutputStream,
+} from "../sdk/index.ts";
+
+export interface NsExtensionCommandIoOptions {
+	statusKey?: string;
+	shouldSuppress?: boolean;
+}
+
+export interface CliCommandIoInput {
+	stdout?: (text: string) => void;
+	stderr?: (text: string) => void;
+	onOutput?: (stream: NsOutputStream, text: string) => void;
+}
+
+export interface CliCommandIoOptions {
+	/** Invoked once per error-level notification, e.g. to flip a CLI exit flag. */
+	onNotifyError?: () => void;
+	/** Suppress transient phase and info notifications for structured output modes. */
+	shouldSuppress?: boolean;
+}
+
+export interface CommandIoChannels {
+	/** Preferred transient phase sink (e.g. live widget). */
+	phaseTransient?: (text: string) => void;
+	/** Sticky phase sink that must be cleared (e.g. Pi setStatus); receives undefined to clear. */
+	phaseSticky?: (value: string | undefined) => void;
+	/** Durable fallback for phase when no transient/sticky channel exists (e.g. stderr). */
+	phaseFallback?: (text: string) => void;
+	/** Notification sink for informational messages. */
+	notifyInfo?: (text: string) => void;
+	/** Notification sink for warning/error messages. */
+	notifyDiagnostic?: (text: string) => void;
+	/** Notification via Pi UI (level-aware), when present. */
+	notifyUi?: (message: string, level?: NsNotifyLevel) => void;
+	/**
+	 * Rich scrollback sink that renders durable messages and can carry opaque
+	 * structured presentation details (e.g. a Pi custom message). When absent,
+	 * `message` falls back to transient phase text (or is dropped when isRichOnly).
+	 */
+	richMessage?: (message: string, options: { level: NsNotifyLevel; details?: unknown }) => void;
+	/** Suppress transient phase entirely (machine/structured output). */
+	shouldSuppress?: boolean;
+}
+
+export { noopNsCommandIo, noopNsProgress } from "../sdk/index.ts";
+
+export async function runWithNsCommandIo<T>(
+	io: NsCommandIo,
+	fn: (io: NsCommandIo) => Promise<T>,
+): Promise<T> {
+	try {
+		return await fn(io);
+	} finally {
+		io.clearPhase();
+	}
+}
+
+export function createCliCommandIo(
+	input: CliCommandIoInput,
+	options: CliCommandIoOptions = {},
+): NsCommandIo {
+	const onOutput = input.onOutput;
+	const io = createCommandIo({
+		...optionalEntries({
+			phaseTransient:
+				onOutput === undefined ? undefined : (text: string) => onOutput("stderr", text),
+			phaseFallback: input.stderr,
+			notifyInfo: input.stdout,
+			notifyDiagnostic: input.stderr,
+			shouldSuppress: options.shouldSuppress,
+		}),
+	});
+
+	const onNotifyError = options.onNotifyError;
+	if (onNotifyError === undefined) return io;
+
+	return {
+		...io,
+		notify: (message, level = "info") => {
+			if (level === "error") onNotifyError();
+			io.notify(message, level);
+		},
+	};
+}
+
+export function createCommandIo(channels: CommandIoChannels): NsCommandIo {
+	function phase(message: string): void {
+		if (channels.shouldSuppress === true) return;
+		if (channels.phaseSticky !== undefined) {
+			channels.phaseSticky(message);
+			return;
+		}
+		const line = `${message}\n`;
+		if (channels.phaseTransient !== undefined) {
+			channels.phaseTransient(line);
+			return;
+		}
+		channels.phaseFallback?.(line);
+	}
+
+	function notify(message: string, level: NsNotifyLevel = "info"): void {
+		if (channels.notifyUi !== undefined) {
+			channels.notifyUi(message, level);
+			return;
+		}
+		const line = `${message.trimEnd()}\n`;
+		if (level === "info" && channels.shouldSuppress !== true) {
+			channels.notifyInfo?.(line);
+			return;
+		}
+		channels.notifyDiagnostic?.(line);
+	}
+
+	function message(text: string, options: NsCommandMessageOptions = {}): void {
+		const level = options.level ?? "info";
+		if (channels.richMessage !== undefined) {
+			channels.richMessage(text, {
+				level,
+				...optionalEntry("details", options.details),
+			});
+			return;
+		}
+		if (options.isRichOnly === true) return;
+		phase(text);
+	}
+
+	function clearPhase(): void {
+		channels.phaseSticky?.(undefined);
+	}
+
+	return { phase, notify, message, clearPhase };
+}
+
+export function commandIoFromNsExtensionApi(
+	ctx: NsExtensionApi,
+	options: NsExtensionCommandIoOptions = {},
+): NsCommandIo {
+	if (options.shouldSuppress === undefined) return ctx.commandIo;
+	return createCliCommandIo(
+		optionalEntries({ stdout: ctx.stdout, stderr: ctx.stderr, onOutput: ctx.onOutput }),
+		{ shouldSuppress: options.shouldSuppress },
+	);
+}

package/src/runtime/diagnostics.ts

@@ -0,0 +1,35 @@
+import { optionalEntry } from "@nseng-ai/foundation/primitives";
+
+export type KernelDiagnosticSeverity = "error" | "info";
+
+export interface KernelDiagnosticBase {
+	severity: KernelDiagnosticSeverity;
+	code: string;
+	message: string;
+	path?: string;
+}
+
+interface KernelDiagnosticRequest<TExtra extends object> {
+	code: string;
+	message: string;
+	path?: string;
+	extra?: TExtra;
+}
+
+export function makeKernelDiagnostic<TExtra extends object = Record<never, never>>(
+	request: KernelDiagnosticRequest<TExtra>,
+): (KernelDiagnosticBase & { severity: "error" }) & TExtra;
+export function makeKernelDiagnostic<TExtra extends object = Record<never, never>>(
+	request: KernelDiagnosticRequest<TExtra> & { severity: "info" },
+): (KernelDiagnosticBase & { severity: "info" }) & TExtra;
+export function makeKernelDiagnostic<TExtra extends object = Record<never, never>>(
+	request: KernelDiagnosticRequest<TExtra> & { severity?: KernelDiagnosticSeverity },
+): KernelDiagnosticBase & TExtra {
+	const base = {
+		severity: request.severity ?? "error",
+		code: request.code,
+		message: request.message,
+		...optionalEntry("path", request.path),
+	};
+	return { ...base, ...(request.extra ?? {}) } as KernelDiagnosticBase & TExtra;
+}

package/src/runtime/extension-root-discovery.ts

@@ -0,0 +1,118 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+import { formatErrorMessage, optionalEntry } from "@nseng-ai/foundation/primitives";
+
+import { makeKernelDiagnostic } from "./diagnostics.ts";
+
+export interface ExtensionRootScanDiagnostic {
+	severity: "error";
+	code: string;
+	message: string;
+	path?: string;
+}
+
+export type ExtensionRootEntry =
+	| { type: "file"; name: string; path: string }
+	| {
+			type: "directory";
+			name: string;
+			path: string;
+			packageJsonPath?: string;
+			indexPath?: string;
+	  };
+
+export interface ExtensionRootScanResult {
+	entries: readonly ExtensionRootEntry[];
+	diagnostics: readonly ExtensionRootScanDiagnostic[];
+}
+
+export function scanExtensionRoot(rootDir: string): ExtensionRootScanResult {
+	if (!existsSync(rootDir)) return { entries: [], diagnostics: [] };
+
+	let isDirectory: boolean;
+	try {
+		isDirectory = statSync(rootDir).isDirectory();
+	} catch (error) {
+		return {
+			entries: [],
+			diagnostics: [
+				diagnostic(
+					"extension_root_stat_failed",
+					`Could not inspect extension root ${rootDir}.\n${formatErrorMessage(error)}`,
+					{ path: rootDir },
+				),
+			],
+		};
+	}
+	if (!isDirectory) {
+		return {
+			entries: [],
+			diagnostics: [
+				diagnostic(
+					"extension_root_not_directory",
+					`Extension root must be a directory: ${rootDir}.`,
+					{
+						path: rootDir,
+					},
+				),
+			],
+		};
+	}
+
+	let dirents;
+	try {
+		dirents = readdirSync(rootDir, { withFileTypes: true });
+	} catch (error) {
+		return {
+			entries: [],
+			diagnostics: [
+				diagnostic(
+					"extension_root_read_failed",
+					`Could not read extension root ${rootDir}.\n${formatErrorMessage(error)}`,
+					{ path: rootDir },
+				),
+			],
+		};
+	}
+
+	const entries: ExtensionRootEntry[] = [];
+	for (const dirent of dirents.sort((left, right) => left.name.localeCompare(right.name))) {
+		const entryPath = join(rootDir, dirent.name);
+		if (dirent.isFile()) {
+			entries.push({ type: "file", name: dirent.name, path: entryPath });
+			continue;
+		}
+		if (!dirent.isDirectory()) continue;
+
+		const packageJsonPath = join(entryPath, "package.json");
+		if (existsSync(packageJsonPath)) {
+			entries.push({ type: "directory", name: dirent.name, path: entryPath, packageJsonPath });
+			continue;
+		}
+		const indexPath = firstExistingDirectoryIndex(entryPath);
+		entries.push({
+			type: "directory",
+			name: dirent.name,
+			path: entryPath,
+			...(indexPath === undefined ? {} : { indexPath }),
+		});
+	}
+	return { entries, diagnostics: [] };
+}
+
+function firstExistingDirectoryIndex(entryPath: string): string | undefined {
+	for (const indexFileName of ["index.ts", "index.js"] as const) {
+		const indexPath = join(entryPath, indexFileName);
+		if (existsSync(indexPath)) return indexPath;
+	}
+	return undefined;
+}
+
+function diagnostic(
+	code: string,
+	message: string,
+	options: { path?: string } = {},
+): ExtensionRootScanDiagnostic {
+	return makeKernelDiagnostic({ code, message, ...optionalEntry("path", options.path) });
+}

package/src/runtime/module-import.ts

@@ -0,0 +1,4 @@
+export async function importDefaultExport(specifier: string): Promise<unknown> {
+	const module = (await import(specifier)) as { default?: unknown };
+	return module.default;
+}

package/src/runtime/module-loader.ts

@@ -0,0 +1,75 @@
+import { createJiti } from "jiti/static";
+
+import {
+	defineExtension,
+	defineRepoLocalNsExtensionDescriptor,
+	failed,
+	noopNsCommandIo,
+	repoLocalNsCommandDescriptor,
+	noopNsProgress,
+	normalizeTextOutput,
+	ok,
+	nsExtensionManifestCommandSchema,
+	nsExtensionManifestSchema,
+	nsExtensionPackageManifestSchema,
+	stripOuterCodeFence,
+	trimOuterBlankLines,
+	truncateTextHead,
+	truncateTextHeadTail,
+	z,
+} from "../sdk/index.ts";
+
+/** Module specifier that ns command entries import the SDK from. */
+const SDK_SPECIFIER = "@nseng-ai/kernel/sdk";
+
+// Keep this object in sync with all runtime value exports from @nseng-ai/kernel/sdk; type-only exports are erased.
+// Descriptor helpers are test-authoring-only today, but stay here while they are runtime exports.
+const nsSdkVirtualModule = {
+	defineExtension,
+	defineRepoLocalNsExtensionDescriptor,
+	failed,
+	noopNsCommandIo,
+	repoLocalNsCommandDescriptor,
+	noopNsProgress,
+	normalizeTextOutput,
+	ok,
+	nsExtensionManifestCommandSchema,
+	nsExtensionManifestSchema,
+	nsExtensionPackageManifestSchema,
+	stripOuterCodeFence,
+	trimOuterBlankLines,
+	truncateTextHead,
+	truncateTextHeadTail,
+	z,
+} satisfies Record<string, unknown>;
+
+/**
+ * Create the ns-aware jiti instance used for user-authored modules.
+ *
+ * The load-bearing option is `virtualModules`: it binds `@nseng-ai/kernel/sdk` to the
+ * exact SDK object imported by this process, so command-entry commands and
+ * schemas share host SDK identity instead of resolving dependency copies from
+ * `.ns/extensions`.
+ *
+ * First-party bundled commands are loaded by package module specifier through
+ * the selected-command loader instead of through source-checkout aliases here.
+ */
+export function createNsJiti(): ReturnType<typeof createJiti> {
+	return createJiti(import.meta.url, {
+		moduleCache: false,
+		virtualModules: {
+			[SDK_SPECIFIER]: nsSdkVirtualModule,
+		},
+	});
+}
+
+/**
+ * Load the default export of a TypeScript or JavaScript ns user module.
+ *
+ * Callers validate the returned value according to the command-entry contract.
+ * Throws when the file cannot be transpiled or imported.
+ */
+export async function loadNsUserModuleDefault(modulePath: string): Promise<unknown> {
+	const jiti = createNsJiti();
+	return jiti.import(modulePath, { default: true });
+}

package/src/runtime/pi-text-generation.ts

@@ -0,0 +1,162 @@
+import type { Api, completeSimple, Model } from "@earendil-works/pi-ai";
+
+import { formatErrorMessage } from "@nseng-ai/foundation/primitives";
+
+import type {
+	TextGenerationRequest,
+	TextGenerationResult,
+	TextGenerationUsage,
+	TextGenerator,
+} from "../sdk/index.ts";
+
+const DEFAULT_MAX_TOKENS = 512;
+const DEFAULT_REASONING = "low";
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+type CompleteSimpleFunction = typeof completeSimple;
+
+type ModelAuth =
+	| { ok: true; apiKey?: string; headers?: Record<string, string> }
+	| { ok: false; error: string };
+
+export interface PiModelRegistry {
+	find(provider: string, modelId: string): Model<Api> | undefined;
+	getApiKeyAndHeaders(model: Model<Api>): Promise<ModelAuth>;
+}
+
+export interface PiTextGeneratorOptions {
+	modelRegistry?: PiModelRegistry;
+	completeSimple?: CompleteSimpleFunction;
+	loadDefaultModelRegistry?: () => Promise<PiModelRegistry>;
+}
+
+export class PiTextGenerator implements TextGenerator {
+	private readonly modelRegistry: PiModelRegistry | undefined;
+	private readonly completeSimple: CompleteSimpleFunction | undefined;
+	private readonly loadDefaultModelRegistry: () => Promise<PiModelRegistry>;
+
+	constructor(options: PiTextGeneratorOptions = {}) {
+		this.modelRegistry = options.modelRegistry;
+		this.completeSimple = options.completeSimple;
+		this.loadDefaultModelRegistry = options.loadDefaultModelRegistry ?? loadDefaultModelRegistry;
+	}
+
+	async generateText(request: TextGenerationRequest): Promise<TextGenerationResult> {
+		const parsed = parsePiModelRef(request.modelRef);
+		if (!parsed.ok) {
+			return { ok: false, error: parsed.error };
+		}
+
+		const modelRegistry = this.modelRegistry ?? (await this.loadDefaultModelRegistry());
+		const model = modelRegistry.find(parsed.provider, parsed.modelId);
+		if (model === undefined) {
+			return { ok: false, error: `Could not find Pi model ${request.modelRef}.` };
+		}
+
+		const auth = await modelRegistry.getApiKeyAndHeaders(model);
+		if (!auth.ok) {
+			return { ok: false, error: `Pi auth failed for ${request.modelRef}: ${auth.error}` };
+		}
+		if (!auth.apiKey) {
+			return {
+				ok: false,
+				error: `No Pi auth found for ${parsed.provider}. Run /login or configure Pi auth.`,
+			};
+		}
+
+		try {
+			const completeSimple = this.completeSimple ?? (await loadCompleteSimple());
+			const response = await completeSimple(
+				model,
+				{
+					systemPrompt: request.system,
+					messages: [
+						{
+							role: "user",
+							content: [{ type: "text", text: request.prompt }],
+							timestamp: Date.now(),
+						},
+					],
+				},
+				{
+					...(auth.headers === undefined ? {} : { headers: auth.headers }),
+					apiKey: auth.apiKey,
+					maxTokens: request.maxTokens ?? DEFAULT_MAX_TOKENS,
+					reasoning: request.reasoning ?? DEFAULT_REASONING,
+					timeoutMs: DEFAULT_TIMEOUT_MS,
+				},
+			);
+
+			if (response.stopReason === "error" || response.stopReason === "aborted") {
+				return {
+					ok: false,
+					error: `Pi model ${request.modelRef} failed to generate text: ${response.errorMessage ?? response.stopReason}`,
+				};
+			}
+
+			const text = response.content
+				.filter(
+					(content): content is { type: "text"; text: string } =>
+						content.type === "text" && typeof content.text === "string",
+				)
+				.map((content) => content.text)
+				.join("\n");
+			if (text.trim().length === 0) {
+				return { ok: false, error: `Pi model ${request.modelRef} returned empty text.` };
+			}
+
+			const usage = textGenerationUsageFromResponse(response.usage);
+			return {
+				ok: true,
+				text,
+				...(usage === undefined ? {} : { usage }),
+			};
+		} catch (error) {
+			return {
+				ok: false,
+				error: `Pi model ${request.modelRef} failed to generate text: ${formatErrorMessage(error)}`,
+			};
+		}
+	}
+}
+
+function textGenerationUsageFromResponse(usage: {
+	input: number;
+	output: number;
+}): TextGenerationUsage | undefined {
+	if (!Number.isFinite(usage.input) || !Number.isFinite(usage.output)) return undefined;
+	return {
+		inputTokens: usage.input,
+		outputTokens: usage.output,
+	};
+}
+
+type ParsedPiModelRef =
+	| { ok: true; provider: string; modelId: string }
+	| { ok: false; error: string };
+
+function parsePiModelRef(modelRef: string): ParsedPiModelRef {
+	const separator = modelRef.indexOf("/");
+	if (separator <= 0 || separator === modelRef.length - 1) {
+		return {
+			ok: false,
+			error: `Invalid Pi model reference ${JSON.stringify(modelRef)}. Expected provider/model-id.`,
+		};
+	}
+
+	return {
+		ok: true,
+		provider: modelRef.slice(0, separator),
+		modelId: modelRef.slice(separator + 1),
+	};
+}
+
+async function loadCompleteSimple(): Promise<CompleteSimpleFunction> {
+	const piAi = await import("@earendil-works/pi-ai");
+	return piAi.completeSimple;
+}
+
+async function loadDefaultModelRegistry(): Promise<PiModelRegistry> {
+	const { AuthStorage, ModelRegistry } = await import("@earendil-works/pi-coding-agent");
+	return ModelRegistry.create(AuthStorage.create());
+}

package/src/sdk/command-name.ts

@@ -0,0 +1,2 @@
+export const NS_COMMAND_NAME_PATTERN = /^[a-z][a-z0-9-]*$/;
+export const NS_COMMAND_NAME_RULE = "[a-z][a-z0-9-]*";

package/src/sdk/command.ts

@@ -0,0 +1,109 @@
+import type {
+	ClinkrCompletionCandidate,
+	ClinkrCompletionResult,
+	ClinkrDynamicCompletionRequest,
+	ClinkrExit,
+	OptionSpec,
+	RenderCapabilities,
+} from "@nseng-ai/clinkr";
+import type { PositionalSpec } from "@nseng-ai/clinkr/raw";
+import type { ExplicitUndefined } from "@nseng-ai/foundation/primitives";
+import type { z } from "zod";
+
+import type { NsExtensionApi } from "./execution.ts";
+import type { NsResult } from "./result.ts";
+
+export type {
+	ClinkrCompletionCandidate,
+	ClinkrCompletionResult,
+	ClinkrDynamicCompletionRequest,
+	ClinkrExit,
+	ClinkrFormat,
+	OptionSpec,
+	PositionalSpec,
+	RenderCapabilities,
+} from "@nseng-ai/clinkr";
+
+export type NsCommandSchema = z.ZodObject;
+export type NsCommandRequest<S extends NsCommandSchema> = z.output<S>;
+export type NsCommandCompletionProvider = (
+	ctx: NsExtensionApi,
+	request: ClinkrDynamicCompletionRequest,
+) =>
+	| Promise<ClinkrCompletionResult | readonly ClinkrCompletionCandidate[]>
+	| ClinkrCompletionResult
+	| readonly ClinkrCompletionCandidate[];
+
+export interface NsCommand<S extends NsCommandSchema = z.ZodObject, T = unknown> {
+	name: string;
+	summary: string;
+	description: string;
+	schema?: ExplicitUndefined<"public-api-compatibility", S>;
+	positionals?: ExplicitUndefined<
+		"public-api-compatibility",
+		Partial<Record<keyof z.infer<S> & string, PositionalSpec>>
+	>;
+	options?: ExplicitUndefined<
+		"public-api-compatibility",
+		Partial<Record<keyof z.infer<S> & string, OptionSpec>>
+	>;
+	resultSchema?: ExplicitUndefined<"public-api-compatibility", z.ZodType<T>>;
+	renderHuman?: ExplicitUndefined<
+		"public-api-compatibility",
+		(data: unknown, caps: RenderCapabilities) => string
+	>;
+	renderMarkdown?: ExplicitUndefined<
+		"public-api-compatibility",
+		(data: unknown, caps: RenderCapabilities) => string
+	>;
+	completionProvider?: ExplicitUndefined<"public-api-compatibility", NsCommandCompletionProvider>;
+	run(
+		ctx: NsExtensionApi,
+		request: z.output<S>,
+	): Promise<NsResult | ClinkrExit<T>> | NsResult | ClinkrExit<T>;
+}
+
+export interface NsExtension<TCommands extends readonly NsCommand[] = readonly NsCommand[]> {
+	commands?: ExplicitUndefined<"overload-selector", TCommands>;
+}
+
+type NsCommandTuple<TSchemas extends readonly NsCommandSchema[]> = {
+	readonly [Index in keyof TSchemas]: NsCommand<TSchemas[Index]>;
+};
+
+export function defineExtension(extension: {
+	commands?: ExplicitUndefined<"overload-selector", never>;
+}): NsExtension<readonly []>;
+export function defineExtension(extension: NsExtension<readonly []>): NsExtension<readonly []>;
+export function defineExtension<S1 extends NsCommandSchema = z.ZodObject>(
+	extension: NsExtension<readonly [NsCommand<S1>]>,
+): NsExtension<readonly [NsCommand<S1>]>;
+export function defineExtension<
+	S1 extends NsCommandSchema = z.ZodObject,
+	S2 extends NsCommandSchema = z.ZodObject,
+>(
+	extension: NsExtension<readonly [NsCommand<S1>, NsCommand<S2>]>,
+): NsExtension<readonly [NsCommand<S1>, NsCommand<S2>]>;
+export function defineExtension<
+	S1 extends NsCommandSchema = z.ZodObject,
+	S2 extends NsCommandSchema = z.ZodObject,
+	S3 extends NsCommandSchema = z.ZodObject,
+>(
+	extension: NsExtension<readonly [NsCommand<S1>, NsCommand<S2>, NsCommand<S3>]>,
+): NsExtension<readonly [NsCommand<S1>, NsCommand<S2>, NsCommand<S3>]>;
+export function defineExtension<
+	S1 extends NsCommandSchema = z.ZodObject,
+	S2 extends NsCommandSchema = z.ZodObject,
+	S3 extends NsCommandSchema = z.ZodObject,
+	S4 extends NsCommandSchema = z.ZodObject,
+	const SRest extends readonly NsCommandSchema[] = readonly [],
+>(
+	extension: NsExtension<
+		readonly [NsCommand<S1>, NsCommand<S2>, NsCommand<S3>, NsCommand<S4>, ...NsCommandTuple<SRest>]
+	>,
+): NsExtension<
+	readonly [NsCommand<S1>, NsCommand<S2>, NsCommand<S3>, NsCommand<S4>, ...NsCommandTuple<SRest>]
+>;
+export function defineExtension(extension: NsExtension): NsExtension {
+	return extension;
+}