@zackbart/connecta 0.34.0 → 0.35.0

package/dist/skills.js

@@ -1,3 +1,7 @@
+import { duringViewEffect } from "./runtime/call.js";
+import { RequestScope, requestOwner } from "./runtime/request-scope.js";
+import { upwardStep } from "./upward.js";
+import { authCall, authInvoke, authFlow, authMethod, registerAuth, registerAuthMethod, authOwnMethod, } from "./auth/native.js";
 import { USAGE_SKILL } from "./usage-guide.js";
 import { boundedEchoText, ConnectorCallError } from "./errors.js";
 import { Effect } from "effect";
@@ -20,8 +24,13 @@ export const CONNECTA_INSTRUCTIONS = `${ROUTE} On a writable endpoint, programs
  * comes from deployment config for the pool the request was admitted through;
  * nothing a request sends reaches it.
  */
-export function endpointInstructions(description) {
-    return description === undefined ? CONNECTA_INSTRUCTIONS : `${CONNECTA_INSTRUCTIONS} This endpoint: ${description}`;
+export function endpointInstructions(description, native) {
+    const instructions = native ? nativeInstructions(native.executeCode) : CONNECTA_INSTRUCTIONS;
+    return description === undefined ? instructions : `${instructions} This endpoint: ${description}`;
+}
+/** Instructions for pools whose host searches the listed native tools. */
+export function nativeInstructions(executeCode) {
+    return `Each tool here is one operation; annotations classify reads/writes. Call known tools directly; ${executeCode ? "combine work in execute_code using the program addresses in tool descriptions." : "find tools with your host's search."} Read-only endpoints omit and refuse writes. Never repeat a write for output. Give auth handoffs to the user/operator. Follow nextAction to page with ${executeCode ? "connecta.result in execute_code" : "read_result"}. skills lists guidance.`;
 }
 export { USAGE_SKILL } from "./usage-guide.js";
 /** True when at least one of `connectors` carries a usage guide. */
@@ -86,7 +95,11 @@ export function connectorSkillName(connectorId) {
 export function connectorGuide(connector) {
     const guide = connector.usageGuide;
     const content = typeof guide === "string" ? guide : guide?.content;
-    return content && content.trim() !== "" ? content : undefined;
+    if (!content || content.trim() === "")
+        return undefined;
+    return connector.readOnly === true
+        ? `Read-only connection: only read-classified tools are available. Write calls are refused, including tools named in this guide.\n\n${content}`
+        : content;
 }
 /** Discovery budget for one connector-guide summary, including an ellipsis. */
 export const GUIDE_SUMMARY_LENGTH = 120;
@@ -298,7 +311,9 @@ export function connectorGuideSummary(connector) {
             // normalization here so direct Connector callers see the same text.
             boundedSummary(connector.usageGuide.summary ?? "")
         : undefined;
-    return configured ?? summarizeGuide(connector, guide);
+    const original = typeof connector.usageGuide === "string" ? connector.usageGuide : connector.usageGuide?.content;
+    const summary = configured ?? summarizeGuide(connector, original ?? guide);
+    return connector.readOnly === true ? boundedSummary(`Read-only. ${summary}`) : summary;
 }
 /** Whether correct use always depends on conventions outside the tool schema. */
 export function connectorGuideRequired(connector) {
@@ -340,38 +355,44 @@ function localRecord(name, uri, description, content, aliases) {
 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,
-            ]),
-            connector,
-        };
-    }));
-    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)];
+function localRecords(connectors) {
+    return runEdge(localRecordsNative(connectors));
 }
+const localRecordsNative = /* @__PURE__ */ registerAuth(localRecords, function (connectors) {
+    return authFlow(function* () {
+        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 = yield* upwardStep(Effect.forEach(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)), (connector) => authFlow(function* () {
+            const name = validSkillName(connector.id)
+                ? connector.id
+                : `connector-${[
+                    ...new Uint8Array(yield* upwardStep(authInvoke(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,
+                ]),
+                connector,
+            };
+        }), { concurrency: "unbounded" }));
+        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)
@@ -446,18 +467,28 @@ function validateEntry(entry) {
     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 }] },
-    };
+function withManifest(record) {
+    return runEdge(withManifestNative(record));
 }
+const withManifestNative = /* @__PURE__ */ registerAuth(withManifest, function (record) {
+    return authFlow(function* () {
+        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(yield* upwardStep(authInvoke(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 }],
+            },
+        };
+    });
+});
 /**
  * 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
@@ -475,42 +506,15 @@ export class SkillsRegistry {
         this.registry = registry;
         this.baseUrl = baseUrl;
         this.options = options;
+        void SkillsRegistry.nativePrograms;
         this.scope = options.requestScope ?? {};
-        this.local = localRecords(registry.listConnectors());
+        this.local = authCall(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 });
+        return runEdge(authOwnMethod(SkillsRegistry.prototype, this, "operation", [connector, read]));
     }
-    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;
+    records() {
+        return runEdge(authOwnMethod(SkillsRegistry.prototype, this, "records", []));
     }
     /** Later catalog/read operations can add credentials to this request. */
     assertSafe(records) {
@@ -530,71 +534,11 @@ export class SkillsRegistry {
             }
         }
     }
-    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 });
-            }
-        }
-        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.");
-        }
-        // 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;
+    build() {
+        return runEdge(authOwnMethod(SkillsRegistry.prototype, this, "build", []));
     }
-    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;
+    lookup(uri) {
+        return runEdge(authOwnMethod(SkillsRegistry.prototype, this, "lookup", [uri]));
     }
     missing(name) {
         const guides = this.registry.listConnectors().filter((connector) => connectorGuide(connector) !== undefined);
@@ -618,92 +562,254 @@ export class SkillsRegistry {
                 : `Unknown skill "${boundedEchoText(name)}".`;
         return new ConnectorCallError("not_found", `${message} Available skills: ${available}.`);
     }
-    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 {
-            ...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}` } : {}),
-        };
+    list(cursor) {
+        return runEdge(authOwnMethod(SkillsRegistry.prototype, this, "list", [cursor]));
     }
-    async get(uri) {
-        return { ...PRIVATE, skill: (await this.lookup(uri)).entry };
+    get(uri) {
+        return runEdge(authOwnMethod(SkillsRegistry.prototype, this, "get", [uri]));
     }
-    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 } : {}),
-        };
+    resources(cursor) {
+        return runEdge(authOwnMethod(SkillsRegistry.prototype, this, "resources", [cursor]));
     }
-    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]);
-            if (record.connector)
-                this.options.onRead?.(record.connector, "local");
-            // A connector guide is operator-authored payload, like a downstream file; built-in guides are Connecta's own.
-            const text = record.connector ? sentSecretsForRequest(this.scope).redact(record.content) : record.content;
-            return { ...PRIVATE, contents: [{ uri: record.entry.uri, mimeType: "text/markdown", text }] };
-        }
-        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.");
-        this.options.onRead?.(record.connector, "downstream");
-        // Downstream file contents take the request's full payload rules before any reader sees them.
-        const clean = sentSecretsForRequest(this.scope).redact(content);
-        return { ...PRIVATE, contents: [{ ...clean, uri }] };
+    read(uri) {
+        return runEdge(authOwnMethod(SkillsRegistry.prototype, this, "read", [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.");
-        }
+    text(name) {
+        return runEdge(authOwnMethod(SkillsRegistry.prototype, this, "text", [name]));
     }
-    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),
-        }));
+    summaries() {
+        return runEdge(authOwnMethod(SkillsRegistry.prototype, this, "summaries", []));
     }
+    static nativePrograms = /* @__PURE__ */ (() => {
+        registerAuthMethod(SkillsRegistry.prototype, "summaries", function () {
+            const self = this;
+            return duringViewEffect({ requestScope: this.scope, signal: this.options.requestSignal }, () => authFlow(function* () {
+                return (yield* upwardStep(authInvoke(self, "records", []))).map((record) => ({
+                    name: record.aliases[0] ?? record.entry.uri,
+                    uri: record.entry.uri,
+                    description: String(record.entry.frontmatter.description),
+                }));
+            })).pipe(Effect.provideService(RequestScope, requestOwner(this.scope)));
+        }, SkillsRegistry.prototype.summaries);
+        registerAuthMethod(SkillsRegistry.prototype, "text", function (name) {
+            const self = this;
+            return duringViewEffect({ requestScope: this.scope, signal: this.options.requestSignal }, () => authFlow(function* () {
+                const record = yield* upwardStep(authInvoke(self, "lookup", [name]));
+                const content = (yield* upwardStep(authInvoke(self, "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.");
+                }
+            })).pipe(Effect.provideService(RequestScope, requestOwner(this.scope)));
+        }, SkillsRegistry.prototype.text);
+        registerAuthMethod(SkillsRegistry.prototype, "read", function (uri) {
+            const self = this;
+            return duringViewEffect({ requestScope: this.scope, signal: this.options.requestSignal }, () => authFlow(function* () {
+                const local = (yield* upwardStep(self.local)).find((record) => record.entry.uri === uri || record.aliases.includes(uri));
+                if (local) {
+                    const record = yield* upwardStep(authCall(withManifest, [local]));
+                    self.assertSafe([record]);
+                    if (record.connector)
+                        self.options.onRead?.(record.connector, "local");
+                    // A connector guide is operator-authored payload, like a downstream file; built-in guides are Connecta's own.
+                    const text = record.connector
+                        ? sentSecretsForRequest(self.scope).redact(record.content)
+                        : record.content;
+                    return { ...PRIVATE, contents: [{ uri: record.entry.uri, mimeType: "text/markdown", text }] };
+                }
+                if (!uri.startsWith("skill://downstream/"))
+                    throw self.missing(uri);
+                const record = (yield* upwardStep(authInvoke(self, "records", []))).find((record) => record.files?.has(uri));
+                if (!record?.connector || !record.files || !self.registry.canReadConnectorSkills(record.connector.id))
+                    throw self.missing(uri);
+                const originalUri = record.files.get(uri);
+                const contents = yield* upwardStep(authInvoke(self, "operation", [
+                    record.connector,
+                    authMethod((ctx) => authInvoke(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.
+                yield* upwardStep(authInvoke(self, "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.");
+                self.options.onRead?.(record.connector, "downstream");
+                // Downstream file contents take the request's full payload rules before any reader sees them.
+                const clean = sentSecretsForRequest(self.scope).redact(content);
+                return { ...PRIVATE, contents: [{ ...clean, uri }] };
+            })).pipe(Effect.provideService(RequestScope, requestOwner(this.scope)));
+        }, SkillsRegistry.prototype.read);
+        registerAuthMethod(SkillsRegistry.prototype, "resources", function (cursor) {
+            const self = this;
+            return duringViewEffect({ requestScope: this.scope, signal: this.options.requestSignal }, () => authFlow(function* () {
+                const page = yield* upwardStep(authInvoke(self, "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 } : {}),
+                };
+            })).pipe(Effect.provideService(RequestScope, requestOwner(this.scope)));
+        }, SkillsRegistry.prototype.resources);
+        registerAuthMethod(SkillsRegistry.prototype, "get", function (uri) {
+            const self = this;
+            return duringViewEffect({ requestScope: this.scope, signal: this.options.requestSignal }, () => authFlow(function* () {
+                return { ...PRIVATE, skill: (yield* upwardStep(authInvoke(self, "lookup", [uri]))).entry };
+            })).pipe(Effect.provideService(RequestScope, requestOwner(this.scope)));
+        }, SkillsRegistry.prototype.get);
+        registerAuthMethod(SkillsRegistry.prototype, "list", function (cursor) {
+            const self = this;
+            return duringViewEffect({ requestScope: this.scope, signal: this.options.requestSignal }, () => authFlow(function* () {
+                const records = yield* upwardStep(authInvoke(self, "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 {
+                    ...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}` }
+                        : {}),
+                };
+            })).pipe(Effect.provideService(RequestScope, requestOwner(this.scope)));
+        }, SkillsRegistry.prototype.list);
+        registerAuthMethod(SkillsRegistry.prototype, "lookup", function (uri) {
+            const self = this;
+            return duringViewEffect({ requestScope: this.scope, signal: this.options.requestSignal }, () => authFlow(function* () {
+                const local = (yield* upwardStep(self.local)).find((record) => record.entry.uri === uri || record.aliases.includes(uri));
+                if (local) {
+                    const record = yield* upwardStep(authCall(withManifest, [local]));
+                    self.assertSafe([record]);
+                    return record;
+                }
+                // A non-skill URI never starts a downstream resource request or listing.
+                if (!uri.startsWith("skill://downstream/"))
+                    throw self.missing(uri);
+                const record = (yield* upwardStep(authInvoke(self, "records", []))).find((record) => record.entry.uri === uri);
+                if (!record)
+                    throw self.missing(uri);
+                return record;
+            })).pipe(Effect.provideService(RequestScope, requestOwner(this.scope)));
+        }, SkillsRegistry.prototype.lookup);
+        registerAuthMethod(SkillsRegistry.prototype, "build", function () {
+            const self = this;
+            return duringViewEffect({ requestScope: this.scope, signal: this.options.requestSignal }, () => authFlow(function* () {
+                const records = yield* upwardStep(Effect.forEach(yield* upwardStep(self.local), (record) => authCall(withManifest, [record]), {
+                    concurrency: "unbounded",
+                }));
+                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 self.registry.listConnectors()) {
+                    if (!connector.downstreamSkills || !self.registry.canReadConnectorSkills(connector.id))
+                        continue;
+                    const entries = yield* upwardStep(authInvoke(self, "operation", [
+                        connector,
+                        authMethod((ctx) => authInvoke(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(self.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 });
+                    }
+                }
+                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.");
+                }
+                // 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]);
+                self.assertSafe(records);
+                return records;
+            })).pipe(Effect.provideService(RequestScope, requestOwner(this.scope)));
+        }, SkillsRegistry.prototype.build);
+        registerAuthMethod(SkillsRegistry.prototype, "records", function () {
+            const instance = this;
+            return duringViewEffect({ requestScope: this.scope, signal: this.options.requestSignal }, () => Effect.gen(function* () {
+                if (!instance.snapshot)
+                    instance.snapshot = yield* Effect.cached(authInvoke(instance, "build", []).pipe(Effect.onError(() => Effect.sync(() => {
+                        instance.snapshot = undefined;
+                    }))));
+                const records = yield* instance.snapshot;
+                instance.assertSafe(records);
+                return records;
+            })).pipe(Effect.provideService(RequestScope, requestOwner(this.scope)));
+        }, SkillsRegistry.prototype.records);
+        registerAuthMethod(SkillsRegistry.prototype, "operation", function (connector, read) {
+            const self = this;
+            const timeoutMs = self.options.probeTimeoutMs ?? 20_000;
+            const operationScope = {};
+            sentSecretsForRequest(self.scope).include(sentSecretsForRequest(operationScope));
+            return duringViewEffect({ requestScope: this.scope, signal: this.options.requestSignal }, () => withDeadlineEffect((signal) => Effect.scoped(Effect.gen(function* () {
+                const ctx = self.registry.contextFor(connector.id, self.baseUrl, operationScope, {
+                    signal,
+                    timeoutMs,
+                    ...(self.options.defer ? { defer: self.options.defer } : {}),
+                });
+                yield* closeScopeOnExit(connector, ctx, self.options.defer);
+                return yield* authCall(read, [ctx]).pipe(Effect.mapError((error) => error instanceof ConnectorCallError && error.code === "auth_required"
+                    ? new ConnectorCallError("auth_required", "Downstream skills require authorization.")
+                    : new ConnectorCallError("unavailable", "Downstream skills are unavailable.")));
+            })), {
+                timeoutMs,
+                ...(self.options.requestSignal ? { signal: self.options.requestSignal } : {}),
+                timeoutError: new ConnectorCallError("unavailable", "Downstream skills timed out."),
+            })).pipe(Effect.provideService(RequestScope, requestOwner(this.scope)));
+        }, SkillsRegistry.prototype.operation);
+    })();
 }