@zackbart/connecta 0.28.0 → 0.29.0

package/dist/skills.js

@@ -1,107 +1,18 @@
-import { boundedEchoText } from "./errors.js";
-const ROUTE = "Choose a route before discovery. A known-address read needs only call_tool. Unknown-address read-only work starts with execute_code to discover, call, and return the answer; use the same route for reduction, multiple or dependent calls, loops, joins, or branches. Keep discovery and calls together when schemas suffice; do not return catalog matches alone. Sample unfamiliar reads.";
-const RECOVERY = 'After auth_required use authorize_connector. After a truncated direct result use get_result. Guidance is on demand: fetch skills({ name: "usage" }) only when these instructions and the tool description are insufficient or a run needs repair.';
+import { USAGE_SKILL } from "./usage-guide.js";
+import { boundedEchoText, ConnectorCallError } from "./errors.js";
+import { Effect } from "effect";
+import { runEdge, withDeadlineEffect } from "./runtime/run.js";
+import { closeScopeOnExit } from "./runtime/connector-scope.js";
+import { sentSecretsForRequest } from "./sent-secrets.js";
+const ROUTE = "Choose a route before discovery. One known-address read uses call_tool; one known-address write uses call_destructive_tool. Unknown-address read-only work starts with execute_code to discover, call, and return the answer; use the same route for reduction, multiple or dependent calls, loops, joins, or branches. Keep discovery and calls together when schemas suffice; do not return catalog matches alone. Sample unfamiliar reads.";
+const RECOVERY = 'After auth_required use authorize_connector. After a truncated direct result use connecta.result. Guidance is on demand: fetch skills({ name: "usage" }) only when these instructions and the tool description are insufficient or a run needs repair.';
 /**
  * The always-loaded MCP `instructions` string. A program runs reads and the
- * writes config exempts from approval; every other write is its own top-level
+ * writes in trusted pools; a read-only pool routes every write to top-level
  * call_destructive_tool, where the host's permission prompt is the approval.
  */
-export const CONNECTA_INSTRUCTIONS = `${ROUTE} Only readOnlyHint: true tools and config-exempt writes run there. Keep catalog inspection and other unannotated, write-capable, or destructive work top level: search_tools then call_destructive_tool when a call is needed. Never repeat a write to recover its output. ${RECOVERY}`;
-const USAGE_SKILL_BASE = `# Connecta usage
-
-## The surface
-
-Seven tools: \`execute_code\`, \`search_tools\`, \`call_tool\`, \`call_destructive_tool\`, \`authorize_connector\`, \`get_result\`, \`skills\`. Discovery and multi-call work live in a program. Top-level search remains for catalog inspection and approval-required work.
-
-Follow the MCP instructions for routing. Read at most once for syntax or repair.
-
-## Inside a program
-
-Write one plain-JavaScript async arrow function, without TypeScript or imports. Return reduced JSON-shaped data.
-
-The minimum guest API is:
-
-- \`connecta.call("connector.tool", args)\` uses the canonical address and returns the unwrapped value.
-- \`connecta.search(args)\` returns \`{ tools, total, offset, limit, hasMore }\`; \`connecta.describe(args)\` returns \`{ tools }\`.
-- Use \`Promise.all\` for independent calls, or \`Promise.allSettled\` to keep successes and failures.
-- \`console.log(...)\` is captured. \`connecta.emit(block)\` produces rich output.
-
-## Discover and select
-
-Search and call in one run when schemas suffice. Sample unfamiliar reads. Reduce a one-time write's full result here or page a direct call with get_result; never repeat the write to recover output. Search distinct operations separately with 2–4 distinctive action/object terms.
-
-For top-level catalog inspection or approval-required discovery, omit \`limit\` initially (the default is 8), then page with a limit up to 50 if needed. Empty or whitespace-only queries browse all tools. A non-empty query with no ASCII terms returns no matches; mixed input searches with its ASCII terms. \`includeSchemas: "compact"\` adds bounded input and available output shapes. An \`outputSchemaSource: "observed"\` shape is a hint, not a contract. Plain objects expose \`inputKeys\`, \`requiredInputKeys\`, and \`outputKeys\`; truncation flags mark incomplete shapes; matches also carry declared annotations.
-
-- \`connecta.search({})\` loads all catalogs. Pass \`connector: "<id>"\` when the integration is obvious. Use \`safety: "readOnly"\` for reads. These inputs filter discovery; they grant no authority.
-- Use \`includeSchemas: "json"\` for programmatic schema inspection; compact schemas are text, not objects with \`.properties\`. Check connectorTitle for the account/environment, then address, purpose, annotations, inputs, and outputs. Never select only because a result ranks first or has fewer required inputs.
-- Supply every \`requiredInputKey\` from the task or a prior result. For dependencies, match the earlier \`outputKey\` to the later required key. An empty required-key list does not permit invented arguments. Missing \`outputKeys\` means inspect \`outputSchema\`.
-- Use \`connecta.describe({ address })\` or \`{ addresses }\` when a compact schema is truncated or insufficient. Use \`format: "json"\` only for exact constraints. Write the property names the schema displays; never guess positions or aliases.
-- Reduce through available output keys. An observed key is a hint; later results may differ. Do not guess collection roots such as \`items\` or \`results\`. If a match is missing, re-search or describe.
-- Match provider identifiers and names exactly after resolving them from source data or a connector guide. A broad regular expression that merely finds a plausible value is not identity resolution.
-- Preserve the schema's JSON types exactly: a numeric id is a number, not a numeric-looking string.
-- Validate tabular headers, row arrays, and row widths before mapping them. Never let a header or partial row become data.
-
-Only explicitly \`readOnlyHint: true\` calls and writes the deployment's config exempts from approval run in a program. Any other write is refused before it is sent: send it through top-level \`call_destructive_tool\`, where the host asks. Sandbox code cannot widen host gates.
-
-## Errors and repair
-
-Caught Connecta errors expose \`message\`, \`code\`, \`retryable\`, and \`details\`. Promise rejections retain these fields. Branch on fields, never prose. After a shared argument failure, repair one call before repeating it across other records. Do not retry \`retryable: false\`, and do not retry \`rate_limited\` immediately because portable code has no timer.
-
-- \`destructive_tool_requires_approval\`: stop and send the returned address through top-level \`call_destructive_tool\`.
-- \`write_outcome_unknown\`: an exempt write was sent but unanswered and is never re-sent; check the target.
-- \`auth_required\`: let the failure reach the model, then use top-level \`authorize_connector\`, give its handoff to the operator, and retry after recovery.
-- Truncated direct call: page with \`get_result\`, never repeat a write. A program result has no page handle; reduce a read in a new program. After a write, check the target or report the gap.
-- Unknown addresses and tools carry scoped search recovery. Use it inside the current run. Do not invent an address.
-
-For a direct call, \`resultMode: "value"\` unwraps the result. \`timeoutMs\` sets its deadline. Every call makes one attempt; use the returned error classification and retry hint to decide whether to reissue. \`diagnostics: true\` adds timing.
-
-\`get_result({ id, offset?, maxBytes? })\` returns a one-line JSON header \`{ resultId, offset, bytes, totalBytes, hasMore, nextAction? }\`, a newline, and then the page as raw text, for a direct-call result. Both sizes are byte counts: \`maxBytes\` must be a whole number at least 1, defaults to the result's cap, and is clamped to it; \`offset\` must be a whole number at least 0 and defaults to 0. An offset inside a multi-byte character moves back to its first byte, and the header reports the served offset. Follow \`nextAction\` until \`hasMore\` is false to reassemble pages. An unknown or expired id is an error.
-
-The \`execute_code\` description states this deployment's host-call and write budgets and per-call deadline.
-
-## Runtime portability
-
-Portable code uses standard JavaScript builtins, \`connecta\`, and \`console.*\`. QuickJS blocks imports and lacks fetch, process, timers, crypto, and WebSocket. Dynamic Workers must use only \`{ loader }\`; bindings, modules, or globalOutbound grant ambient authority. With loader only, environment maps are empty; node:fs/http/https are absent; outbound fetch, WebSocket, node:net, and node:tls are denied; DNS is unresolved. Runtime builtins remain through \`import()\` and \`process.getBuiltinModule()\`, including node:path and cloudflare:workers; this set can drift. Timers, process, crypto, WebSocket, and data: fetch remain. Avoid every runtime-only capability because QuickJS fails.
-
-## Examples
-
-One read-only call at a known address:
-
-\`async () => await connecta.call("crm.get_account", { id: "acct_42" })\`
-
-Dependent lookup: verify connector \`ci\`, run 42, and these schema fields first.
-
-\`\`\`js
-async () => {
-  const find = async name => {
-    const page = await connecta.search({ connector: "ci", query: name, safety: "readOnly", includeSchemas: "compact" });
-    if (page.queryAnalysis?.catalogError) throw new Error(JSON.stringify(page.queryAnalysis.catalogError));
-    return page.tools.find(tool => tool.name === name);
-  };
-  const runTool = await find("get_run");
-  if (!runTool) return { gap: "Run lookup not resolved" };
-  const run = await connecta.call(runTool.address, { runId: 42 });
-  if (!run.failedJobId) return { status: run.status, gap: "No failed job identified" };
-  const logsTool = await find("get_job_logs");
-  if (!logsTool) return { status: run.status, gap: "Job logs not resolved" };
-  const logs = await connecta.call(logsTool.address, { jobId: run.failedJobId });
-  return logs.filter(row => row.level === "error").map(({ timestamp, message }) => ({ timestamp, message }));
-}
-\`\`\`
-
-## Media output
-
-\`connecta.emit\` accepts text, image, or audio blocks and delivers them only on success. Its byte and block budgets are separate from the JSON return budget. Return data for the client to render as a view.
-
-`;
-/** Deployment-scoped guide routing appended to the shared usage guide. */
-const CONNECTOR_GUIDES_SECTION = `
-## Per-connector guides
-
-Connector guides appear in \`skills({})\` and discovery with an exact \`guide\` name and bounded \`guideSummary\`. Fetch only a listed or carried name with \`skills({ name: <guide> })\`; never infer one from a connector id. \`guideRequired: true\` is a hard stop. \`guideRequiredReasons\` says why: \`connector_required\` and \`approval_required\` stand after schema expansion; \`schema_truncated\` clears after exact describe. Otherwise fetch for a relevant sequence, unit, pagination rule, alias, or API convention. A read-only call with a complete compact schema may skip an irrelevant guide. Connector guides never apply to another deployment.
-`;
-/** Shared Connecta routing guidance, byte-identical across deployments. */
-export const USAGE_SKILL = USAGE_SKILL_BASE + CONNECTOR_GUIDES_SECTION;
+export const CONNECTA_INSTRUCTIONS = `${ROUTE} Programs call reads in read-only pools and may also write in trusted pools. The execute_code description names this endpoint's trust. In a read-only pool, discover writes with search_tools then use call_destructive_tool. Never repeat a write to recover its output. ${RECOVERY}`;
+export { USAGE_SKILL } from "./usage-guide.js";
 /** True when at least one of `connectors` carries a usage guide. */
 export function hasConnectorGuides(connectors) {
     return connectors.some((connector) => connectorGuide(connector) !== undefined);
@@ -112,10 +23,15 @@ export function hasConnectorGuides(connectors) {
  * copy. Guide-free deployments still pay no fixed tool-description cost: the
  * conditional notes in meta-tools.ts remain absent.
  */
-function usageSkill(_connectors) {
+function usageSkill() {
     return USAGE_SKILL;
 }
-const INVESTIGATE_SKILL = `# Investigate across services
+const INVESTIGATE_SKILL = `---
+name: investigate
+description: Plan purchase verification, experiment checks, and customer or deployment investigations across services; resolve scope and capability limits before querying.
+---
+
+# Investigate across services
 
 ## Plan the investigation
 
@@ -147,8 +63,8 @@ const AVAILABLE_SKILLS = [
  * Namespace for operator-authored per-connector guides. Built-in skill names
  * are bare identifiers and never contain ":", so `connector:<id>` cannot
  * collide with one — not even when a connector's id is literally "usage".
- * The prefixed form is the ONLY way to reach a connector guide: a bare
- * connector id is never resolved, so nothing shadows anything silently.
+ * Canonical skill URIs and the prefixed compatibility alias reach connector
+ * guides. A bare connector id never resolves, so nothing shadows silently.
  */
 const CONNECTOR_SKILL_PREFIX = "connector:";
 /** The skill name that fetches `connector`'s guide. */
@@ -197,8 +113,7 @@ function isAbbreviation(text, end) {
         return true;
     if (/^(?:Mr|Mrs|Ms|Dr|Prof|Sr|Jr|St)\.$/iu.test(token))
         return true;
-    if (!/^(?:[A-Za-z]\.){2,}$/u.test(token) &&
-        !/^(?:vs|etc|approx|dept|fig|no)\.$/iu.test(token)) {
+    if (!/^(?:[A-Za-z]\.){2,}$/u.test(token) && !/^(?:vs|etc|approx|dept|fig|no)\.$/iu.test(token)) {
         return false;
     }
     // Initialisms can end a sentence or extend a name ("U.S. East region").
@@ -206,16 +121,13 @@ function isAbbreviation(text, end) {
     // complete thought, while a missed ending gets an honest ellipsis. Count
     // the period only with narrow evidence of a new clause: an article in one
     // of its first two words. This is grammar evidence, not a starter-word list.
-    const following = text
-        .slice(end)
-        .match(/^[)\]}'"”’]*\s+(\S+)(?:\s+(\S+))?/u);
+    const following = text.slice(end).match(/^[)\]}'"”’]*\s+(\S+)(?:\s+(\S+))?/u);
     if (!following)
         return false;
     const [, nextWord, afterNext] = following;
     const startsClause = nextWord !== undefined &&
         /^\p{Lu}/u.test(nextWord) &&
-        (OPENS_CLAUSE_RE.test(nextWord) ||
-            (afterNext !== undefined && ARTICLE_RE.test(afterNext)));
+        (OPENS_CLAUSE_RE.test(nextWord) || (afterNext !== undefined && ARTICLE_RE.test(afterNext)));
     return !startsClause;
 }
 /** Drop a leading YAML frontmatter block — metadata, not summary text. */
@@ -253,8 +165,7 @@ function boundedSummary(summary) {
         if (end > GUIDE_SUMMARY_LENGTH)
             break;
         const punctuationEnd = (match.index ?? 0) + 1;
-        if (match[0].startsWith(".") &&
-            isAbbreviation(normalized, punctuationEnd)) {
+        if (match[0].startsWith(".") && isAbbreviation(normalized, punctuationEnd)) {
             continue;
         }
         // Do not mistake another short fragment for a useful complete thought.
@@ -321,8 +232,7 @@ function summarizeGuide(connector, guide) {
         }
         if (startsTable(lines, index)) {
             index++;
-            while (index + 1 < lines.length &&
-                (lines[index + 1] ?? "").includes("|")) {
+            while (index + 1 < lines.length && (lines[index + 1] ?? "").includes("|")) {
                 index++;
             }
             continue;
@@ -373,9 +283,9 @@ export function connectorGuideSummary(connector) {
     if (!guide)
         return undefined;
     const configured = typeof connector.usageGuide === "object"
-        // Registry construction rejects over-budget configured summaries. Keep
-        // normalization here so direct Connector callers see the same text.
-        ? boundedSummary(connector.usageGuide.summary ?? "")
+        ? // Registry construction rejects over-budget configured summaries. Keep
+            // normalization here so direct Connector callers see the same text.
+            boundedSummary(connector.usageGuide.summary ?? "")
         : undefined;
     return configured ?? summarizeGuide(connector, guide);
 }
@@ -385,72 +295,394 @@ export function connectorGuideRequired(connector) {
         typeof connector.usageGuide === "object" &&
         connector.usageGuide.required === true);
 }
-/**
- * Every fetchable skill: the built-in guides plus one entry per connector that
- * carries a usage guide. Derived from the connector list passed in — the single
- * place guide visibility is decided.
- */
-export function listSkills(connectors) {
-    const listing = AVAILABLE_SKILLS.map((skill) => ({
-        name: skill.name,
-        description: skill.description,
+/** Complete entries stay atomic within ChatGPT's five-skill import budget. */
+const SKILL_PAGE_SIZE = 5;
+const MAX_SKILL_FILES = 512;
+const MAX_SKILL_BYTES = 16 * 1024 * 1024;
+const MAX_SKILL_CATALOG_BYTES = 8 * 1024 * 1024;
+const MAX_SKILLS = 1_024;
+const encoder = new TextEncoder();
+const PRIVATE = { resultType: "complete", ttlMs: 0, cacheScope: "private" };
+/** Bound metadata before cloning it, without another payload-sized byte array. */
+function jsonBytes(value) {
+    const json = JSON.stringify(value);
+    let bytes = 0;
+    for (let i = 0; i < json.length; i++) {
+        const code = json.charCodeAt(i);
+        if (code < 0x80)
+            bytes++;
+        else if (code < 0x800)
+            bytes += 2;
+        else if (code >= 0xd800 && code <= 0xdbff && json.charCodeAt(i + 1) >= 0xdc00 && json.charCodeAt(i + 1) <= 0xdfff) {
+            bytes += 4;
+            i++;
+        }
+        else
+            bytes += 3;
+    }
+    return bytes;
+}
+function localRecord(name, uri, description, content, aliases) {
+    return { entry: { uri, frontmatter: { name, description }, resources: "dynamic" }, content, aliases };
+}
+/** JSON frontmatter is YAML too; no runtime provider imports or filesystem reads. */
+function validSkillName(name) {
+    return name.length <= 64 && /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name);
+}
+async function localRecords(connectors) {
+    const builtIns = AVAILABLE_SKILLS.map((skill) => localRecord(skill.name, `skill://connecta/${skill.name}/SKILL.md`, skill.description, skill.content(), [
+        skill.name,
+        `skill://connecta/${skill.name}`,
+    ]));
+    const guides = await Promise.all(connectors
+        .filter((connector) => connectorGuide(connector) !== undefined)
+        .sort((a, b) => Number(connectorGuideRequired(b)) - Number(connectorGuideRequired(a)) ||
+        (a.id < b.id ? -1 : a.id > b.id ? 1 : 0))
+        .map(async (connector) => {
+        const name = validSkillName(connector.id)
+            ? connector.id
+            : `connector-${[...new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(connector.id)))]
+                .map((byte) => byte.toString(16).padStart(2, "0"))
+                .join("")
+                .slice(0, 48)}`;
+        const description = connectorGuideSummary(connector);
+        const root = `skill://connecta/connectors/${encodeURIComponent(name)}`;
+        const content = `---\n${JSON.stringify({ name, description }, null, 2)}\n---\n\n${connectorGuide(connector)}`;
+        return localRecord(name, `${root}/SKILL.md`, description, content, [
+            connectorSkillName(connector.id),
+            `skill://connecta/connectors/${encodeURIComponent(connector.id)}`,
+            root,
+        ]);
     }));
-    for (const connector of connectors) {
-        // Undefined here means "no guide" and nothing else: a connector that has
-        // one always summarizes to a non-empty line, configured or derived.
-        const summary = connectorGuideSummary(connector);
-        if (!summary)
-            continue;
-        listing.push({
-            name: connectorSkillName(connector.id),
-            description: summary,
-        });
+    if (new Set(guides.map((guide) => guide.entry.uri)).size !== guides.length)
+        throw new ConnectorCallError("unavailable", "Connector skill slugs collide.");
+    return [builtIns[0], ...guides, ...builtIns.slice(1)];
+}
+/** Keep the downstream path tree, so relative supporting-file references still resolve. */
+export function downstreamSkillUri(connectorId, uri) {
+    if (uri.length > 32_768)
+        throw new ConnectorCallError("unavailable", "Downstream skill URI exceeds its bound.");
+    const match = /^([A-Za-z][A-Za-z0-9+.-]*:(?:\/\/[^/?#]*)?)(\/[^?#]+)$/.exec(uri);
+    if (!match ||
+        match[2]
+            .split("/")
+            .slice(1)
+            .some((segment) => {
+            try {
+                const decoded = decodeURIComponent(segment);
+                return (!decoded ||
+                    decoded === "." ||
+                    decoded === ".." ||
+                    decoded.includes("\\") ||
+                    decoded.includes("/") ||
+                    decoded.includes("\u0000"));
+            }
+            catch {
+                return true;
+            }
+        }))
+        throw new ConnectorCallError("unavailable", "Downstream skill URI is not a supported file URI.");
+    const authority = match[1].split("://")[1];
+    // A skill may root at the authority, e.g. skill://review/SKILL.md.
+    // Repeating it as a path segment preserves the Agent Skills directory name.
+    const mapped = `skill://downstream/${encodeURIComponent(connectorId)}/${encodeURIComponent(match[1])}${authority ? `/${encodeURIComponent(authority)}` : ""}${match[2]}`;
+    if (mapped.length > 32_768)
+        throw new ConnectorCallError("unavailable", "Downstream skill URI exceeds its bound.");
+    return mapped;
+}
+function validateEntry(entry) {
+    if (!entry ||
+        typeof entry.uri !== "string" ||
+        entry.uri.length > 32_768 ||
+        typeof entry.frontmatter !== "object" ||
+        !entry.frontmatter ||
+        Array.isArray(entry.frontmatter) ||
+        typeof entry.frontmatter.name !== "string" ||
+        !validSkillName(entry.frontmatter.name) ||
+        typeof entry.frontmatter.description !== "string" ||
+        !entry.frontmatter.description ||
+        entry.frontmatter.description.length > 1024 ||
+        (entry.resources !== "dynamic" && !Array.isArray(entry.resources))) {
+        throw new ConnectorCallError("unavailable", "Downstream skill entry is invalid.");
+    }
+    const root = entry.uri.slice(0, entry.uri.lastIndexOf("/") + 1);
+    if (!entry.uri.endsWith("/SKILL.md") || decodeURIComponent(root.split("/").at(-2) ?? "") !== entry.frontmatter.name) {
+        throw new ConnectorCallError("unavailable", "Downstream skill root does not match its name.");
+    }
+    if (entry.resources === "dynamic")
+        return;
+    if (!entry.resources.length || entry.resources.length > MAX_SKILL_FILES)
+        throw new ConnectorCallError("unavailable", "Downstream skill manifest exceeds the file bound.");
+    let bytes = 0;
+    const files = new Set();
+    for (const file of entry.resources) {
+        if (!file ||
+            typeof file.uri !== "string" ||
+            !file.uri.startsWith(root) ||
+            files.has(file.uri) ||
+            typeof file.digest !== "string" ||
+            !/^sha256:[a-f0-9]{64}$/.test(file.digest) ||
+            !Number.isSafeInteger(file.size) ||
+            file.size < 0) {
+            throw new ConnectorCallError("unavailable", "Downstream skill manifest is invalid.");
+        }
+        bytes += file.size;
+        files.add(file.uri);
     }
-    return listing;
+    if (!files.has(entry.uri) || bytes > MAX_SKILL_BYTES)
+        throw new ConnectorCallError("unavailable", "Downstream skill manifest is incomplete or oversized.");
+}
+async function withManifest(record) {
+    const bytes = encoder.encode(record.content);
+    if (bytes.length > MAX_SKILL_BYTES)
+        throw new ConnectorCallError("unavailable", "Local skill exceeds the byte bound.");
+    const digest = [...new Uint8Array(await crypto.subtle.digest("SHA-256", bytes))]
+        .map((byte) => byte.toString(16).padStart(2, "0"))
+        .join("");
+    return {
+        ...record,
+        entry: { ...record.entry, resources: [{ uri: record.entry.uri, digest: `sha256:${digest}`, size: bytes.length }] },
+    };
 }
 /**
- * Resolve one skill name. Built-in names match exactly; connector guides are
- * reachable only through the `connector:` prefix. Every miss — unknown name,
- * unknown connector, connector without a guide — is an explicit error, never a
- * silent fallback to the generic guide.
+ * One caller-view registry for native methods, the meta-tool and the guest API.
+ * No content reaches storage or operator sinks. Downstream skills use uncached
+ * list/read operations on the caller's request-scoped credential partition.
+ * Only a complete snapshot lives in this request; a failed build is discarded.
  */
-export function resolveSkill(name, connectors) {
-    const builtIn = AVAILABLE_SKILLS.find((skill) => skill.name === name);
-    if (builtIn) {
-        return { found: true, content: builtIn.content(connectors) };
+export class SkillsRegistry {
+    registry;
+    baseUrl;
+    options;
+    scope;
+    local;
+    snapshot;
+    constructor(registry, baseUrl, options = {}) {
+        this.registry = registry;
+        this.baseUrl = baseUrl;
+        this.options = options;
+        this.scope = options.requestScope ?? {};
+        this.local = localRecords(registry.listConnectors());
+    }
+    operation(connector, read) {
+        const timeoutMs = this.options.probeTimeoutMs ?? 20_000;
+        const operationScope = {};
+        sentSecretsForRequest(this.scope).include(sentSecretsForRequest(operationScope));
+        return runEdge(withDeadlineEffect((signal) => Effect.scoped(Effect.gen({ self: this }, function* () {
+            const ctx = this.registry.contextFor(connector.id, this.baseUrl, operationScope, {
+                signal,
+                timeoutMs,
+                ...(this.options.defer ? { defer: this.options.defer } : {}),
+            });
+            yield* closeScopeOnExit(connector, ctx, this.options.defer);
+            return yield* Effect.tryPromise({
+                try: () => read(ctx),
+                catch: (error) => error instanceof ConnectorCallError && error.code === "auth_required"
+                    ? new ConnectorCallError("auth_required", "Downstream skills require authorization.")
+                    : new ConnectorCallError("unavailable", "Downstream skills are unavailable."),
+            });
+        })), {
+            timeoutMs,
+            ...(this.options.requestSignal ? { signal: this.options.requestSignal } : {}),
+            timeoutError: new ConnectorCallError("unavailable", "Downstream skills timed out."),
+        }), { signal: this.options.requestSignal });
+    }
+    async records() {
+        if (!this.snapshot) {
+            this.snapshot = this.build();
+            this.snapshot.catch(() => {
+                this.snapshot = undefined;
+            });
+        }
+        const records = await this.snapshot;
+        this.assertSafe(records);
+        return records;
+    }
+    /** Later catalog/read operations can add credentials to this request. */
+    assertSafe(records) {
+        const secrets = sentSecretsForRequest(this.scope);
+        for (const record of records) {
+            const uris = [record.entry.uri, ...(record.files?.values() ?? [])];
+            if (record.entry.resources !== "dynamic") {
+                for (const file of record.entry.resources) {
+                    uris.push(file.uri);
+                    if (secrets.contains(file.digest))
+                        throw new ConnectorCallError("unavailable", "Skill digest contains sent credentials.");
+                }
+            }
+            if (record.aliases.some((alias) => secrets.contains(alias)) ||
+                uris.some((uri) => secrets.containsUrl(uri) || secrets.contains(uri))) {
+                throw new ConnectorCallError("unavailable", "Skill URI contains sent credentials.");
+            }
+        }
     }
-    const available = () => listSkills(connectors)
-        .map((skill) => skill.name)
-        .join(", ");
-    if (name.startsWith(CONNECTOR_SKILL_PREFIX)) {
-        const id = name.slice(CONNECTOR_SKILL_PREFIX.length);
-        const connector = connectors.find((c) => c.id === id);
-        if (!connector) {
-            return {
-                found: false,
-                message: `Unknown connector "${boundedEchoText(id)}". Available skills: ${available()}.`,
-            };
+    async build() {
+        const records = await Promise.all((await this.local).map(withManifest));
+        let catalogBytes = jsonBytes(records.map((record) => record.entry));
+        // Bounded sequential connector reads avoid unbounded fan-out and finish
+        // cleanup before a later connector's failure can end the whole listing.
+        for (const connector of this.registry.listConnectors()) {
+            if (!connector.downstreamSkills || !this.registry.canReadConnectorSkills(connector.id))
+                continue;
+            const entries = await this.operation(connector, (ctx) => connector.downstreamSkills.list(ctx));
+            if (!Array.isArray(entries) || records.length + entries.length > MAX_SKILLS)
+                throw new ConnectorCallError("unavailable", "Downstream skills listing exceeds its bound.");
+            for (const original of entries) {
+                if (catalogBytes + jsonBytes(original) + 1 > MAX_SKILL_CATALOG_BYTES)
+                    throw new ConnectorCallError("unavailable", "Skills listing exceeds its byte bound.");
+                const entry = structuredClone(original);
+                validateEntry(entry);
+                const files = new Map();
+                const uri = downstreamSkillUri(connector.id, entry.uri);
+                const secrets = sentSecretsForRequest(this.scope);
+                if (secrets.containsUrl(entry.uri))
+                    throw new ConnectorCallError("unavailable", "Downstream skill URI contains sent credentials.");
+                files.set(uri, entry.uri);
+                const resources = entry.resources === "dynamic"
+                    ? "dynamic"
+                    : entry.resources.map((file) => {
+                        const uri = downstreamSkillUri(connector.id, file.uri);
+                        if (secrets.containsUrl(file.uri))
+                            throw new ConnectorCallError("unavailable", "Downstream skill URI contains sent credentials.");
+                        files.set(uri, file.uri);
+                        return { ...file, uri };
+                    });
+                if (records.some((record) => record.entry.uri === uri))
+                    throw new ConnectorCallError("unavailable", "Downstream skills listing contains duplicate entries.");
+                const mapped = { ...entry, uri, resources };
+                catalogBytes += jsonBytes(mapped) + 1;
+                if (catalogBytes > MAX_SKILL_CATALOG_BYTES)
+                    throw new ConnectorCallError("unavailable", "Skills listing exceeds its byte bound.");
+                records.push({ entry: mapped, aliases: [], connector, files });
+            }
         }
-        const guide = connectorGuide(connector);
-        if (!guide) {
-            return {
-                found: false,
-                message: `Connector "${boundedEchoText(id)}" has no usage guide. Available skills: ${available()}.`,
-            };
+        if (records.length > MAX_SKILLS || jsonBytes(records.map((record) => record.entry)) > MAX_SKILL_CATALOG_BYTES) {
+            throw new ConnectorCallError("unavailable", "Skills listing exceeds its byte or entry bound.");
         }
-        return { found: true, content: guide };
+        // Keep the old investigation guide behind every connector and downstream
+        // guide, where it cannot consume one of the first five import slots.
+        const investigate = records.findIndex((record) => record.aliases.includes("investigate"));
+        if (investigate >= 0)
+            records.push(records.splice(investigate, 1)[0]);
+        this.assertSafe(records);
+        return records;
+    }
+    async lookup(uri) {
+        const local = (await this.local).find((record) => record.entry.uri === uri || record.aliases.includes(uri));
+        if (local) {
+            const record = await withManifest(local);
+            this.assertSafe([record]);
+            return record;
+        }
+        // A non-skill URI never starts a downstream resource request or listing.
+        if (!uri.startsWith("skill://downstream/"))
+            throw this.missing(uri);
+        const record = (await this.records()).find((record) => record.entry.uri === uri);
+        if (!record)
+            throw this.missing(uri);
+        return record;
+    }
+    missing(name) {
+        const available = [
+            "usage",
+            ...this.registry
+                .listConnectors()
+                .filter((connector) => connectorGuide(connector) !== undefined)
+                .map((connector) => connectorSkillName(connector.id)),
+            "investigate",
+        ].join(", ");
+        // Caller-authored URI/error text never enters operator records. Preserve
+        // legacy guidance without allowing a missing name to probe a hidden view.
+        const id = name.startsWith(CONNECTOR_SKILL_PREFIX) ? name.slice(CONNECTOR_SKILL_PREFIX.length) : name;
+        const connector = this.registry.getConnector(id);
+        const message = name.startsWith(CONNECTOR_SKILL_PREFIX)
+            ? connector
+                ? `Connector "${boundedEchoText(id)}" has no usage guide.`
+                : `Unknown connector "${boundedEchoText(id)}".`
+            : connector
+                ? `Unknown skill "${boundedEchoText(name)}". Connector guides are fetched as "${boundedEchoText(connectorSkillName(name))}".`
+                : `Unknown skill "${boundedEchoText(name)}".`;
+        return new ConnectorCallError("not_found", `${message} Available skills: ${available}.`);
     }
-    const bare = connectors.find((c) => c.id === name);
-    if (bare) {
+    async list(cursor) {
+        const records = await this.records();
+        const offset = cursor === undefined ? 0 : /^skills:[1-9][0-9]*$/.test(cursor) ? Number(cursor.slice(7)) : NaN;
+        if (!Number.isSafeInteger(offset) || offset % SKILL_PAGE_SIZE !== 0 || offset >= records.length)
+            throw new ConnectorCallError("invalid_args", "Invalid skills cursor.");
         return {
-            found: false,
-            message: connectorGuide(bare)
-                ? `Unknown skill "${boundedEchoText(name)}". Connector guides are fetched as "${boundedEchoText(connectorSkillName(name))}". Available skills: ${available()}.`
-                : `Connector "${boundedEchoText(name)}" has no usage guide. Available skills: ${available()}.`,
+            ...PRIVATE,
+            skills: records.slice(offset, offset + SKILL_PAGE_SIZE).map((record) => record.entry),
+            ...(offset + SKILL_PAGE_SIZE < records.length ? { nextCursor: `skills:${offset + SKILL_PAGE_SIZE}` } : {}),
         };
     }
-    return {
-        found: false,
-        message: `Unknown skill "${boundedEchoText(name)}". Available skills: ${available()}.`,
-    };
+    async get(uri) {
+        return { ...PRIVATE, skill: (await this.lookup(uri)).entry };
+    }
+    async resources(cursor) {
+        const page = await this.list(cursor);
+        return {
+            ...PRIVATE,
+            resources: page.skills.flatMap((skill) => (skill.resources === "dynamic" ? [{ uri: skill.uri }] : skill.resources).map((file) => ({
+                uri: file.uri,
+                name: file.uri === skill.uri ? String(skill.frontmatter.name) : file.uri.slice(file.uri.lastIndexOf("/") + 1),
+                ...(file.uri === skill.uri
+                    ? { description: String(skill.frontmatter.description), mimeType: "text/markdown" }
+                    : {}),
+                ...("size" in file ? { size: file.size } : {}),
+            }))),
+            ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}),
+        };
+    }
+    async read(uri) {
+        const local = (await this.local).find((record) => record.entry.uri === uri || record.aliases.includes(uri));
+        if (local) {
+            const record = await withManifest(local);
+            this.assertSafe([record]);
+            return { ...PRIVATE, contents: [{ uri: record.entry.uri, mimeType: "text/markdown", text: record.content }] };
+        }
+        if (!uri.startsWith("skill://downstream/"))
+            throw this.missing(uri);
+        const record = (await this.records()).find((record) => record.files?.has(uri));
+        if (!record?.connector || !record.files || !this.registry.canReadConnectorSkills(record.connector.id))
+            throw this.missing(uri);
+        const originalUri = record.files.get(uri);
+        const contents = await this.operation(record.connector, (ctx) => record.connector.downstreamSkills.read(originalUri, ctx));
+        // Structural fields and preserved digests cannot be repaired by the
+        // output boundary after this read has sent another credential.
+        await this.records();
+        if (!Array.isArray(contents) || contents.length !== 1 || contents[0]?.uri !== originalUri)
+            throw new ConnectorCallError("unavailable", "Downstream skill read returned unexpected files.");
+        const content = contents[0];
+        if (!content || (typeof content.text === "string") === (typeof content.blob === "string"))
+            throw new ConnectorCallError("unavailable", "Downstream skill read did not return one file.");
+        let bytes;
+        try {
+            bytes = typeof content.text === "string" ? encoder.encode(content.text).length : atob(content.blob).length;
+        }
+        catch {
+            throw new ConnectorCallError("unavailable", "Downstream skill file is not valid base64.");
+        }
+        if (bytes > MAX_SKILL_BYTES)
+            throw new ConnectorCallError("unavailable", "Downstream skill file exceeds the byte bound.");
+        return { ...PRIVATE, contents: [{ ...content, uri }] };
+    }
+    async text(name) {
+        const record = await this.lookup(name);
+        const content = (await this.read(record.entry.uri)).contents[0];
+        if (typeof content.text === "string")
+            return content.text;
+        try {
+            return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(Uint8Array.from(atob(content.blob), (char) => char.charCodeAt(0)));
+        }
+        catch {
+            throw new ConnectorCallError("unavailable", "Skill instructions are not UTF-8 text.");
+        }
+    }
+    async summaries() {
+        return (await this.records()).map((record) => ({
+            name: record.aliases[0] ?? record.entry.uri,
+            uri: record.entry.uri,
+            description: String(record.entry.frontmatter.description),
+        }));
+    }
 }