@neruok/pi-common 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cody Wentz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,73 @@
-# Temporary Holding Version
+# @neruok/pi-common
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared behavior for Neruok Pi extensions. This package is a library, not an extension to install with `pi install`.
+
+## Modules
+
+| Import | Responsibility |
+| --- | --- |
+| `@neruok/pi-common/model-picker` | Inline searchable model picker and RPC selection |
+| `@neruok/pi-common/model-types` | Provider-free model types and reasoning values |
+| `@neruok/pi-common/models` | Host-SDK reasoning capability checks |
+| `@neruok/pi-common/settings` | Bounded reads, scoped layers, locked updates, and explicit replacement |
+| `@neruok/pi-common/commands` | Scope parsing, autocomplete, and context invalidation |
+| `@neruok/pi-common/presentation` | Text sanitization and UI/non-UI command reporting |
+
+The package has no root export. Each extension imports the modules it needs.
+The library does not register tools, change models, call providers, or start background resources.
+Commands and model workflows remain in each extension.
+
+## Settings contract
+
+The settings module uses Node APIs only. Supply the existing byte limit and the extension schema.
+Wrap each complete update or replacement in Pi's `withFileMutationQueue`.
+The caller owns that queue. The library owns no process-global queue.
+
+`updateJsonSettings` reads and validates JSON before it calls a synchronous update function.
+Use it for scope-owned patches. Do not report, call models, or start asynchronous work inside the update function.
+
+`replaceJsonSettings` replaces a regular file without decoding its old content.
+Use it for explicit repair or reset. It compares streamed raw-byte fingerprints before replacement.
+
+Writes acquire an exclusive lock. They use a synchronized same-directory temporary file.
+Existing files use rename. First creation uses an exclusive hard link.
+Changed checkpoints and lock contention fail without retry. The library does not reclaim stale locks.
+Inspect a failed save before retry. A save can have completed before a cleanup or delivery failure.
+
+Target and immediate-parent symlinks, special files, malformed UTF-8 reads, and oversized reads fail.
+Parent-directory races and nonparticipating writers remain outside the guarantee.
+These checks are not an OS sandbox or a power-loss durability guarantee.
+
+## Development
+
+Requires Node.js 24 or newer. SDK-dependent modules use host Pi peers.
+The settings, model-types, and presentation modules can load without Pi installed.
+The picker and reporter accept narrow structural capabilities instead of complete session contexts.
+
+```sh
+npm ci --ignore-scripts
+npm run verify
+```
+
+Build this library before checking the consumer extensions.
+The initial consumers are pi-advisor, pi-magic8ball, and pi-compaction-model.
+Library verification does not require sibling consumer checkouts.
+In the maintainer workspace, run `npm run check:consumers` to check all three packed consumers against their pinned Pi hosts.
+Registry releases pin `@neruok/pi-common` to `0.1.0`. A consumer checkout does not need this repository.
+Do not publish a consumer with a local file dependency.
+
+## Compatibility and release
+
+Requires Node.js 24 or newer. Checks cover Pi 1.0.4 and 1.1.0 on Linux.
+CI tests both host versions. Other Pi versions and operating systems do not have release evidence here.
+Host Pi packages remain optional wildcard peers, as Pi's packaging contract requires.
+The library does not install or bundle host SDKs.
+Exported shared constants are immutable. Command registration and session state remain consumer-owned.
+
+The first release is `0.1.0`. Run `npm run verify` before publication.
+The `prepublishOnly` gate runs the same checks and stops publication on failure.
+The `prepack` gate builds the runtime modules and declarations.
+Inspect the archive, then verify a clean npm installation before publication.
+Publish the library before consumers. Verify registry availability and downloaded integrity before consumer installation checks.
+There are no live-provider checks in `verify`.
+The canonical contract is the workspace document `pi-common`. Its generated project output is `docs/pi-common.md`.

package/dist/commands.d.ts

@@ -0,0 +1,26 @@
+import { type AutocompleteItem } from '@earendil-works/pi-tui';
+import { type PickerModel, type ModelSelection } from './model-types.js';
+export interface Choice {
+    value: string;
+    description: string;
+}
+export type Scope = 'global' | 'project';
+export declare const SCOPE_CHOICES: readonly Readonly<Choice>[];
+export declare function scopedArguments(args: string): {
+    scope: Scope;
+    args: string[];
+} | undefined;
+export interface CompletionSpec {
+    commands: readonly Choice[];
+    modelCommands: readonly string[];
+    isolatedCommands?: Readonly<Record<string, readonly Choice[]>>;
+    models?: (command: string) => readonly PickerModel[] | Promise<readonly PickerModel[]>;
+    reasoning?: (project: boolean) => readonly Choice[] | Promise<readonly Choice[]>;
+    validateModel: (command: string, pair: ModelSelection) => void;
+}
+export declare function argumentCompletions(prefix: string, spec: CompletionSpec): Promise<AutocompleteItem[] | null>;
+/** Each registration owns its context. Pending results cannot survive a context change. */
+export declare function completionContext<T>(complete: (prefix: string, context?: T) => Promise<AutocompleteItem[] | null>): {
+    set(next?: T): void;
+    complete(prefix: string): Promise<AutocompleteItem[] | null>;
+};

package/dist/commands.js

@@ -0,0 +1,117 @@
+import { fuzzyFilter } from '@earendil-works/pi-tui';
+import { REASONING_LEVELS } from './model-types.js';
+export const SCOPE_CHOICES = Object.freeze([
+    Object.freeze({ value: '--global', description: 'Use global settings (default save scope)' }),
+    Object.freeze({ value: '--project', description: 'Use project settings (writes require trust)' }),
+]);
+export function scopedArguments(args) {
+    const tokens = args.trim() ? args.trim().split(/\s+/) : [];
+    const flags = tokens.filter(token => token.startsWith('--'));
+    if (flags.length > 1 || flags.some(flag => !SCOPE_CHOICES.some(choice => choice.value === flag)))
+        return undefined;
+    return { scope: flags[0] === '--project' ? 'project' : 'global', args: tokens.filter(token => !token.startsWith('--')) };
+}
+function isolatedChoices(spec, command) {
+    return spec.isolatedCommands && Object.hasOwn(spec.isolatedCommands, command) ? spec.isolatedCommands[command] : undefined;
+}
+function syntax(prefix, spec) {
+    const fragment = prefix.match(/\S*$/)[0];
+    const base = prefix.slice(0, prefix.length - fragment.length);
+    const parsed = scopedArguments(base);
+    if (!parsed)
+        return undefined;
+    const { args } = parsed;
+    const scoped = /(?:^|\s)--(?:global|project)(?:\s|$)/u.test(base);
+    const [command, argument] = args;
+    const isolated = isolatedChoices(spec, command);
+    if (isolated) {
+        if (scoped || args.length > 2 || (argument && !isolated.some(choice => choice.value === argument)))
+            return undefined;
+    }
+    else if (command === 'show') {
+        if (args.length > 1)
+            return undefined;
+    }
+    else if (command === 'reasoning') {
+        if (args.length > 2 || (argument && !REASONING_LEVELS.some(level => level === argument)))
+            return undefined;
+    }
+    else if (command === 'timeout') {
+        if (args.length > 2 || (argument && argument !== 'default' &&
+            (!/^[0-9]+$/.test(argument) || Number(argument) < 1 || Number(argument) > 2147483647)))
+            return undefined;
+    }
+    else if (spec.modelCommands.includes(command)) {
+        if (args.length > 3)
+            return undefined;
+    }
+    else if (command)
+        return undefined;
+    return { base, fragment, args, scoped, project: parsed.scope === 'project' };
+}
+async function choices(input, spec) {
+    const { args, fragment, scoped, project } = input;
+    const [command, provider] = args;
+    const isolated = isolatedChoices(spec, command);
+    const scopes = scoped || isolated ? [] : SCOPE_CHOICES;
+    if (fragment.startsWith('--'))
+        return scopes;
+    if (!command)
+        return [...spec.commands.filter(choice => !scoped || !isolatedChoices(spec, choice.value)), ...scopes];
+    if (isolated)
+        return args.length === 1 ? isolated : [];
+    if (command === 'show' || ((command === 'reasoning' || command === 'timeout') && args.length === 2) || args.length === 3)
+        return scopes;
+    if (command === 'timeout')
+        return [{ value: 'default', description: 'Remove the scoped timeout and restore inheritance' }];
+    if (command === 'reasoning')
+        return await spec.reasoning?.(project) ?? [];
+    const models = await spec.models?.(command) ?? [];
+    if (!provider) {
+        return [...new Set(models.map(model => model.provider))].sort((a, b) => a.localeCompare(b))
+            .filter(value => value.toLowerCase().startsWith(fragment.toLowerCase()))
+            .map(value => ({ value, description: `Available ${command} provider` }));
+    }
+    const candidates = models.filter(model => model.provider === provider).sort((a, b) => a.id.localeCompare(b.id));
+    return fuzzyFilter(candidates, fragment, model => `${model.id} ${model.name ?? ''}`)
+        .map(model => ({ value: model.id, description: model.name || `Available ${command} model` }));
+}
+export async function argumentCompletions(prefix, spec) {
+    const input = syntax(prefix, spec);
+    if (!input)
+        return null;
+    try {
+        const catalog = spec.modelCommands.includes(input.args[0]) && input.args.length < 3 && !input.fragment.startsWith('--');
+        const candidates = await choices(input, spec);
+        const matched = catalog ? candidates : candidates.filter(choice => choice.value.startsWith(input.fragment));
+        const items = matched.filter(choice => {
+            if (!catalog)
+                return true;
+            if (choice.value.startsWith('--'))
+                return false;
+            try {
+                spec.validateModel(input.args[0], { provider: input.args[1] ?? choice.value, model: input.args[1] ? choice.value : 'placeholder' });
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }).map(choice => ({ value: `${input.base}${choice.value} `, label: choice.value, description: choice.description }));
+        return items.length ? items : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Each registration owns its context. Pending results cannot survive a context change. */
+export function completionContext(complete) {
+    let context, revision = 0;
+    return {
+        set(next) { context = next; revision++; },
+        async complete(prefix) {
+            const before = revision;
+            const items = await complete(prefix, context);
+            return before === revision ? items : null;
+        },
+    };
+}

package/dist/model-picker.d.ts

@@ -0,0 +1,28 @@
+import type { ModelSelection as Selection, PickerModel } from './model-types.js';
+export declare class ModelPickerError extends Error {
+}
+interface PickerComponent {
+    focused: boolean;
+    render(width: number): string[];
+    invalidate(): void;
+    handleInput(data: string): void;
+}
+interface PickerTheme {
+    fg(color: 'accent' | 'muted' | 'dim', text: string): string;
+    bold(text: string): string;
+}
+export interface ModelPickerContext {
+    mode: string;
+    ui: {
+        select(title: string, choices: string[]): Promise<string | undefined>;
+        custom<T>(factory: (tui: {
+            terminal: {
+                rows: number;
+            };
+            requestRender(): void;
+        }, theme: PickerTheme, keybindings: unknown, done: (value: T) => void) => PickerComponent): Promise<T>;
+    };
+}
+/** Shared inline picker. The caller supplies the eligible model snapshot. */
+export declare function selectModel(ctx: ModelPickerContext, title: string, models: readonly PickerModel[], current?: Selection): Promise<Selection | undefined>;
+export {};

package/dist/model-picker.js

@@ -0,0 +1,90 @@
+import { fuzzyFilter, getKeybindings, Input, SelectList, truncateToWidth } from '@earendil-works/pi-tui';
+import { sanitizeLabel } from './presentation.js';
+export class ModelPickerError extends Error {
+}
+const key = (model) => `${model.provider} / ${model.id}`;
+/** Shared inline picker. The caller supplies the eligible model snapshot. */
+export async function selectModel(ctx, title, models, current) {
+    const entries = new Map(models.map(model => [key(model), model]));
+    if (ctx.mode !== 'tui') {
+        // Use the same provider/model labels in every RPC client.
+        const choices = new Map(models.map(model => [`${model.provider}/${model.id}`, model]));
+        const selected = await ctx.ui.select(title, [...choices.keys()]);
+        if (selected === undefined)
+            return undefined;
+        const model = choices.get(selected);
+        if (!model)
+            throw new ModelPickerError('Model unavailable.');
+        return { provider: model.provider, model: model.id };
+    }
+    return ctx.ui.custom((tui, theme, _keybindings, done) => {
+        const isCurrent = (model) => model.provider === current?.provider && model.id === current.model;
+        const items = [...entries.values()]
+            .sort((a, b) => Number(isCurrent(b)) - Number(isCurrent(a)) || a.provider.localeCompare(b.provider))
+            .map(model => ({ value: key(model), label: `${isCurrent(model) ? '✓ ' : '  '}${sanitizeLabel(model.id)} [${sanitizeLabel(model.provider)}]`, model }));
+        const search = new Input();
+        const style = {
+            selectedPrefix: (text) => theme.fg('accent', text),
+            selectedText: (text) => theme.fg('accent', text),
+            description: (text) => theme.fg('muted', text),
+            scrollInfo: (text) => theme.fg('muted', text),
+            noMatch: () => theme.fg('muted', '  No matching models'),
+        };
+        let filtered = items, selectedIndex = 0, visible = 10;
+        function makeList() {
+            const next = new SelectList(filtered, visible, style);
+            next.setSelectedIndex(selectedIndex);
+            next.onSelectionChange = item => { selectedIndex = filtered.findIndex(entry => entry.value === item.value); };
+            next.onSelect = item => {
+                const model = entries.get(item.value);
+                done({ provider: model.provider, model: model.id });
+            };
+            next.onCancel = () => done(undefined);
+            return next;
+        }
+        let list = makeList();
+        search.onSubmit = () => list.handleInput('\r');
+        function filter(query) {
+            // Same search text order and token ranking as Pi's /model selector.
+            filtered = fuzzyFilter(items, query, ({ model }) => `${model.provider} ${model.provider}/${model.id} ${model.provider} ${model.id}${model.name ? ` ${model.name}` : ''}`);
+            selectedIndex = query ? 0 : Math.min(selectedIndex, Math.max(0, filtered.length - 1));
+            list = makeList();
+        }
+        return {
+            get focused() { return search.focused; },
+            set focused(value) { search.focused = value; },
+            render(width) {
+                const height = Math.max(1, tui.terminal.rows - 2);
+                const full = height >= 10;
+                const border = theme.fg('accent', '─'.repeat(Math.max(0, width)));
+                const heading = theme.fg('accent', theme.bold(sanitizeLabel(title)));
+                const prefix = full ? [border, heading, ...search.render(width), '']
+                    : height >= 4 ? [heading, ...search.render(width)] : height >= 2 ? search.render(width) : [];
+                const selected = filtered[selectedIndex]?.model;
+                const suffix = full ? ['', theme.fg('muted', `  Model Name: ${sanitizeLabel(selected?.name ?? selected?.id)}`), theme.fg('dim', '↑↓ navigate • enter select • esc cancel'), border] : [];
+                const listHeight = height - prefix.length - suffix.length;
+                // Count SelectList's position indicator within the viewport budget.
+                const count = Math.max(1, Math.min(10, filtered.length, listHeight - (filtered.length > Math.min(10, listHeight) ? 1 : 0)));
+                if (count !== visible) {
+                    visible = count;
+                    list = makeList();
+                }
+                return [...prefix, ...list.render(width).slice(0, listHeight), ...suffix].map(line => truncateToWidth(line, width));
+            },
+            invalidate() { search.invalidate(); list.invalidate(); },
+            handleInput(data) {
+                const kb = getKeybindings();
+                if (kb.matches(data, 'tui.select.up') || kb.matches(data, 'tui.select.down') || kb.matches(data, 'tui.select.confirm') || kb.matches(data, 'tui.select.cancel')) {
+                    list.handleInput(data);
+                }
+                else {
+                    const before = search.getValue();
+                    search.handleInput(data);
+                    if (search.getValue() !== before)
+                        filter(search.getValue());
+                }
+                tui.requestRender();
+            },
+        };
+    });
+}

package/dist/model-types.d.ts

@@ -0,0 +1,13 @@
+/** Data-only types and values. Safe for provider-free cores and standalone scripts. */
+export declare const REASONING_LEVELS: readonly ["default", "off", "minimal", "low", "medium", "high", "xhigh", "max"];
+export type Reasoning = typeof REASONING_LEVELS[number];
+export type ModelSelection = {
+    provider: string;
+    model: string;
+    reasoning?: Reasoning;
+};
+export type PickerModel = {
+    provider: string;
+    id: string;
+    name?: string;
+};

package/dist/model-types.js

@@ -0,0 +1,2 @@
+/** Data-only types and values. Safe for provider-free cores and standalone scripts. */
+export const REASONING_LEVELS = Object.freeze(['default', 'off', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max']);

package/dist/models.d.ts

@@ -0,0 +1,6 @@
+import { type Api, type Model } from '@earendil-works/pi-ai';
+import type { Reasoning } from './model-types.js';
+export { REASONING_LEVELS } from './model-types.js';
+export type { Reasoning, ModelSelection, PickerModel } from './model-types.js';
+export declare function supportedReasoning(model: Model<Api>): Reasoning[];
+export declare function supportsReasoning(model: Model<Api>, level?: Reasoning): boolean;

package/dist/models.js

@@ -0,0 +1,8 @@
+import { getSupportedThinkingLevels } from '@earendil-works/pi-ai';
+export { REASONING_LEVELS } from './model-types.js';
+export function supportedReasoning(model) {
+    return ['default', ...getSupportedThinkingLevels(model)];
+}
+export function supportsReasoning(model, level) {
+    return level === undefined || supportedReasoning(model).includes(level);
+}

package/dist/presentation.d.ts

@@ -0,0 +1,23 @@
+export interface ReportHost {
+    sendMessage(message: {
+        customType: string;
+        content: string;
+        display: boolean;
+        details: {
+            level: 'info' | 'error';
+        };
+    }, options: {
+        triggerTurn: false;
+    }): void;
+}
+export interface ReportContext {
+    hasUI: boolean;
+    ui: {
+        notify(text: string, level: 'info' | 'error'): void;
+    };
+}
+/** Sanitize data before theme styling. Preserve multiline text, not terminal controls. */
+export declare function sanitizeText(text: string): string;
+export declare function sanitizeLabel(value: unknown): string;
+/** Reporting never starts a turn or changes the operation's outcome. */
+export declare function reportCommand(pi: ReportHost, ctx: ReportContext, customType: string, content: string, level: 'info' | 'error'): boolean;

package/dist/presentation.js

@@ -0,0 +1,22 @@
+/** Sanitize data before theme styling. Preserve multiline text, not terminal controls. */
+export function sanitizeText(text) {
+    return text.replace(/\t/g, ' ').replace(/[\x00-\x09\x0b-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/gu, '');
+}
+export function sanitizeLabel(value) {
+    return sanitizeText(String(value ?? '')).replace(/\n/g, ' ');
+}
+/** Reporting never starts a turn or changes the operation's outcome. */
+export function reportCommand(pi, ctx, customType, content, level) {
+    try {
+        const text = sanitizeText(content);
+        if (ctx.hasUI)
+            ctx.ui.notify(text, level);
+        else
+            pi.sendMessage({ customType, content: text, display: true, details: { level } }, { triggerTurn: false });
+        return true;
+    }
+    catch {
+        console.error(`${sanitizeLabel(customType)}: could not report the result.`);
+        return false;
+    }
+}

package/dist/settings.d.ts

@@ -0,0 +1,17 @@
+export declare class SettingsError extends Error {
+    readonly code: 'invalid-config' | 'settings-unavailable';
+    constructor(code: 'invalid-config' | 'settings-unavailable');
+}
+export declare function readSettingsBytes(path: string, maxBytes: number): Promise<Buffer | undefined>;
+export type Scope = 'global' | 'project';
+export type SettingsPaths = Record<Scope, string>;
+export declare function settingsPaths(cwd: string, agentDir: string, filename: string): SettingsPaths;
+export declare function loadScopedSettings<T extends object>(paths: SettingsPaths, trusted: boolean, maxBytes: number, parse: (value: unknown) => T): Promise<{
+    settings: T;
+    sources: Partial<Record<keyof T, Scope>>;
+}>;
+export declare function decodeSettings(raw: Buffer | undefined): unknown;
+/** Update only valid JSON. The synchronous callback supplies schema and merge policy. */
+export declare function updateJsonSettings(path: string, maxBytes: number, update: (value: unknown) => unknown): Promise<void>;
+/** Explicit replacement repairs malformed regular files. It never follows symlinks. */
+export declare function replaceJsonSettings(path: string, value: unknown, maxBytes: number): Promise<void>;

package/dist/settings.js

@@ -0,0 +1,216 @@
+import { constants } from 'node:fs';
+import { lstat, open, mkdir, rename, link, unlink } from 'node:fs/promises';
+import { randomUUID, createHash } from 'node:crypto';
+import { dirname, join } from 'node:path';
+export class SettingsError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+const missing = (error) => Boolean(error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT');
+function unavailable(error) {
+    throw error instanceof SettingsError ? error : new SettingsError('settings-unavailable');
+}
+function bound(maxBytes) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1)
+        throw new SettingsError('invalid-config');
+}
+async function checkParent(path) {
+    try {
+        const stat = await lstat(dirname(path));
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new SettingsError('settings-unavailable');
+    }
+    catch (error) {
+        if (!missing(error))
+            unavailable(error);
+    }
+}
+async function regularFile(path) {
+    await checkParent(path);
+    try {
+        const stat = await lstat(path);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            throw new SettingsError('settings-unavailable');
+        const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+        try {
+            if (!(await file.stat()).isFile())
+                throw new SettingsError('settings-unavailable');
+            return file;
+        }
+        catch (error) {
+            await file.close();
+            throw error;
+        }
+    }
+    catch (error) {
+        if (missing(error))
+            return undefined;
+        return unavailable(error);
+    }
+}
+export async function readSettingsBytes(path, maxBytes) {
+    bound(maxBytes);
+    const file = await regularFile(path);
+    if (!file)
+        return undefined;
+    try {
+        if ((await file.stat()).size > maxBytes)
+            throw new SettingsError('invalid-config');
+        const buffer = Buffer.alloc(maxBytes + 1);
+        let length = 0;
+        while (length < buffer.length) {
+            const { bytesRead } = await file.read(buffer, length, buffer.length - length, length);
+            if (!bytesRead)
+                break;
+            length += bytesRead;
+        }
+        if (length > maxBytes)
+            throw new SettingsError('invalid-config');
+        return buffer.subarray(0, length);
+    }
+    catch (error) {
+        return unavailable(error);
+    }
+    finally {
+        await file.close();
+    }
+}
+export function settingsPaths(cwd, agentDir, filename) {
+    return { global: join(agentDir, filename), project: join(cwd, '.pi', filename) };
+}
+export async function loadScopedSettings(paths, trusted, maxBytes, parse) {
+    const read = async (path) => {
+        const value = decodeSettings(await readSettingsBytes(path, maxBytes));
+        try {
+            return parse(value);
+        }
+        catch {
+            throw new SettingsError('invalid-config');
+        }
+    };
+    const global = await read(paths.global);
+    const project = trusted ? await read(paths.project) : {};
+    const settings = { ...global, ...project };
+    const sources = {};
+    for (const key of Object.keys(settings))
+        sources[key] = Object.hasOwn(project, key) ? 'project' : 'global';
+    return { settings, sources };
+}
+export function decodeSettings(raw) {
+    if (raw === undefined)
+        return {};
+    try {
+        return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(raw));
+    }
+    catch {
+        throw new SettingsError('invalid-config');
+    }
+}
+/** Raw repair checkpoints do not decode or retain the complete old file. */
+async function fingerprint(path) {
+    const file = await regularFile(path);
+    if (!file)
+        return undefined;
+    try {
+        const hash = createHash('sha256'), chunk = Buffer.alloc(65536);
+        while (true) {
+            const { bytesRead } = await file.read(chunk, 0, chunk.length, null);
+            if (!bytesRead)
+                break;
+            hash.update(chunk.subarray(0, bytesRead));
+        }
+        return hash.digest('hex');
+    }
+    finally {
+        await file.close();
+    }
+}
+function serialize(value, maxBytes) {
+    bound(maxBytes);
+    const json = JSON.stringify(value, null, 2);
+    if (json === undefined)
+        throw new SettingsError('invalid-config');
+    const text = json + '\n';
+    if (Buffer.byteLength(text) > maxBytes)
+        throw new SettingsError('invalid-config');
+    return text;
+}
+/** Caller owns the host queue. The exclusive lock covers read, update, and commit. */
+async function transaction(path, prepare) {
+    let lock, ownedTemp = false;
+    const lockPath = path + '.lock', temp = path + '.' + randomUUID() + '.tmp';
+    try {
+        await checkParent(path);
+        await mkdir(dirname(path), { recursive: true });
+        await checkParent(path);
+        lock = await open(lockPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+        const checkpoint = await prepare();
+        const output = await open(temp, 'wx', 0o600);
+        ownedTemp = true;
+        try {
+            await output.writeFile(checkpoint.text, 'utf8');
+            await output.sync();
+        }
+        finally {
+            await output.close();
+        }
+        if (!(await checkpoint.unchanged()))
+            throw new SettingsError('settings-unavailable');
+        if (checkpoint.exists)
+            await rename(temp, path);
+        else
+            await link(temp, path);
+    }
+    catch (error) {
+        unavailable(error);
+    }
+    finally {
+        try {
+            if (ownedTemp) {
+                try {
+                    await unlink(temp);
+                }
+                catch (error) {
+                    if (!missing(error))
+                        unavailable(error);
+                }
+            }
+        }
+        finally {
+            if (lock) {
+                try {
+                    const owned = await lock.stat(), current = await lstat(lockPath);
+                    if (owned.ino !== current.ino || owned.dev !== current.dev || current.isSymbolicLink())
+                        throw new SettingsError('settings-unavailable');
+                    await unlink(lockPath);
+                }
+                finally {
+                    await lock.close();
+                }
+            }
+        }
+    }
+}
+/** Update only valid JSON. The synchronous callback supplies schema and merge policy. */
+export async function updateJsonSettings(path, maxBytes, update) {
+    bound(maxBytes);
+    await transaction(path, async () => {
+        const before = await readSettingsBytes(path, maxBytes);
+        const text = serialize(update(decodeSettings(before)), maxBytes);
+        return { text, exists: before !== undefined, unchanged: async () => {
+                const current = await readSettingsBytes(path, maxBytes);
+                return before === undefined ? current === undefined : current !== undefined && current.equals(before);
+            } };
+    });
+}
+/** Explicit replacement repairs malformed regular files. It never follows symlinks. */
+export async function replaceJsonSettings(path, value, maxBytes) {
+    const text = serialize(value, maxBytes);
+    await transaction(path, async () => {
+        const before = await fingerprint(path);
+        return { text, exists: before !== undefined, unchanged: async () => (await fingerprint(path)) === before };
+    });
+}

package/docs/pi-common.md

@@ -0,0 +1,198 @@
+<!-- generated by workspace-docs. source: pi-common revision 6. do not edit; author with workspace-docs checkout. -->
+
+# Pi common: shared extension behavior
+
+## Contents
+
+- [Scope](#scope)
+- [Contract](#contract)
+- [Acceptance](#acceptance)
+- [Remaining scope](#remaining-scope)
+- [Initial implementation and verification](#implementation)
+
+
+## Scope {#scope}
+
+The user requested shared extension behavior, not only code deduplication. The first consumers are advisor, magic8ball, and compaction-model.
+
+The library owns model pickers, reasoning discovery, settings transactions, completion mechanics, command reporting, and text sanitization.
+Extensions retain domain workflows, model eligibility, schemas, paths, scope rules, request budgets, authentication, and response envelopes.
+The documentation, file-memory, and llama-swap cores retain their separate storage and provider contracts.
+
+## Contract {#contract}
+
+<a id="CC-REQ-1"></a>
+
+**CC-REQ-1**
+
+The package MUST be a compiled ESM library named @neruok/pi-common, with explicit typed subpath exports.
+It MUST NOT register extensions, start background resources, call models, or own a mutable singleton.
+Host Pi packages MUST be optional peers, never bundled runtime dependencies.
+The settings subpath MUST load without Pi packages. Callers MUST provide Pi's mutation queue around each complete transaction.
+Local migrations MUST use declared file dependencies until a separately authorized release provides registry dependencies.
+
+
+<a id="CC-REQ-2"></a>
+
+**CC-REQ-2**
+
+All three model extensions MUST use one model picker and one reasoning-discovery implementation.
+The picker MUST preserve current-first ordering, fuzzy ranking, focus forwarding, ten-row limits, resize handling, and cancellation.
+RPC model labels MUST use provider/model in all three extensions. Returned identifiers MUST remain complete and unchanged.
+Reasoning choices MUST be default followed by Pi getSupportedThinkingLevels. Unsupported explicit effort MUST NOT clamp or fall back.
+Domain errors, model eligibility, and request-option handling MUST remain extension-owned.
+
+
+<a id="CC-REQ-3"></a>
+
+**CC-REQ-3**
+
+Settings reads MUST reject target and immediate-parent symlinks, special files, invalid UTF-8, and oversized content.
+Readers MUST enforce the caller's existing inclusive bound: 16000 bytes for magic8ball and 16384 for advisor and compaction-model.
+Each settings write MUST use an exclusive lock, an owned same-directory temporary file, file synchronization, and a final checkpoint comparison.
+Existing files MUST use atomic rename. First creation MUST use exclusive link without replacing a newly appeared file.
+Lock contention or a changed checkpoint MUST fail without a retry or stale-lock reclamation.
+Cleanup MUST remove only owned temporary files and locks whose inode and device still match.
+A replacement operation MUST preserve compaction's repair of malformed regular files without JSON or UTF-8 decoding.
+Replacement checkpoints MUST stream raw bytes, so malformed or oversized old files do not require whole-file buffering.
+These checks MUST NOT claim an OS sandbox, power-loss durability, or containment of nonparticipating writers and parent-directory races.
+
+
+<a id="CC-REQ-4"></a>
+
+**CC-REQ-4**
+
+Advisor and magic8ball MUST use common completion tokenization, scope validation, prefix replacement, and catalog ranking.
+Static completion MUST work without settings or catalog access. Dynamic failures MUST remain silent and return no suggestions.
+A changed session context MUST invalidate pending completion results.
+Existing command grammar, trust checks, supported model types, and transcript rules MUST remain unchanged.
+
+
+<a id="CC-REQ-5"></a>
+
+**CC-REQ-5**
+
+All three model extensions MUST use one reporter for settings commands and safe outcome notices.
+With UI, it MUST notify. Without UI, it MUST send a visible custom message with triggerTurn false.
+Reporting failure MUST use fixed local fallback text without exposing exceptions or starting a model turn.
+Shared text sanitizers MUST remove terminal controls and bidirectional controls before styling.
+Multiline text MUST preserve line breaks. Single-line labels MUST flatten line breaks.
+Domain result layouts and usage accounting MUST remain unchanged.
+Transcript viewing MUST retain its existing UI-only delivery. It MUST NOT copy captured transcript text into custom session messages.
+
+
+<a id="CC-REQ-6"></a>
+
+**CC-REQ-6**
+
+The first registry release MUST be @neruok/pi-common@0.1.0 with public npm access and repository metadata.
+The library MUST keep host Pi packages as optional wildcard peers. CI MUST verify Node 24 with Pi 1.0.4 and 1.1.0.
+The publication lifecycle MUST run independent library verification and stop on verification failure.
+Consumers MUST pin 0.1.0 exactly and use registry lockfiles before their release. They MUST NOT publish local file dependencies.
+Release validation MUST install the library archive through npm in isolation, then test consumer archives through Pi's real package manager.
+The release MUST NOT call model providers. Source, packaged bytes, downloaded registry integrity, and GitHub commits MUST agree.
+After any unknown publication outcome, inspect registry state before another publication attempt.
+
+
+## Acceptance {#acceptance}
+
+<a id="CC-AC-1"></a>
+
+**CC-AC-1**
+
+Changed behavior. Before migration, dependency checks fail because the three consumers do not declare pi-common.
+After migration, all three declare the library. Packed-library tests verify typed exports, import restrictions, and pure settings loading.
+Each packed consumer loads through its installed Pi resource loader with the packed common dependency in node_modules.
+No sibling-source symlink or bundled Pi package may satisfy the archive checks.
+Changed behavior during release preparation. An immutable-constants check fails for the exported scope choices before freezing.
+After freezing, mutation of either the shared array or its entries throws without changing command behavior.
+
+
+<a id="CC-AC-2"></a>
+
+**CC-AC-2**
+
+Preserved behavior. Existing advisor and compaction picker tests pass before and after migration.
+Changed behavior. A magic8ball RPC picker test fails before migration because labels contain spaces around the slash.
+After migration, all three use provider/model labels, preserve full identifiers, and cancel without writes or model calls.
+Shared picker tests cover search, no-match Enter, focus, narrow dimensions, wrapping navigation, and Unicode identifiers.
+Reasoning support tests compare the shared result with the public SDK and reject unsupported levels without provider work.
+
+
+<a id="CC-AC-3"></a>
+
+**CC-AC-3**
+
+Preserved behavior. Existing settings tests pass before and after migration, including trust, limits, malformed files, and reset repair.
+Changed behavior. Compaction lock and immediate-parent-symlink tests fail before migration and pass afterward.
+Shared transaction tests verify exact byte bounds, malformed UTF-8 refusal, special-file refusal, concurrent checkpoint changes, and owned cleanup.
+Replacement tests repair invalid UTF-8 and oversized old regular files, retain lock refusal, and refuse symlink targets.
+
+
+<a id="CC-AC-4"></a>
+
+**CC-AC-4**
+
+Preserved behavior. Existing advisor and magic8ball autocomplete suites pass before and after migration.
+Shared checks cover repeated/conflicting scopes, preserved whitespace, sorted providers, fuzzy model ranking, silent lookup failure, and stale-context rejection.
+Neither completion nor command reporting may write settings or perform model work.
+
+
+<a id="CC-AC-5"></a>
+
+**CC-AC-5**
+
+Changed behavior. Magic8ball no-UI command tests fail before migration because reports only call ui.notify.
+After migration, show, reasoning, timeout, invalid syntax, cancellation, and save results use a visible custom message without a model turn.
+Shared reporter checks cover UI notification, non-UI delivery, and a failed delivery with fixed fallback text.
+A magic8ball renderer check fails before migration for bidirectional controls and passes with common sanitization.
+
+
+- #CC-REQ-1 verified-by: [#CC-AC-1](#CC-AC-1)
+
+
+- #CC-REQ-2 verified-by: [#CC-AC-2](#CC-AC-2)
+
+
+- #CC-REQ-3 verified-by: [#CC-AC-3](#CC-AC-3)
+
+
+- #CC-REQ-4 verified-by: [#CC-AC-4](#CC-AC-4)
+
+
+- #CC-REQ-5 verified-by: [#CC-AC-5](#CC-AC-5)
+
+
+<a id="CC-AC-6"></a>
+
+**CC-AC-6**
+
+Changed behavior. Before release preparation, manifest checks fail for private publication, missing public metadata, and a missing prepublishOnly gate.
+After preparation, the manifest is public, declares the repository, and has a verification gate. A lifecycle fixture proves success propagation and failure refusal.
+A clean npm install of the library tarball exposes all declared runtime and type exports without installing host SDK copies.
+Each consumer's release manifest pins common 0.1.0. Clean Pi installations resolve that registry dependency without a sibling checkout.
+The installed extensions load under their tested Pi host, register their expected resources, and execute safe show/cancellation checks without provider calls.
+Published version, dependency metadata, dist integrity, and remote commit identities must match the inspected release artifacts.
+
+
+## Remaining scope {#remaining-scope}
+
+The first migration does not change command names, compaction scope, request deadlines, retention, or result schemas.
+Further unification of those public contracts requires explicit decisions and acceptance checks.
+The user authorized release preparation, repository creation, commits, pushes, and npm publication for this library and its three initial consumers.
+Live-provider tests remain outside this release.
+
+## Initial implementation and verification {#implementation}
+
+The library exports model-picker, model-types, models, settings, commands, and presentation.
+The model-types module contains provider-free constants. Standalone benchmark scripts do not load Pi through those constants.
+Picker and reporter interfaces expose only the structural capabilities they use. They do not expose complete Pi session contexts.
+
+Changed checks failed before migration for missing dependencies, RPC label spacing, no-UI reports, foreign locks, and parent symlinks.
+The preserved picker, settings, reasoning, completion, and reset checks passed before migration.
+Packed dependency checks load actual archives without sibling-source symlinks or bundled host packages.
+Release preparation added public metadata, verification gates, an npm archive-install check, and immutable command constants.
+CI checks Node 24 with Pi 1.0.4 and 1.1.0. Local registry migrations used file dependencies before the authorized release.
+Uniform command names, compaction project scope, deadlines, retention, and domain result layouts remain outside this first migration.
+
+- #CC-REQ-6 verified-by: [#CC-AC-6](#CC-AC-6)

package/package.json

@@ -1,6 +1,75 @@
 {
   "name": "@neruok/pi-common",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "repository": { "type": "git", "url": "https://github.com/neruok/pi-common.git" },
+  "homepage": "https://github.com/neruok/pi-common#readme",
+  "bugs": { "url": "https://github.com/neruok/pi-common/issues" },
+  "type": "module",
+  "description": "Shared behavior for Neruok Pi extensions",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    "./model-types": { "types": "./dist/model-types.d.ts", "import": "./dist/model-types.js" },
+    "./model-picker": {
+      "types": "./dist/model-picker.d.ts",
+      "import": "./dist/model-picker.js"
+    },
+    "./models": {
+      "types": "./dist/models.d.ts",
+      "import": "./dist/models.js"
+    },
+    "./settings": {
+      "types": "./dist/settings.d.ts",
+      "import": "./dist/settings.js"
+    },
+    "./commands": {
+      "types": "./dist/commands.d.ts",
+      "import": "./dist/commands.js"
+    },
+    "./presentation": {
+      "types": "./dist/presentation.d.ts",
+      "import": "./dist/presentation.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "docs/pi-common.md"
+  ],
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-ai": {
+      "optional": true
+    },
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "1.0.4",
+    "@earendil-works/pi-coding-agent": "1.0.4",
+    "@earendil-works/pi-tui": "1.0.4",
+    "typescript": "5.9.3",
+    "@types/node": "26.6.4"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "check": "node --test tests/*.test.mjs",
+    "check:consumers": "node --test integration/*.test.mjs",
+    "verify": "npm run build && npm run check",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm run verify"
+  }
+}