@jini-ai/platform 0.6.15-rc.2 → 0.6.16

package/dist/secrets/credential-sets/vault-archive.js

@@ -0,0 +1,64 @@
+import { VaultError, isInVaultQueryScope } from "./vault.types.js";
+function assertPortable(kind, principalId) {
+    // Personal and MCP credentials require their own identity/configuration transport, outside v1.
+    if (principalId !== null || ["personal-execution", "mcp-env", "mcp-auth"].includes(kind))
+        throw new VaultError({ code: "context" });
+}
+/** Capture through the owning service's authorization and parsers. Hosts supply exact scopes and
+ * attachment-filtered repositories; this helper never discovers other workspaces or principals.
+ * Diagnostics contain only a count, because even labels/IDs may contain pasted secrets.
+ * @example const captured = await captureVaultArchive({ vault, repo, queries: [siteScope] });
+ * @complexity O(rows + payload bytes), bounded to 2,000 rows by the transport contract.
+ */
+export async function captureVaultArchive({ vault, queries, repo }, _options = {}) {
+    const entries = [];
+    let omitted = 0, count = 0;
+    for (const query of queries) {
+        assertPortable(query.kind, query.principalId);
+        // Optional raw enumeration isolates unsupported metadata; every payload still passes get's
+        // exact identity, authorization, parser and AAD checks before it can enter the result.
+        for (const row of await (repo ?? vault).list(query)) {
+            if (++count > 2000)
+                throw new VaultError({ code: "invalid-record" });
+            try {
+                if (!isInVaultQueryScope({ record: row, query }))
+                    throw new VaultError({ code: "context" });
+                const found = await vault.get(row);
+                if (!found)
+                    throw new VaultError({ code: "conflict" });
+                const s = found.summary;
+                entries.push({ id: s.id, kind: s.kind, ownerKey: s.ownerKey, binding: s.binding, provider: s.provider,
+                    label: s.label, isDefault: s.isDefault, meta: s.meta, payload: found.payload });
+            }
+            catch {
+                omitted++;
+            }
+        }
+    }
+    return { entries, notices: omitted ? [`${omitted} saved credential(s) could not be opened and were left out.`] : [] };
+}
+/** Validate and re-seal every entry before the host atomically commits any of them. Keeping the
+ * transaction in the host lets settings and vault rows join the same commit. Never call put in a
+ * loop: a bad later entry must leave the recipient completely unchanged.
+ * @throws VaultError or the host's policy error; callers expose a fixed optional-import notice.
+ * @example const records = await prepareVaultArchiveRestore({ vault, workspaceId, entries });
+ * @complexity O(entries + payload bytes), at most 2,000 entries.
+ */
+export async function prepareVaultArchiveRestore({ vault, workspaceId, entries }, _options = {}) {
+    if (!Array.isArray(entries) || entries.length > 2000)
+        throw new VaultError({ code: "invalid-record" });
+    const ids = new Set();
+    const records = [];
+    for (const entry of entries) {
+        assertPortable(entry.kind, null);
+        if (ids.has(entry.id))
+            throw new VaultError({ code: "invalid-record" });
+        ids.add(entry.id);
+        // Enumerating fields prevents an archive from supplying a revision, principal or workspace.
+        records.push(await vault.prepare({ workspaceId, id: entry.id, kind: entry.kind, ownerKey: entry.ownerKey,
+            principalId: null, binding: entry.binding, provider: entry.provider, label: entry.label,
+            isDefault: entry.isDefault, meta: entry.meta, payload: entry.payload, expectedRevision: null }));
+    }
+    return records;
+}
+//# sourceMappingURL=vault-archive.js.map

package/dist/secrets/credential-sets/vault.meta.js

@@ -39,16 +39,20 @@ function isJson(value) {
  * @throws VaultError when a supplied subtype or compatibility list is invalid.
  * @complexity O(worksFor characters); returns a fresh metadata object.
  */
+/** Older vendor rows imply compatibility with their own provider; nothing else implies any. */
+function defaultWorksFor({ credentialType, provider }) {
+    return credentialType === "vendor" && provider != null ? [provider] : [];
+}
 function credentialMeta({ meta, kind, provider }) {
     const credentialType = meta.credentialType === undefined ? kind : meta.credentialType;
     if ((credentialType !== "vendor" && credentialType !== "custom") || (kind === "custom" && credentialType !== "custom"))
         throw new VaultError({ code: "invalid-meta" });
-    const worksFor = meta.worksFor === undefined ? (credentialType === "vendor" && provider != null ? [provider] : []) : meta.worksFor;
+    const worksFor = meta.worksFor === undefined ? defaultWorksFor({ credentialType, provider }) : meta.worksFor;
     return { ...meta, credentialType, worksFor: normalizeCredentialWorksFor({ value: worksFor }) };
 }
 /** Plain JSON object with identifier-only top-level keys; checked on input and on override output. */
 function requireMetaShape({ value }) {
-    if (!isObject(value) || !isJson(value) || Object.keys(value).some(key => !/^[A-Za-z0-9_]+$/.test(key)))
+    if (!isObject(value) || !isJson(value) || Object.keys(value).some(key => !/^\w+$/.test(key)))
         throw new VaultError({ code: "invalid-meta" });
     return value;
 }

package/dist/secrets/credential-sets/vault.repo.memory.js

@@ -1,4 +1,4 @@
-import { assertVaultReplacement, vaultGroupKey, VaultError } from "./vault.types.js";
+import { assertVaultReplacement, isInVaultQueryScope, vaultGroupKey, VaultError } from "./vault.types.js";
 /** Single-turn mutations are atomic in JS; clones prevent callers bypassing CAS through aliases. */
 export class InMemoryVaultRepo {
     rows = new Map();
@@ -56,15 +56,13 @@ export class InMemoryVaultRepo {
     /** O(n) memory scan, n stored rows; clones only the default, never its siblings. */
     async findDefault(input, _options = {}) {
         for (const row of this.rows.values()) {
-            if (row.isDefault && row.workspaceId === input.workspaceId && row.kind === input.kind && row.ownerKey === input.ownerKey &&
-                row.principalId === input.principalId && row.provider === input.provider)
+            if (row.isDefault && row.provider === input.provider && isInVaultQueryScope({ record: row, query: input }))
                 return structuredClone(row);
         }
         return null;
     }
     async list(input, _options = {}) {
-        return structuredClone([...this.rows.values()].filter(row => row.workspaceId === input.workspaceId && row.kind === input.kind &&
-            row.ownerKey === input.ownerKey && row.principalId === input.principalId && (input.provider === undefined || row.provider === input.provider))
+        return structuredClone([...this.rows.values()].filter(row => isInVaultQueryScope({ record: row, query: input }))
             // Rows are keyed by (workspaceId, id), so one workspace never lists two equal IDs.
             .sort((a, b) => a.id < b.id ? -1 : 1));
     }

package/dist/secrets/credential-sets/vault.service.js

@@ -1,18 +1,23 @@
 import { credentialTokenHint } from "../credential-token.js";
 import { buildVaultAad } from "./vault.aad.js";
 import { isCopyableKind } from "./vault.meta.js";
-import { VAULT_KINDS, VaultError } from "./vault.types.js";
+import { VAULT_KINDS, VaultError, isInVaultQueryScope } from "./vault.types.js";
 /** Kinds whose payloads are addresses, environment maps or OAuth sessions, never single tokens. */
 const HINTLESS_KINDS = ["database-destination", "mcp-env", "mcp-auth"];
 function isNonEmptyString({ value }) {
     return typeof value === "string" && value !== "";
 }
+/** The one error for malformed, missing or unsupported records and repo capabilities. */
+function invalidRecord() {
+    return new VaultError({ code: "invalid-record" });
+}
 function isNullableString({ value }) {
     return value === null || typeof value === "string";
 }
 function hasValidOwnership({ context }) {
+    const validBinding = !("binding" in context) || isNullableString({ value: context.binding });
     return isNonEmptyString({ value: context.workspaceId }) && isNonEmptyString({ value: context.ownerKey }) &&
-        isNullableString({ value: context.principalId }) && (!("binding" in context) || isNullableString({ value: context.binding }));
+        isNullableString({ value: context.principalId }) && validBinding;
 }
 function hasValidKind({ context }) {
     if (!VAULT_KINDS.some(kind => kind === context.kind) && context.kind !== "custom")
@@ -25,19 +30,19 @@ function assertContext(context) {
 }
 /** Unified credential rows declare both subtype and compatibility; read defaults cover older rows. */
 function declaresCredential({ meta }) {
-    return meta !== null && typeof meta === "object" && Object.hasOwn(meta, "credentialType") && Object.hasOwn(meta, "worksFor");
-}
-function isInQueryScope({ record, query }) {
-    return record.workspaceId === query.workspaceId && record.kind === query.kind && record.ownerKey === query.ownerKey &&
-        record.principalId === query.principalId && (query.provider === undefined || record.provider === query.provider);
+    if (meta === null || typeof meta !== "object")
+        return false;
+    return Object.hasOwn(meta, "credentialType") && Object.hasOwn(meta, "worksFor");
 }
 /** Copy changes the site/key, never the credential's owning feature or endpoint. Principal
  * identities are local to each installation and cannot be carried to the target.
  */
 function isCopyTarget({ sourceContext, targetContext, sameRepo }) {
-    return sourceContext.kind === targetContext.kind && sourceContext.ownerKey === targetContext.ownerKey &&
-        sourceContext.binding === targetContext.binding && sourceContext.principalId === null && targetContext.principalId === null &&
-        !(sameRepo && sourceContext.workspaceId === targetContext.workspaceId);
+    const sameFeature = sourceContext.kind === targetContext.kind && sourceContext.ownerKey === targetContext.ownerKey &&
+        sourceContext.binding === targetContext.binding;
+    const noPrincipal = sourceContext.principalId === null && targetContext.principalId === null;
+    const sameSite = sameRepo && sourceContext.workspaceId === targetContext.workspaceId;
+    return sameFeature && noPrincipal && !sameSite;
 }
 function sourceNeedsUpgrade({ raw }) {
     return Object.hasOwn(raw.meta, "legacyAad") || (raw.kind === "vendor" && !declaresCredential({ meta: raw.meta }));
@@ -97,7 +102,7 @@ export class SecretsVaultService {
         // JSON round-trip makes the payload contract explicit; encryption never receives an object
         // coerced to '[object Object]' or a connection URI masquerading as an entire payload.
         if (typeof input.payload !== "object" || Array.isArray(input.payload))
-            throw new VaultError({ code: "invalid-record" });
+            throw invalidRecord();
         const plaintext = JSON.stringify(input.payload);
         return this.deps.sealer.seal({ plaintext, key: await this.deps.keyring.activeKey({}), aad: buildVaultAad(input.context) });
     }
@@ -110,10 +115,10 @@ export class SecretsVaultService {
             payload = JSON.parse(plaintext);
         }
         catch {
-            throw new VaultError({ code: "invalid-record" });
+            throw invalidRecord();
         }
         if (payload === null || typeof payload !== "object" || Array.isArray(payload))
-            throw new VaultError({ code: "invalid-record" });
+            throw invalidRecord();
         return payload;
     }
     /** Create/replace configuration and a sealed JSON payload. Throws on policy, validation or CAS failure. */
@@ -167,7 +172,7 @@ export class SecretsVaultService {
     async putEnvelope({ input, identity, existing }) {
         if (input.payload === undefined) {
             if (!existing)
-                throw new VaultError({ code: "invalid-record" });
+                throw invalidRecord();
             return { sealed: existing.sealed, last4: existing.last4, tokenLength: existing.tokenLength };
         }
         const sealed = await this.seal({ context: identity, payload: input.payload });
@@ -195,7 +200,7 @@ export class SecretsVaultService {
         assertContext(input);
         await this.authorize({ action: "get", context: input });
         if (!this.deps.repo.findOne)
-            throw new VaultError({ code: "invalid-record" });
+            throw invalidRecord();
         const record = await this.deps.repo.findOne(input);
         if (!record)
             return null;
@@ -213,7 +218,7 @@ export class SecretsVaultService {
         await this.authorize({ action: "get", context: input });
         // Old injected ports retain their existing operations; default reads require this capability.
         if (!this.deps.repo.findDefault)
-            throw new VaultError({ code: "invalid-record" });
+            throw invalidRecord();
         const record = await this.deps.repo.findDefault(input);
         if (!record)
             return null;
@@ -301,7 +306,7 @@ export class SecretsVaultService {
         assertContext(input);
         await this.authorize({ action: "list", context: input });
         return (await this.deps.repo.list(input)).map(record => {
-            if (!isInQueryScope({ record, query: input }))
+            if (!isInVaultQueryScope({ record, query: input }))
                 throw new VaultError({ code: "context" });
             return summary(this.parse(record));
         });

package/dist/secrets/credential-sets/vault.types.d.ts

@@ -152,6 +152,12 @@ export interface VaultRepoPort {
         expectedRevision: number;
     }, options?: VaultOptions): Promise<boolean>;
 }
+/** The record belongs to the query's exact workspace, kind, owner and principal; an omitted provider
+ * matches every provider. @complexity O(1). */
+export declare function isInVaultQueryScope({ record, query }: {
+    record: Pick<VaultRecord, keyof VaultQuery>;
+    query: VaultQuery;
+}, _options?: VaultOptions): boolean;
 /** Unambiguous scope encoding keeps adapter default/identity checks on the same contract. */
 export declare function vaultGroupKey({ record }: {
     record: VaultDefaultQuery;

package/dist/secrets/credential-sets/vault.types.js

@@ -9,6 +9,13 @@ export class VaultError extends Error {
         this.name = "VaultError";
     }
 }
+/** The record belongs to the query's exact workspace, kind, owner and principal; an omitted provider
+ * matches every provider. @complexity O(1). */
+export function isInVaultQueryScope({ record, query }, _options = {}) {
+    const sameOwner = record.workspaceId === query.workspaceId && record.kind === query.kind && record.ownerKey === query.ownerKey;
+    const sameProvider = query.provider === undefined || record.provider === query.provider;
+    return sameOwner && record.principalId === query.principalId && sameProvider;
+}
 /** Unambiguous scope encoding keeps adapter default/identity checks on the same contract. */
 export function vaultGroupKey({ record }, _options = {}) {
     return JSON.stringify([record.workspaceId, record.kind, record.ownerKey, record.principalId, record.provider]);

package/dist/secrets/credential-token.js

@@ -60,10 +60,17 @@ export function credentialTokenHint({ token }, _optional = {}) {
     return { length: token.length, last4: token.length >= 12 ? token.slice(-4) : null };
 }
 const SECRET_NAME = /(?:^|[_-])(?:key|api[_-]?key|token|access[_-]?token|secret|password|auth|sig)$/i;
-const SECRET_ARG = /(?:^|\s)--[\w-]*(?:api[_-]?key|token|secret|password)(?:=|\s+)(?!\s*$)\S/i;
+// A `--flag` followed by a value; the flag name is captured whole and its suffix checked separately,
+// so the name run and the keyword can no longer backtrack against each other.
+const CLI_FLAG_WITH_VALUE = /(?:^|\s)--([\w-]*)(?=(?:=|\s+)\S)/gi;
+const SECRET_FLAG_SUFFIX = /(?:api[_-]?key|token|secret|password)$/i;
+/** True when some `--…api-key/token/secret/password` flag carries a value. @complexity O(value length). */
+function hasSecretCliArg(value) {
+    return [...value.matchAll(CLI_FLAG_WITH_VALUE)].some(match => SECRET_FLAG_SUFFIX.test(match[1]));
+}
 /** Protect plaintext metadata, using Jini's detector plus structural URL/CLI rules. */
 export function assertCredentialFreeField({ value, field, containsSecret }, _optional = {}) {
-    let credential = containsSecret({ text: value }) || SECRET_ARG.test(value);
+    let credential = containsSecret({ text: value }) || hasSecretCliArg(value);
     try {
         const url = new URL(value);
         credential ||= url.username !== '' || url.password !== '' || [...url.searchParams.keys()].some(key => SECRET_NAME.test(key));

package/dist/secrets/keyring.env.js

@@ -206,8 +206,7 @@ function toActiveRootKeyMaterial(source, raw) {
  * @example inspectRootKeyMaterial({ env, envVarName, keyFilePath })
  */
 export function inspectRootKeyMaterial(options) {
-    const envVarName = options.envVarName;
-    const keyFilePath = options.keyFilePath;
+    const { envVarName, keyFilePath } = options;
     const raw = readActiveRootKeyMaterial({ env: options.env, envVarName, keyFilePath });
     if (raw.hex)
         return { active: true, source: raw.source, fingerprint: fingerprintRootKeyHex({ hex: raw.hex }), keyFilePath };
@@ -221,8 +220,7 @@ function invalidFields(raw) {
  * @example revealRootKeyMaterial({ env, envVarName, keyFilePath })
  */
 export function revealRootKeyMaterial(options) {
-    const envVarName = options.envVarName;
-    const keyFilePath = options.keyFilePath;
+    const { envVarName, keyFilePath } = options;
     const raw = readActiveRootKeyMaterial({ env: options.env, envVarName, keyFilePath });
     if (raw.hex)
         return { active: true, source: raw.source, hex: raw.hex, fingerprint: fingerprintRootKeyHex({ hex: raw.hex }), keyFilePath };

package/dist/shell.js

@@ -41,7 +41,8 @@ export function execFileBuffered(command, args, opts = {}) {
 /** @internal Single-quote a POSIX shell argument, escaping embedded single quotes. */
 function quotePosixShellArg(value) {
     const text = String(value ?? "");
-    return `'${text.replace(/'/g, `'\\''`)}'`;
+    const escapedQuote = "'\\''";
+    return `'${text.replace(/'/g, escapedQuote)}'`;
 }
 /** @internal Join a command and its arguments into one quoted POSIX shell command line. */
 function buildShellCommandLine(command, args) {

package/dist/terminal.js

@@ -171,7 +171,8 @@ export function createTerminalService(options) {
         }
     };
     const emit = (session, event, data) => {
-        const id = session.nextEventId++;
+        const id = session.nextEventId;
+        session.nextEventId += 1;
         const byteLength = recordByteLength(data);
         const record = { id, event, data, timestamp: Date.now(), byteLength };
         session.events.push(record);
@@ -282,12 +283,8 @@ export function createTerminalService(options) {
         return session ? toPublicSession(session) : null;
     };
     const list = (filter = {}) => Array.from(sessions.values())
-        .filter((session) => {
-        if (typeof filter.projectId === 'string' && filter.projectId && session.projectId !== filter.projectId) {
-            return false;
-        }
-        return true;
-    })
+        // Only a non-empty string projectId filters; anything else lists every session.
+        .filter((session) => !(typeof filter.projectId === 'string' && filter.projectId && session.projectId !== filter.projectId))
         .map(toPublicSession);
     const attach = (id, lastEventId, sink) => {
         const session = sessions.get(id);

package/dist/toolchain.js

@@ -255,18 +255,13 @@ function compareVersionLikeDirNames(left, right) {
     const leftSemver = parseVersionLikeDirName(left);
     const rightSemver = parseVersionLikeDirName(right);
     if (leftSemver && rightSemver) {
-        for (let index = 0; index < leftSemver.length; index += 1) {
-            const difference = rightSemver[index] - leftSemver[index];
-            if (difference !== 0)
-                return difference;
-        }
+        const difference = leftSemver.map((part, index) => rightSemver[index] - part).find((value) => value !== 0);
+        return difference ?? left.localeCompare(right);
     }
-    else if (leftSemver) {
+    if (leftSemver)
         return -1;
-    }
-    else if (rightSemver) {
+    if (rightSemver)
         return 1;
-    }
     return left.localeCompare(right);
 }
 /** @internal Parse a `vX.Y.Z` / `X.Y.Z` directory name into its numeric parts, or `null` when it does not match. */

package/dist/web/first-distinct.d.ts

@@ -0,0 +1,11 @@
+/** Items with distinct non-empty keys, in order, capped at `max`; `truncated` reports a further
+ * distinct key beyond the cap (scanning stops there). @complexity O(items). */
+export declare function firstDistinct<T>({ items, max, keyOf }: {
+    items: readonly T[];
+    max: number;
+    keyOf: (item: T) => string | null | undefined;
+}): {
+    picked: [string, T][];
+    truncated: boolean;
+};
+//# sourceMappingURL=first-distinct.d.ts.map

package/dist/web/first-distinct.js

@@ -0,0 +1,16 @@
+/** Items with distinct non-empty keys, in order, capped at `max`; `truncated` reports a further
+ * distinct key beyond the cap (scanning stops there). @complexity O(items). */
+export function firstDistinct({ items, max, keyOf }) {
+    const picked = new Map();
+    const truncated = items.some((item) => {
+        const key = keyOf(item);
+        if (!key || picked.has(key))
+            return false;
+        if (picked.size === max)
+            return true;
+        picked.set(key, item);
+        return false;
+    });
+    return { picked: [...picked], truncated };
+}
+//# sourceMappingURL=first-distinct.js.map

package/dist/web/html-document.js

@@ -1,4 +1,5 @@
 import { parse, serialize } from "parse5";
+import { firstDistinct } from "./first-distinct.js";
 export const MAX_LINKS = 500;
 export const MAX_IMAGES = 300;
 const MAX_STYLESHEETS = 100;
@@ -88,19 +89,25 @@ const COLLECTED = new Map([["a", "anchors"], ["img", "images"], ["link", "linkTa
 function collect(document) {
     const raw = { anchors: [], images: [], linkTags: [], metas: [] };
     for (const node of walk(document)) {
-        if (!isElement(node))
-            continue;
-        const list = COLLECTED.get(node.tagName);
-        if (list)
-            raw[list].push(node);
-        else if (node.tagName === "title" || node.tagName === "html")
-            raw[node.tagName] ??= node;
-        // The first base WITH an href wins, as in browsers.
-        else if (node.tagName === "base")
-            raw.base ??= attr({ element: node, name: "href" });
+        if (isElement(node))
+            collectElement(raw, node);
     }
     return raw;
 }
+function collectElement(raw, node) {
+    const list = COLLECTED.get(node.tagName);
+    if (list) {
+        raw[list].push(node);
+        return;
+    }
+    if (node.tagName === "title" || node.tagName === "html") {
+        raw[node.tagName] ??= node;
+        return;
+    }
+    // The first base WITH an href wins, as in browsers.
+    if (node.tagName === "base")
+        raw.base ??= attr({ element: node, name: "href" });
+}
 /** Meta keys whose values are URLs and are returned absolute. */
 const URL_META = new Set(["og:image", "og:url", "twitter:image"]);
 /** `<link rel>` tokens copied into meta, in emission order, under their meta key. */
@@ -127,11 +134,16 @@ function putMeta({ meta, key, value }, _optional = {}) {
         return;
     meta[key] = collapse(value).slice(0, MAX_META_VALUE);
 }
+function metaKey({ property, name }) {
+    if (property?.startsWith("og:"))
+        return property;
+    return name && META_NAMES.has(name) ? name : undefined;
+}
 /** Every `og:*` property, or an allowlisted `name`; URL-valued keys are resolved. */
 function metaTagEntry({ element, base }, _optional = {}) {
     const property = attr({ element, name: "property" })?.toLowerCase();
     const name = attr({ element, name: "name" })?.toLowerCase();
-    const key = property?.startsWith("og:") ? property : name && META_NAMES.has(name) ? name : undefined;
+    const key = metaKey({ property, name });
     if (key === undefined)
         return undefined;
     const content = attr({ element, name: "content" });
@@ -141,37 +153,21 @@ function relTokens({ element }, _optional = {}) {
     return (attr({ element, name: "rel" }) ?? "").toLowerCase().split(/\s+/);
 }
 function readLinks(anchors, base, pageHost) {
-    const seen = new Set();
-    const links = [];
-    let truncated = false;
-    for (const anchor of anchors) {
-        const href = absolute({ raw: attr({ element: anchor, name: "href" }), base, protocols: LINK_PROTOCOLS });
-        if (!href || seen.has(href))
-            continue;
-        seen.add(href);
-        if (links.length === MAX_LINKS) {
-            truncated = true;
-            break;
-        }
-        links.push({ href, text: linkText(anchor), internal: isInternal(href, pageHost) });
-    }
+    const { picked, truncated } = firstDistinct({
+        items: anchors,
+        max: MAX_LINKS,
+        keyOf: (anchor) => absolute({ raw: attr({ element: anchor, name: "href" }), base, protocols: LINK_PROTOCOLS }),
+    });
+    const links = picked.map(([href, anchor]) => ({ href, text: linkText(anchor), internal: isInternal(href, pageHost) }));
     return { links, truncated };
 }
 function readImages(images, base) {
-    const seen = new Set();
-    const out = [];
-    let truncated = false;
-    for (const img of images) {
-        const src = absolute({ raw: imageSource({ img }), base, protocols: ASSET_PROTOCOLS });
-        if (!src || seen.has(src))
-            continue;
-        seen.add(src);
-        if (out.length === MAX_IMAGES) {
-            truncated = true;
-            break;
-        }
-        out.push({ src, alt: collapse(attr({ element: img, name: "alt" }) ?? "") });
-    }
+    const { picked, truncated } = firstDistinct({
+        items: images,
+        max: MAX_IMAGES,
+        keyOf: (img) => absolute({ raw: imageSource({ img }), base, protocols: ASSET_PROTOCOLS }),
+    });
+    const out = picked.map(([src, img]) => ({ src, alt: collapse(attr({ element: img, name: "alt" }) ?? "") }));
     return { images: out, truncated };
 }
 function readStylesheets(linkTags, base) {

package/dist/web/html-to-markdown.js

@@ -12,18 +12,25 @@ const MAX_DEPTH = 300;
 function isElement(node) {
     return "tagName" in node;
 }
+/** A node's children for {@link plainText}; skipped elements and leaves contribute none. */
+function scannableChildren(node) {
+    if (!("childNodes" in node) || (isElement(node) && SKIPPED.has(node.tagName)))
+        return [];
+    return node.childNodes;
+}
 /** Iterative so a degraded, very deep subtree cannot overflow the stack either. O(subtree nodes). */
 function plainText(root) {
     const pending = [root];
     const parts = [];
     while (pending.length) {
         const node = pending.pop();
-        if (node.nodeName === "#text" && "value" in node)
+        if (node.nodeName === "#text" && "value" in node) {
             parts.push(node.value);
-        else if ("childNodes" in node && !(isElement(node) && SKIPPED.has(node.tagName))) {
-            for (let i = node.childNodes.length - 1; i >= 0; i--)
-                pending.push(node.childNodes[i]);
+            continue;
         }
+        const children = scannableChildren(node);
+        for (let i = children.length - 1; i >= 0; i--)
+            pending.push(children[i]);
     }
     return parts.join("").replace(/\s+/g, " ");
 }
@@ -112,9 +119,11 @@ function takeEdgeWhitespace({ node, last }, _options = {}) {
     const edge = edgeText({ node, last });
     if (!edge)
         return "";
-    const whitespace = (last ? /\s+$/ : /^\s+/).exec(edge.value)?.[0] ?? "";
-    edge.value = last ? edge.value.slice(0, edge.value.length - whitespace.length) : edge.value.slice(whitespace.length);
-    return whitespace;
+    const value = edge.value;
+    // trimStart/trimEnd strip exactly the characters `\s` matches.
+    const kept = last ? value.trimEnd() : value.trimStart();
+    edge.value = kept;
+    return last ? value.slice(kept.length) : value.slice(0, value.length - kept.length);
 }
 /** The first/last leaf of the subtree when it is a text node. */
 function edgeText({ node, last }, _options = {}) {
@@ -141,9 +150,11 @@ function hastText(root) {
     while (pending.length) {
         const node = pending.pop();
         // HAST text nodes always carry a value.
-        if (node.type === "text")
+        if (node.type === "text") {
             parts.push(node.value);
-        else if (node.children)
+            continue;
+        }
+        if (node.children)
             for (let i = node.children.length - 1; i >= 0; i--)
                 pending.push(node.children[i]);
     }

package/dist/web/web-page.js

@@ -1,4 +1,5 @@
 import { boundHtml } from "./html-resource.js";
+import { firstDistinct } from "./first-distinct.js";
 import { ToolInputError } from "@jini-ai/core";
 import { EgressRefusedError } from "../http/guarded/errors.js";
 import { htmlToText, readHtmlDocument, stripActiveHtml, MAX_LINKS, MAX_IMAGES } from "./html-document.js";
@@ -145,28 +146,25 @@ const EMPTY_FACTS = { links: [], linksTruncated: false, images: [], imagesTrunca
 /** A sitemap's `<loc>` entries become links so an importer can enumerate pages from one call. */
 function sitemapFacts(xml, pageUrl) {
     const host = new URL(pageUrl).hostname.replace(/^www\./, "");
-    const seen = new Set();
-    const links = [];
-    let linksTruncated = false;
-    for (const match of xml.matchAll(/<loc>\s*([^<\s]+)\s*<\/loc>/gi)) {
-        let url;
-        try {
-            url = new URL(match[1].replace(/&amp;/g, "&"), pageUrl);
-        }
-        catch {
-            continue;
-        }
-        if ((url.protocol !== "http:" && url.protocol !== "https:") || seen.has(url.href))
-            continue;
-        seen.add(url.href);
-        if (links.length === MAX_LINKS) {
-            linksTruncated = true;
-            break;
-        }
-        links.push({ href: url.href, text: "", internal: url.hostname.replace(/^www\./, "") === host });
-    }
+    const { picked, truncated: linksTruncated } = firstDistinct({
+        items: [...xml.matchAll(/<loc>\s*([^<\s]+)\s*<\/loc>/gi)],
+        max: MAX_LINKS,
+        keyOf: (match) => sitemapHref(match[1], pageUrl),
+    });
+    const links = picked.map(([href]) => ({ href, text: "", internal: new URL(href).hostname.replace(/^www\./, "") === host }));
     return { ...EMPTY_FACTS, links, linksTruncated };
 }
+/** The absolute http(s) href of one `<loc>` value, or undefined when it is unparsable or another scheme. */
+function sitemapHref(loc, pageUrl) {
+    let url;
+    try {
+        url = new URL(loc.replace(/&amp;/g, "&"), pageUrl);
+    }
+    catch {
+        return undefined;
+    }
+    return url.protocol === "http:" || url.protocol === "https:" ? url.href : undefined;
+}
 function render(format, body, isHtml, pageUrl, ports) {
     if (!isHtml || format === "raw")
         return body;
@@ -364,9 +362,9 @@ function projectRendered({ input, ports, url, page }) {
 }
 /** Any clipped or dropped fact, image, data or text marks the whole rendered result truncated. */
 function renderedFlags({ page, result, images, factsTruncated, textTruncated }) {
-    const imagesTruncated = images.truncated || page.imagesTruncated || result.imagesTruncated || images.byUrl.size > MAX_IMAGES;
-    const truncated = imagesTruncated || factsTruncated || page.title.length > MAX_RENDERED_TITLE || result.truncated
-        || result.linksTruncated || page.dataTruncated || textTruncated;
+    const imagesTruncated = [images.truncated, page.imagesTruncated, result.imagesTruncated, images.byUrl.size > MAX_IMAGES].some(Boolean);
+    const truncated = [imagesTruncated, factsTruncated, page.title.length > MAX_RENDERED_TITLE, result.truncated,
+        result.linksTruncated, page.dataTruncated, textTruncated].some(Boolean);
     return { imagesTruncated, truncated };
 }
 /** Browser image facts come first, so their alt text wins over the parsed DOM's for the same src. */
@@ -391,8 +389,13 @@ function boundRenderedFacts({ result }, _optional = {}) {
     const stylesheets = result.stylesheets.filter(href => href.length <= MAX_URL_LENGTH);
     const meta = Object.fromEntries(Object.entries(result.meta).filter(([key]) => key.length <= MAX_RENDERED_META_KEY));
     const linksDropped = links.length < result.links.length;
-    const truncated = linksDropped || stylesheets.length < result.stylesheets.length || Object.keys(meta).length < Object.keys(result.meta).length
-        || (result.description?.length ?? 0) > MAX_RENDERED_DESCRIPTION || (result.lang?.length ?? 0) > MAX_RENDERED_LANG;
+    const truncated = [
+        linksDropped,
+        stylesheets.length < result.stylesheets.length,
+        Object.keys(meta).length < Object.keys(result.meta).length,
+        (result.description?.length ?? 0) > MAX_RENDERED_DESCRIPTION,
+        (result.lang?.length ?? 0) > MAX_RENDERED_LANG,
+    ].some(Boolean);
     return { links, stylesheets, meta, linksDropped, truncated };
 }
 /** `none` empties content; `summary` and text format use the browser's visible text instead of the projection. */