@jini-ai/daemon 0.6.8 → 0.6.9

package/dist/http/research-tavily.adapter.js

@@ -7,6 +7,74 @@ const TAVILY_MAX_RESULTS_LIMIT = 20;
 const DEFAULT_MAX_SOURCES = 5;
 /** Matches OD's own `tavily.ts` timeout — see research.ts's module doc. */
 const DEFAULT_TAVILY_TIMEOUT_MS = 30_000;
+/**
+ * Marks an error already redacted and formatted by `fetchTavilySearch`'s `!response.ok` branch, so
+ * `toTavilyFailure` can rethrow it verbatim instead of wrapping it a second time (which would
+ * otherwise produce a "Tavily request failed: Tavily 429: ..." double-prefixed message).
+ */
+class TavilyHttpError extends Error {
+}
+function resolveTavilyBase(credentials) {
+    const baseUrl = credentials.baseUrl ?? DEFAULT_TAVILY_BASE_URL;
+    const baseUrlCheck = validateBaseUrl({ baseUrl });
+    if (baseUrlCheck.error) {
+        throw new Error(baseUrlCheck.error);
+    }
+    return baseUrl.replace(/\/+$/, '');
+}
+function trimmedOrUndefined(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+/** One raw Tavily result as a source, or `null` when it carries no usable URL. */
+function toResearchSource(raw) {
+    const url = typeof raw.url === 'string' ? raw.url : '';
+    if (!url)
+        return null;
+    const publishedAt = trimmedOrUndefined(raw.published_date);
+    return {
+        title: trimmedOrUndefined(raw.title) ?? url,
+        url,
+        snippet: typeof raw.content === 'string' ? raw.content.trim().slice(0, 800) : '',
+        provider: 'tavily',
+        ...(publishedAt ? { publishedAt } : {}),
+    };
+}
+function parseTavilyResponse(json) {
+    const answer = typeof json.answer === 'string' ? json.answer : '';
+    const rawResults = Array.isArray(json.results) ? json.results : [];
+    const sources = [];
+    for (const raw of rawResults) {
+        const source = toResearchSource(raw);
+        if (source)
+            sources.push(source);
+    }
+    return { answer, sources };
+}
+async function fetchTavilySearch({ fetchImpl, url, apiKey, body, signal }) {
+    const response = await fetchImpl(url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}` },
+        body: JSON.stringify(body),
+        signal,
+    });
+    if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        throw new TavilyHttpError(redactSecrets({ input: `Tavily ${response.status}: ${text.slice(0, 200) || 'no body'}` }, { exactSecrets: [apiKey] }));
+    }
+    return parseTavilyResponse((await response.json()));
+}
+/** The redacted error `tavilySearch` throws for any failure: a timeout, an already-formatted HTTP error, or anything else. */
+function toTavilyFailure(error, { apiKey, timedOut }) {
+    if (!timedOut && error instanceof TavilyHttpError) {
+        return error;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return new Error(redactSecrets({
+        input: timedOut
+            ? `Tavily request timed out after ${DEFAULT_TAVILY_TIMEOUT_MS}ms`
+            : `Tavily request failed: ${message}`,
+    }, { exactSecrets: [apiKey] }));
+}
 /**
  * Calls Tavily's real `POST /search` endpoint directly — see research.ts's module doc for the port's exact
  * scope/provenance. Throws (never a `Result`) on any failure; the route handler in research.ts is the one
@@ -20,12 +88,7 @@ const DEFAULT_TAVILY_TIMEOUT_MS = 30_000;
  * `credentials` is still passed for its optional transport config (`baseUrl`).
  */
 async function tavilySearch({ apiKey, credentials, request }, { fetch: fetchImpl = globalThis.fetch } = {}) {
-    const baseUrl = credentials.baseUrl ?? DEFAULT_TAVILY_BASE_URL;
-    const baseUrlCheck = validateBaseUrl({ baseUrl });
-    if (baseUrlCheck.error) {
-        throw new Error(baseUrlCheck.error);
-    }
-    const base = baseUrl.replace(/\/+$/, '');
+    const base = resolveTavilyBase(credentials);
     // Floor before clamping, matching OD's real `clampMaxSources` — see research.ts's module doc. Without the
     // floor, a fractional `maxSources` (e.g. `2.7`, or `0.5` before the `Math.max(1, ...)` floor
     // below) would forward a non-integer `max_results` straight to Tavily's real API.
@@ -42,12 +105,7 @@ async function tavilySearch({ apiKey, credentials, request }, { fetch: fetchImpl
     // external audit caught (and locally reproduced) an earlier version of this fix that cleared
     // the timer right after `fetch` resolved, leaving `response.text()`/`response.json()` below
     // completely unbounded against a server that sends headers promptly and then stalls the body.
-    //
-    // `TavilyHttpError` marks an error already redacted and formatted by the `!response.ok` branch
-    // below, so the outer catch can rethrow it verbatim instead of wrapping it a second time (which
-    // would otherwise produce a "Tavily request failed: Tavily 429: ..." double-prefixed message).
-    class TavilyHttpError extends Error {
-    }
+    // `fetchTavilySearch` therefore reads the body inside the same armed window.
     const timeoutController = new AbortController();
     const timeoutHandle = setTimeout(() => timeoutController.abort(), DEFAULT_TAVILY_TIMEOUT_MS);
     // Assigned in the `try` and returned *after* the `finally`, rather than returned from inside the
@@ -57,45 +115,10 @@ async function tavilySearch({ apiKey, credentials, request }, { fetch: fetchImpl
     // keeps the cleanup path honestly measurable instead of permanently one-third uncovered.
     let output;
     try {
-        const response = await fetchImpl(`${base}/search`, {
-            method: 'POST',
-            headers: { 'content-type': 'application/json', authorization: `Bearer ${apiKey}` },
-            body: JSON.stringify(body),
-            signal: timeoutController.signal,
-        });
-        if (!response.ok) {
-            const text = await response.text().catch(() => '');
-            throw new TavilyHttpError(redactSecrets({ input: `Tavily ${response.status}: ${text.slice(0, 200) || 'no body'}` }, { exactSecrets: [apiKey] }));
-        }
-        const json = (await response.json());
-        const answer = typeof json.answer === 'string' ? json.answer : '';
-        const rawResults = Array.isArray(json.results) ? json.results : [];
-        const sources = [];
-        for (const raw of rawResults) {
-            const url = typeof raw.url === 'string' ? raw.url : '';
-            if (!url)
-                continue;
-            const publishedAt = typeof raw.published_date === 'string' && raw.published_date.trim() ? raw.published_date.trim() : undefined;
-            sources.push({
-                title: typeof raw.title === 'string' && raw.title.trim() ? raw.title.trim() : url,
-                url,
-                snippet: typeof raw.content === 'string' ? raw.content.trim().slice(0, 800) : '',
-                provider: 'tavily',
-                ...(publishedAt ? { publishedAt } : {}),
-            });
-        }
-        output = { answer, sources };
+        output = await fetchTavilySearch({ fetchImpl, url: `${base}/search`, apiKey, body, signal: timeoutController.signal });
     }
     catch (error) {
-        if (!timeoutController.signal.aborted && error instanceof TavilyHttpError) {
-            throw error;
-        }
-        const message = error instanceof Error ? error.message : String(error);
-        throw new Error(redactSecrets({
-            input: timeoutController.signal.aborted
-                ? `Tavily request timed out after ${DEFAULT_TAVILY_TIMEOUT_MS}ms`
-                : `Tavily request failed: ${message}`,
-        }, { exactSecrets: [apiKey] }));
+        throw toTavilyFailure(error, { apiKey, timedOut: timeoutController.signal.aborted });
     }
     finally {
         clearTimeout(timeoutHandle);

package/dist/http/research.js

@@ -98,9 +98,7 @@ import { redactSecrets } from '@jini-ai/core';
 import { randomUUID } from 'node:crypto';
 import { createTavilyResearchProvider } from './research-tavily.adapter.js';
 import { createApiError } from '@jini-ai/protocol';
-import { defineJsonRoute, mountJsonRoute } from '@jini-ai/http-kit';
-import { validationError } from '@jini-ai/http-kit';
-import { err, ok } from '@jini-ai/http-kit';
+import { defineJsonRoute, err, mountJsonRoute, ok, validationError } from '@jini-ai/http-kit';
 /** Matches OD's real `research/index.ts#searchResearch` query cap — see module doc. */
 const MAX_QUERY_LENGTH = 1000;
 function defaultInternalErrorSink(context) {
@@ -142,7 +140,7 @@ function validateRequestedProvider(rawProviders, providerId) {
     }
     return ok({ value: null });
 }
-function parseResearchSearch(input, providerId = 'tavily') {
+function parseResearchSearch(input, providerId) {
     if (!isRecord(input.body))
         return err({ error: validationError({ message: 'body must be a JSON object' }) });
     const rawQuery = nonEmptyString(input.body.query);
@@ -166,22 +164,45 @@ function synthesizeFallbackSummary(sources) {
         .join('\n');
     return `(No provider summary; top snippets follow.)\n${lead}`;
 }
+/** The route-bound provider, else the host's `deps.provider`, else the built-in Tavily transport over `deps.fetch`. */
+function selectProvider(bound, deps) {
+    return bound ?? deps.provider ?? createTavilyResearchProvider({}, deps.fetch ? { fetch: deps.fetch } : {});
+}
+/** The host's resolver, else `TAVILY_API_KEY` for a `'tavily'` provider and no credentials for any other. */
+function credentialResolver(provider, deps) {
+    return deps.resolveCredentials ?? (() => provider.id === 'tavily' ? defaultResolveCredentials({ env: deps.env ?? process.env }) : Promise.resolve({}));
+}
+/** Reports `error` to the host sink under a fresh correlation id and returns the generic SEC-005 public error. */
+function reportInternalError(deps, error) {
+    const correlationId = randomUUID();
+    (deps.onInternalError ?? defaultInternalErrorSink)({ correlationId, error });
+    return createApiError({ code: 'INTERNAL_ERROR', message: 'an internal error occurred' }, { requestId: correlationId });
+}
+/** A copy of a provider failure with `apiKey` redacted from its message, name and stack, safe for the error sink. */
+function redactProviderError(error, apiKey) {
+    const redact = (input) => redactSecrets({ input }, { exactSecrets: [apiKey] });
+    const safeError = new Error(redact(error instanceof Error ? error.message : String(error)));
+    if (error instanceof Error) {
+        safeError.name = redact(error.name);
+        if (error.stack === undefined)
+            delete safeError.stack;
+        else
+            safeError.stack = redact(error.stack);
+    }
+    return safeError;
+}
 /** Builds one route over a host-selected provider, preserving the default Tavily validation contract. */
 export function createResearchSearchRoute({ provider }, _optional = {}) {
     const providerId = provider?.id ?? 'tavily';
     return defineJsonRoute({
         method: 'post', path: '/api/research/search', parse: (input) => parseResearchSearch(input, providerId), handle: async ({ input: request, deps }) => {
-            const selectedProvider = provider ?? deps.provider ?? createTavilyResearchProvider({}, deps.fetch ? { fetch: deps.fetch } : {});
-            const resolveCredentials = deps.resolveCredentials ?? (() => selectedProvider.id === 'tavily' ? defaultResolveCredentials({ env: deps.env ?? process.env }) : Promise.resolve({}));
-            const onInternalError = deps.onInternalError ?? defaultInternalErrorSink;
+            const selectedProvider = selectProvider(provider, deps);
             let credentials;
             try {
-                credentials = await resolveCredentials({ providerId: selectedProvider.id });
+                credentials = await credentialResolver(selectedProvider, deps)({ providerId: selectedProvider.id });
             }
             catch (error) {
-                const correlationId = randomUUID();
-                onInternalError({ correlationId, error });
-                return err({ error: createApiError({ code: 'INTERNAL_ERROR', message: 'an internal error occurred' }, { requestId: correlationId }) });
+                return err({ error: reportInternalError(deps, error) });
             }
             const apiKey = credentials.apiKey;
             if (!apiKey) {
@@ -205,19 +226,8 @@ export function createResearchSearchRoute({ provider }, _optional = {}) {
                 return ok({ value: result });
             }
             catch (error) {
-                const correlationId = randomUUID();
                 // A host provider can throw transport text too; keep its configured key out of the sink.
-                const safeMessage = redactSecrets({ input: error instanceof Error ? error.message : String(error) }, { exactSecrets: [apiKey] });
-                const safeError = new Error(safeMessage);
-                if (error instanceof Error) {
-                    safeError.name = redactSecrets({ input: error.name }, { exactSecrets: [apiKey] });
-                    if (error.stack === undefined)
-                        delete safeError.stack;
-                    else
-                        safeError.stack = redactSecrets({ input: error.stack }, { exactSecrets: [apiKey] });
-                }
-                onInternalError({ correlationId, error: safeError });
-                return err({ error: createApiError({ code: 'INTERNAL_ERROR', message: 'an internal error occurred' }, { requestId: correlationId }) });
+                return err({ error: reportInternalError(deps, redactProviderError(error, apiKey)) });
             }
         }
     }, { requireSameOrigin: true });

package/dist/http/resource-request.d.ts

@@ -0,0 +1,37 @@
+import { type Result } from '@jini-ai/http-kit';
+import { type WorkspaceRootResolver } from './workspace-root.js';
+/** A plain JSON object body (not `null`, not an array). */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** Defined-only view of `T`: every key optional, and present only when its value is not `undefined`. */
+export type DefinedFields<T> = {
+    [K in keyof T]?: Exclude<T[K], undefined>;
+};
+/**
+ * Copies `fields` without its `undefined`-valued keys, keeping key order — the
+ * `...(x === undefined ? {} : { x })` spread pattern for many fields at once, so an absent
+ * optional field is omitted from the result rather than carried as `undefined`.
+ */
+export declare function withoutUndefined<T extends Record<string, unknown>>(fields: T): DefinedFields<T>;
+/** Reads an optional body field that, when present, must be a non-empty string; refuses with `<field> must be a non-empty string when provided`. */
+export declare function readOptionalNonEmptyString({ body, field }: {
+    readonly body: Readonly<Record<string, unknown>>;
+    readonly field: string;
+}): Result<string | undefined>;
+/** Reads an optional body field that, when present, must be `typeof 'number'` (NaN/Infinity included — see the terminals pin tests); refuses with `<field> must be a number when provided`. */
+export declare function readOptionalNumber({ body, field }: {
+    readonly body: Readonly<Record<string, unknown>>;
+    readonly field: string;
+}): Result<number | undefined>;
+/**
+ * Resolves `resourceRef`/`detail` to a working directory through `resolver`. A denial
+ * ({@link WorkspaceRootDeniedError}, which the zero-config `denyAllWorkspaceRoots` default always
+ * produces) becomes a generic `NOT_FOUND`; any other resolver failure is rethrown unchanged so the
+ * transport's internal-error path handles it rather than disguising it as a missing resource.
+ */
+export declare function resolveResourceRoot({ resourceRef, detail }: {
+    readonly resourceRef: string;
+    readonly detail?: string | undefined;
+}, { resolver }: {
+    readonly resolver: WorkspaceRootResolver;
+}): Promise<Result<string>>;
+//# sourceMappingURL=resource-request.d.ts.map

package/dist/http/resource-request.js

@@ -0,0 +1,59 @@
+/**
+ * @module resource-request
+ *
+ * Request-parsing and workspace-root helpers shared by the route packs that turn a caller's
+ * `resourceRef`/`detail` into a working directory: `host-tools.ts`'s open-in route and
+ * `terminals.ts`'s create route. Both previously inlined the same `detail` validation and the
+ * same "resolve the root, map a {@link WorkspaceRootDeniedError} to `NOT_FOUND`, rethrow anything
+ * else" block; this file is that one copy. Not re-exported from the package barrel.
+ */
+import { createApiError } from '@jini-ai/protocol';
+import { err, ok, validationError } from '@jini-ai/http-kit';
+import { resolveWorkspaceRoot, WorkspaceRootDeniedError } from './workspace-root.js';
+/** A plain JSON object body (not `null`, not an array). */
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * Copies `fields` without its `undefined`-valued keys, keeping key order — the
+ * `...(x === undefined ? {} : { x })` spread pattern for many fields at once, so an absent
+ * optional field is omitted from the result rather than carried as `undefined`.
+ */
+export function withoutUndefined(fields) {
+    return Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined));
+}
+/** Reads an optional body field that, when present, must be a non-empty string; refuses with `<field> must be a non-empty string when provided`. */
+export function readOptionalNonEmptyString({ body, field }) {
+    const value = body[field];
+    if (value === undefined)
+        return ok({ value: undefined });
+    if (typeof value !== 'string' || value.length === 0) {
+        return err({ error: validationError({ message: `${field} must be a non-empty string when provided` }) });
+    }
+    return ok({ value });
+}
+/** Reads an optional body field that, when present, must be `typeof 'number'` (NaN/Infinity included — see the terminals pin tests); refuses with `<field> must be a number when provided`. */
+export function readOptionalNumber({ body, field }) {
+    const value = body[field];
+    if (value === undefined || typeof value === 'number')
+        return ok({ value });
+    return err({ error: validationError({ message: `${field} must be a number when provided` }) });
+}
+/**
+ * Resolves `resourceRef`/`detail` to a working directory through `resolver`. A denial
+ * ({@link WorkspaceRootDeniedError}, which the zero-config `denyAllWorkspaceRoots` default always
+ * produces) becomes a generic `NOT_FOUND`; any other resolver failure is rethrown unchanged so the
+ * transport's internal-error path handles it rather than disguising it as a missing resource.
+ */
+export async function resolveResourceRoot({ resourceRef, detail }, { resolver }) {
+    try {
+        return ok({ value: await resolveWorkspaceRoot({ request: { resourceRef, ...withoutUndefined({ detail }) } }, { resolver }) });
+    }
+    catch (error) {
+        if (error instanceof WorkspaceRootDeniedError) {
+            return err({ error: createApiError({ code: 'NOT_FOUND', message: `resource "${resourceRef}" was not found` }) });
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=resource-request.js.map

package/dist/http/routines.js

@@ -96,46 +96,52 @@ function parseContextSelection(value) {
     }
     return ok({ value: context });
 }
+function parseOptionalBoolean(body, field) {
+    const value = body[field];
+    if (value !== undefined && typeof value !== 'boolean') {
+        return err({ error: validationError({ message: `${field} must be a boolean when provided` }) });
+    }
+    return ok({ value });
+}
+/** Table order is the validation order shared by create and update: the first failing field is the one a caller sees. */
+const ROUTINE_FIELD_PARSERS = [
+    ['name', (body) => parseNonEmptyString(body.name, 'name')],
+    ['prompt', (body) => parseNonEmptyString(body.prompt, 'prompt')],
+    ['schedule', (body) => parseSchedule(body.schedule)],
+    ['target', (body) => parseTarget(body.target)],
+    ['skillId', (body) => parseOptionalNullableString(body, 'skillId')],
+    ['agentId', (body) => parseOptionalNullableString(body, 'agentId')],
+    ['context', (body) => parseContextSelection(body.context)],
+    ['enabled', (body) => parseOptionalBoolean(body, 'enabled')],
+];
+/**
+ * Parses every routine field in table order, omitting any that parse to `undefined`. With
+ * `onlyProvided` (update), a field absent from the body is skipped before parsing, so required
+ * fields are not demanded and an absent `context` is not defaulted to `{}`.
+ */
+function parseRoutineFields({ body }, { onlyProvided = false } = {}) {
+    // `RoutineCreateInput`/`RoutineUpdateInput`'s fields are `readonly` (an immutable port-input
+    // contract) — built here as a mutable local shape field-by-field, then handed back as that
+    // readonly type, which is a safe widening (mutable -> readonly), not the reverse.
+    const fields = {};
+    for (const [key, parse] of ROUTINE_FIELD_PARSERS) {
+        if (onlyProvided && body[key] === undefined)
+            continue;
+        const parsed = parse(body);
+        if (!parsed.ok)
+            return parsed;
+        if (parsed.value !== undefined)
+            fields[key] = parsed.value;
+    }
+    return ok({ value: fields });
+}
 function parseRoutineCreate(input) {
     if (!isRecord(input.body))
         return err({ error: validationError({ message: 'body must be a JSON object' }) });
-    const name = parseNonEmptyString(input.body.name, 'name');
-    if (!name.ok)
-        return name;
-    const prompt = parseNonEmptyString(input.body.prompt, 'prompt');
-    if (!prompt.ok)
-        return prompt;
-    const schedule = parseSchedule(input.body.schedule);
-    if (!schedule.ok)
-        return schedule;
-    const target = parseTarget(input.body.target);
-    if (!target.ok)
-        return target;
-    const skillId = parseOptionalNullableString(input.body, 'skillId');
-    if (!skillId.ok)
-        return skillId;
-    const agentId = parseOptionalNullableString(input.body, 'agentId');
-    if (!agentId.ok)
-        return agentId;
-    const context = parseContextSelection(input.body.context);
-    if (!context.ok)
-        return context;
-    const enabled = input.body.enabled;
-    if (enabled !== undefined && typeof enabled !== 'boolean') {
-        return err({ error: validationError({ message: 'enabled must be a boolean when provided' }) });
-    }
-    return ok({
-        value: {
-            name: name.value,
-            prompt: prompt.value,
-            schedule: schedule.value,
-            target: target.value,
-            ...(skillId.value !== undefined ? { skillId: skillId.value } : {}),
-            ...(agentId.value !== undefined ? { agentId: agentId.value } : {}),
-            context: context.value,
-            ...(enabled !== undefined ? { enabled } : {}),
-        }
-    });
+    const fields = parseRoutineFields({ body: input.body });
+    if (!fields.ok)
+        return fields;
+    return ok({ value: fields.value });
 }
 function parseRoutineUpdate(input) {
     const idResult = parseRoutineId(input);
@@ -143,59 +149,12 @@ function parseRoutineUpdate(input) {
         return idResult;
     if (!isRecord(input.body))
         return err({ error: validationError({ message: 'body must be a JSON object' }) });
-    const body = input.body;
-    // `RoutineUpdateInput`'s fields are `readonly` (an immutable port-input contract) — built here
-    // as a mutable local shape field-by-field, then handed back as that readonly type, which is a
-    // safe widening (mutable -> readonly), not the reverse.
-    const patch = {};
-    if (body.name !== undefined) {
-        const name = parseNonEmptyString(body.name, 'name');
-        if (!name.ok)
-            return name;
-        patch.name = name.value;
-    }
-    if (body.prompt !== undefined) {
-        const prompt = parseNonEmptyString(body.prompt, 'prompt');
-        if (!prompt.ok)
-            return prompt;
-        patch.prompt = prompt.value;
-    }
-    if (body.schedule !== undefined) {
-        const schedule = parseSchedule(body.schedule);
-        if (!schedule.ok)
-            return schedule;
-        patch.schedule = schedule.value;
-    }
-    if (body.target !== undefined) {
-        const target = parseTarget(body.target);
-        if (!target.ok)
-            return target;
-        patch.target = target.value;
-    }
-    if (body.skillId !== undefined) {
-        const skillId = parseOptionalNullableString(body, 'skillId');
-        if (!skillId.ok)
-            return skillId;
-        patch.skillId = skillId.value ?? null;
-    }
-    if (body.agentId !== undefined) {
-        const agentId = parseOptionalNullableString(body, 'agentId');
-        if (!agentId.ok)
-            return agentId;
-        patch.agentId = agentId.value ?? null;
-    }
-    if (body.context !== undefined) {
-        const context = parseContextSelection(body.context);
-        if (!context.ok)
-            return context;
-        patch.context = context.value;
-    }
-    if (body.enabled !== undefined) {
-        if (typeof body.enabled !== 'boolean')
-            return err({ error: validationError({ message: 'enabled must be a boolean when provided' }) });
-        patch.enabled = body.enabled;
-    }
-    return ok({ value: { id: idResult.value, patch } });
+    // A provided `skillId`/`agentId` parses to a string or `null` (never `undefined`), so an explicit
+    // `null` reaches the patch and clears the field.
+    const patch = parseRoutineFields({ body: input.body }, { onlyProvided: true });
+    if (!patch.ok)
+        return patch;
+    return ok({ value: { id: idResult.value, patch: patch.value } });
 }
 function parseRoutineRunsQuery(input) {
     const idResult = parseRoutineId(input);

package/dist/http/runs.d.ts

@@ -37,12 +37,12 @@ export interface RunHttpDeps {
     /**
      * Delivers a message the human sent mid-run into that run's live agent — a host passes its
      * `AgentExecutor.sendUserMessage`. Omitted, every such message reports `'unsupported'`, so the
-     * client falls back to interrupting the run and sending the text as the next turn.
+     * client falls back to interrupting the run and sending the text as the next turn. Attachment
+     * turns use the explicit hook below, or report unsupported without sending anything.
      */
-    readonly deliverUserMessage?: (input: {
-        readonly runId: string;
-        readonly text: string;
-    }) => UserMessageDelivery | Promise<UserMessageDelivery>;
+    readonly deliverUserMessage?: (input: RunMessageRequest) => UserMessageDelivery | Promise<UserMessageDelivery>;
+    /** Explicit opt-in: legacy text-only hosts must never acknowledge a turn while discarding its files. */
+    readonly deliverUserMessageWithAttachments?: (input: RunMessageRequest) => UserMessageDelivery | Promise<UserMessageDelivery>;
 }
 export interface RunStartResponse {
     readonly run: RunStatus;
@@ -57,6 +57,8 @@ export interface RunCancelResponse {
 export interface RunMessageRequest {
     readonly runId: string;
     readonly text: string;
+    /** Opaque upload capabilities; the host must authorize and prepare every ref before delivery. */
+    readonly attachmentIds?: readonly string[];
 }
 export interface RunMessageResponse {
     readonly delivery: 'delivered';

package/dist/http/runs.js

@@ -5,11 +5,7 @@
  */
 import { randomUUID } from 'node:crypto';
 import { createApiError } from '@jini-ai/protocol';
-import { defineJsonRoute, mountJsonRoute } from '@jini-ai/http-kit';
-import { validationError } from '@jini-ai/http-kit';
-import { sendApiError } from '@jini-ai/http-kit';
-import { createSseChannel, requestedAfterCursor, sendRawApiError } from '@jini-ai/http-kit';
-import { err, ok } from '@jini-ai/http-kit';
+import { createSseChannel, defineJsonRoute, err, mountJsonRoute, ok, requestedAfterCursor, sendApiError, sendRawApiError, validationError, } from '@jini-ai/http-kit';
 /** Default sink when a host does not supply `onInternalError`: still observable, never silent. */
 function defaultInternalErrorSink(context) {
     // eslint-disable-next-line no-console
@@ -59,6 +55,20 @@ function parseRunCreate(input) {
 }
 /** Ceiling on one mid-run message, matching what a person can reasonably type or paste into a composer. */
 export const RUN_MESSAGE_MAX_CHARS = 100_000;
+/** Most attachment refs one mid-run message may carry. */
+const MAX_ATTACHMENTS_PER_MESSAGE = 10;
+/** An opaque upload capability: `attachment:` then 1-128 word characters or dashes, nothing path-shaped. */
+function isAttachmentRef(ref) {
+    return typeof ref === 'string' && /^attachment:[\w-]{1,128}$/u.test(ref);
+}
+/** `attachmentIds` is optional; when present it must be an array of at most ten well-formed refs, or the whole message is refused. */
+function parseAttachmentIds(value) {
+    if (value === undefined)
+        return ok({ value: undefined });
+    if (Array.isArray(value) && value.length <= MAX_ATTACHMENTS_PER_MESSAGE && value.every(isAttachmentRef))
+        return ok({ value });
+    return err({ error: validationError({ message: 'attachmentIds must contain at most 10 opaque attachment refs' }) });
+}
 function parseRunMessage(input) {
     const parsedRunId = parseRunId(input);
     if (!parsedRunId.ok)
@@ -72,7 +82,10 @@ function parseRunMessage(input) {
     if (text.length > RUN_MESSAGE_MAX_CHARS) {
         return err({ error: validationError({ message: `text must be at most ${RUN_MESSAGE_MAX_CHARS} characters` }, { issues: [{ path: 'text', message: 'too long' }] }) });
     }
-    return ok({ value: { runId: parsedRunId.value, text } });
+    const attachmentIds = parseAttachmentIds(input.body.attachmentIds);
+    if (!attachmentIds.ok)
+        return attachmentIds;
+    return ok({ value: { runId: parsedRunId.value, text, ...(attachmentIds.value === undefined ? {} : { attachmentIds: attachmentIds.value }) } });
 }
 function parseRunList(input) {
     const value = input.query.contextRef;
@@ -149,7 +162,8 @@ export const runMessageRoute = defineJsonRoute({
         const run = await deps.lifecycle.get({ runId: input.runId });
         if (run === undefined)
             return err({ error: createApiError({ code: 'NOT_FOUND', message: `run "${input.runId}" was not found` }) });
-        const delivery = deps.deliverUserMessage ? await deps.deliverUserMessage({ runId: input.runId, text: input.text }) : 'unsupported';
+        const deliver = input.attachmentIds?.length ? deps.deliverUserMessageWithAttachments : deps.deliverUserMessage;
+        const delivery = deliver ? await deliver(input) : 'unsupported';
         if (delivery === 'delivered')
             return ok({ value: { delivery } });
         return err({ error: createApiError({ code: 'CONFLICT', message: `run "${input.runId}" did not take the message` }, { details: { delivery } }) });