@qvac/harness 0.2.10 → 0.2.12

package/dist-lib/index.d.ts

@@ -1,6 +1,8 @@
 import type { AbortSignal as BareAbortSignal } from 'bare-abort-controller';
 import ReadyResource from 'ready-resource';
 import { type Agent, type ApproveFn, type AskUserFn, type AttachFn, type CompletionEvent, type FetchAttachmentFn, type Message, type ProgressFn, type RagSearchFn, type ResponseFormat, type ToolDefinition, type ToolExecuteContext } from './lib/capabilities/completion.ts';
+import { type DetectLanguageContext, type DetectedLanguage } from './lib/capabilities/detect-language.ts';
+import { type Capability } from './lib/capabilities/invoke.ts';
 import { type DownloadArgs, type DownloadEventStream } from './lib/capabilities/download.ts';
 import { type EmbedContext } from './lib/capabilities/embed.ts';
 import { type KvCacheDeletionResult } from './lib/capabilities/kv-cache.ts';
@@ -22,6 +24,8 @@ import type { ResolvedSkillCatalogEntry } from './lib/tools/skills/catalog.ts';
 import { type SkillSettingEntry } from './lib/tools/skills/skill-settings.ts';
 export * from './lib/capabilities/completion.ts';
 export { attachmentTurn, loadedSkillsFrom, skillLoadedTurn } from './lib/capabilities/tool-turns.ts';
+export { CAPABILITIES, isCapability, type Capability } from './lib/capabilities/invoke.ts';
+export type { DetectLanguageContext, DetectedLanguage } from './lib/capabilities/detect-language.ts';
 export * from './lib/capabilities/download.ts';
 export type { EmbedContext } from './lib/capabilities/embed.ts';
 export type { SpeakContext, SpeakResult, SpeakStreamContext, TranscribeContext } from './lib/capabilities/voice.ts';
@@ -37,7 +41,7 @@ export { requiredSettings, settingEnvName, type SkillSettingEntry, type SkillSet
 export type { ToolCatalogEntry } from './lib/tools/catalog.ts';
 export { TOOLSETS, toolsetEnabled, type Toolset } from './lib/tools/toolsets.ts';
 export { markCredentialRejected, markCredentialValid, recordCredentialHealth, resetAllCredentialHealth, resetCredentialHealth } from './lib/tools/skills/credential-health.ts';
-export type { InstallStep, SkillRequires, SkillSetup, SkillSetupField, SkillSetupRoute } from './lib/tools/skills/manifest.ts';
+export type { InstallStep, SkillOAuthConfig, SkillRequires, SkillSetup, SkillSetupField, SkillSetupRoute } from './lib/tools/skills/manifest.ts';
 export { readSetup as normalizeSkillSetup } from './lib/tools/skills/manifest-parse.ts';
 export type { CredentialRecord, CredentialStoreValue } from './lib/tools/skills/auth-resolver.ts';
 export { isAvailableState, SKILL_STATE, type SkillState } from './lib/tools/skills/skill-state.ts';
@@ -106,6 +110,15 @@ export interface CompletionContext {
     askUser?: AskUserFn;
     signal?: BareAbortSignal;
 }
+export interface InvokeContext {
+    capability: Capability;
+    args: Record<string, unknown>;
+    agent?: Agent;
+    attach?: AttachFn;
+    fetchAttachment?: FetchAttachmentFn;
+    progress?: ProgressFn;
+    signal?: BareAbortSignal;
+}
 export declare class Harness extends ReadyResource {
     private _tools;
     private _sdk;
@@ -224,6 +237,7 @@ export declare class Harness extends ReadyResource {
     private _defaultVoiceSrc;
     private _voiceJob;
     transcribe({ model, audio, signal }: TranscribeContext): Promise<string>;
+    detectLanguage(context: DetectLanguageContext): DetectedLanguage[];
     speak({ model, text, signal }: SpeakContext): Promise<SpeakResult>;
     speakStream({ model, text, signal }: SpeakStreamContext): AsyncIterable<SpeakResult>;
     list(options?: ListModelsOptions): Promise<ModelInfo[]>;
@@ -240,6 +254,7 @@ export declare class Harness extends ReadyResource {
         agent?: Agent;
         signal?: BareAbortSignal;
     }): Promise<void>;
+    invoke({ capability, args, agent, attach, fetchAttachment, progress, signal }: InvokeContext): AsyncGenerator<CompletionEvent>;
     completion({ model, agent, messages, cacheKey, thinkingDefault, toolConfigs, generationParams, responseFormat, captureInferenceCalls, grantedDirs, grantedDrives, driveOp, grantedWriteDirs, approve, attach, fetchAttachment, ragSearch, progress, askUser, signal }: CompletionContext): AsyncGenerator<CompletionEvent>;
     private _makeRoomForCompletion;
     private _evictWedgedModel;

package/dist-lib/index.js

@@ -5,7 +5,9 @@ import ReadyResource from 'ready-resource';
 import { probeGpuStats } from './lib/hardware/gpu-probe.js';
 import { probeCapabilityProfile } from './lib/hardware/capability-probe.js';
 import { closePythonWorker } from './lib/tools/exec/adapters/python/worker/client.js';
-import { completion } from './lib/capabilities/completion.js';
+import { completion, imageSettingsFrom } from './lib/capabilities/completion.js';
+import { detectLanguage } from './lib/capabilities/detect-language.js';
+import { invoke } from './lib/capabilities/invoke.js';
 import { download } from './lib/capabilities/download.js';
 import { createEmbedLane } from './lib/capabilities/embed.js';
 import { deleteAllKvCaches, deleteKvCacheKey } from './lib/capabilities/kv-cache.js';
@@ -45,6 +47,7 @@ import { isDeviceSharedCredentialKey, scopeKey } from './lib/tools/skills/scope-
 import { settingsScopeKey } from './lib/tools/skills/skill-settings.js';
 export * from './lib/capabilities/completion.js';
 export { attachmentTurn, loadedSkillsFrom, skillLoadedTurn } from './lib/capabilities/tool-turns.js';
+export { CAPABILITIES, isCapability } from './lib/capabilities/invoke.js';
 export * from './lib/capabilities/download.js';
 export * from './lib/models/model-catalog.js';
 export * from './lib/models/model-list.js';
@@ -809,6 +812,9 @@ export class Harness extends ReadyResource {
             return transcribeOnce(sdk, id, pcm ? buildWavBuffer(pcm) : audio);
         });
     }
+    detectLanguage(context) {
+        return detectLanguage(context);
+    }
     async speak({ model, text, signal }) {
         const samples = await this._voiceJob(this._ttsModels, 'tts', model, signal, (sdk, id) => speakOnce(sdk, id, text));
         return { audio: packSamples(samples), sampleRate: SUPERTONIC_SAMPLE_RATE };
@@ -943,6 +949,30 @@ export class Harness extends ReadyResource {
             releaseModel(pool, key);
         }
     }
+    async *invoke({ capability, args, agent, attach, fetchAttachment, progress, signal }) {
+        if (!this.opened)
+            await this.ready();
+        if (this.suspended)
+            return yield { type: 'aborted' };
+        hlog('invoke start', { capability });
+        try {
+            yield* invoke({
+                capability,
+                args,
+                tools: this._tools,
+                ctx: {
+                    image: imageSettingsFrom(agent),
+                    attach,
+                    fetchAttachment,
+                    progress,
+                    signal
+                }
+            });
+        }
+        finally {
+            hlog('invoke end', { capability });
+        }
+    }
     async *completion({ model, agent, messages, cacheKey, thinkingDefault, toolConfigs, generationParams, responseFormat, captureInferenceCalls, grantedDirs, grantedDrives, driveOp, grantedWriteDirs, approve, attach, fetchAttachment, ragSearch, progress, askUser, signal }) {
         await this.ready();
         if (this.suspended)

package/dist-lib/lib/capabilities/detect-language.d.ts

@@ -0,0 +1,11 @@
+export interface DetectedLanguage {
+    code: string;
+    language: string;
+    probability?: number;
+}
+export interface DetectLanguageContext {
+    text: string;
+    topK?: number;
+}
+export declare const UNDETERMINED = "und";
+export declare function detectLanguage({ text, topK }: DetectLanguageContext): DetectedLanguage[];

package/dist-lib/lib/capabilities/detect-language.js

@@ -0,0 +1,13 @@
+import { detectMultiple, detectOne } from '@qvac/langdetect-text';
+export const UNDETERMINED = 'und';
+export function detectLanguage({ text, topK }) {
+    if (!topK || topK === 1) {
+        const { code, language } = detectOne(text);
+        return [{ code, language }];
+    }
+    return detectMultiple(text, topK).map(({ code, language, probability }) => ({
+        code,
+        language,
+        probability
+    }));
+}

package/dist-lib/lib/capabilities/invoke.d.ts

@@ -0,0 +1,15 @@
+import type { CompletionEvent, ToolDefinition, ToolExecuteContext } from './completion.ts';
+declare const CAPABILITY_TOOLS: {
+    readonly image: 'generate_image';
+};
+export type Capability = keyof typeof CAPABILITY_TOOLS;
+export declare const CAPABILITIES: Capability[];
+export declare function isCapability(name: string): name is Capability;
+export interface InvokeOptions {
+    capability: Capability;
+    args: Record<string, unknown>;
+    tools: readonly ToolDefinition[];
+    ctx: ToolExecuteContext;
+}
+export declare function invoke({ capability, args, tools, ctx }: InvokeOptions): AsyncGenerator<CompletionEvent>;
+export {};

package/dist-lib/lib/capabilities/invoke.js

@@ -0,0 +1,33 @@
+import { AbortedError } from '../helpers/race-abort.js';
+const CAPABILITY_TOOLS = {
+    image: 'generate_image'
+};
+export const CAPABILITIES = Object.keys(CAPABILITY_TOOLS);
+export function isCapability(name) {
+    return name in CAPABILITY_TOOLS;
+}
+export async function* invoke({ capability, args, tools, ctx }) {
+    const name = CAPABILITY_TOOLS[capability];
+    const tool = tools.find((candidate) => candidate.name === name);
+    if (!tool) {
+        yield { type: 'error', message: `${capability} is not available on this device` };
+        return;
+    }
+    const startedAt = Date.now();
+    yield { type: 'tool-call', name, args, effect: tool.effect(args, ctx) };
+    try {
+        const result = await tool.execute(args, ctx);
+        if (ctx.signal?.aborted)
+            return yield { type: 'aborted' };
+        yield { type: 'tool-result', name, result };
+    }
+    catch (err) {
+        if (err instanceof AbortedError || ctx.signal?.aborted) {
+            yield { type: 'aborted' };
+            return;
+        }
+        yield { type: 'error', message: err instanceof Error ? err.message : String(err) };
+        return;
+    }
+    yield { type: 'metrics', totalTokens: 0, durationMs: Date.now() - startedAt };
+}

package/dist-lib/lib/connect.d.ts

@@ -1,7 +1,7 @@
 import EventEmitter from 'events';
 import { type Transport } from './rpc-session.ts';
 import { type KvCacheDeletionResult } from './capabilities/kv-cache.ts';
-import type { CapabilityInfo, CompletionContext, DownloadContext, EmbedContext, HarnessContract, HarnessDiagnostics, HarnessEvent, HarnessInfo, ListModelsOptions, ModelInfo, ResolvedSkillCatalogEntry, SpeakContext, SpeakResult, SpeakStreamContext, ToolCatalogEntry, TranscribeContext, WarmModelContext } from './contract-types.ts';
+import type { CapabilityInfo, CompletionContext, DetectedLanguage, DetectLanguageContext, DownloadContext, EmbedContext, HarnessContract, HarnessDiagnostics, HarnessEvent, HarnessInfo, InvokeContext, ListModelsOptions, ModelInfo, ResolvedSkillCatalogEntry, SpeakContext, SpeakResult, SpeakStreamContext, ToolCatalogEntry, TranscribeContext, WarmModelContext } from './contract-types.ts';
 import { type EmbedDevice } from './models/embed-config.ts';
 import type { DeleteModelSummary } from './models/model-delete.ts';
 import type { ManagedSkill, SkillFileContent } from './tools/skills/overlay-crud.ts';
@@ -20,9 +20,12 @@ export declare class RemoteHarness extends EventEmitter implements HarnessContra
     private _ensure;
     private _open;
     completion(context: CompletionContext): AsyncIterable<HarnessEvent>;
+    invoke(context: InvokeContext): AsyncIterable<HarnessEvent>;
+    private _run;
     download(context: DownloadContext): AsyncIterable<HarnessEvent>;
     embed(context: EmbedContext): Promise<number[][]>;
     transcribe(context: TranscribeContext): Promise<string>;
+    detectLanguage(context: DetectLanguageContext): Promise<DetectedLanguage[]>;
     speak(context: SpeakContext): Promise<SpeakResult>;
     speakStream(context: SpeakStreamContext): AsyncIterable<SpeakResult>;
     getEmbeddingDevice(): Promise<EmbedDevice>;

package/dist-lib/lib/connect.js

@@ -91,6 +91,44 @@ export class RemoteHarness extends EventEmitter {
         return session;
     }
     async *completion(context) {
+        yield* this._run({
+            type: 'start',
+            model: context.model,
+            agent: knobs(context.agent),
+            cacheKey: context.cacheKey,
+            thinkingDefault: context.thinkingDefault,
+            generationParams: context.generationParams,
+            responseFormat: context.responseFormat,
+            captureInferenceCalls: context.captureInferenceCalls,
+            messages: context.messages.map(({ role, content, attachments }) => ({
+                role,
+                content,
+                attachments: attachments?.map(({ path: file }) => ({ path: file }))
+            })),
+            toolConfigs: context.toolConfigs,
+            grantedDirs: context.grantedDirs,
+            grantedDrives: context.grantedDrives,
+            grantedWriteDirs: context.grantedWriteDirs
+        }, context);
+    }
+    async *invoke(context) {
+        const agent = context.agent ?? {};
+        yield* this._run({
+            type: 'invoke',
+            capability: context.capability,
+            arguments: context.args,
+            agent: knobs(agent)
+        }, {
+            model: '',
+            agent,
+            messages: [],
+            attach: context.attach,
+            fetchAttachment: context.fetchAttachment,
+            progress: context.progress,
+            signal: context.signal
+        });
+    }
+    async *_run(open, context) {
         const { client } = await this._ensure();
         let duplex = null;
         let emittedAborted = false;
@@ -104,32 +142,14 @@ export class RemoteHarness extends EventEmitter {
         const onAbort = () => duplex?.destroy();
         try {
             duplex = client.completion();
-            duplex.write({
-                type: 'start',
-                model: context.model,
-                agent: knobs(context.agent),
-                cacheKey: context.cacheKey,
-                thinkingDefault: context.thinkingDefault,
-                generationParams: context.generationParams,
-                responseFormat: context.responseFormat,
-                captureInferenceCalls: context.captureInferenceCalls,
-                messages: context.messages.map(({ role, content, attachments }) => ({
-                    role,
-                    content,
-                    attachments: attachments?.map(({ path: file }) => ({ path: file }))
-                })),
-                toolConfigs: context.toolConfigs,
-                grantedDirs: context.grantedDirs,
-                grantedDrives: context.grantedDrives,
-                grantedWriteDirs: context.grantedWriteDirs
-            });
+            duplex.write(open);
             if (context.signal?.aborted) {
                 duplex.destroy();
                 yield { type: 'aborted' };
                 return;
             }
             context.signal?.addEventListener?.('abort', onAbort, { once: true });
-            hlog('client wire open', { model: context.model });
+            hlog('client wire open', { model: context.model, capability: open.capability });
             for await (const event of frames(duplex)) {
                 received++;
                 if (event.type !== 'content' && event.type !== 'thinking') {
@@ -288,7 +308,7 @@ export class RemoteHarness extends EventEmitter {
             throw died(`harness died mid-run: ${err.message}`);
         }
         finally {
-            hlog('client completion end', { received, aborted: Boolean(context.signal?.aborted) });
+            hlog('client run end', { received, aborted: Boolean(context.signal?.aborted) });
             context.signal?.removeEventListener?.('abort', onAbort);
             duplex?.destroy();
             closed = true;
@@ -350,6 +370,14 @@ export class RemoteHarness extends EventEmitter {
         const response = await abortable(client.transcribe({ model: context.model, audio: context.audio }), context.signal);
         return response.text;
     }
+    async detectLanguage(context) {
+        const { client } = await this._ensure();
+        const response = await client.detectLanguage({
+            text: context.text,
+            topK: context.topK
+        });
+        return response.languages.map(({ code, language, probability }) => probability ? { code, language, probability } : { code, language });
+    }
     async speak(context) {
         const { client } = await this._ensure();
         const response = await abortable(client.speak({ model: context.model, text: context.text }), context.signal);

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

@@ -68,6 +68,24 @@ export interface CompletionContext {
         removeEventListener?: (type: 'abort', fn: () => void) => void;
     };
 }
+export interface InvokeContext {
+    capability: string;
+    args: Record<string, unknown>;
+    agent?: AgentKnobs;
+    attach?: AttachFn;
+    fetchAttachment?: FetchAttachmentFn;
+    progress?: ProgressFn;
+    signal?: CompletionContext['signal'];
+}
+export interface DetectLanguageContext {
+    text: string;
+    topK?: number;
+}
+export interface DetectedLanguage {
+    code: string;
+    language: string;
+    probability?: number;
+}
 export interface HarnessEvent {
     type: string;
     text?: string;
@@ -146,10 +164,12 @@ export interface CapabilityInfo {
 }
 export interface HarnessContract {
     completion(context: CompletionContext): AsyncIterable<HarnessEvent>;
+    invoke?(context: InvokeContext): AsyncIterable<HarnessEvent>;
     download?(context: DownloadContext): AsyncIterable<HarnessEvent>;
     describe?(): Promise<HarnessInfo | null> | HarnessInfo;
     embed?(context: EmbedContext): Promise<number[][]>;
     transcribe?(context: TranscribeContext): Promise<string>;
+    detectLanguage?(context: DetectLanguageContext): DetectedLanguage[] | Promise<DetectedLanguage[]>;
     speak?(context: SpeakContext): Promise<SpeakResult>;
     speakStream?(context: SpeakStreamContext): AsyncIterable<SpeakResult>;
     getEmbeddingDevice?(): EmbedDevice | Promise<EmbedDevice>;

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

@@ -1,3 +1,4 @@
+import { planVendoredInstall } from '../../tools/exec/adapters/python/wheels.js';
 import { bareBin, firstCommandToken } from '../../tools/exec/scope.js';
 const NETWORK_BINS = new Set([
     'curl',
@@ -32,7 +33,8 @@ export class SandboxHook {
             return;
         if (!ctx.sandboxMode || ctx.toolName !== 'exec')
             return;
-        if (Array.isArray(ctx.args.packages) && ctx.args.packages.length) {
+        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(/^.*[/\\]/, ''));

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/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: {

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;

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

@@ -29,6 +29,17 @@ export interface SkillSetupField {
     readonly secret?: boolean;
     readonly required?: boolean;
 }
+export interface SkillOAuthConfig {
+    readonly stateKey: string;
+    readonly authUrl: string;
+    readonly tokenUrl: string;
+    readonly scopes: readonly string[];
+    readonly tokenAuth: 'pkce-only' | 'secret-in-body' | 'secret-in-basic';
+    readonly extraAuthParams?: Readonly<Record<string, string>>;
+    readonly registrationEndpoint?: string;
+    readonly port?: number;
+    readonly sharedIosSession?: boolean;
+}
 export interface SkillSetupRoute {
     readonly kind: 'oauth' | 'token' | 'install' | 'picker' | 'instructions';
     readonly label: string;
@@ -40,6 +51,7 @@ export interface SkillSetupRoute {
     readonly configSteps?: readonly string[];
     readonly fields?: readonly SkillSetupField[];
     readonly satisfied?: boolean;
+    readonly oauth?: SkillOAuthConfig;
 }
 export interface SkillSetup {
     readonly summary?: string;

package/dist-lib/lib/tools/web-fetch.js

@@ -28,7 +28,11 @@ export function createWebFetchTool({ fetch: fetchImpl, resolveHost = lookupHost
         toolset: 'web-search',
         description: 'Fetch a public web page and return its readable text. ' +
             'Use this to read the full content behind a web_search result URL, or a page the user ' +
-            'shares, when a search snippet is not enough to answer.',
+            'shares, when a search snippet is not enough to answer. ' +
+            'When the URL serves a file rather than a page — PDF, .docx, .xlsx, .pptx, an image, any ' +
+            'binary — this is also the tool that downloads it: the bytes become a chat attachment and ' +
+            'the result carries its attachmentId. It is the only way to get a remote file into the ' +
+            'chat; exec has no network and http_request truncates binary bodies.',
         parameters: {
             type: 'object',
             properties: {
@@ -178,8 +182,14 @@ async function attachDocument(response, url, mimeType, attach) {
         raw: !mime.startsWith('image/')
     });
     return {
+        attachmentId: record.id,
+        fileName: record.fileName,
+        byteLength: record.byteLength,
         content: `Attached the file "${record.fileName}" (${Math.round(record.byteLength / 1024)}KB, ${mime}) from ${url.toString()} — ` +
-            'the user can open or save it. Its contents were NOT read: do not claim to know what is inside.'
+            'the user can open or save it. Its contents were NOT read, so do not describe what is inside ' +
+            'yet. To read it, stage it with exec as ' +
+            `inputs [{ "attachmentId": "${record.id}", "path": "${record.fileName}" }] — never ask the ` +
+            'user to attach a file this call already attached.'
     };
 }
 const MIME_EXTENSIONS = {