@n8r/surface 0.0.0-stage → 0.1.0-experimental.2

package/README.md

@@ -1,3 +1,182 @@
-# Temporary Holding Version
+# n8r-surface
 
-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.
+The home of the **AI Surface Model**, an open model for describing the connected
+components, configuration and relationships of an AI system, at the level of
+detail available or useful. This repository also develops the experimental
+`n8r-surface` command and Researcher library.
+
+> [!NOTE]
+> **Early draft; experimental tooling.** The model concepts and illustrative
+> fields remain provisional. The library and command are unreleased;
+> there is no universal schema, exporter or deployment engine yet. The Researcher
+> skill supports working research through the host. The standalone command now
+> supports bounded Codex research with numbered Markdown saves and fresh-session reopening.
+
+## Why this is needed
+
+An AI model's name does not tell you which services an application calls, how
+authentication is configured, or which setup produced an Experiment result.
+Answering those questions can mean piecing together diagrams, configuration files
+and notes, often with incomplete information.
+
+The AI Surface Model aims to make that context explicit and shareable. Start with
+the components and connections you know, record the gaps, and add detail as it
+becomes available. A saved description should help someone investigate a system,
+understand a result or assess what they would need to recreate a setup.
+
+## Who it is for
+
+| If you… | The model is intended to help you… |
+| --- | --- |
+| Build or operate AI applications | Describe services, integration settings and dependencies across a setup. |
+| Investigate security or component changes | Find affected components while keeping unknown versions and coverage gaps visible. |
+| Run experiments | Connect results to the definition revision and effective setup actually used. |
+| Build inventory, provenance or analysis tools | Explore exchange of a defined subset with explicit mapping losses. |
+
+It is usable independently of Injectionator or any particular application.
+Security investigation, reproducibility and configuration understanding are all
+part of its scope.
+
+For a compact security view, start with the provisional
+[Skeleton Surface v0.1](spec/README.md#output-profiles-and-size): key nodes,
+relationships and potential LLM/tool interception points, with linked evidence
+and explicit gaps. Bindings are optional; larger research is not a minimum size.
+
+This repository maintains the model and standalone tooling. Application design
+and implementation for `n8r-labs` are maintained in its separate repository.
+
+## What it describes
+
+An **AI Surface** is the connected system being described: applications, agents,
+AI models, inference services, authentication, tools, data stores and supporting
+infrastructure, together with their configuration and relationships.
+
+There is one model: the **AI Surface Model**. A **fragment** is a working term
+for a focused part of a description within it, such as Lab or Experiment; fragment
+boundaries and serialization remain open. A Lab contains Experiments, and each
+Experiment requests its setup directly from the Lab.
+
+Definitions stay separate from deployments, dated observations and Experiment
+Runs. A Run refers to the definition revision and effective setup used, so later
+discovery does not silently change what an earlier result refers to.
+
+## Experimental tooling
+
+The [Researcher library](docs/n8r-surface/contracts.md) reads and writes bounded
+HTML research records and partial definitions in JSON/YAML, with
+[synthetic acceptance cases](examples/researcher/README.md). These checks do not
+establish universal model conformance or consumer compatibility.
+
+**To try the command, follow [Install, run and check research](docs/n8r-surface/getting-started.md).**
+
+The [bare-startup command](docs/n8r-surface/startup.md) displays local settings and
+saved artefacts, then offers explicitly confirmed local vault setup or reuses the
+saved vault. The explicit `discover [source]` command now starts a
+[Codex research conversation](docs/n8r-surface/codex-research-verification.md)
+with source evidence, follow-up, explicit Markdown saves and fresh-session reopening.
+See [save/reopen evidence and limits](docs/n8r-surface/save-reopen-verification.md).
+The current candidate adds validated paired research HTML and partial Surface JSON,
+with fresh-session revision; see the [candidate evidence and limits](docs/n8r-surface/surface-revisions-verification.md). See the
+[critical path](docs/n8r-surface/critical-path.md) for the next work and the
+[command outcome specification](docs/n8r-surface/command-outcomes.md) for the
+intended interactions and required evidence.
+
+The [n8r-surface Researcher skill package](docs/n8r-surface/researcher-skill.md) is now
+available for testing in the existing Codex/ChatGPT harness. It uses the host's
+source access and conversation to produce evidence-backed working notes. The
+[discovery guide](docs/n8r-surface/researcher-discovery.md) focuses on AI-relevant
+graphs, reusable product knowledge and comparing descriptions with evidence. See
+[verification and pending Work-mode checks](docs/n8r-surface/researcher-skill-verification.md).
+The delivery order is skill first, n8r-labs adaptation second, standalone CLI third.
+The [local vault](docs/n8r-surface/researcher-vault.md) holds research notes, intermediate artifacts
+and Surface descriptions at a user-selected local path. It also includes prepared test material
+and a walkthrough for investigating another chat-system repository.
+
+## Start at the depth you need
+
+The levels are reading paths, not prerequisites. Start at 100 for an introduction,
+or jump to the examples, design questions or contribution guidance.
+
+| Level | Start here | What you will find |
+| --- | --- | --- |
+| **100 · Understand** | [Model overview](models/ai-surface-model.md), then [Conceptual guide](models/README.md) | The purpose, vocabulary and a walkthrough of one investigation. |
+| **200 · Explore** | [Synthetic examples](examples/README.md) | Compare descriptions at two depths; identify known facts, gaps and recreation requirements. |
+| **300 · Examine** | [Draft concepts](spec/README.md) and [interoperability research](docs/interoperability.md) | Identity, evidence, partial knowledge, open decisions and proposed mappings to other formats. |
+| **400 · Contribute and extend** | [Propose a change or extension](CONTRIBUTING.md#propose-a-change-or-extension) | Turn a use case into a proposal, example or bounded mapping, then follow the contribution workflow. |
+
+The [roadmap](docs/roadmap.md) describes the intended sequence of work and the
+evidence needed before a release.
+
+## See progressive detail
+
+Both [LibreChat examples](examples/README.md) describe a fictional authentication
+path. These JSON excerpts show the **same component** at two levels of detail.
+Field names are illustrative, not a released schema.
+
+In the [minimal description](examples/librechat/minimal.json), its role is known
+but its product is not:
+
+```json
+{
+  "id": "component:authentication",
+  "kind": "service",
+  "role": "authentication",
+  "product": { "status": "unknown" }
+}
+```
+
+In the [expanded description](examples/librechat/expanded.json), the same identity
+has more detail:
+
+```json
+{
+  "id": "component:authentication",
+  "kind": "service",
+  "role": "authentication",
+  "product": {
+    "status": "known",
+    "name": "Keycloak",
+    "basis": "synthetic example"
+  }
+}
+```
+
+The expanded file also describes an OpenID Connect relationship and a supporting
+database. Some settings remain unknown or omitted; inference and other application
+dependencies remain unexplored. Neither example establishes a running integration
+or enough information for recreation. They are alternative synthetic descriptions,
+not a revision history or evidence of a deployment change.
+
+Detail can grow along any connection, with shared components and cycles. Depth is
+relative to the starting point and has no fixed two-hop ceiling. Missing detail
+does not establish absence.
+
+## Working with existing standards and tools
+
+We intend to exchange supported subsets through CycloneDX and SPDX, using native
+constructs where suitable and reporting omitted or transformed information.
+Compatibility and round-trip fidelity still need evidence from named versions and
+consuming tools. See the [interoperability research](docs/interoperability.md) for
+mapping questions and related work, including Prismor and sbom-tools.
+
+## Contribute or cite
+
+Start with an issue, use a dedicated branch and open a linked draft PR; see
+[Contributing](CONTRIBUTING.md) for proposals, checks and the full workflow.
+
+Use [CITATION.cff](CITATION.cff) for attribution and include the exact commit URL
+you used when citing this evolving draft.
+
+## Licence
+
+Machine-readable model assets, schemas, examples, code snippets and tooling use
+[Apache-2.0](LICENSE). Written specification and documentation use
+[CC-BY-4.0](LICENSE-DOCS). See [LICENSING.md](LICENSING.md) for the material split
+and attribution requirements.
+
+Commercial and proprietary reuse are welcome under those terms. Users retain
+control of the licensing and publication of their own Surface descriptions and
+Experiment data. Third-party material retains its applicable terms.
+
+This is an independent Injectionator project, with no claimed OWASP affiliation
+or endorsement.

package/dist/activity.d.ts

@@ -0,0 +1,16 @@
+import type { Writable } from 'node:stream';
+/** Terminal liveness only: elapsed time does not imply remote progress. */
+export declare class Activity {
+    private stream;
+    private label;
+    private started;
+    private frame;
+    private timer;
+    constructor(stream?: Writable & {
+        isTTY?: boolean;
+    });
+    private clear;
+    private draw;
+    log(text: string): void;
+    run<T>(label: string, action: () => Promise<T>): Promise<T>;
+}

package/dist/activity.js

@@ -0,0 +1,44 @@
+/** Terminal liveness only: elapsed time does not imply remote progress. */
+export class Activity {
+    stream;
+    label;
+    started = 0;
+    frame = 0;
+    timer;
+    constructor(stream = process.stdout) {
+        this.stream = stream;
+    }
+    clear() { if (this.label && this.stream.isTTY)
+        this.stream.write('\r\x1b[2K'); }
+    draw() {
+        if (this.label && this.stream.isTTY) {
+            const frames = ['|', '/', '-', '\\'];
+            this.stream.write(`\r\x1b[2K${frames[this.frame++ % frames.length]} ${this.label}… ${Math.floor((Date.now() - this.started) / 1000)}s (Ctrl-C to cancel)`);
+        }
+    }
+    log(text) {
+        this.clear();
+        this.stream.write(text);
+        this.draw();
+    }
+    async run(label, action) {
+        this.label = label;
+        this.started = Date.now();
+        this.frame = 0;
+        if (this.stream.isTTY) {
+            this.draw();
+            this.timer = setInterval(() => this.draw(), 250);
+            this.timer.unref();
+        }
+        try {
+            return await action();
+        }
+        finally {
+            if (this.timer)
+                clearInterval(this.timer);
+            this.timer = undefined;
+            this.clear();
+            this.label = undefined;
+        }
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+import { overview } from './startup.js';
+import { chooseVault, inspectVault, saveSetup } from './setup.js';
+import { line, problem, loadSettings, localPath, InspectionError } from './settings.js';
+import { SourceTools } from './source-tools.js';
+import { ResearchConversation } from './codex.js';
+import { Activity } from './activity.js';
+import { Notes, readNote, latestNote } from './notes.js';
+import { SurfaceStore, readSurfacePair } from './surface-store.js';
+import { previewSurface } from './surface-draft.js';
+async function setup(config) {
+    const existing = config.vault === undefined ? undefined : inspectVault(config.vault);
+    if (existing && !existing.missing) {
+        console.log(`Vault ready: ${line(existing.root)}`);
+        return 0;
+    }
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        console.log('Vault setup required; run n8r-surface in an interactive terminal.');
+        return 1;
+    }
+    const input = createInterface({ input: process.stdin, output: process.stdout });
+    let closed = false;
+    input.once('close', () => { closed = true; });
+    const cancel = () => input.close();
+    input.on('SIGINT', cancel);
+    process.on('SIGINT', cancel);
+    const ask = (prompt) => new Promise(resolve => {
+        if (closed) {
+            resolve(undefined);
+            return;
+        }
+        const ended = () => resolve(undefined);
+        input.once('close', ended);
+        input.question(prompt, answer => {
+            input.removeListener('close', ended);
+            resolve(answer);
+        });
+    });
+    try {
+        let vault = existing?.root;
+        if (vault === undefined) {
+            const answer = await ask('Vault directory [~/n8r/]: ');
+            if (answer === undefined)
+                return 1;
+            vault = chooseVault(answer === '' ? '~/n8r/' : answer, config.home, process.cwd());
+            inspectVault(vault);
+        }
+        console.log(`Vault directory: ${line(vault)}`);
+        if (existing)
+            console.log('Required vault folders are missing; confirmation will create them.');
+        const answer = await ask('Create vault folders and save this location? [y/N] ');
+        if (answer === undefined || !/^y(es)?$/i.test(answer.trim()))
+            return 1;
+        const saved = saveSetup(config, vault, process.cwd());
+        console.log(`Vault ready: ${line(saved)}`);
+        return 0;
+    }
+    finally {
+        input.close();
+        process.removeListener('SIGINT', cancel);
+    }
+}
+const help = `n8r-surface — experimental local AI Surface research
+
+  n8r-surface                        Set up or show your local vault
+  n8r-surface discover [source]       Research a directory or file (default: cwd)
+  n8r-surface discover [source] --model MODEL
+  n8r-surface reopen [NOTE] --source SOURCE [--model MODEL]
+                                    Continue a note or pair; omit NOTE for latest edited note
+  n8r-surface --help                  Show this help
+  n8r-surface --version               Show package version
+
+Discovery requires a configured vault, an interactive terminal, and Codex CLI
+0.166.0 signed in with ChatGPT. You confirm before source text is sent to OpenAI.
+Uses your configured Codex model unless --model selects one; no fallback.
+Source tools list, search and read bounded UTF-8 text. Hidden entries, dependency
+folders, symlinks, key files and oversized/binary files are excluded.
+No source execution, edits or web access. /save writes numbered Markdown notes.
+Ask for a Surface to preview it; /save surface saves that exact HTML/JSON pair.
+Reopen either research.html or surface.json from a saved pair to revise it.
+Reopen confirms note/source transmission again; no old Codex thread is restored.
+Codex manages its own auth/cache/diagnostics. /exit ends the chat; Ctrl-C cancels.`;
+async function discover(args, reopening = false) {
+    let source, model, notePath;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--model' && model === undefined && args[i + 1] && /^[a-zA-Z0-9._-]{1,100}$/.test(args[i + 1]))
+            model = args[++i];
+        else if (reopening && arg === '--source' && source === undefined && args[i + 1] && !args[i + 1].startsWith('-'))
+            source = args[++i];
+        else if (reopening && !arg.startsWith('-') && notePath === undefined)
+            notePath = arg;
+        else if (!reopening && !arg.startsWith('-') && source === undefined)
+            source = arg;
+        else
+            throw new InspectionError('Unsupported arguments; run n8r-surface discover --help');
+    }
+    if (reopening && !source)
+        throw new InspectionError('Reopen requires --source SOURCE; source access must be selected again');
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        console.log('Discovery requires an interactive terminal; no research started.');
+        return 1;
+    }
+    const config = loadSettings();
+    if (!config.vault || inspectVault(config.vault).missing) {
+        console.log('Vault setup required; run n8r-surface first.');
+        return 1;
+    }
+    const tools = new SourceTools(localPath(source ?? process.cwd(), config.home, process.cwd()));
+    console.log(`Research source: ${line(tools.selected)} (${tools.file ? 'one file' : 'directory'})`);
+    console.log('Inspected source text and your messages will be sent to OpenAI through Codex using ChatGPT sign-in.');
+    console.log('Source access is read-only. /save saves a Markdown note; /save surface saves a previewed HTML/JSON pair.');
+    const input = createInterface({ input: process.stdin, output: process.stdout });
+    const controller = new AbortController();
+    let closed = false, interrupted = false;
+    let session;
+    input.once('close', () => { closed = true; controller.abort(); });
+    const cancel = () => { interrupted = true; controller.abort(); input.close(); };
+    input.on('SIGINT', cancel);
+    process.on('SIGINT', cancel);
+    const ask = (prompt) => new Promise(resolve => {
+        if (closed) {
+            resolve(undefined);
+            return;
+        }
+        const ended = () => resolve(undefined);
+        input.once('close', ended);
+        input.question(prompt, answer => { input.removeListener('close', ended); resolve(answer); });
+    });
+    const activity = new Activity();
+    const output = (text) => activity.log(text.split('\n').map(part => line(part)).join('\n') + '\n');
+    try {
+        let note;
+        let pair;
+        if (reopening && notePath && /(?:research\.html|surface\.json)$/.test(notePath)) {
+            pair = readSurfacePair(localPath(notePath, config.home, process.cwd()));
+            console.log(`Saved pair: ${line(pair.directory)}`);
+            console.log('Both saved artefacts and host evidence will be sent to OpenAI after confirmation.');
+        }
+        else if (reopening) {
+            note = notePath ? readNote(localPath(notePath, config.home, process.cwd())) : latestNote(config.vault, tools.selected);
+            if (!note) {
+                console.log('No saved numbered note found for this source. Name a note explicitly or start with discover.');
+                return 1;
+            }
+            console.log(`Saved note: ${line(note.path)}`);
+            console.log(`Last edited: ${note.modifiedAt}`);
+            console.log(`Recorded source: ${line(note.metadata.source.name)} (${note.metadata.source.kind}); this is not verified identity.`);
+            if (!notePath) {
+                const choice = await ask('Open this note? [y/N] ');
+                if (interrupted)
+                    return 130;
+                if (choice === undefined || !/^y(es)?$/i.test(choice.trim()))
+                    return 1;
+            }
+            console.log('The saved note, including human edits, will also be sent to OpenAI after confirmation.');
+        }
+        const notes = new Notes(config.vault, tools.selected, note);
+        const surfaces = new SurfaceStore(config.vault, tools.selected, pair, note);
+        const accepted = await ask('Start research with OpenAI using Codex ChatGPT sign-in? [y/N] ');
+        if (interrupted)
+            return 130;
+        if (accepted === undefined || !/^y(es)?$/i.test(accepted.trim()))
+            return 1;
+        console.log('Connecting to Codex…');
+        session = await activity.run('Connecting to Codex', () => ResearchConversation.start(tools, output, model, controller.signal));
+        console.log(`Connected: ChatGPT sign-in; model ${line(session.model)}.`);
+        console.log(`Researcher ${session.instructions.version}; ${session.instructions.digest}`);
+        console.log('Ask about your source or request a Surface preview. /save saves a note; /save surface saves the preview; /exit ends the chat; Ctrl-C cancels.');
+        if (note)
+            await activity.run('Reopening research', () => session.reopen(note));
+        if (pair)
+            await activity.run('Reopening Surface', () => session.reopenSurface(pair));
+        if (session.surfaceDraft)
+            output(previewSurface(session.surfaceDraft));
+        while (!closed) {
+            const question = await ask('You> ');
+            if (question === undefined || question.trim() === '/exit')
+                break;
+            if (!question.trim())
+                continue;
+            if (question.trim() === '/save surface') {
+                if (!session.surfaceDraft) {
+                    console.log('No current validated Surface preview. Ask to create or update a Surface first.');
+                    continue;
+                }
+                const saved = surfaces.save(session.surfaceDraft, { researcher: { version: session.instructions.version, digest: session.instructions.digest }, model: session.model, evidence: session.evidence });
+                session.acceptSurface(saved);
+                console.log(`Saved and read back: ${line(saved.researchPath)}`);
+                console.log(`Saved and read back: ${line(saved.surfacePath)}`);
+            }
+            else if (question.trim() === '/save') {
+                const destination = notes.next();
+                console.log(`Save destination: ${line(destination)}`);
+                const markdown = await activity.run('Preparing note', () => session.prepareNote());
+                if (closed || controller.signal.aborted)
+                    throw new InspectionError('Research cancelled; nothing saved');
+                const saved = notes.save(destination, markdown, { researcher: { version: session.instructions.version, digest: session.instructions.digest }, model: session.model, evidence: session.evidence });
+                console.log(`Saved and read back: ${line(saved.path)}`);
+                console.log(saved.digest);
+            }
+            else if (question.trim().startsWith('/')) {
+                console.log('Unknown chat command. Use /save, /save surface or /exit.');
+            }
+            else {
+                await activity.run('Waiting for Codex', () => session.turn(question));
+                if (session.surfaceDraft)
+                    output(previewSurface(session.surfaceDraft));
+            }
+        }
+        return interrupted ? 130 : 0;
+    }
+    catch (error) {
+        if (interrupted) {
+            console.log('Research cancelled.');
+            return 130;
+        }
+        if (closed) {
+            console.log('Research input closed; answer incomplete.');
+            return 1;
+        }
+        throw error;
+    }
+    finally {
+        if (session)
+            await session.close();
+        input.close();
+        process.removeListener('SIGINT', cancel);
+    }
+}
+const args = process.argv.slice(2);
+try {
+    if ((args.length === 1 && args[0] === '--help') || (args.length === 2 && ['discover', 'reopen'].includes(args[0]) && args[1] === '--help'))
+        console.log(help);
+    else if (args.length === 1 && args[0] === '--version')
+        console.log(`n8r-surface ${JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version}`);
+    else if (args[0] === 'reopen')
+        process.exitCode = await discover(args.slice(1), true);
+    else if (args[0] === 'discover')
+        process.exitCode = await discover(args.slice(1));
+    else if (args.length) {
+        console.log('Unsupported arguments; run n8r-surface --help.');
+        process.exitCode = 2;
+    }
+    else {
+        const state = overview();
+        console.log(state.text);
+        console.log('Setup does not start research. Use n8r-surface discover to begin a conversation.');
+        if (state.failed || !state.settings)
+            process.exitCode = 2;
+        else
+            process.exitCode = await setup(state.settings);
+    }
+}
+catch (error) {
+    console.log(`n8r-surface failed: ${problem(error)}`);
+    process.exitCode = 2;
+}

package/dist/codec.d.ts

@@ -0,0 +1,4 @@
+import type { Artefact } from './contracts.js';
+export type Encoding = 'json' | 'yaml';
+export declare function decode(text: string, format: Encoding): Artefact;
+export declare function encode(value: unknown, format: Encoding): string;

package/dist/codec.js

@@ -0,0 +1,41 @@
+import { isAlias, isMap, isNode, isScalar, parseDocument, stringify, visit } from 'yaml';
+import { checkSize, fail, MAX_DEPTH, portable } from './portable.js';
+import { validateArtefact } from './validate.js';
+function formatCheck(format) { if (format !== 'json' && format !== 'yaml')
+    fail('$format', 'unsupported encoding'); }
+export function decode(text, format) {
+    formatCheck(format);
+    checkSize(text);
+    if (format === 'json')
+        JSON.parse(text); // enforce JSON grammar before YAML's duplicate/number checks
+    if (/^%/m.test(text))
+        fail('$', 'YAML directives unsupported');
+    const doc = parseDocument(text, { version: '1.2', schema: 'core', uniqueKeys: true, strict: true });
+    if (doc.errors.length || doc.warnings.length)
+        fail('$', [...doc.errors, ...doc.warnings].map(x => x.message).join('; '));
+    visit(doc, (_key, node, path) => {
+        if (path.length > MAX_DEPTH * 2 + 2)
+            fail('$', 'exceeds depth 64');
+        if (isAlias(node) || (isNode(node) && (node.tag || ('anchor' in node && node.anchor))))
+            fail('$', 'YAML tags/anchors/aliases unsupported');
+        if (isMap(node))
+            for (const pair of node.items) {
+                if (!isScalar(pair.key) || typeof pair.key.value !== 'string')
+                    fail('$', 'mapping keys must be strings');
+                if (format === 'yaml' && pair.key.value === '<<' && pair.key.type !== 'QUOTE_DOUBLE' && pair.key.type !== 'QUOTE_SINGLE')
+                    fail('$', 'unquoted YAML merge keys unsupported');
+            }
+        if (isScalar(node) && typeof node.value === 'number' && !/^-?(0|[1-9][0-9]*)$/.test(node.source ?? ''))
+            fail('$', 'numbers require decimal integer notation');
+    });
+    const data = format === 'json' ? JSON.parse(text) : doc.toJS({ maxAliasCount: 0 });
+    portable(data);
+    return validateArtefact(data);
+}
+export function encode(value, format) {
+    formatCheck(format);
+    const a = validateArtefact(value);
+    const text = format === 'json' ? JSON.stringify(a, null, 2) + '\n' : stringify(a, { version: '1.2', aliasDuplicateObjects: false, lineWidth: 0, defaultKeyType: 'QUOTE_DOUBLE' });
+    checkSize(text);
+    return text;
+}

package/dist/codex.d.ts

@@ -0,0 +1,72 @@
+import { type ChildProcessWithoutNullStreams } from 'node:child_process';
+import { SourceTools } from './source-tools.js';
+import { type Evidence, type Note } from './notes.js';
+import { type SurfaceDraft } from './surface-draft.js';
+import { type SavedSurfacePair } from './surface-store.js';
+type Wire = Record<string, any>;
+export declare class CodexRpc {
+    private child;
+    private event;
+    private serve;
+    private sequence;
+    private pending;
+    private failure;
+    private buffer;
+    constructor(child: ChildProcessWithoutNullStreams, event: (method: string, params: Wire) => void, serve: (method: string, params: Wire) => Promise<unknown>);
+    private send;
+    private receive;
+    private fail;
+    request(method: string, params: unknown, timeout?: number): Promise<Wire>;
+    notify(method: string): void;
+    close(): Promise<void>;
+}
+export declare function researcherInstructions(): {
+    version: string;
+    digest: string;
+    text: string;
+};
+export declare function runnerConfiguration(current: Wire): Wire;
+export declare class ResearchConversation {
+    private source;
+    private output;
+    private signal?;
+    private rpc;
+    private scratch;
+    private threadId;
+    readonly evidence: Evidence[];
+    surfaceDraft: SurfaceDraft | undefined;
+    private pendingSurface;
+    private previousSurface;
+    private saving;
+    private draft;
+    private turnId;
+    private earlyEvents;
+    private ready;
+    private markReady;
+    private active;
+    private cancelled;
+    private closing;
+    private abortListener;
+    readonly instructions: {
+        version: string;
+        digest: string;
+        text: string;
+    };
+    model: string;
+    private constructor();
+    static start(source: SourceTools, output: (text: string) => void, model?: string, signal?: AbortSignal): Promise<ResearchConversation>;
+    private event;
+    private serve;
+    private finish;
+    private recordEvidence;
+    prepareNote(): Promise<string>;
+    acceptSurface(draft: SurfaceDraft): void;
+    reopenSurface(pair: SavedSurfacePair): Promise<void>;
+    reopen(note: Note): Promise<void>;
+    private reopenContext;
+    turn(text: string): Promise<void>;
+    private runTurn;
+    cancel(): Promise<void>;
+    close(): Promise<void>;
+}
+export {};