@neruok/pi-advisor 0.0.0-stage → 0.1.1

package/lib/session.ts

@@ -0,0 +1,193 @@
+import { randomUUID } from 'node:crypto';
+import type { AssistantMessage, ModelsSimpleStreamOptions, Context, Usage } from '@earendil-works/pi-ai';
+import { ADVISOR_PROMPT } from './prompt.ts';
+import { replay, type Replay } from './replay.ts';
+import { contextUsage, type ContextUsage } from './context.ts';
+import { AdvisorError, LIMITS, parseTimeoutMs, addUsage, checkLimit, failure, parseInput, replyText, zeroUsage, completionCategory, terminalDiagnostics, type Diagnostics, type Failure, type Selection, type SelectionSource, type UsageTotals } from './protocol.ts';
+
+type Exchange = { role: 'user' | 'assistant'; text: string; replay?: Replay; usage?: Usage };
+type Session = { id: string; label: string; model?: Selection; selectionSource?: SelectionSource; timeoutMs?: number; contextWindow?: number; history: Exchange[]; usage: Usage; totalUsageComplete: boolean; pending?: AbortController };
+export type Phase = 'preparing' | 'waiting';
+export type Dependencies = {
+  prepare: (reportSelection?: (model: Selection, source: SelectionSource) => void, reportTimeout?: (timeoutMs: number) => void) => Promise<Selection>;
+  getContextWindow: (model: Selection) => number;
+  complete: (model: Selection, context: Context, options: ModelsSimpleStreamOptions) => Promise<AssistantMessage>;
+  progress?: (phase: Phase) => void;
+};
+export type Advice = { ok: true; advisory: true; session: string; response: string; turns: number; model: Selection; usage: Usage; usageComplete: boolean; contextUsage: ContextUsage } & UsageTotals;
+export type Metadata = { session: string; label: string; turns: number; model: Selection; busy: boolean; historyBytes: number; contextUsage: ContextUsage } & UsageTotals;
+const size = (history: Exchange[]): number => Buffer.byteLength(JSON.stringify(history.map(({ role, text, replay }) => ({ role, text, ...(replay ? { replay } : {}) }))));
+const retainedContext = (session: Session): ContextUsage => contextUsage(context(session.history, session.model!).messages, session.contextWindow!);
+const totals = (session: Session, pending = Boolean(session.pending)): UsageTotals => ({ totalUsage: structuredClone(session.usage), totalUsageComplete: session.totalUsageComplete && !pending });
+function progress(deps: Dependencies, phase: Phase): void {
+  // Presentation failure must never replace a consultation outcome.
+  try { deps.progress?.(phase); } catch { /* The host owns display diagnostics. */ }
+}
+
+function context(history: Exchange[], model: Selection): Context {
+  return { messages: [
+    { role: 'system', content: ADVISOR_PROMPT, toolsAdded: [], timestamp: 0 },
+    ...history.map(entry => entry.role === 'user'
+      ? { role: 'user' as const, content: entry.text, timestamp: 0 }
+      : { role: 'assistant' as const, content: entry.replay ? structuredClone(entry.replay.content) : [{ type: 'text' as const, text: entry.text }], provider: model.provider, model: model.model, api: entry.replay?.api ?? 'advisor-text', timestamp: 0, stopReason: 'stop' as const, usage: structuredClone(entry.usage ?? zeroUsage()) })
+  ] };
+}
+// The caller owns the race. Late provider completion can never commit consultation state.
+async function interruptible<T>(operation: () => Promise<T>, signal: AbortSignal): Promise<T> {
+  if (signal.aborted) throw signal.reason;
+  let abort: (() => void) | undefined;
+  const cancelled = new Promise<never>((_resolve, reject) => { abort = () => reject(signal.reason); signal.addEventListener('abort', abort, { once: true }); });
+  try { return await Promise.race([Promise.resolve().then(() => { if (signal.aborted) throw signal.reason; return operation(); }), cancelled]); }
+  finally { if (abort) signal.removeEventListener('abort', abort); }
+}
+
+export class Consultations {
+  private readonly sessions = new Map<string, Session>();
+  private readonly limits: typeof LIMITS;
+  constructor(overrides: Partial<Pick<typeof LIMITS, 'timeoutMs'>> = {}) {
+    if (Object.keys(overrides).some(key => key !== 'timeoutMs')) throw new AdvisorError('invalid-argument');
+    for (const value of Object.values(overrides)) if (!Number.isSafeInteger(value) || value < 1) throw new AdvisorError('invalid-argument');
+    if (overrides.timeoutMs !== undefined) parseTimeoutMs(overrides.timeoutMs, 'invalid-argument');
+    this.limits = { ...LIMITS, ...overrides };
+  }
+  list(): Metadata[] {
+    return [...this.sessions.values()].filter((s): s is Session & { model: Selection } => Boolean(s.model)).map(s => ({
+      session: s.id, label: s.label, turns: s.history.length / 2, model: { ...s.model }, busy: Boolean(s.pending),
+      ...totals(s),
+      historyBytes: size(s.history), contextUsage: retainedContext(s)
+    }));
+  }
+  close(id: string): { ok: true; session: string } | Failure {
+    const session = this.sessions.get(id);
+    if (!session) return failure(new AdvisorError('not-found'), zeroUsage(), id);
+    if (session.pending) return failure(new AdvisorError('busy'), zeroUsage(), id);
+    this.sessions.delete(id);
+    return { ok: true, session: id };
+  }
+  clear(): void {
+    for (const session of this.sessions.values()) session.pending?.abort(new AdvisorError('cancelled'));
+    this.sessions.clear();
+  }
+  async send(value: unknown, deps: Dependencies, signal?: AbortSignal): Promise<Advice | Failure> {
+    let session: Session | undefined;
+    let input: ReturnType<typeof parseInput> | undefined;
+    const requestedSession = value && typeof value === 'object' && 'session' in value && typeof value.session === 'string' && value.session.trim() ? value.session : undefined;
+    let controller: AbortController | undefined;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let relay: (() => void) | undefined;
+    let usage = zeroUsage();
+    let usageComplete = true;
+    const diagnosticsEnabled = Boolean(value && typeof value === 'object' && 'diagnostics' in value && value.diagnostics === true);
+    let phase: Diagnostics['phase'] = 'validation';
+    let terminalHint: Pick<Diagnostics, 'category' | 'code' | 'httpStatus'> | undefined;
+    let diagnosticModel: Selection | undefined;
+    let selectionSource: SelectionSource = 'unknown';
+    let timeoutMs: number = this.limits.timeoutMs, finished = false;
+    const started = performance.now();
+    const armDeadline = (): void => {
+      if (timer) clearTimeout(timer);
+      const remaining = timeoutMs - (performance.now() - started);
+      if (remaining <= 0) throw new AdvisorError('timeout');
+      timer = setTimeout(() => controller!.abort(new AdvisorError('timeout')), remaining);
+    };
+    try {
+      input = parseInput(value);
+      if (signal?.aborted) throw new AdvisorError('cancelled');
+      session = this.reserve(input);
+      diagnosticModel = session.model ? { ...session.model } : undefined;
+      selectionSource = session.selectionSource ?? 'unknown';
+      controller = new AbortController();
+      session.pending = controller;
+      relay = () => controller!.abort(new AdvisorError('cancelled'));
+      signal?.addEventListener('abort', relay, { once: true });
+      timeoutMs = session.timeoutMs ?? this.limits.timeoutMs;
+      armDeadline();
+      const pending: Exchange[] = [...session.history, { role: 'user', text: input.message }];
+      phase = 'preparation';
+      const selected = session.model ?? await interruptible(() => {
+        progress(deps, 'preparing');
+        if (controller!.signal.aborted) throw controller!.signal.reason;
+        return deps.prepare((model, source) => {
+          // A late preparation must not mutate pinned state or the returned diagnostics.
+          if (!finished && phase === 'preparation' && !controller!.signal.aborted) { diagnosticModel = { ...model }; selectionSource = source; }
+        }, configured => {
+          if (!finished && phase === 'preparation' && !controller!.signal.aborted) {
+            timeoutMs = parseTimeoutMs(configured);
+            armDeadline();
+          }
+        });
+      }, controller.signal);
+      if (performance.now() - started >= timeoutMs) throw new AdvisorError('timeout');
+      const model = { ...selected };
+      const window = session.contextWindow ?? deps.getContextWindow?.(model);
+      if (!Number.isSafeInteger(window) || window < 1) throw new AdvisorError('model-unavailable');
+      // Pin before awaiting model work. The map identity guards against lifecycle invalidation.
+      session.model = model;
+      session.contextWindow = window;
+      session.selectionSource = selectionSource;
+      session.timeoutMs = timeoutMs;
+      diagnosticModel = { ...model };
+      checkLimit('context-tokens', window, contextUsage(context(pending, model).messages, window).tokens);
+      phase = 'completion';
+      const reply = await interruptible(() => {
+        progress(deps, 'waiting');
+        if (controller!.signal.aborted) throw controller!.signal.reason;
+        if (performance.now() - started >= timeoutMs) throw new AdvisorError('timeout');
+        usageComplete = false;
+        return deps.complete(model, context(pending, model), {
+          signal: controller!.signal, timeoutMs: Math.max(1, Math.floor(timeoutMs - (performance.now() - started))), maxRetries: 0,
+          cacheRetention: 'short', sessionId: session!.id,
+          ...(model.reasoning && model.reasoning !== 'default' && model.reasoning !== 'off' ? { reasoning: model.reasoning } : {})
+        });
+      }, controller.signal);
+      phase = 'response-validation';
+      if (reply.stopReason === 'error') terminalHint = diagnosticsEnabled ? terminalDiagnostics(reply, model.provider) : { category: 'provider-error' };
+      if (reply.stopReason === 'aborted') terminalHint = { category: 'provider-aborted' };
+      usage = addUsage(usage, reply.usage);
+      usageComplete = true;
+      const response = replyText(reply);
+      const opaque = replay(reply, model);
+      const next: Exchange[] = [...pending, { role: 'assistant', text: response, usage: structuredClone(usage), ...(opaque ? { replay: opaque } : {}) }];
+      const nextContext = contextUsage(context(next, model).messages, window);
+      checkLimit('context-tokens', window, nextContext.tokens);
+      phase = 'commit';
+      if (controller.signal.aborted || this.sessions.get(session.id) !== session) throw new AdvisorError('cancelled');
+      if (performance.now() - started >= timeoutMs) throw new AdvisorError('timeout');
+      session.history = next;
+      session.usage = addUsage(session.usage, usage);
+      return { ok: true, advisory: true, session: session.id, response, turns: next.length / 2, model: { ...model }, usage, usageComplete, contextUsage: nextContext, ...totals(session, false) };
+    } catch (error) {
+      if (session && controller && session.history.length === 0 && this.sessions.get(session.id) === session) this.sessions.delete(session.id);
+      // Only the request owner updates accounting. Rejected replies still consume resources.
+      if (session && controller && session.history.length > 0 && this.sessions.get(session.id) === session) {
+        session.usage = addUsage(session.usage, usage);
+        session.totalUsageComplete &&= usageComplete;
+      }
+      const existing = requestedSession ? this.sessions.get(requestedSession) : undefined;
+      const result = failure(error, usage, requestedSession, usageComplete);
+      if (diagnosticsEnabled) result.error.diagnostics = {
+        phase,
+        category: error instanceof AdvisorError ? 'advisor-error' : phase === 'completion' ? completionCategory(error) : 'local-error',
+        ...terminalHint,
+        ...(diagnosticModel ? { model: { ...diagnosticModel }, selectionSource } : {})
+      };
+      return { ...result, ...(existing ? { ...totals(existing, existing.pending !== controller && Boolean(existing.pending)), ...(existing.contextWindow && existing.model ? { contextUsage: retainedContext(existing) } : {}) } : {}) };
+    } finally {
+      finished = true;
+      if (timer) clearTimeout(timer);
+      if (relay) signal?.removeEventListener('abort', relay);
+      if (session && controller && session.pending === controller) session.pending = undefined;
+    }
+  }
+  private reserve(input: ReturnType<typeof parseInput>): Session {
+    if (input.session !== undefined) {
+      const existing = this.sessions.get(input.session);
+      if (!existing) throw new AdvisorError('not-found');
+      if (existing.pending) throw new AdvisorError('busy');
+      return existing;
+    }
+    const session: Session = { id: 'adv_' + randomUUID(), label: Array.from(input.message.trim().replace(/\s+/gu, ' ')).slice(0, 80).join(''), history: [], usage: zeroUsage(), totalUsageComplete: true };
+    this.sessions.set(session.id, session);
+    return session;
+  }
+}

package/lib/settings-command.ts

@@ -0,0 +1,105 @@
+import { getAgentDir, type ExtensionAPI, type ExtensionCommandContext, type ExtensionContext } from '@earendil-works/pi-coding-agent';
+import type { Api, Model } from '@earendil-works/pi-ai';
+import { AdvisorError, LIMITS, REASONING_LEVELS, parseSelection, parseTimeoutMs, type Reasoning, type Selection } from './protocol.ts';
+import { argumentCompletions, type CompletionContext } from './completions.ts';
+import { assertReasoning, supportedReasoning } from './reasoning.ts';
+import { selectModel } from './model-picker.ts';
+import { loadSettings, saveSettings, settingsPaths, type LoadedSettings, type Scope } from './settings.ts';
+
+const USAGE = 'Usage: /advisor [--global|--project] [show | model <provider> <model> | reasoning [level] | timeout [milliseconds|default]]. Bare command opens model selection with UI. Saves default to global.';
+export function resolveModel(ctx: ExtensionContext, pair: Selection, requireAuth: boolean): Model<Api> {
+  const model = ctx.modelRegistry.find(pair.provider, pair.model);
+  if (!model || model.api === 'pi-virtual' || (requireAuth && !ctx.modelRegistry.hasConfiguredAuth(model))) throw new AdvisorError('model-unavailable');
+  assertReasoning(model, pair.reasoning);
+  return model;
+}
+function parseCommand(args: string): { scope: Scope; show: boolean; pair?: Selection; reasoning?: Reasoning; reasoningQuery?: boolean; timeout?: number | 'default'; timeoutQuery?: boolean } {
+  const tokens = args.trim() ? args.trim().split(/\s+/) : [];
+  const flags = tokens.filter(t => t.startsWith('--'));
+  if (flags.length > 1 || flags.some(f => f !== '--global' && f !== '--project')) throw new AdvisorError('invalid-argument');
+  const scope = flags[0] === '--project' ? 'project' : 'global';
+  const rest = tokens.filter(t => !t.startsWith('--'));
+  if (!rest.length) return { scope, show: false };
+  if (rest.length === 1 && rest[0] === 'show') return { scope, show: true };
+  if (rest[0] === 'timeout') {
+    if (rest.length === 1) return { scope, show: false, timeoutQuery: true };
+    if (rest.length === 2 && rest[1] === 'default') return { scope, show: false, timeout: 'default' };
+    if (rest.length === 2 && /^[0-9]+$/.test(rest[1])) return { scope, show: false, timeout: parseTimeoutMs(Number(rest[1]), 'invalid-argument') };
+    throw new AdvisorError('invalid-argument');
+  }
+  if (rest[0] === 'reasoning') {
+    if (rest.length === 1) return { scope, show: false, reasoningQuery: true };
+    if (rest.length === 2 && REASONING_LEVELS.includes(rest[1] as Reasoning)) return { scope, show: false, reasoning: rest[1] as Reasoning };
+    throw new AdvisorError('invalid-argument');
+  }
+  if (rest.length === 3 && rest[0] === 'model') return { scope, show: false, pair: parseSelection({ provider: rest[1], model: rest[2] }) };
+  throw new AdvisorError('invalid-argument');
+}
+function describe(loaded: LoadedSettings): string {
+  const pair = loaded.settings.model;
+  return `Advisor model: ${pair ? `${pair.provider}/${pair.model} (${loaded.source})` : 'not configured'}. Reasoning: ${pair?.reasoning ?? 'default (legacy provider behavior)'}. Timeout: ${loaded.settings.timeoutMs ?? LIMITS.timeoutMs} ms (${loaded.timeoutSource ?? 'default'}). Configuration changes affect new consultations only.`;
+}
+async function pick(ctx: ExtensionCommandContext, current?: Selection): Promise<Selection | undefined> {
+  const models = ctx.modelRegistry.getAvailable().filter(m => m.api !== 'pi-virtual');
+  if (!models.length) throw new AdvisorError('model-unavailable');
+  return selectModel(ctx, 'Advisor model', models, current);
+}
+export function registerSettingsCommand(pi: ExtensionAPI): (ctx?: CompletionContext) => void {
+  let context: CompletionContext | undefined;
+  let contextRevision = 0;
+  const report = (ctx: ExtensionCommandContext, text: string, level: 'info' | 'error'): void => {
+    if (ctx.hasUI) ctx.ui.notify(text, level);
+    else pi.sendMessage({ customType: 'advisor-settings', content: text, display: true, details: { level } }, { triggerTurn: false });
+  };
+  pi.registerCommand('advisor', {
+    description: 'Configure the isolated advisor: picker, show, model <provider> <model>, reasoning [level], timeout [milliseconds|default], --global/--project',
+    async getArgumentCompletions(prefix) {
+      const revision = contextRevision;
+      const items = await argumentCompletions(prefix, context);
+      return revision === contextRevision ? items : null;
+    },
+    async handler(args, ctx) {
+      const paths = settingsPaths(ctx.cwd, getAgentDir());
+      let saveStarted = false;
+      try {
+        let command: ReturnType<typeof parseCommand>;
+        try { command = parseCommand(args); } catch { report(ctx, USAGE, 'error'); return; }
+        const loaded = await loadSettings(paths, ctx.isProjectTrusted());
+        if (command.timeoutQuery) { report(ctx, describe(loaded), 'info'); return; }
+        if (command.reasoningQuery) {
+          const pair = loaded.settings.model;
+          if (!pair) throw new AdvisorError('not-configured');
+          const model = ctx.modelRegistry.find(pair.provider, pair.model);
+          if (!model || model.api === 'pi-virtual') throw new AdvisorError('model-unavailable');
+          report(ctx, `${describe(loaded)}\nSupported advisor reasoning: ${supportedReasoning(model).join(', ')}.\nUse /advisor [--global|--project] reasoning <level>. Higher reasoning can increase cost and latency.`, 'info');
+          return;
+        }
+        if (command.show || (!command.pair && command.reasoning === undefined && command.timeout === undefined && !ctx.hasUI)) { report(ctx, `${describe(loaded)}\n${USAGE}\nglobal: ${paths.global}\nproject: ${paths.project}${ctx.isProjectTrusted() ? '' : ' (ignored: untrusted)'}`, 'info'); return; }
+        if (command.scope === 'project' && !ctx.isProjectTrusted()) throw new AdvisorError('settings-unavailable');
+        await ctx.waitForIdle();
+        if (command.timeout !== undefined) {
+          const settings = command.timeout === 'default' ? {} : { timeoutMs: command.timeout };
+          saveStarted = true;
+          await saveSettings(paths, command.scope, settings, ctx.isProjectTrusted(), 'model');
+          report(ctx, `Saved ${command.scope} settings at ${paths[command.scope]}.\n${describe(await loadSettings(paths, ctx.isProjectTrusted()))}`, 'info');
+          return;
+        }
+        let pair: Selection | undefined;
+        if (command.reasoning !== undefined) {
+          const target = command.scope === 'global' ? await loadSettings(paths, false) : loaded;
+          if (!target.settings.model) throw new AdvisorError('not-configured');
+          pair = { ...target.settings.model, reasoning: command.reasoning };
+        } else pair = command.pair ?? await pick(ctx, loaded.settings.model);
+        if (!pair) { report(ctx, 'Advisor configuration cancelled. Settings unchanged.', 'info'); return; }
+        resolveModel(ctx, pair, false);
+        saveStarted = true;
+        await saveSettings(paths, command.scope, { model: pair }, ctx.isProjectTrusted(), 'timeoutMs');
+        report(ctx, `Saved ${command.scope} settings at ${paths[command.scope]}.\n${describe(await loadSettings(paths, ctx.isProjectTrusted()))}`, 'info');
+      } catch (error) {
+        const message = error instanceof AdvisorError ? error.message : 'Cannot configure advisor settings.';
+        report(ctx, `${message}\n${saveStarted ? 'A save may have completed. Inspect before retrying.' : 'This command did not save settings.'}\nUse /advisor show to inspect.`, 'error');
+      }
+    }
+  });
+  return ctx => { context = ctx; contextRevision++; };
+}

package/lib/settings.ts

@@ -0,0 +1,99 @@
+import { constants } from 'node:fs';
+import { lstat, open, mkdir, rename, link, unlink, type FileHandle } from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { dirname, join } from 'node:path';
+import { withFileMutationQueue } from '@earendil-works/pi-coding-agent';
+import { AdvisorError, object, parseSelection, parseTimeoutMs, type Selection } from './protocol.ts';
+
+const MAX_SETTINGS_BYTES = 16384;
+
+export type Settings = { model?: Selection; timeoutMs?: number };
+export type Scope = 'global' | 'project';
+export type SettingsPaths = Record<Scope, string>;
+export type LoadedSettings = { settings: Settings; source?: Scope; timeoutSource?: Scope };
+export function settingsPaths(cwd: string, agentDir: string): SettingsPaths { return { global: join(agentDir, 'advisor.json'), project: join(cwd, '.pi', 'advisor.json') }; }
+export function parseSettings(value: unknown): Settings {
+  const settings = object(value, ['model', 'timeoutMs'], 'invalid-config');
+  return {
+    ...(settings.model === undefined ? {} : { model: parseSelection(settings.model) }),
+    ...(settings.timeoutMs === undefined ? {} : { timeoutMs: parseTimeoutMs(settings.timeoutMs) })
+  };
+}
+function missing(error: unknown): boolean { return Boolean(error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT'); }
+function safe(error: unknown): never { throw error instanceof AdvisorError ? error : new AdvisorError('settings-unavailable'); }
+async function checkParent(path: string): Promise<void> {
+  try { const stat = await lstat(dirname(path)); if (!stat.isDirectory() || stat.isSymbolicLink()) throw new AdvisorError('settings-unavailable'); }
+  catch (error) { if (!missing(error)) safe(error); }
+}
+async function readLayer(path: string): Promise<{ settings: Settings; raw?: Buffer }> {
+  let handle: FileHandle | undefined;
+  try {
+    await checkParent(path);
+    const stat = await lstat(path);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new AdvisorError('settings-unavailable');
+    handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    const opened = await handle.stat();
+    if (!opened.isFile()) throw new AdvisorError('settings-unavailable');
+    if (opened.size > MAX_SETTINGS_BYTES) throw new AdvisorError('invalid-config');
+    const buffer = Buffer.alloc(MAX_SETTINGS_BYTES + 1);
+    let length = 0;
+    while (length < buffer.length) {
+      const { bytesRead } = await handle.read(buffer, length, buffer.length - length, length);
+      if (!bytesRead) break;
+      length += bytesRead;
+    }
+    if (length > MAX_SETTINGS_BYTES) throw new AdvisorError('invalid-config');
+    const raw = buffer.subarray(0, length);
+    try { return { settings: parseSettings(JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(raw))), raw }; }
+    catch { throw new AdvisorError('invalid-config'); }
+  } catch (error) { if (missing(error)) return { settings: {} }; return safe(error); }
+  finally { try { await handle?.close(); } catch (error) { safe(error); } }
+}
+export async function loadSettings(paths: SettingsPaths, trusted: boolean): Promise<LoadedSettings> {
+  const global = (await readLayer(paths.global)).settings;
+  const project = trusted ? (await readLayer(paths.project)).settings : {};
+  const model = project.model ?? global.model, timeoutMs = project.timeoutMs ?? global.timeoutMs;
+  return {
+    settings: { ...(model ? { model } : {}), ...(timeoutMs === undefined ? {} : { timeoutMs }) },
+    ...(model ? { source: project.model ? 'project' as const : 'global' as const } : {}),
+    ...(timeoutMs === undefined ? {} : { timeoutSource: project.timeoutMs === undefined ? 'global' as const : 'project' as const })
+  };
+}
+export async function saveSettings(paths: SettingsPaths, scope: Scope, value: unknown, trusted: boolean, preserve?: keyof Settings): Promise<void> {
+  if (scope === 'project' && !trusted) throw new AdvisorError('settings-unavailable');
+  const settings = parseSettings(value);
+  const path = paths[scope];
+  try {
+    await withFileMutationQueue(path, async () => {
+      await checkParent(path); await mkdir(dirname(path), { recursive: true }); await checkParent(path);
+      const lockPath = path + '.lock', temp = path + '.' + randomUUID() + '.tmp';
+      let lock: FileHandle | undefined;
+      let ownedTemp = false;
+      try {
+        lock = await open(lockPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+        const before = await readLayer(path);
+        // Preserve the independent field from the locked checkpoint, not a prior command read.
+        const next = { ...(preserve ? { [preserve]: before.settings[preserve] } : {}), ...settings };
+        const text = JSON.stringify(next, null, 2) + '\n';
+        if (Buffer.byteLength(text) > MAX_SETTINGS_BYTES) throw new AdvisorError('invalid-config');
+        const output = await open(temp, 'wx', 0o600); ownedTemp = true;
+        try { await output.writeFile(text, 'utf8'); await output.sync(); } finally { await output.close(); }
+        const current = await readLayer(path);
+        if (before.raw ? !current.raw?.equals(before.raw) : current.raw !== undefined) throw new AdvisorError('settings-unavailable');
+        if (before.raw) await rename(temp, path);
+        else await link(temp, path);
+      } finally {
+        try { if (ownedTemp) { try { await unlink(temp); } catch (error) { if (!missing(error)) throw 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 AdvisorError('settings-unavailable');
+              await unlink(lockPath);
+            } finally { await lock.close(); }
+          }
+        }
+      }
+    });
+  } catch (error) { safe(error); }
+}

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@neruok/pi-advisor",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "license": "MIT",
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "type": "module",
+  "description": "Isolated, multi-turn advice for Pi agents",
+  "keywords": ["pi-package", "pi-extension", "advisor", "coding-agent"],
+  "repository": { "type": "git", "url": "git+https://github.com/neruok/pi-advisor.git" },
+  "homepage": "https://github.com/neruok/pi-advisor#readme",
+  "bugs": { "url": "https://github.com/neruok/pi-advisor/issues" },
+  "pi": { "extensions": ["./advisor.ts"] },
+  "files": ["advisor.ts", "lib/*.ts", "README.md", "docs/pi-advisor.md"],
+  "engines": { "node": ">=24" },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": { "optional": true },
+    "@earendil-works/pi-ai": { "optional": true },
+    "@earendil-works/pi-tui": { "optional": true },
+    "typebox": { "optional": true }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.0.4",
+    "@earendil-works/pi-ai": "1.0.4",
+    "@earendil-works/pi-tui": "1.0.4",
+    "typebox": "1.3.27",
+    "typescript": "5.9.3",
+    "@types/node": "26.6.4"
+  },
+  "scripts": {
+    "check": "node --test tests/*.test.mjs",
+    "typecheck": "tsc --noEmit",
+    "verify": "npm run typecheck && npm run check",
+    "packcheck": "node scripts/check-package.mjs",
+    "prepublishOnly": "npm run verify && npm run packcheck"
+  }
+}