@jini-ai/daemon 0.6.12 → 0.6.15-rc.1

package/dist/http/attachment-lookup-routes.js

@@ -0,0 +1,71 @@
+/**
+ * @module attachment-lookup-routes
+ *
+ * `POST /internal/attachment-lookup` — lets another local process (a site server running the
+ * attachment tools) read this daemon's `AttachmentStore` without owning a second copy of it. The
+ * store stays the sole owner of upload records; the caller gets exactly what the store's own two
+ * read methods return, including the store's non-disclosing rejection for a ref another run owns.
+ *
+ * Body: `{ op: "resolveForRun", ref, runId }` or `{ op: "listPendingForOwner", ownerId, runId? }`.
+ * Answer: `200 { value }` (`value: null` for an unknown ref), `400 ATTACHMENT_REJECTED` with
+ * `details.reason` for a store rejection, `400 BAD_REQUEST` for a malformed body, and a redacted
+ * `500` for anything else.
+ *
+ * Authentication is the host's: mount this behind the daemon's own bearer middleware. Run and owner
+ * ids come from the authenticated caller's execution context, never from model input — the store
+ * scopes by them (see `AttachmentStore.listPendingForOwner`).
+ */
+import express, {} from 'express';
+import { createApiError } from '@jini-ai/protocol';
+import { sendApiError, sendJson } from '@jini-ai/http-kit';
+import { AttachmentRejectedError } from './attachments.js';
+export const ATTACHMENT_LOOKUP_ROUTE_PATH = '/internal/attachment-lookup';
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function nonEmpty(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+function parseLookup(body) {
+    if (!isRecord(body))
+        return null;
+    if (body.op === 'resolveForRun' && nonEmpty(body.ref) && nonEmpty(body.runId))
+        return { op: 'resolveForRun', ref: body.ref, runId: body.runId };
+    if (body.op !== 'listPendingForOwner' || !nonEmpty(body.ownerId))
+        return null;
+    if (body.runId !== undefined && !nonEmpty(body.runId))
+        return null;
+    return { op: 'listPendingForOwner', ownerId: body.ownerId, ...(body.runId === undefined ? {} : { runId: body.runId }) };
+}
+async function runLookup(store, lookup) {
+    if (lookup.op === 'resolveForRun')
+        return (await store.resolveForRun({ ref: lookup.ref, runId: lookup.runId })) ?? null;
+    return store.listPendingForOwner({ ownerId: lookup.ownerId }, lookup.runId === undefined ? {} : { runId: lookup.runId });
+}
+function sendLookupFailure(res, error) {
+    if (error instanceof AttachmentRejectedError) {
+        sendApiError({ res, status: 400, error: createApiError({ code: 'ATTACHMENT_REJECTED', message: error.message }, { details: { reason: error.reason } }) });
+        return;
+    }
+    sendApiError({ res, status: 500, error: createApiError({ code: 'INTERNAL_ERROR', message: 'an internal error occurred' }) });
+}
+/**
+ * Mounts the lookup route. It brings a small JSON parser of its own, which is a no-op when the host
+ * already parsed the body upstream.
+ */
+export function registerAttachmentLookupRoutes({ app, store }, _optional = {}) {
+    app.post(ATTACHMENT_LOOKUP_ROUTE_PATH, express.json({ limit: '64kb' }), async (req, res) => {
+        const lookup = parseLookup(req.body);
+        if (lookup === null) {
+            sendApiError({ res, status: 400, error: createApiError({ code: 'BAD_REQUEST', message: 'body must be { op: "resolveForRun", ref, runId } or { op: "listPendingForOwner", ownerId, runId? }' }) });
+            return;
+        }
+        try {
+            sendJson({ res, status: 200, body: { value: await runLookup(store, lookup) } });
+        }
+        catch (error) {
+            sendLookupFailure(res, error);
+        }
+    });
+}
+//# sourceMappingURL=attachment-lookup-routes.js.map

package/dist/http/attachments.d.ts

@@ -1,3 +1,105 @@
+/**
+ * @module attachments
+ *
+ * `POST /api/attachments`, `DELETE /api/attachments` — an HTTP route pack for user file/image
+ * uploads staged for one agent run, over a narrow, transport-owned `AttachmentStore` port plus a
+ * batteries-included disk implementation (`createDiskAttachmentStore`).
+ *
+ * **The capability this closes.** A chat composer that accepts drag-and-drop needs somewhere to put
+ * the bytes, a way to hand the agent a path it is actually allowed to read, and a guarantee that
+ * those bytes disappear when the run ends. That is three separate concerns (an upload endpoint, a
+ * trusted-metadata registry, and a run-scoped lifetime) which every host would otherwise hand-roll.
+ * This module owns all three; `@jini-ai/chat-react`'s `createDaemonAttachmentUploader` is the
+ * matching client half.
+ *
+ * **Trust model.** A renderer supplies bytes, a filename, and a batch id. None of that is trusted:
+ * - the filename is reduced to a basename over a conservative character allowlist
+ *   (`sanitizeAttachmentName`) and is only ever used as *display* text plus a short extension
+ *   suffix — never as the stored filename, which is a fresh `randomUUID()`;
+ * - the `kind` (`'image' | 'file'`) is sniffed from the leading bytes (`detectAttachmentKind`),
+ *   never taken from a renderer-controlled MIME type or file extension;
+ * - the byte count is measured while streaming, never read from a client-supplied length;
+ * - the returned `path` is an opaque `attachment:<uuid>` capability id, not a filesystem path, so a
+ *   renderer never learns where the upload root is and cannot name a file it did not upload.
+ *   `claim()` is what exchanges those ids for real paths, server-side.
+ *
+ * **What `claim()` guarantees.** Exactly once per registered attachment, and only if the file is
+ * still the same file: `lstat` must report a regular non-symlink whose `dev`/`ino`/`size` and
+ * recorded modification/change timestamps match, and `realpath` must equal the recorded path
+ * (so neither the file nor any parent directory was swapped for a symlink between upload and run
+ * start). Legacy sidecars establish their timestamp baseline on first verified read. Every
+ * claimed attachment must belong to one batch, so the single `batchDirectory` a host grants the
+ * agent read access to cannot be widened by mixing batches.
+ *
+ * **Ownership is opt-in and host-attached, not self-asserted.** `register()`'s optional `ownerId`
+ * (and `listPendingForOwner`, the discovery method it enables) is never read from anything a
+ * renderer sends — a host wires `AttachmentsHttpDeps.resolveOwnerId` to pull it from a channel IT
+ * already trusts (its own session-verified principal header, say), never from `req` unauthenticated.
+ * A store with no `resolveOwnerId` wired registers every attachment ownerless, and
+ * `listPendingForOwner` never returns an ownerless record for any caller — see that method's own doc
+ * for why an absent `ownerId` must never become a wildcard match.
+ *
+ * **Storage lifetime is daemon-lifetime by default, and opt-in restart-surviving.** With
+ * `retainAcrossRestarts` left off (the default, and this pack's only behavior before that option
+ * existed), `createDiskAttachmentStore` empties its upload directory on construction: files left
+ * behind by an interrupted previous process cannot be authenticated against an in-memory registry
+ * that no longer exists, so they are removed rather than adopted. Unclaimed uploads also expire by
+ * TTL (`pruneExpired`), and a run's claimed files are deleted by `cleanupRun`.
+ *
+ * That default is wrong for any host whose process restarts while a person is still using the
+ * composer. A file-watching dev server restarting the daemon on an unrelated source edit is not a
+ * crash, but the construction wipe cannot tell the two apart, so it destroys uploads the user is
+ * about to send — real data loss, not a tidy-up. `retainAcrossRestarts: true` replaces "wipe
+ * everything, always" with "adopt exactly what can still be authenticated": see
+ * {@link prepareAttachmentStorage} for the whole mechanism and {@link loadPersistedAttachments} for
+ * why an adopted record is no less trusted than one this process registered itself.
+ *
+ * **This pack does not auto-wire itself into a run's lifecycle**, because no generic hook for that
+ * exists — the same deliberate choice `@jini-ai/daemon`'s `createRunScopedContextStore` makes. A
+ * host claims in its own `onRunStarted` and cleans up in a `finally`, roughly:
+ *
+ * ```ts
+ * const store = await createDiskAttachmentStore({ uploadDirectory });
+ * // ... httpExtensions: [(app, { adapter }) => registerAttachmentRoutes({ app, deps: { store }, adapter })]
+ * onRunStarted: (context) => {
+ *   void (async () => {
+ *     try {
+ *       const claimed = await store.claim({ attachments: attachmentRefsFrom(context.request), runId: context.run.id });
+ *       await executor.run({
+ *         runId: context.run.id,
+ *         // ... prompt, cwd, agentId
+ *       }, {
+ *         ...(claimed.batchDirectory === undefined ? {} : {
+ *           imagePaths: claimed.attachments.filter((a) => a.kind === 'image').map((a) => a.path),
+ *           extraAllowedDirs: [claimed.batchDirectory],
+ *           uploadRoot: claimed.batchDirectory,
+ *         }),
+ *       });
+ *     } finally {
+ *       await store.cleanupRun({ runId: context.run.id });
+ *     }
+ *   })();
+ * }
+ * ```
+ *
+ * `imagePaths`/`extraAllowedDirs`/`uploadRoot` are pre-existing `AgentExecutor.run()` options; this
+ * module only produces real values for them.
+ *
+ * **Body-parser ordering (`POST` reads the raw request stream).** The upload route streams
+ * `request` straight to disk, so any body-parsing middleware that has already consumed the stream
+ * leaves nothing to write. The classic way to hit this is a JSON body parser mounted app-wide: a
+ * user drops a `.json` file, the browser sets `content-type: application/json`, and
+ * `express.json()` eats the body — which without a guard shows up as the deeply unhelpful
+ * "attachment is empty". `registerAttachmentRoutes` detects an already-consumed stream up front and
+ * reports it as a host misconfiguration (`'attachment-body-consumed'`) instead of failing silently.
+ * Mount this pack before any global body parser, or scope the parser so it skips this path.
+ *
+ * **SEC-005 redaction**: a store failure can carry filesystem paths a caller must not see, so
+ * anything that is not an explicitly-classified `AttachmentRejectedError` becomes a
+ * correlation-id-bearing generic `INTERNAL_ERROR`, with the real error reaching a host-owned sink —
+ * the same `reportInternalError` shape `media.ts`/`delegated-tools.ts` use.
+ */
+import { type FileHandle } from 'node:fs/promises';
 import type { Express, Request, Response } from 'express';
 import type { AdapterContext } from '@jini-ai/http-kit';
 /**
@@ -36,6 +138,7 @@ export interface AttachmentClaim {
 /** Copy an already authenticated claim into the host's filesystem boundary. Keep the original
  * store records intact for promotion/read-back; the caller owns cleanup after the run ends.
  * Only claimed files are copied, never batch sidecars or another upload's capability ids.
+ * Exact staged paths alias the original store record until cleanup revokes them.
  * O(b) I/O for b claimed bytes, bounded by the attachment store's batch limits. Partial copies
  * are removed before rejection. The temporary directory is private and directly under real root.
  */
@@ -138,6 +241,9 @@ export interface AttachmentStore {
      * `image-prompt-delivery.ts` narrates the resolved PATH into the run's prompt text for an
      * already-claimed attachment — never the id — so a caller built from that prompt has the path, not
      * the id; a caller with the id (from the original upload response) can still use it directly.
+     * Exact paths issued by `stageAttachmentClaim()` for this store's claim also resolve to the
+     * original record, with the same run-ownership and integrity checks. Staging cleanup revokes
+     * those aliases. No basename inference or caller-supplied filesystem path is read.
      *
      * Ownership is enforced here, which is new: an attachment nobody has claimed yet is claimed for
      * `runId` on this call (identical effect to `claim()`, same integrity re-check); an attachment
@@ -440,18 +546,17 @@ export declare function detectAttachmentKind({ body }: {
  * Opened `wx`, so this can never overwrite an existing file. A partial write is removed before the
  * rejection propagates: the cap is enforced *during* the stream, which necessarily means some bytes
  * already reached disk by the time it trips.
+ * An optional already-open `handle` transfers ownership here: it is closed on success or failure.
+ * This lets the upload route recover a directory/open race before consuming any request bytes.
  */
-export declare function writeBoundedAttachmentBody(requiredArgs: Omit<{
-    request: AsyncIterable<unknown>;
-    filePath: string;
-    maxBytes: number;
-    mode?: number;
-}, 'mode'>, optionalArgs?: Pick<{
+export declare function writeBoundedAttachmentBody(requiredArgs: {
     request: AsyncIterable<unknown>;
     filePath: string;
     maxBytes: number;
+}, optionalArgs?: {
     mode?: number;
-}, 'mode'>): Promise<{
+    handle?: FileHandle;
+}): Promise<{
     size: number;
     signature: Uint8Array;
 }>;

package/dist/http/attachments.js

@@ -99,23 +99,32 @@
  * correlation-id-bearing generic `INTERNAL_ERROR`, with the real error reaching a host-owned sink —
  * the same `reportInternalError` shape `media.ts`/`delegated-tools.ts` use.
  */
-import { chmod, copyFile, lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, rm, rmdir, writeFile } from 'node:fs/promises';
+import { chmod, copyFile, lstat, mkdir, mkdtemp, open, readFile, readdir, realpath, rm, rmdir } from 'node:fs/promises';
 import { randomUUID } from 'node:crypto';
 import { basename, dirname, extname, resolve } from 'node:path';
 import { createApiError } from '@jini-ai/protocol';
 import { guardSameOrigin } from '@jini-ai/http-kit';
 import { sendApiError, sendJson } from '@jini-ai/http-kit';
 import { writeJsonFileAtomicAsync } from '@jini-ai/platform/fs';
+// Only objects returned by this store's claim() carry aliases. Weak keys keep this staging bridge
+// private without extending the wire/persisted formats or retaining completed claims indefinitely.
+const stagedPathsByAttachment = new WeakMap();
 /** Copy an already authenticated claim into the host's filesystem boundary. Keep the original
  * store records intact for promotion/read-back; the caller owns cleanup after the run ends.
  * Only claimed files are copied, never batch sidecars or another upload's capability ids.
+ * Exact staged paths alias the original store record until cleanup revokes them.
  * O(b) I/O for b claimed bytes, bounded by the attachment store's batch limits. Partial copies
  * are removed before rejection. The temporary directory is private and directly under real root.
  */
 export async function stageAttachmentClaim(required, _optional = {}) {
     const root = await realpath(required.filesystemRoot);
     const directory = await mkdtemp(resolve(root, '.agent-attachments-'));
-    const cleanup = () => rm(directory, { recursive: true, force: true });
+    const stagedAliases = new Map();
+    const cleanup = async () => {
+        for (const [path, aliases] of stagedAliases)
+            aliases.delete(path);
+        await rm(directory, { recursive: true, force: true });
+    };
     try {
         await chmod(directory, 0o700);
         const attachments = [];
@@ -124,6 +133,11 @@ export async function stageAttachmentClaim(required, _optional = {}) {
             await copyFile(attachment.path, target);
             await chmod(target, 0o600);
             attachments.push({ ...attachment, path: target });
+            const aliases = stagedPathsByAttachment.get(attachment);
+            if (aliases) {
+                aliases.add(target);
+                stagedAliases.set(target, aliases);
+            }
         }
         return { claim: { attachments, batchDirectory: directory }, cleanup };
     }
@@ -424,10 +438,12 @@ export function detectAttachmentKind({ body }, _optional = {}) {
  * Opened `wx`, so this can never overwrite an existing file. A partial write is removed before the
  * rejection propagates: the cap is enforced *during* the stream, which necessarily means some bytes
  * already reached disk by the time it trips.
+ * An optional already-open `handle` transfers ownership here: it is closed on success or failure.
+ * This lets the upload route recover a directory/open race before consuming any request bytes.
  */
 export async function writeBoundedAttachmentBody(requiredArgs, optionalArgs = {}) {
     const { request, filePath, maxBytes, mode = 0o600, } = { ...requiredArgs, ...optionalArgs };
-    const handle = await open(filePath, 'wx', mode);
+    const handle = optionalArgs.handle ?? await open(filePath, 'wx', mode);
     let total = 0;
     let signature = Buffer.alloc(0);
     try {
@@ -713,6 +729,10 @@ export async function createDiskAttachmentStore(requiredArgs, optionalArgs = {})
     // no record to authenticate it against) or adopts the previous process's authenticated survivors.
     // See `prepareAttachmentStorage`.
     const records = await prepareAttachmentStorage({ canonicalUploadDirectory, retainAcrossRestarts, retentionMs });
+    const stagedPathsByRecord = new WeakMap();
+    /** Only issued refs match; no caller-supplied path is opened. O(n) time for n stored records,
+     * bounded by maxStoredAttachments, with no filesystem I/O. */
+    const findRecord = ({ ref }, _optional = {}) => records.get(ref) ?? [...records.values()].find((candidate) => candidate.filePath === ref || stagedPathsByRecord.get(candidate)?.has(ref));
     const sidecarDirectory = resolve(canonicalUploadDirectory, SIDECAR_DIRECTORY_NAME);
     const sidecarPathFor = (record) => resolve(sidecarDirectory, attachmentSidecarFileName({ id: record.id }));
     /**
@@ -867,12 +887,13 @@ export async function createDiskAttachmentStore(requiredArgs, optionalArgs = {})
             try {
                 const batchDirectory = await verifyClaimedAttachments({ claimed });
                 return {
-                    attachments: claimed.map((record) => ({
-                        path: record.filePath,
-                        name: record.name,
-                        kind: record.kind,
-                        size: record.size,
-                    })),
+                    attachments: claimed.map((record) => {
+                        const attachment = { path: record.filePath, name: record.name, kind: record.kind, size: record.size };
+                        const aliases = new Set();
+                        stagedPathsByAttachment.set(attachment, aliases);
+                        stagedPathsByRecord.set(record, aliases);
+                        return attachment;
+                    }),
                     batchDirectory,
                 };
             }
@@ -886,7 +907,7 @@ export async function createDiskAttachmentStore(requiredArgs, optionalArgs = {})
             // Synchronous check-then-reserve, same reasoning as `reserveAttachmentRecords`: nothing may
             // `await` between reading `claimedRunId` and writing it, or a concurrent call could observe
             // the same unclaimed record and both believe they reserved it.
-            const record = records.get(ref) ?? [...records.values()].find((candidate) => candidate.filePath === ref);
+            const record = findRecord({ ref });
             if (!record)
                 return undefined;
             if (record.claimedRunId !== undefined && record.claimedRunId !== runId) {
@@ -995,18 +1016,38 @@ function refusalBeforeUpload({ req, state, maxConcurrentUploads }) {
     }
     return undefined;
 }
+/**
+ * Creates and exclusively opens one upload before its stream is consumed. Batch cleanup may
+ * remove an empty directory between mkdir/chmod/open, so retry that preparation once on ENOENT.
+ * Other failures propagate unchanged; the body writer owns the returned handle and partial file.
+ * @complexity O(1) filesystem operations and memory; at most two preparation attempts.
+ */
+async function openAttachmentUpload({ store, batchId, name }, _optional = {}) {
+    // A fresh UUID, never the client's filename. The extension is carried over (bounded) only
+    // because some agent runtimes decide how to read a file from its suffix.
+    const fileName = `${randomUUID()}${extname(name).slice(0, 12)}`;
+    const prepare = async (_required, _optional = {}) => {
+        const batchDirectory = await store.createBatchDirectory({ batchId });
+        const path = resolve(batchDirectory, fileName);
+        return { path, handle: await open(path, 'wx', 0o600) };
+    };
+    try {
+        return await prepare({});
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        return prepare({});
+    }
+}
 /**
  * The body of one admitted upload: prune, batch directory, bounded stream to disk, signature sniff,
  * register, answer. Throws for the caller to map; the caller owns the slot and the `finally` tidy.
  */
-async function storeAttachmentUpload({ req, res, deps, batchId, name, maxAttachmentBytes }) {
+async function storeAttachmentUpload({ req, res, deps, batchId, name, maxAttachmentBytes }, _optional = {}) {
     await deps.store.pruneExpired({});
-    const batchDirectory = await deps.store.createBatchDirectory({ batchId });
-    // A fresh UUID, never the client's filename. The extension is carried over (bounded) only
-    // because some agent runtimes decide how to read a file from its suffix.
-    const suffix = extname(name).slice(0, 12);
-    const path = resolve(batchDirectory, `${randomUUID()}${suffix}`);
-    const upload = await writeBoundedAttachmentBody({ request: req, filePath: path, maxBytes: maxAttachmentBytes });
+    const { path, handle } = await openAttachmentUpload({ store: deps.store, batchId, name });
+    const upload = await writeBoundedAttachmentBody({ request: req, filePath: path, maxBytes: maxAttachmentBytes }, { handle });
     if (upload.size === 0) {
         await rm(path, { force: true });
         sendApiError({ res, status: 400, error: createApiError({ code: 'BAD_REQUEST', message: 'Attachment is empty' }) });

package/dist/http/connectors.js

@@ -19,7 +19,8 @@
  * **SEC-005 throughout**: every provider call is wrapped so a raw storage/SQL/JWT/WebSocket error
  * never reaches the HTTP caller verbatim — matching `media.ts`/`delegated-tools.ts`'s
  * `reportInternalError` precedent exactly (a correlation-id-bearing generic `INTERNAL_ERROR`, the
- * real error only reaching a host-owned sink).
+ * real error only reaching a host-owned sink). Explicit `ClientFacingError` rejections retain
+ * their caller-safe API error without triggering that sink.
  *
  * **`NOT_CONFIGURED` (503)**: every route's very first check is whether its one required
  * capability slot (`deps.auth`/`deps.storage`/`deps.db`/`deps.realtime`) is even
@@ -45,7 +46,7 @@
  */
 import { randomUUID } from 'node:crypto';
 import { createApiError } from '@jini-ai/protocol';
-import { defineJsonRoute, mountJsonRoute } from '@jini-ai/http-kit';
+import { ClientFacingError, defineJsonRoute, mountJsonRoute } from '@jini-ai/http-kit';
 import { validationError } from '@jini-ai/http-kit';
 import { err, ok } from '@jini-ai/http-kit';
 function defaultInternalErrorSink(context) {
@@ -55,12 +56,15 @@ function defaultInternalErrorSink(context) {
 function notConfiguredError(capability) {
     return createApiError({ code: 'NOT_CONFIGURED', message: `${capability} provider not configured` });
 }
-/** Runs one provider call, converting any thrown error into a redacted, correlation-id-bearing `INTERNAL_ERROR` (SEC-005) instead of letting it reach the HTTP caller verbatim. */
-async function guardedCall(deps, source, operation, fn) {
+/** Runs one provider call, preserving explicit caller-safe rejections and converting unexpected
+ * errors into a redacted, correlation-id-bearing `INTERNAL_ERROR` (SEC-005). */
+async function guardedCall({ deps, source, operation, fn }, _optional = {}) {
     try {
         return ok({ value: await fn() });
     }
     catch (error) {
+        if (error instanceof ClientFacingError)
+            return err({ error: error.apiError });
         const correlationId = randomUUID();
         const sink = deps.onInternalError ?? defaultInternalErrorSink;
         sink({ source, operation, correlationId, error });
@@ -103,7 +107,7 @@ export const connectorsAuthSignUpRoute = defineJsonRoute({
     method: 'post', path: '/api/connectors/auth/signup', parse: parseAuthCredentials, handle: async ({ input: credentials, deps }) => {
         if (!deps.auth)
             return err({ error: notConfiguredError('auth') });
-        const result = await guardedCall(deps, 'auth', 'signUp', () => deps.auth.signUp(credentials));
+        const result = await guardedCall({ deps, source: 'auth', operation: 'signUp', fn: () => deps.auth.signUp(credentials) });
         return result.ok ? ok({ value: { user: result.value } }) : result;
     }
 }, { requireSameOrigin: true, successStatus: 201 });
@@ -111,7 +115,7 @@ export const connectorsAuthSignInRoute = defineJsonRoute({
     method: 'post', path: '/api/connectors/auth/signin', parse: parseAuthCredentials, handle: async ({ input: credentials, deps }) => {
         if (!deps.auth)
             return err({ error: notConfiguredError('auth') });
-        const result = await guardedCall(deps, 'auth', 'signIn', () => deps.auth.signIn(credentials));
+        const result = await guardedCall({ deps, source: 'auth', operation: 'signIn', fn: () => deps.auth.signIn(credentials) });
         return result.ok ? ok({ value: { session: result.value } }) : result;
     }
 }, { requireSameOrigin: true });
@@ -119,7 +123,7 @@ export const connectorsAuthSignOutRoute = defineJsonRoute({
     method: 'post', path: '/api/connectors/auth/signout', parse: parseAuthToken, handle: async ({ input: token, deps }) => {
         if (!deps.auth)
             return err({ error: notConfiguredError('auth') });
-        const result = await guardedCall(deps, 'auth', 'signOut', () => deps.auth.signOut({ token }));
+        const result = await guardedCall({ deps, source: 'auth', operation: 'signOut', fn: () => deps.auth.signOut({ token }) });
         return result.ok ? ok({ value: { ok: true } }) : result;
     }
 }, { requireSameOrigin: true });
@@ -127,7 +131,7 @@ export const connectorsAuthSessionRoute = defineJsonRoute({
     method: 'post', path: '/api/connectors/auth/session', parse: parseAuthToken, handle: async ({ input: token, deps }) => {
         if (!deps.auth)
             return err({ error: notConfiguredError('auth') });
-        const result = await guardedCall(deps, 'auth', 'verifySession', () => deps.auth.verifySession({ token }));
+        const result = await guardedCall({ deps, source: 'auth', operation: 'verifySession', fn: () => deps.auth.verifySession({ token }) });
         return result.ok ? ok({ value: { user: result.value } }) : result;
     }
 }, { requireSameOrigin: true });
@@ -180,7 +184,8 @@ export const connectorsStoragePutRoute = defineJsonRoute({
         if (!deps.storage)
             return err({ error: notConfiguredError('storage') });
         const options = contentType !== undefined ? { contentType } : undefined;
-        const result = await guardedCall(deps, 'storage', 'put', () => deps.storage.put({ key, data: Buffer.from(dataBase64, 'base64') }, options));
+        const result = await guardedCall({ deps, source: 'storage', operation: 'put', fn: () => deps.storage.put({ key, data: Buffer.from(dataBase64, 'base64') }, options),
+        });
         return result.ok ? ok({ value: { object: result.value } }) : result;
     }
 }, { requireSameOrigin: true });
@@ -188,7 +193,7 @@ export const connectorsStorageGetRoute = defineJsonRoute({
     method: 'get', path: '/api/connectors/storage/:key', parse: parseStorageKey, handle: async ({ input: key, deps }) => {
         if (!deps.storage)
             return err({ error: notConfiguredError('storage') });
-        const result = await guardedCall(deps, 'storage', 'get', () => deps.storage.get({ key }));
+        const result = await guardedCall({ deps, source: 'storage', operation: 'get', fn: () => deps.storage.get({ key }) });
         if (!result.ok)
             return result;
         if (result.value === null)
@@ -200,7 +205,7 @@ export const connectorsStorageDeleteRoute = defineJsonRoute({
     method: 'delete', path: '/api/connectors/storage/:key', parse: parseStorageKey, handle: async ({ input: key, deps }) => {
         if (!deps.storage)
             return err({ error: notConfiguredError('storage') });
-        const result = await guardedCall(deps, 'storage', 'delete', () => deps.storage.delete({ key }));
+        const result = await guardedCall({ deps, source: 'storage', operation: 'delete', fn: () => deps.storage.delete({ key }) });
         return result.ok ? ok({ value: { ok: true } }) : result;
     }
 }, { requireSameOrigin: true });
@@ -208,7 +213,7 @@ export const connectorsStorageListRoute = defineJsonRoute({
     method: 'get', path: '/api/connectors/storage', parse: parseStorageListQuery, handle: async ({ input: prefix, deps }) => {
         if (!deps.storage)
             return err({ error: notConfiguredError('storage') });
-        const result = await guardedCall(deps, 'storage', 'list', () => deps.storage.list({}, { prefix }));
+        const result = await guardedCall({ deps, source: 'storage', operation: 'list', fn: () => deps.storage.list({}, { prefix }) });
         return result.ok ? ok({ value: { objects: result.value } }) : result;
     }
 });
@@ -272,7 +277,7 @@ export const connectorsDbInsertRoute = defineJsonRoute({
     method: 'post', path: '/api/connectors/db/:collection', parse: parseDbInsert, handle: async ({ input: { collection, record }, deps }) => {
         if (!deps.db)
             return err({ error: notConfiguredError('db') });
-        const result = await guardedCall(deps, 'db', 'insert', () => deps.db.insert({ collection, record }));
+        const result = await guardedCall({ deps, source: 'db', operation: 'insert', fn: () => deps.db.insert({ collection, record }) });
         return result.ok ? ok({ value: { record: result.value } }) : result;
     }
 }, { requireSameOrigin: true, successStatus: 201 });
@@ -280,7 +285,7 @@ export const connectorsDbGetRoute = defineJsonRoute({
     method: 'get', path: '/api/connectors/db/:collection/:id', parse: parseDbCollectionId, handle: async ({ input: { collection, id }, deps }) => {
         if (!deps.db)
             return err({ error: notConfiguredError('db') });
-        const result = await guardedCall(deps, 'db', 'get', () => deps.db.get({ collection, id }));
+        const result = await guardedCall({ deps, source: 'db', operation: 'get', fn: () => deps.db.get({ collection, id }) });
         if (!result.ok)
             return result;
         if (result.value === null)
@@ -292,7 +297,7 @@ export const connectorsDbUpdateRoute = defineJsonRoute({
     method: 'patch', path: '/api/connectors/db/:collection/:id', parse: parseDbUpdate, handle: async ({ input: { collection, id, patch }, deps }) => {
         if (!deps.db)
             return err({ error: notConfiguredError('db') });
-        const result = await guardedCall(deps, 'db', 'update', () => deps.db.update({ collection, id, patch }));
+        const result = await guardedCall({ deps, source: 'db', operation: 'update', fn: () => deps.db.update({ collection, id, patch }) });
         if (!result.ok)
             return result;
         if (result.value === null)
@@ -304,7 +309,7 @@ export const connectorsDbDeleteRoute = defineJsonRoute({
     method: 'delete', path: '/api/connectors/db/:collection/:id', parse: parseDbCollectionId, handle: async ({ input: { collection, id }, deps }) => {
         if (!deps.db)
             return err({ error: notConfiguredError('db') });
-        const result = await guardedCall(deps, 'db', 'delete', () => deps.db.delete({ collection, id }));
+        const result = await guardedCall({ deps, source: 'db', operation: 'delete', fn: () => deps.db.delete({ collection, id }) });
         return result.ok ? ok({ value: { ok: true } }) : result;
     }
 }, { requireSameOrigin: true });
@@ -312,7 +317,7 @@ export const connectorsDbQueryRoute = defineJsonRoute({
     method: 'get', path: '/api/connectors/db/:collection', parse: parseDbQueryRequest, handle: async ({ input: { collection, query }, deps }) => {
         if (!deps.db)
             return err({ error: notConfiguredError('db') });
-        const result = await guardedCall(deps, 'db', 'query', () => deps.db.query({ collection }, query));
+        const result = await guardedCall({ deps, source: 'db', operation: 'query', fn: () => deps.db.query({ collection }, query) });
         return result.ok ? ok({ value: { records: result.value } }) : result;
     }
 });
@@ -330,7 +335,7 @@ export const connectorsRealtimePublishRoute = defineJsonRoute({
     method: 'post', path: '/api/connectors/realtime/:channel/publish', parse: parseRealtimePublish, handle: async ({ input: { channel, event }, deps }) => {
         if (!deps.realtime)
             return err({ error: notConfiguredError('realtime') });
-        const result = await guardedCall(deps, 'realtime', 'publish', () => deps.realtime.publish({ channel, event }));
+        const result = await guardedCall({ deps, source: 'realtime', operation: 'publish', fn: () => deps.realtime.publish({ channel, event }) });
         return result.ok ? ok({ value: { ok: true } }) : result;
     }
 }, { requireSameOrigin: true });

package/dist/http/index.d.ts

@@ -50,5 +50,11 @@ export { ATTACHMENTS_ROUTE_PATH, AttachmentRejectedError, createDiskAttachmentSt
 export type { XaiAuthStatusResponse, XaiHttpDeps, XaiInternalErrorContext, XaiOauthStartResponse, XaiOkResponse, XaiSearchResponse, } from './xai.js';
 export { registerXaiRoutes, xaiAuthStatusRoute, xaiOauthCancelRoute, xaiOauthCompleteRoute, xaiOauthDisconnectRoute, xaiOauthStartRoute, xaiSearchRoute, } from './xai.js';
 export * from './run-credentials.js';
+export type { RunWithToolContext, ToolExecutionRouteTarget, ToolExecutionRoutesOptional, ToolExecutionRoutesRequired, } from './tool-execution-routes.js';
+export { DEFAULT_TOOL_EXEC_MAX_BODY_BYTES, DEFAULT_TOOL_EXEC_TOKEN_ENV_VAR, registerToolExecutionRoutes, requireToolExecutionCaller, TOOL_CATALOG_ROUTE_PATH, TOOL_EXECUTIONS_ROUTE_PATH, } from './tool-execution-routes.js';
+export type { AttachmentLookup, AttachmentLookupRequest, AttachmentLookupRoutesRequired } from './attachment-lookup-routes.js';
+export { ATTACHMENT_LOOKUP_ROUTE_PATH, registerAttachmentLookupRoutes } from './attachment-lookup-routes.js';
+export type { RemoteAttachmentLookupOptional, RemoteAttachmentLookupRequired } from '../remote-attachment-lookup.js';
+export { createRemoteAttachmentLookup } from '../remote-attachment-lookup.js';
 export { createTavilyResearchProvider } from './research-tavily.adapter.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/http/index.js

@@ -26,5 +26,8 @@ export { mediaGenerateRoute, mediaTaskDeleteRoute, mediaTaskGetRoute, mediaTaskL
 export { ATTACHMENTS_ROUTE_PATH, AttachmentRejectedError, createDiskAttachmentStore, detectAttachmentKind, handleAttachmentCleanup, handleAttachmentUpload, isUnchangedAttachment, registerAttachmentRoutes, sanitizeAttachmentName, stageAttachmentClaim, writeBoundedAttachmentBody, } from './attachments.js';
 export { registerXaiRoutes, xaiAuthStatusRoute, xaiOauthCancelRoute, xaiOauthCompleteRoute, xaiOauthDisconnectRoute, xaiOauthStartRoute, xaiSearchRoute, } from './xai.js';
 export * from './run-credentials.js';
+export { DEFAULT_TOOL_EXEC_MAX_BODY_BYTES, DEFAULT_TOOL_EXEC_TOKEN_ENV_VAR, registerToolExecutionRoutes, requireToolExecutionCaller, TOOL_CATALOG_ROUTE_PATH, TOOL_EXECUTIONS_ROUTE_PATH, } from './tool-execution-routes.js';
+export { ATTACHMENT_LOOKUP_ROUTE_PATH, registerAttachmentLookupRoutes } from './attachment-lookup-routes.js';
+export { createRemoteAttachmentLookup } from '../remote-attachment-lookup.js';
 export { createTavilyResearchProvider } from './research-tavily.adapter.js';
 //# sourceMappingURL=index.js.map

package/dist/http/tool-execution-routes.d.ts

@@ -0,0 +1,69 @@
+/**
+ * @module tool-execution-routes
+ *
+ * `POST /internal/tool-executions` and `GET /internal/tool-catalog` — the server end of
+ * `createRemoteToolExecutor`. A host whose agent runtime runs in another local process mounts these
+ * over its own gated `ToolExecutor`, so that process can run tools without loading them. The wire
+ * protocol and the at-most-once rules are documented on `remote-tool-executor.ts`.
+ *
+ * Trust boundary, checked before any body byte is parsed:
+ * - a dedicated per-boot secret read from `tokenEnvVar`, compared in constant time; unset → 503 (the
+ *   route fails closed, there is no "open" mode), wrong or missing → 401;
+ * - the TCP peer (`req.socket.remoteAddress`, never a forwarded header) must be loopback → else 403.
+ * Only then does the route's own `express.json({ limit: maxBodyBytes })` run, so an unauthenticated
+ * caller cannot make the host buffer a large body, and an app-level parser with a smaller limit
+ * mounted after this route never sees these requests. Over the limit → 413.
+ *
+ * The executor below is the host's full gate (authorize, confirm, audit); this route adds no
+ * authority of its own and the serialized principal is passed through untouched for it to judge.
+ *
+ * Cancellation: the 200 headers are flushed before the executor runs, and the executor's signal
+ * aborts when the response closes before it finished (the caller destroyed its request). A request
+ * body that never completed never reaches the executor. Listeners are detached once the call
+ * settles, so a long-lived keep-alive socket never accumulates them.
+ */
+import { type ErrorRequestHandler, type RequestHandler } from 'express';
+import type { ToolDescriptor } from '@jini-ai/core';
+import type { ToolExecutor } from '../tool-executor.js';
+import { TOOL_EXECUTIONS_ROUTE_PATH } from '../remote-tool-executor.js';
+export { TOOL_EXECUTIONS_ROUTE_PATH };
+export declare const TOOL_CATALOG_ROUTE_PATH = "/internal/tool-catalog";
+export declare const DEFAULT_TOOL_EXEC_TOKEN_ENV_VAR = "JINI_TOOL_EXEC_TOKEN";
+/** Tool inputs carry whole documents; 16 MiB matches the largest the agent side sends. */
+export declare const DEFAULT_TOOL_EXEC_MAX_BODY_BYTES: number;
+/** Anything routes can be mounted on: an Express app or a `Router`. */
+export interface ToolExecutionRouteTarget {
+    post(path: string, ...handlers: Array<RequestHandler | ErrorRequestHandler>): unknown;
+    get(path: string, ...handlers: RequestHandler[]): unknown;
+}
+/** Runs one call inside host context (e.g. an AsyncLocalStorage scope) built from the wire `context`. */
+export type RunWithToolContext = <T>(required: {
+    readonly context: unknown;
+    readonly fn: () => Promise<T>;
+}, optional?: Record<string, never>) => Promise<T>;
+export interface ToolExecutionRoutesRequired {
+    readonly app: ToolExecutionRouteTarget;
+    readonly executor: ToolExecutor;
+    /** Built fresh on every catalog request; the route never caches it. */
+    readonly listToolsFor: (required: {
+        readonly principalId: string;
+    }, optional?: Record<string, never>) => readonly ToolDescriptor[] | Promise<readonly ToolDescriptor[]>;
+}
+export interface ToolExecutionRoutesOptional {
+    /** Env var holding the shared secret. Defaults to {@link DEFAULT_TOOL_EXEC_TOKEN_ENV_VAR}. */
+    readonly tokenEnvVar?: string;
+    /** Defaults to `process.env`; injectable so tests never mutate the real env. */
+    readonly env?: NodeJS.ProcessEnv;
+    /** Defaults to {@link DEFAULT_TOOL_EXEC_MAX_BODY_BYTES}. */
+    readonly maxBodyBytes?: number;
+    readonly runWithContext?: RunWithToolContext;
+}
+/** The token + loopback gate; mounted before any body parser. Exported for hosts that need it on another path. */
+export declare function requireToolExecutionCaller(_required: Record<string, never>, { tokenEnvVar, env }?: Pick<ToolExecutionRoutesOptional, 'tokenEnvVar' | 'env'>): RequestHandler;
+/**
+ * Mounts both routes on `app` (an Express app or a `Router`). Mount it BEFORE any app-level
+ * `express.json()` with a smaller limit: this route parses its own body after its gate, and an
+ * earlier parser would both buffer unauthenticated bodies and cap tool inputs at its own limit.
+ */
+export declare function registerToolExecutionRoutes({ app, executor, listToolsFor }: ToolExecutionRoutesRequired, { tokenEnvVar, env, maxBodyBytes, runWithContext }?: ToolExecutionRoutesOptional): void;
+//# sourceMappingURL=tool-execution-routes.d.ts.map