@qvac/harness 0.2.9 → 0.2.12

package/dist-lib/lib/hooks/built-in/sandbox.js

@@ -0,0 +1,45 @@
+import { planVendoredInstall } from '../../tools/exec/adapters/python/wheels.js';
+import { bareBin, firstCommandToken } from '../../tools/exec/scope.js';
+const NETWORK_BINS = new Set([
+    'curl',
+    'wget',
+    'nc',
+    'ncat',
+    'netcat',
+    'ssh',
+    'scp',
+    'sftp',
+    'rsync',
+    'ftp',
+    'telnet',
+    'git',
+    'npm',
+    'npx',
+    'pnpm',
+    'yarn',
+    'bun',
+    'pip',
+    'pip3',
+    'brew',
+    'dig',
+    'nslookup',
+    'ping',
+    'openssl'
+]);
+export class SandboxHook {
+    phase = 'preToolCall';
+    run(ctx) {
+        if (ctx.phase !== 'preToolCall')
+            return;
+        if (!ctx.sandboxMode || ctx.toolName !== 'exec')
+            return;
+        const packages = ctx.args.packages;
+        if (Array.isArray(packages) && packages.length && !planVendoredInstall(packages.map(String))) {
+            return { error: 'sandbox mode: installing packages reaches the network', guidance: true };
+        }
+        const bin = bareBin(firstCommandToken(String(ctx.args.command ?? '')).replace(/^.*[/\\]/, ''));
+        if (bin && NETWORK_BINS.has(bin)) {
+            return { error: `sandbox mode: ${bin} reaches the network`, guidance: true };
+        }
+    }
+}

package/dist-lib/lib/hooks/built-in/skill-catalog.js

@@ -11,7 +11,12 @@ export class SkillCatalogGuardHook {
         const known = new Set(entries.map((entry) => (typeof entry === 'string' ? entry : entry.name)));
         const raw = ctx.args.name ?? ctx.args.skill_name ?? ctx.args.skill;
         const name = typeof raw === 'string' ? raw : '';
-        if (!known.has(name))
-            return { error: `skill not found: ${name}`, guidance: true };
+        if (known.has(name))
+            return;
+        const listed = [...known].join(', ');
+        const rest = listed
+            ? `The only skills are: ${listed}. Nothing else needs a skill load — answer or act with the tools you already have.`
+            : 'No skill is available this turn — answer or act with the tools you already have.';
+        return { error: `skill not found: ${name}. ${rest}`, guidance: true };
     }
 }

package/dist-lib/lib/hooks/registry.js

@@ -1,6 +1,7 @@
-import { ArgRepairHook, EgressGuardHook, SkillCatalogGuardHook } from './built-in/index.js';
+import { ArgRepairHook, EgressGuardHook, SandboxHook, SkillCatalogGuardHook } from './built-in/index.js';
 export const harnessHooks = [
     new ArgRepairHook(),
     new EgressGuardHook(),
+    new SandboxHook(),
     new SkillCatalogGuardHook()
 ];

package/dist-lib/lib/hooks/types.d.ts

@@ -14,6 +14,7 @@ export interface PreToolCallPayload {
     readonly signal?: BareAbortSignal | undefined;
     readonly skillNames?: readonly string[];
     readonly parameters?: ToolDefinition['parameters'];
+    readonly sandboxMode?: boolean;
     args: Record<string, unknown>;
 }
 export interface PostToolCallPayload {

package/dist-lib/lib/office/index.d.ts

@@ -0,0 +1,6 @@
+import type { AbortSignal } from 'bare-abort-controller';
+export { closePythonWorker as closeOfficeWorker } from '../tools/exec/adapters/python/worker/client.ts';
+export declare function extractOfficeText(bytes: Uint8Array, fileName: string, options?: {
+    readonly signal?: AbortSignal | undefined;
+    readonly mimeType?: string | undefined;
+}): Promise<string>;

package/dist-lib/lib/office/index.js

@@ -0,0 +1,38 @@
+import path from 'path';
+import { extractDocxText } from '../docx/index.js';
+import { extractWithPython } from './python.js';
+import { XLSX_EXTRACT } from './xlsx.js';
+import { PPTX_EXTRACT } from './pptx.js';
+export { closePythonWorker as closeOfficeWorker } from '../tools/exec/adapters/python/worker/client.js';
+const OFFICE_MIME_EXTENSIONS = {
+    'application/vnd.openxmlformats-officedocument.wordprocessingml.document': '.docx',
+    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': '.xlsx',
+    'application/vnd.openxmlformats-officedocument.presentationml.presentation': '.pptx'
+};
+export async function extractOfficeText(bytes, fileName, options = {}) {
+    const mimeType = options.mimeType?.split(';')[0]?.trim().toLowerCase();
+    const suffix = path.extname(fileName).toLowerCase();
+    const extension = ['.docx', '.xlsx', '.pptx'].includes(suffix)
+        ? suffix
+        : OFFICE_MIME_EXTENSIONS[mimeType ?? ''];
+    if (extension === '.docx') {
+        return extractDocxText(bytes, fileName, options);
+    }
+    if (extension === '.xlsx') {
+        return extractWithPython(bytes, fileName, {
+            format: 'XLSX',
+            packages: ['openpyxl==3.1.5'],
+            source: XLSX_EXTRACT,
+            signal: options.signal
+        });
+    }
+    if (extension === '.pptx') {
+        return extractWithPython(bytes, fileName, {
+            format: 'PPTX',
+            packages: ['python-pptx==1.0.2'],
+            source: PPTX_EXTRACT,
+            signal: options.signal
+        });
+    }
+    throw new Error(`Unsupported Office document: ${fileName}`);
+}

package/dist-lib/lib/office/pptx.d.ts

@@ -0,0 +1 @@
+export declare const PPTX_EXTRACT: string;

package/dist-lib/lib/office/pptx.js

@@ -0,0 +1,26 @@
+export const PPTX_EXTRACT = `from pptx import Presentation
+from pptx.enum.shapes import MSO_SHAPE_TYPE
+from pathlib import Path
+
+def text(shapes):
+    for shape in shapes:
+        if shape.shape_type == MSO_SHAPE_TYPE.GROUP:
+            yield from text(shape.shapes)
+        elif shape.has_text_frame:
+            if shape.text.strip():
+                yield shape.text
+        elif shape.has_table:
+            for row in shape.table.rows:
+                cells = ["" if cell.is_spanned else cell.text.replace("\\n", " ") for cell in row.cells]
+                if any(cell.strip() for cell in cells):
+                    yield " | ".join(cells)
+
+with Path("extracted.txt").open("w", encoding="utf-8") as output:
+    for number, slide in enumerate(Presentation("input.pptx").slides, 1):
+        heading = False
+        for block in text(slide.shapes):
+            if not heading:
+                output.write("Slide " + str(number) + "\\n")
+                heading = True
+            output.write(block + "\\n")
+`;

package/dist-lib/lib/office/python.d.ts

@@ -0,0 +1,7 @@
+import type { AbortSignal } from 'bare-abort-controller';
+export declare function extractWithPython(bytes: Uint8Array, fileName: string, { format, packages, source, signal }: {
+    readonly format: string;
+    readonly packages: readonly string[];
+    readonly source: string;
+    readonly signal?: AbortSignal | undefined;
+}): Promise<string>;

package/dist-lib/lib/office/python.js

@@ -0,0 +1,32 @@
+import b4a from 'b4a';
+import fs from 'fs';
+import { runPython } from '../tools/exec/adapters/python/pyodide.js';
+import { planVendoredInstall, vendoredManifest, wheelsDir } from '../tools/exec/adapters/python/wheels.js';
+const MAX_OFFICE_BYTES = 20 * 1024 * 1024;
+export async function extractWithPython(bytes, fileName, { format, packages, source, signal }) {
+    if (bytes.byteLength > MAX_OFFICE_BYTES) {
+        throw new Error(`document is too large to extract: ${bytes.byteLength} bytes, limit ${MAX_OFFICE_BYTES}`);
+    }
+    const dir = wheelsDir();
+    const manifest = vendoredManifest(dir);
+    const install = planVendoredInstall(packages, { dir, manifest });
+    if (!dir ||
+        !manifest ||
+        !install ||
+        !['micropip', ...install.packages].every((name) => Object.keys(manifest.files).some((file) => file.replaceAll('_', '-').startsWith(`${name}-`) && fs.existsSync(`${dir}/${file}`)))) {
+        throw new Error(`bundled ${format} extraction packages are unavailable`);
+    }
+    const result = await runPython(source, {
+        packages,
+        inputs: [{ path: `input.${format.toLowerCase()}`, bytes }],
+        outputs: ['extracted.txt'],
+        signal
+    });
+    if (result.exitCode !== 0)
+        throw new Error(`${fileName}: ${result.stderr.trim()}`);
+    const output = result.files?.get('extracted.txt');
+    if (!output) {
+        throw new Error(result.rejected?.[0]?.reason ?? `${format} extraction produced no text file`);
+    }
+    return b4a.toString(output, 'utf8');
+}

package/dist-lib/lib/office/xlsx.d.ts

@@ -0,0 +1 @@
+export declare const XLSX_EXTRACT: string;

package/dist-lib/lib/office/xlsx.js

@@ -0,0 +1,26 @@
+export const XLSX_EXTRACT = `from openpyxl import load_workbook
+from pathlib import Path
+
+formulas = load_workbook("input.xlsx", read_only=True, data_only=False, keep_links=False)
+values = load_workbook("input.xlsx", read_only=True, data_only=True, keep_links=False)
+try:
+    with Path("extracted.txt").open("w", encoding="utf-8") as output:
+        for sheet in formulas.worksheets:
+            heading = False
+            cached = values[sheet.title]
+            sheet.reset_dimensions()
+            cached.reset_dimensions()
+            for cells, results in zip(sheet.iter_rows(), cached.iter_rows()):
+                row = [result.value if cell.data_type == "f" and result.value is not None else cell.value
+                       for cell, result in zip(cells, results)]
+                if not any(value is not None and str(value).strip() for value in row):
+                    continue
+                if not heading:
+                    output.write("Sheet: " + sheet.title + "\\n")
+                    heading = True
+                output.write(" | ".join("" if value is None else str(value).replace("\\n", " ")
+                                        for value in row) + "\\n")
+finally:
+    formulas.close()
+    values.close()
+`;

package/dist-lib/lib/serve.js

@@ -4,6 +4,7 @@ import { settleOnClose } from './rpc-session.js';
 import { pipeline, Readable } from 'streamx';
 import { bindApi } from '../spec/bind.js';
 import HRPC from '../spec/hrpc/index.js';
+import { isCapability } from './capabilities/invoke.js';
 import { unsupportedKvCacheDeletion } from './capabilities/kv-cache.js';
 import { errorMessage } from './error-fields.js';
 import { hlog } from './log.js';
@@ -11,7 +12,7 @@ import { pushQueue } from './queue.js';
 import { TextCoalescer } from './helpers/text-coalescer.js';
 import { prepareOpenclCache } from './models/opencl-cache.js';
 import { stageFile, sweepStaging } from './staging.js';
-import { readSetup } from './tools/skills/manifest-parse.js';
+import { readSetup, toWireSetup } from './tools/skills/manifest-parse.js';
 import { packVectors, toDownloadWire, toWire } from './wire.js';
 const MODEL_STATUSES = new Set([
     'loading',
@@ -96,6 +97,15 @@ export function serveHarness(stream, harness) {
                 text: await harness.transcribe({ model: model ?? '', audio: audio ?? Buffer.alloc(0) })
             };
         },
+        detectLanguage: async ({ text, topK }) => {
+            if (!harness.detectLanguage)
+                throw new Error('harness does not support detectLanguage');
+            const languages = await harness.detectLanguage({
+                text: text ?? '',
+                topK: topK ?? undefined
+            });
+            return { languages };
+        },
         speak: async ({ model, text }) => {
             if (!harness.speak)
                 throw new Error('harness does not support speak');
@@ -159,7 +169,7 @@ export function serveHarness(stream, harness) {
     });
 }
 function toWireSkill(skill) {
-    const setupV2 = readSetup(skill.setup);
+    const setupV2 = toWireSetup(readSetup(skill.setup));
     const binaries = (skill.requires?.bins ?? []).map((bin) => ({
         bin,
         minVersion: skill.requires?.binMinVersions?.[bin]?.min,
@@ -275,6 +285,24 @@ function speakStream(harness) {
         }
     };
 }
+function runFrame(harness, frame, context) {
+    if (frame.type !== 'invoke')
+        return harness.completion(context);
+    if (!harness.invoke)
+        throw new Error('harness does not support invoke');
+    const capability = frame.capability ?? '';
+    if (!isCapability(capability))
+        throw new Error(`unknown capability: ${capability}`);
+    return harness.invoke({
+        capability,
+        args: frame.arguments ?? {},
+        agent: frame.agent ?? undefined,
+        attach: context.attach,
+        fetchAttachment: context.fetchAttachment,
+        progress: context.progress,
+        signal: context.signal
+    });
+}
 function completion(harness) {
     return async function* (duplex) {
         const events = pushQueue({ highWaterMark: WIRE_HIGH_WATER_MARK });
@@ -404,7 +432,7 @@ function completion(harness) {
                 waiter.resolve((frame.payload ?? {}));
                 return;
             }
-            if (frame.type !== 'start' || started)
+            if (started || (frame.type !== 'start' && frame.type !== 'invoke'))
                 return;
             started = true;
             const context = {
@@ -523,7 +551,7 @@ function completion(harness) {
                     return events.push({ type, text: merged });
                 }, { cap: TEXT_COALESCE_CAP, holdMs: TEXT_COALESCE_MS });
                 try {
-                    for await (const event of harness.completion(context)) {
+                    for await (const event of runFrame(harness, frame, context)) {
                         produced++;
                         const wire = toWire(event);
                         if ((wire.type === 'content' || wire.type === 'thinking') && wire.text) {

package/dist-lib/lib/tools/edit-image.js

@@ -170,7 +170,7 @@ export function createEditImageTool(runtime, { loadMedia = defaultLoadMedia, res
             if (sources.length > 1 && !inContext)
                 return { error: MULTI_SOURCE_UNSUPPORTED };
             if (!runtime.acquire())
-                return { error: BUSY_ERROR };
+                return { error: BUSY_ERROR, code: 'busy' };
             const report = ctx.progress;
             const onTick = report && generationPercentTick((percentage) => report({ percentage }), sources.length);
             try {

package/dist-lib/lib/tools/generate-image.js

@@ -323,7 +323,7 @@ export function createGenerateImageTool(runtime, clamps) {
             if (!ctx?.attach)
                 return { error: 'this device cannot persist generated images' };
             if (!runtime.acquire())
-                return { error: BUSY_ERROR };
+                return { error: BUSY_ERROR, code: 'busy' };
             const report = ctx.progress;
             const onTick = report && generationPercentTick((percentage) => report({ percentage }));
             try {

package/dist-lib/lib/tools/generate-music.js

@@ -443,7 +443,7 @@ export function createGenerateMusicTool(runtime, clamps) {
             if (!ctx?.attach)
                 return { error: 'this device cannot persist generated audio' };
             if (!runtime.acquire())
-                return { error: BUSY_ERROR };
+                return { error: BUSY_ERROR, code: 'busy' };
             const report = ctx.progress;
             const onTick = report && musicPercentTick((percentage) => report({ percentage }));
             const capMax = stepsCap ?? MAX_STEPS;

package/dist-lib/lib/tools/http-request.js

@@ -14,7 +14,7 @@ export function createHttpRequestTool({ fetch: fetchImpl, credentialStore, crede
     return {
         name: 'http_request',
         toolset: 'http-request',
-        description: 'Make an outbound HTTP or HTTPS request and return the response status and body (truncated). Authorization/Cookie headers are stripped before sending. Stored skill credentials are attached automatically for their allow-listed hosts; `auth` is only needed to force a specific credential key.',
+        description: 'Make an outbound HTTP or HTTPS request and return the response status and body (truncated) as text. Authorization/Cookie headers are stripped before sending. Stored skill credentials are attached automatically for their allow-listed hosts; `auth` is only needed to force a specific credential key. For APIs and text responses only: a URL that serves a file — PDF, .docx, .xlsx, an image, any binary — comes back as truncated garbage here. Use web_fetch for those; it downloads and attaches the file.',
         parameters: {
             type: 'object',
             properties: {
@@ -163,10 +163,10 @@ export function createHttpRequestTool({ fetch: fetchImpl, credentialStore, crede
             }
             catch (err) {
                 const error = err instanceof Error ? err : new Error(String(err));
+                const timedOut = error.name === 'AbortError' || error instanceof AbortedError;
                 return {
-                    error: error.name === 'AbortError' || error instanceof AbortedError
-                        ? 'request timed out'
-                        : `request failed: ${error.message}`
+                    error: timedOut ? 'request timed out' : `request failed: ${error.message}`,
+                    code: timedOut ? 'timeout' : 'transport'
                 };
             }
             finally {

package/dist-lib/lib/tools/mcp-call.js

@@ -141,10 +141,10 @@ export function createMcpCallTool({ fetch: fetchImpl, credentialStore, credentia
             }
             catch (err) {
                 const error = err instanceof Error ? err : new Error(String(err));
+                const timedOut = error.name === 'AbortError' || error instanceof AbortedError;
                 return {
-                    error: error.name === 'AbortError' || error instanceof AbortedError
-                        ? 'request timed out'
-                        : `request failed: ${error.message}`
+                    error: timedOut ? 'request timed out' : `request failed: ${error.message}`,
+                    code: timedOut ? 'timeout' : 'transport'
                 };
             }
             finally {

package/dist-lib/lib/tools/skill.js

@@ -131,8 +131,10 @@ export function createSkillTool({ skillsDir, overlayDir = resolveSkillsOverlayDi
                 if (file === MAIN_FILE)
                     return { error: `skill not found: ${name}` };
                 const available = await listSkillFiles([overlayDrive, baseDrive], name);
-                const listing = available.length ? ` — files this skill has: ${available.join(', ')}` : '';
-                return { error: `file not found in skill ${name}: ${file}${listing}` };
+                const rest = available.length
+                    ? ` — files this skill has: ${available.join(', ')}`
+                    : '. This skill has no other files; you already have its full instructions — act now.';
+                return { error: `file not found in skill ${name}: ${file}${rest}` };
             }
         }
     };

package/dist-lib/lib/tools/skills/auth-resolver.d.ts

@@ -19,6 +19,7 @@ export declare function isCredentialUrlAllowed(target: string, patterns: readonl
 export type CredentialAllowListFn = (ctx?: ToolExecuteContext) => CredentialAllowList;
 export type AuthOutcome = {
     readonly token: string;
+    readonly key: string;
 } | {
     readonly error: string;
 };

package/dist-lib/lib/tools/skills/auth-resolver.js

@@ -60,49 +60,79 @@ export function parseAuth(v) {
     }
     return { ok: true, value: { type: 'bearer', tokenCredentialKey: key } };
 }
-export async function resolveAuth(auth, url, credentialStore, credentialAllowList, ctx) {
-    const key = auth.tokenCredentialKey;
-    if (!credentialStore)
-        return { error: 'credentials not configured' };
-    const entry = credentialAllowList?.[key];
-    if (!entry) {
+function grantedKeys(url, credentialAllowList) {
+    return Object.entries(credentialAllowList)
+        .filter(([, entry]) => urlAllowed(url, Array.isArray(entry) ? entry : [entry]))
+        .map(([key]) => key);
+}
+async function connectedCredentials(keys, credentialStore, ctx) {
+    const connected = [];
+    for (const key of keys) {
+        const record = credentialRecord(await credentialStore(key, ctx));
+        if (record)
+            connected.push({ token: record.token, key });
+    }
+    return connected;
+}
+function ambiguous(keys) {
+    return {
+        error: `multiple credentials match this URL; set auth.tokenCredentialKey to one of ${keys.join(', ')}`
+    };
+}
+async function resolveGuessedKey(key, url, credentialStore, credentialAllowList, ctx) {
+    const granted = grantedKeys(url, credentialAllowList);
+    if (granted.length === 0) {
         return {
-            error: `credential ${key} is not available here — load the skill that declares it first`
+            error: `unknown credential key ${key}; no loaded skill grants a credential for ${url.host} — omit auth, or load the skill that declares it`
         };
     }
+    const [first, ...rest] = await connectedCredentials(granted, credentialStore, ctx);
+    if (!first) {
+        return {
+            error: `unknown credential key ${key}; no connected credential for ${url.host} (${granted.join(', ')}). Tell the user to connect it in Skills; do not retry`
+        };
+    }
+    if (rest.length > 0)
+        return ambiguous([first, ...rest].map((c) => c.key));
+    return first;
+}
+async function resolveDeclaredKey(key, url, credentialStore, credentialAllowList, ctx) {
+    const entry = credentialAllowList?.[key];
+    if (!entry)
+        return null;
     const patterns = Array.isArray(entry) ? entry : [entry];
     if (!urlAllowed(url, patterns)) {
         return { error: `credential ${key} is not allowed for URL ${url.href}` };
     }
     const record = credentialRecord(await credentialStore(key, ctx));
-    if (!record)
-        return { error: `unknown credential: ${key}` };
-    return { token: record.token };
+    if (!record) {
+        return {
+            error: `credential ${key} is not connected for ${url.host}. Tell the user to connect it in Skills; do not retry`
+        };
+    }
+    return { token: record.token, key };
+}
+export async function resolveAuth(auth, url, credentialStore, credentialAllowList, ctx) {
+    const key = auth.tokenCredentialKey;
+    if (!credentialStore)
+        return { error: 'credentials not configured' };
+    return ((await resolveDeclaredKey(key, url, credentialStore, credentialAllowList, ctx)) ??
+        resolveGuessedKey(key, url, credentialStore, credentialAllowList ?? {}, ctx));
 }
 export async function resolveAutoAuth(url, credentialStore, credentialAllowList, ctx) {
     if (!credentialStore || !credentialAllowList)
         return null;
-    let selected = null;
-    for (const [key, entry] of Object.entries(credentialAllowList)) {
-        const patterns = Array.isArray(entry) ? entry : [entry];
-        if (!urlAllowed(url, patterns))
-            continue;
-        const record = credentialRecord(await credentialStore(key, ctx));
-        if (!record)
-            continue;
-        if (selected) {
-            return { error: 'multiple credentials match this URL; set auth.tokenCredentialKey' };
-        }
-        selected = { token: record.token, key };
-    }
-    return selected;
+    const connected = await connectedCredentials(grantedKeys(url, credentialAllowList), credentialStore, ctx);
+    if (connected.length > 1)
+        return ambiguous(connected.map((c) => c.key));
+    return connected[0] ?? null;
 }
 export async function resolveBearerHeader(auth, url, credentialStore, credentialAllowList, ctx, signal) {
     if (auth) {
         const resolved = await raceAbort(resolveAuth(auth, url, credentialStore, credentialAllowList, ctx), signal);
         if ('error' in resolved)
             return { error: resolved.error };
-        return { header: `Bearer ${resolved.token}`, credentialKey: auth.tokenCredentialKey };
+        return { header: `Bearer ${resolved.token}`, credentialKey: resolved.key };
     }
     const resolved = await raceAbort(resolveAutoAuth(url, credentialStore, credentialAllowList, ctx), signal);
     if (resolved && 'error' in resolved)
@@ -112,10 +142,10 @@ export async function resolveBearerHeader(auth, url, credentialStore, credential
         : { header: null };
 }
 export async function resolveRedirectBearerHeader(auth, url, credentialStore, credentialAllowList, ctx, signal) {
-    if (!auth)
+    if (!auth || !credentialStore)
         return { header: null };
-    const resolved = await raceAbort(resolveAuth(auth, url, credentialStore, credentialAllowList, ctx), signal);
-    return 'error' in resolved
+    const resolved = await raceAbort(resolveDeclaredKey(auth.tokenCredentialKey, url, credentialStore, credentialAllowList, ctx), signal);
+    return !resolved || 'error' in resolved
         ? { header: null }
-        : { header: `Bearer ${resolved.token}`, credentialKey: auth.tokenCredentialKey };
+        : { header: `Bearer ${resolved.token}`, credentialKey: resolved.key };
 }

package/dist-lib/lib/tools/skills/manifest-parse.d.ts

@@ -10,3 +10,4 @@ export interface ParsedManifest {
 export declare function parseManifestBlock(block: string, key?: string): ParsedManifest;
 export declare function readInstall(v: unknown): InstallStep[] | undefined;
 export declare function readSetup(v: unknown): SkillSetup | undefined;
+export declare function toWireSetup(setup: SkillSetup | undefined): unknown;

package/dist-lib/lib/tools/skills/manifest-parse.js

@@ -165,6 +165,9 @@ function readRoutes(v) {
         const steps = strArr(raw.steps);
         const configSteps = strArr(raw.configSteps);
         const fields = readFields(raw.fields);
+        const oauth = readOAuth(raw.oauth);
+        if (raw.kind === 'oauth' && !oauth)
+            continue;
         routes.push({
             kind: raw.kind,
             label: raw.label,
@@ -175,11 +178,99 @@ function readRoutes(v) {
             ...(steps ? { steps } : {}),
             ...(configSteps ? { configSteps } : {}),
             ...(fields ? { fields } : {}),
-            ...(typeof raw.satisfied === 'boolean' ? { satisfied: raw.satisfied } : {})
+            ...(typeof raw.satisfied === 'boolean' ? { satisfied: raw.satisfied } : {}),
+            ...(oauth ? { oauth } : {})
         });
     }
     return routes.length > 0 ? routes : undefined;
 }
+const OAUTH_TOKEN_AUTH = new Set(['pkce-only', 'secret-in-body', 'secret-in-basic']);
+const OAUTH_RESERVED_PARAMS = new Set([
+    'client_id',
+    'client_secret',
+    'redirect_uri',
+    'response_type',
+    'state',
+    'scope',
+    'code_challenge',
+    'code_challenge_method'
+]);
+function isOAuthTokenAuth(v) {
+    return typeof v === 'string' && OAUTH_TOKEN_AUTH.has(v);
+}
+function httpsUrl(v) {
+    if (typeof v !== 'string' || v.length === 0)
+        return undefined;
+    try {
+        return new URL(v).protocol === 'https:' ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isPort(v) {
+    return typeof v === 'number' && Number.isInteger(v) && v > 0 && v < 65536;
+}
+function readAuthParams(v) {
+    const raw = Array.isArray(v)
+        ? Object.fromEntries(v.flatMap((pair) => isObj(pair) && typeof pair.key === 'string' && typeof pair.value === 'string'
+            ? [[pair.key, pair.value]]
+            : []))
+        : v;
+    const record = readStringRecord(raw);
+    if (!record)
+        return undefined;
+    const out = Object.fromEntries(Object.entries(record).filter(([key]) => !OAUTH_RESERVED_PARAMS.has(key)));
+    return Object.keys(out).length > 0 ? out : undefined;
+}
+function readOAuth(v) {
+    if (!isObj(v))
+        return undefined;
+    const authUrl = httpsUrl(v.authUrl);
+    const tokenUrl = httpsUrl(v.tokenUrl);
+    if (typeof v.stateKey !== 'string' ||
+        v.stateKey.length === 0 ||
+        !authUrl ||
+        !tokenUrl ||
+        !isOAuthTokenAuth(v.tokenAuth)) {
+        return undefined;
+    }
+    const scopes = v.scopes === undefined || v.scopes === null ? [] : strArr(v.scopes);
+    if (!scopes)
+        return undefined;
+    const extraAuthParams = readAuthParams(v.extraAuthParams);
+    const registrationEndpoint = httpsUrl(v.registrationEndpoint);
+    return {
+        stateKey: v.stateKey,
+        authUrl,
+        tokenUrl,
+        scopes,
+        tokenAuth: v.tokenAuth,
+        ...(extraAuthParams ? { extraAuthParams } : {}),
+        ...(registrationEndpoint ? { registrationEndpoint } : {}),
+        ...(isPort(v.port) ? { port: v.port } : {}),
+        ...(typeof v.sharedIosSession === 'boolean' ? { sharedIosSession: v.sharedIosSession } : {})
+    };
+}
+export function toWireSetup(setup) {
+    if (!setup?.routes)
+        return setup;
+    return {
+        ...setup,
+        routes: setup.routes.map((route) => route.oauth?.extraAuthParams
+            ? {
+                ...route,
+                oauth: {
+                    ...route.oauth,
+                    extraAuthParams: Object.entries(route.oauth.extraAuthParams).map(([key, value]) => ({
+                        key,
+                        value
+                    }))
+                }
+            }
+            : route)
+    };
+}
 function readFields(v) {
     if (!Array.isArray(v))
         return undefined;