@try-works/dsh-model-as-tool 0.1.3 → 0.3.6

package/lib/headless.d.ts

@@ -0,0 +1,97 @@
+/**
+ * The REAL headless `serve` composition entry (RUN-03, task-74).
+ *
+ * Composes the host services the plugin needs WITHOUT the DSH CLI context:
+ * config load (file/env), the extension-store-less operator surface, the model
+ * catalog with capability resolution, the standard-contract bindings with the
+ * SAME selection rule the plugin applies (providers override, else the first
+ * eligible implementation), the MCP host over those bindings plus `model_tools`
+ * and the `tool_mode_run` contract, and a bounded graceful shutdown on
+ * SIGINT/SIGTERM.
+ *
+ * Two boundaries are deliberate and named, not faked:
+ * - `tool_mode_run` is REGISTERED (its contract appears on tools/list) but its
+ *   execution refuses: a headless process composes no DSH hosted-code runtime
+ *   (the plugin's ProgramRunner needs the DSH PtcHostContext), and pretending
+ *   otherwise would claim a confinement the deployment does not have.
+ * - Extension-routed models resolve through the same bridge as the plugin; a
+ *   model the headless deployment cannot run simply has no tool, exactly like
+ *   the plugin.
+ *
+ * @module @try-works/dsh-model-as-tool/headless
+ */
+/** The headless config document (the same Config surface, parsed loosely). */
+interface HeadlessConfig {
+    readonly catalogFile?: string;
+    readonly allowNpm?: boolean;
+    readonly providers?: Record<string, string>;
+    readonly grantId?: string;
+    readonly recordReceipts?: boolean;
+    readonly approvedRoots?: string[];
+    readonly cli?: {
+        enabled?: boolean;
+        command?: string;
+    };
+    readonly remote?: {
+        endpoint?: string;
+        token?: string;
+    };
+    readonly registerControlTool?: boolean;
+    readonly mcpV3?: {
+        host?: string;
+        port?: number;
+        path?: string;
+    };
+    readonly repairAttempts?: number;
+    readonly harnessExecutorV3?: {
+        defaultRepairAttempts?: number;
+    };
+    readonly [key: string]: unknown;
+}
+/** A named headless-configuration error. */
+export declare class HeadlessConfigError extends Error {
+    readonly name = "HeadlessConfigError";
+}
+/** Read and validate the headless config document. */
+export declare function readHeadlessConfig(configPath: string | undefined, env: NodeJS.ProcessEnv): {
+    config: HeadlessConfig;
+    path: string;
+};
+/** One started headless serve, with its shutdown. */
+export interface HeadlessServe {
+    /** The URL clients should use. */
+    readonly url: string;
+    /** The host/port actually bound. */
+    readonly host: string;
+    readonly port: number;
+    /** Close the server and settle owned resources (bounded). */
+    close(): Promise<void>;
+}
+/**
+ * Start the headless serve composition (RUN-03).
+ *
+ * @param configPath - the config file path; falls back to DSH_TOOL_MODE_CONFIG
+ *   then ./tool-mode.json.
+ * @returns the bound endpoint and a shutdown handle.
+ * @throws HeadlessConfigError for a missing/invalid configuration.
+ */
+export declare function startHeadlessServe(configPath?: string): Promise<HeadlessServe>;
+/**
+ * Run the headless serve as a PROCESS (the launcher entry): prints the bound
+ * endpoint and waits for SIGINT/SIGTERM, then exits 0 after a bounded shutdown.
+ *
+ * @param options - the config path and the JSON-mode flag.
+ * @param io - output sinks (injected for tests).
+ * @returns the process exit code.
+ */
+export declare function runHeadlessServe(options: {
+    readonly configPath?: string;
+    readonly json?: boolean;
+}, io: {
+    readonly out: (line: string) => void;
+    readonly err: (line: string) => void;
+}, signals?: {
+    once(name: 'SIGINT' | 'SIGTERM', handler: () => void): void;
+}): Promise<number>;
+export {};
+//# sourceMappingURL=headless.d.ts.map

package/lib/headless.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headless.d.ts","sourceRoot":"","sources":["../src/headless.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AA0BH,8EAA8E;AAC9E,UAAU,cAAc;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC3C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAA;IACjC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IACjC,QAAQ,CAAC,GAAG,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACtD,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACvD,QAAQ,CAAC,mBAAmB,CAAC,EAAE,OAAO,CAAA;IACtC,QAAQ,CAAC,KAAK,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAChE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAA;IAChC,QAAQ,CAAC,iBAAiB,CAAC,EAAE;QAAE,qBAAqB,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC/D,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CAChC;AAED,4CAA4C;AAC5C,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,SAAkB,IAAI,yBAAwB;CAC/C;AAED,sDAAsD;AACtD,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG;IAC1F,MAAM,EAAE,cAAc,CAAA;IACtB,IAAI,EAAE,MAAM,CAAA;CACb,CAoCA;AAqDD,qDAAqD;AACrD,MAAM,WAAW,aAAa;IAC5B,kCAAkC;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,oCAAoC;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,6DAA6D;IAC7D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB;AAED;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAkJpF;AAwBD;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE;IAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,EAClE,EAAE,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,EAClF,OAAO,GAAE;IAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,SAAS,EAAE,OAAO,EAAE,MAAM,IAAI,GAAG,IAAI,CAAA;CAAY,GACjF,OAAO,CAAC,MAAM,CAAC,CA6BjB"}

package/lib/headless.js

@@ -0,0 +1,349 @@
+/**
+ * The REAL headless `serve` composition entry (RUN-03, task-74).
+ *
+ * Composes the host services the plugin needs WITHOUT the DSH CLI context:
+ * config load (file/env), the extension-store-less operator surface, the model
+ * catalog with capability resolution, the standard-contract bindings with the
+ * SAME selection rule the plugin applies (providers override, else the first
+ * eligible implementation), the MCP host over those bindings plus `model_tools`
+ * and the `tool_mode_run` contract, and a bounded graceful shutdown on
+ * SIGINT/SIGTERM.
+ *
+ * Two boundaries are deliberate and named, not faked:
+ * - `tool_mode_run` is REGISTERED (its contract appears on tools/list) but its
+ *   execution refuses: a headless process composes no DSH hosted-code runtime
+ *   (the plugin's ProgramRunner needs the DSH PtcHostContext), and pretending
+ *   otherwise would claim a confinement the deployment does not have.
+ * - Extension-routed models resolve through the same bridge as the plugin; a
+ *   model the headless deployment cannot run simply has no tool, exactly like
+ *   the plugin.
+ *
+ * @module @try-works/dsh-model-as-tool/headless
+ */
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { STANDARD_CONTRACTS } from '@try-works/tool-mode-contracts';
+import { assertValidContract, assertValidInput, assertValidOutput, crossFieldRules, } from '@try-works/tool-mode-contracts';
+import { createGrant, authorizeTool, createInvocationAuthority } from "./authority.js";
+import { buildMeta, buildReceipt } from "./bindings.js";
+import { DEFAULT_CATALOG_FILE, loadCatalog } from "./catalog.js";
+import { resolveCapability } from "./capability.js";
+import { toContractPayload, toNativeArgs } from "./contract-payload.js";
+import { createAdapter } from "./adapters/index.js";
+import { ProviderBridge } from "./provider-bridge.js";
+import { assertConfigV3DisabledFlags, describeModels, repairCeilingOf } from "./index.js";
+import { TOOL_MODE_RUN_CONTRACT } from "./tool-mode-run.js";
+import { createMcpHost } from "./mcp/host-binding.js";
+import { startHttpServer } from "./mcp/http.js";
+import { commandExists } from "./transport.js";
+/** A named headless-configuration error. */
+export class HeadlessConfigError extends Error {
+    name = 'HeadlessConfigError';
+}
+/** Read and validate the headless config document. */
+export function readHeadlessConfig(configPath, env) {
+    const target = configPath ?? env.DSH_TOOL_MODE_CONFIG ?? './tool-mode.json';
+    let text;
+    try {
+        text = readFileSync(target, 'utf8');
+    }
+    catch (error) {
+        throw new HeadlessConfigError(`the config file ${target} could not be read: ${error instanceof Error ? error.message : String(error)}. `
+            + 'serve requires a config (--config <path> or DSH_TOOL_MODE_CONFIG).');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (error) {
+        throw new HeadlessConfigError(`the config file ${target} is not valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new HeadlessConfigError(`the config file ${target} is not a JSON object`);
+    }
+    const config = parsed;
+    // The same fixed-false gate the plugin applies: unsupported values REFUSE.
+    try {
+        assertConfigV3DisabledFlags(config);
+    }
+    catch (error) {
+        throw new HeadlessConfigError(error instanceof Error ? error.message : String(error));
+    }
+    // The CODE-11 repair ceiling validates here too: the flat `repairAttempts`
+    // key drives, the v3 nested spelling is its equivalent, and an out-of-range
+    // value refuses at config load rather than silently clamping.
+    try {
+        repairCeilingOf(config);
+    }
+    catch (error) {
+        throw new HeadlessConfigError(error instanceof Error ? error.message : String(error));
+    }
+    return { config, path: resolve(target) };
+}
+/** Resolve the contract bindings exactly like the plugin's selection rule. */
+function resolveBindings(config) {
+    const entries = loadCatalog(config.catalogFile ?? DEFAULT_CATALOG_FILE);
+    const cliCommand = config.cli?.command ?? 'desertant';
+    const cliAvailable = (config.cli?.enabled ?? true) && commandExists(cliCommand);
+    const remoteEndpoint = config.remote?.endpoint;
+    const transportOptions = {
+        cliCommand,
+        ...remoteEndpoint !== undefined ? { endpoint: remoteEndpoint } : {},
+        ...config.remote?.token !== undefined ? { token: config.remote.token } : {},
+    };
+    const resolved = entries.map(entry => ({
+        entry,
+        verdict: resolveCapability(entry, {
+            cliAvailable,
+            remoteEndpoint,
+            ...config.allowNpm !== undefined ? { allowNpm: config.allowNpm } : {},
+        }),
+    }));
+    const grant = createGrant({
+        grantId: config.grantId ?? 'local-interactive',
+        allowedTools: [...STANDARD_CONTRACTS.map(contract => contract.toolName), 'model_tools', 'tool_mode_run'],
+        approvedRoots: config.approvedRoots ?? [],
+        hostedCode: false,
+        recordingPolicy: config.recordReceipts === false ? 'none' : 'receipts',
+    });
+    const bridge = new ProviderBridge({
+        grant,
+        activationGeneration: 1,
+        log: () => { },
+    });
+    const bindings = new Map();
+    for (const contract of STANDARD_CONTRACTS) {
+        const eligible = resolved.filter(item => item.entry.contract === contract.contract && item.verdict.runnable);
+        if (eligible.length === 0)
+            continue;
+        const override = config.providers?.[contract.contract];
+        const chosen = eligible.find(item => item.entry.id === override) ?? eligible[0];
+        if (chosen === undefined)
+            continue;
+        const adapter = createAdapter(chosen.entry, { route: chosen.verdict.route, ...transportOptions }, undefined, bridge);
+        if (adapter === undefined)
+            continue;
+        bindings.set(contract.contract, {
+            contract,
+            implementation: chosen.entry,
+            adapter,
+            route: chosen.verdict.route,
+            alternatives: eligible.filter(item => item.entry.id !== chosen.entry.id).map(item => item.entry.id),
+        });
+    }
+    return bindings;
+}
+/**
+ * Start the headless serve composition (RUN-03).
+ *
+ * @param configPath - the config file path; falls back to DSH_TOOL_MODE_CONFIG
+ *   then ./tool-mode.json.
+ * @returns the bound endpoint and a shutdown handle.
+ * @throws HeadlessConfigError for a missing/invalid configuration.
+ */
+export async function startHeadlessServe(configPath) {
+    const { config } = readHeadlessConfig(configPath, process.env);
+    const bindings = resolveBindings(config);
+    // The MCP surface is NEVER unauthenticated (SEC-01): the headless serve
+    // requires a credential exactly like the stdio relay does.
+    const token = process.env.DSH_TOOL_MODE_MCP_TOKEN;
+    if (token === undefined || token.length === 0) {
+        throw new HeadlessConfigError('serve requires a credential (DSH_TOOL_MODE_MCP_TOKEN); the MCP surface is never unauthenticated (SEC-01)');
+    }
+    const models = (() => {
+        const entries = loadCatalog(config.catalogFile ?? DEFAULT_CATALOG_FILE);
+        const cliCommand = config.cli?.command ?? 'desertant';
+        const cliAvailable = (config.cli?.enabled ?? true) && commandExists(cliCommand);
+        const remoteEndpoint = config.remote?.endpoint;
+        return entries.map(entry => ({
+            entry,
+            verdict: resolveCapability(entry, {
+                cliAvailable,
+                remoteEndpoint,
+                ...config.allowNpm !== undefined ? { allowNpm: config.allowNpm } : {},
+            }),
+        }));
+    })();
+    let receiptCounter = 0;
+    const host = {
+        extension: '@try-works/dsh-model-as-tool',
+        extensionVersion: '0.1.1',
+        activationGeneration: 1,
+        nextReceiptId: () => `rcpt_${(++receiptCounter).toString(36).padStart(6, '0')}`,
+        grant: createGrant({
+            grantId: config.grantId ?? 'local-interactive',
+            allowedTools: [...STANDARD_CONTRACTS.map(contract => contract.toolName), 'model_tools', 'tool_mode_run'],
+            approvedRoots: config.approvedRoots ?? [],
+            hostedCode: false,
+            recordingPolicy: config.recordReceipts === false ? 'none' : 'receipts',
+        }),
+        callerKind: 'interactive',
+    };
+    const published = [];
+    for (const binding of bindings.values()) {
+        /**
+         * Registration is what compiles a contract's validators. The plugin path gets
+         * this from registerContractTool; the headless surface builds the published
+         * list directly, so it must register each contract here or every real call
+         * fails with "input was validated before the contract was registered".
+         */
+        assertValidContract(binding.contract);
+        published.push({ toolName: binding.contract.toolName, contract: binding.contract });
+    }
+    if (config.registerControlTool !== false) {
+        published.push({ toolName: 'model_tools', contract: modelToolsContract() });
+    }
+    published.push({ toolName: 'tool_mode_run', contract: TOOL_MODE_RUN_CONTRACT });
+    const mcpHost = createMcpHost({
+        serverInfo: { name: '@try-works/dsh-model-as-tool', version: '0.1.1' },
+        surface: {
+            get published() {
+                return published;
+            },
+            async execute(request) {
+                if (request.caller !== undefined) {
+                    try {
+                        authorizeTool({
+                            grantId: request.caller.grantId,
+                            allowedTools: request.caller.allowedTools,
+                            approvedRoots: [],
+                            remoteDestinations: [],
+                            hostedCode: false,
+                            recordingPolicy: request.caller.recordingPolicy,
+                            limits: request.caller.limits,
+                        }, request.name);
+                    }
+                    catch (error) {
+                        return { isError: true, message: error instanceof Error ? error.message : String(error) };
+                    }
+                }
+                if (request.name === 'model_tools') {
+                    return { isError: false, value: { models: describeModels(models) } };
+                }
+                if (request.name === 'tool_mode_run') {
+                    return {
+                        isError: true,
+                        message: 'tool_mode_run is registered but refused in the headless serve: this process composes no DSH hosted-code '
+                            + 'runtime (the ProgramRunner needs the DSH PtcHostContext), and the refusal is reported rather than a '
+                            + 'confinement the deployment does not have being claimed (CODE-10)',
+                    };
+                }
+                const binding = [...bindings.values()].find(candidate => candidate.contract.toolName === request.name);
+                if (binding === undefined) {
+                    return { isError: true, message: `unknown tool ${JSON.stringify(request.name)}` };
+                }
+                const { contract, adapter } = binding;
+                assertValidInput(contract, request.arguments);
+                for (const rule of crossFieldRules(contract)) {
+                    const violation = rule(request.arguments);
+                    if (violation !== undefined) {
+                        return { isError: true, message: `${contract.toolName}: ${violation}` };
+                    }
+                }
+                authorizeTool(host.grant, contract.toolName);
+                const nativeArgs = toNativeArgs(contract.contract, request.arguments);
+                const native = await adapter.invoke({
+                    args: nativeArgs,
+                    signal: request.signal,
+                    authority: createInvocationAuthority(host.grant, host.callerKind),
+                });
+                const payload = toContractPayload(contract.contract, native, request.arguments);
+                const meta = buildMeta(binding, host);
+                const value = { ...payload, meta };
+                assertValidOutput(contract, value);
+                host.recordReceipt?.(buildReceipt(binding, host, meta));
+                return { isError: false, value };
+            },
+        },
+    });
+    const endpoint = await startHttpServer({
+        path: config.mcpV3?.path ?? '/mcp',
+        host: config.mcpV3?.host ?? '127.0.0.1',
+        port: config.mcpV3?.port ?? 3765,
+        maxBodyBytes: 16 * 1024 * 1024,
+        allowedOrigins: [],
+        auth: { scheme: 'static-token', token, clientId: 'headless-serve' },
+    }, mcpHost);
+    let closing = false;
+    return {
+        url: endpoint.url,
+        host: endpoint.host,
+        port: endpoint.port,
+        async close() {
+            if (closing)
+                return;
+            closing = true;
+            await Promise.race([
+                endpoint.close(),
+                new Promise(resolve => setTimeout(resolve, 3000)),
+            ]);
+        },
+    };
+}
+/** The `model_tools` control contract, rendered for the headless MCP surface. */
+function modelToolsContract() {
+    return {
+        contract: 'model.tools',
+        version: '1.0.0',
+        toolName: 'model_tools',
+        description: 'Inspect the models this headless deployment can run.',
+        inputSchema: { type: 'object', additionalProperties: false, properties: {} },
+        outputSchema: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['models'],
+            properties: {
+                models: { type: 'array', items: { type: 'object', additionalProperties: true } },
+            },
+        },
+        semantics: { scoreKind: 'none' },
+        limits: {},
+        unsupported: ['Changing the catalog: this is an inspection surface.'],
+    };
+}
+/**
+ * Run the headless serve as a PROCESS (the launcher entry): prints the bound
+ * endpoint and waits for SIGINT/SIGTERM, then exits 0 after a bounded shutdown.
+ *
+ * @param options - the config path and the JSON-mode flag.
+ * @param io - output sinks (injected for tests).
+ * @returns the process exit code.
+ */
+export async function runHeadlessServe(options, io, signals = process) {
+    try {
+        const serve = await startHeadlessServe(options.configPath);
+        if (options.json === true) {
+            io.out(JSON.stringify({ ok: true, listening: true, url: serve.url }));
+        }
+        else {
+            io.out(`dsh-tool-mode serve: listening on ${serve.url}`);
+        }
+        return await new Promise(resolve => {
+            let shuttingDown = false;
+            const shutdown = () => {
+                if (shuttingDown)
+                    return;
+                shuttingDown = true;
+                void serve.close().finally(() => resolve(0));
+            };
+            signals.once('SIGINT', shutdown);
+            signals.once('SIGTERM', shutdown);
+        });
+    }
+    catch (error) {
+        if (error instanceof HeadlessConfigError) {
+            if (options.json === true)
+                io.out(JSON.stringify({ ok: false, error: error.message }));
+            else
+                io.err(`dsh-tool-mode serve: ${error.message}`);
+            return 2;
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        if (options.json === true)
+            io.out(JSON.stringify({ ok: false, error: message }));
+        else
+            io.err(`dsh-tool-mode serve: ${message}`);
+        return 1;
+    }
+}
+//# sourceMappingURL=headless.js.map

package/lib/http-acquisition.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The HTTP acquisition source for pinned asset downloads (RES-03).
+ *
+ * `acquireAsset` is source-agnostic and its tests inject fakes, which is right
+ * for the failure paths — but a source nobody wires means the host-driven
+ * acquisition path NDL-01 names was never exercised against a real URL. This
+ * module is the real source: fetch with byte ranges, bounded redirect
+ * handling, and no writes outside the injected store.
+ *
+ * @module @try-works/dsh-model-as-tool/http-acquisition
+ */
+import type { AcquisitionSource } from './asset-acquisition.ts';
+/**
+ * Create an HTTP acquisition source.
+ *
+ * Uses the platform fetch, which supports HTTPS and HTTP on Node 18+. Ranges
+ * are requested per chunk; a server that ignores the Range header is detected
+ * by the returned byte count and the transfer fails rather than resuming from
+ * wrong offsets.
+ * @param options - redirect budget and optional fetch override (for tests).
+ * @returns the source.
+ */
+export declare function createHttpSource(options?: {
+    readonly maxRedirects?: number;
+    readonly fetchImpl?: typeof fetch;
+}): AcquisitionSource;
+//# sourceMappingURL=http-acquisition.d.ts.map

package/lib/http-acquisition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-acquisition.d.ts","sourceRoot":"","sources":["../src/http-acquisition.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AAS/D;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE;IACxC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CAC7B,GAAG,iBAAiB,CAgEzB"}

package/lib/http-acquisition.js

@@ -0,0 +1,136 @@
+/**
+ * The HTTP acquisition source for pinned asset downloads (RES-03).
+ *
+ * `acquireAsset` is source-agnostic and its tests inject fakes, which is right
+ * for the failure paths — but a source nobody wires means the host-driven
+ * acquisition path NDL-01 names was never exercised against a real URL. This
+ * module is the real source: fetch with byte ranges, bounded redirect
+ * handling, and no writes outside the injected store.
+ *
+ * @module @try-works/dsh-model-as-tool/http-acquisition
+ */
+/** Maximum redirects followed, so a download cannot bounce forever. */
+const MAX_REDIRECTS = 5;
+/** Maximum response size a single range fetch admits, as a guard above the chunk size. */
+const MAX_CHUNK_BYTES = 16 * 1024 * 1024;
+/**
+ * Create an HTTP acquisition source.
+ *
+ * Uses the platform fetch, which supports HTTPS and HTTP on Node 18+. Ranges
+ * are requested per chunk; a server that ignores the Range header is detected
+ * by the returned byte count and the transfer fails rather than resuming from
+ * wrong offsets.
+ * @param options - redirect budget and optional fetch override (for tests).
+ * @returns the source.
+ */
+export function createHttpSource(options = {}) {
+    const maxRedirects = options.maxRedirects ?? MAX_REDIRECTS;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    return {
+        supportsRanges: true,
+        async fetchRange(asset, from, to, signal) {
+            if (to - from + 1 > MAX_CHUNK_BYTES) {
+                throw new Error(`a range fetch of ${to - from + 1} bytes exceeds the ${MAX_CHUNK_BYTES} cap`);
+            }
+            let url = asset.source;
+            for (let redirect = 0; redirect <= maxRedirects; redirect += 1) {
+                const response = await fetchImpl(url, {
+                    headers: { range: `bytes=${from}-${to}` },
+                    signal,
+                    // Redirects are followed MANUALLY so each hop is counted: a redirect
+                    // loop is an error, not a hang.
+                    redirect: 'manual',
+                });
+                if (response.status >= 300 && response.status < 400) {
+                    const location = response.headers.get('location');
+                    if (location === null) {
+                        throw new Error(`${asset.assetId}: a redirect carried no location`);
+                    }
+                    url = new URL(location, url).href;
+                    continue;
+                }
+                if (!response.ok) {
+                    throw new Error(`${asset.assetId}: HTTP ${response.status} fetching ${asset.source}`);
+                }
+                // RFC 9110 §14.2 permits a server to IGNORE the Range header entirely and
+                // answer 200 with the full body. That is a legal response, so it is
+                // handled rather than rejected: the wanted window is sliced out of the
+                // full body at ITS absolute offset, and the caller's offset math stays
+                // correct whether the server honored the Range or not. The budget admits
+                // exactly the bytes up to the window's end — the server chose to send
+                // them, and the operator already approved the asset's declared size.
+                const wanted = to - from + 1;
+                if (response.status === 200) {
+                    // The budget is the operator-approved asset size: a 200 IS the full
+                    // asset, which the approval already disclosed; anything beyond it is a
+                    // server that cannot be trusted.
+                    const body = await readBoundedBody(response, asset.bytes, `${asset.assetId}: full-body`);
+                    if (body.byteLength < from + wanted) {
+                        throw new Error(`${asset.assetId}: a 200 response carried ${body.byteLength} bytes, fewer than the ${from + wanted} the requested window requires`);
+                    }
+                    return body.subarray(from, from + wanted);
+                }
+                if (response.status === 206) {
+                    const body = await readBoundedBody(response, wanted, `${asset.assetId}: range body`);
+                    if (body.byteLength !== wanted) {
+                        // A 206 must carry exactly the range the Content-Range describes; a
+                        // short body means the server truncated, and trusting it would corrupt
+                        // the resume offsets.
+                        throw new Error(`${asset.assetId}: requested ${wanted} bytes at ${from}, received ${body.byteLength}`);
+                    }
+                    return body;
+                }
+                throw new Error(`${asset.assetId}: unexpected HTTP ${response.status}`);
+            }
+            throw new Error(`${asset.assetId}: more than ${maxRedirects} redirects`);
+        },
+    };
+}
+/**
+ * Read a response body under a HARD byte budget.
+ *
+ * The budget bounds MEMORY before any byte is buffered: the reader is streamed
+ * chunk by chunk and refuses the moment the running total would exceed the cap,
+ * so a Range-ignoring server cannot push an entire multi-GB asset into a single
+ * buffer (the round-48 review's finding 2).
+ * @param response - the response to read.
+ * @param budget - the maximum bytes admitted.
+ * @param label - what is being read, for the error.
+ * @returns the buffered bytes.
+ */
+async function readBoundedBody(response, budget, label) {
+    if (response.body === null) {
+        // No stream (rare: opaque or empty responses). Read with a guard anyway.
+        const buffer = new Uint8Array(await response.arrayBuffer());
+        if (buffer.byteLength > budget)
+            throw new Error(`${label} exceeded the ${budget} byte budget`);
+        return buffer;
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let total = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > budget) {
+                await reader.cancel();
+                throw new Error(`${label} exceeded the ${budget} byte budget`);
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return out;
+}
+//# sourceMappingURL=http-acquisition.js.map