@zackbart/connecta 0.40.0 → 0.42.0

package/dist/sent-secrets.d.ts

@@ -2,6 +2,9 @@ import type { ConnectorContext, JsonSchema, Logger } from "./types.js";
 /** One payload-free warning per configured connector, regardless of requests. */
 export declare function shortSecretWarning(): (value: string | undefined, logger: Logger) => void;
 export declare class SentSecrets {
+    /** Rises whenever this set could match more. Text checked at one revision has not been
+     * checked against a later one. */
+    revision: number;
     /** Normalized form to its strongest kind. */
     private readonly forms;
     /** A form's leading units that encode only public auth framing; absent is none. */
@@ -44,6 +47,10 @@ export declare class SentSecrets {
     contains(value: string, ignoreCase?: boolean): boolean;
     containsUrl(value: string): boolean;
     header(value: string): void;
+    /** A header maintained provider code declares a public identifier: matched whole only. A name
+     * alone never establishes this. Whitespace means an auth scheme or other framing, so that value
+     * is a credential whatever its header, and the answer is false. */
+    publicIdentifierHeader(value: string): boolean;
     request(input: RequestInfo | URL, init?: RequestInit): void;
     /** Serialized wire text about to be returned, stored, or paged, under payload rules. */
     text(value: string): string;
@@ -95,6 +102,13 @@ export declare class SentSecrets {
     /** Credentials alone: later calls keep the private arguments they submit, and cached
      * catalogs never depend on one request's arguments. */
     redactCredentials<T>(value: T): T;
+    /** A program's outbound arguments, with what the {@link outbound} check matched replaced,
+     * and whether it matched anything: a write that did is refused rather than sent altered.
+     * Output keeps the stricter matching; a program never holds what output withheld. */
+    filterCredentials<T>(value: T): {
+        value: T;
+        changed: boolean;
+    };
     private idle;
     private scan;
     private matcher;
@@ -104,6 +118,12 @@ export declare class SentSecrets {
     private wholeMatcher;
     private fragments;
     private credentials;
+    /** Credentials as an outbound argument can hold them: a whole form, or eight units of what
+     * follows its public framing and label. Identifiers and submitted private values are not
+     * here. Telling a secret from a label by shape has a limit: fewer than eight units past a
+     * label pass, and a public value sharing eight units of the rest, such as a publishable key
+     * beside its secret key, still matches. */
+    private outbound;
     /** Every form lowercased, for fields such as hosts that reach output lowercased. */
     private folded;
     /** The shortest text that might hold something this set cannot check, which is withheld: a

package/dist/sent-secrets.js

@@ -24,6 +24,11 @@ const MIN_SECRET_LENGTH = 8;
 // units is fragment-indexed. Eight units keeps ordinary words, dates, counts and auth framing out
 // of the index: a public run must repeat eight consecutive units of a secret's form to match.
 const FRAGMENT_LENGTH = MIN_SECRET_LENGTH;
+// A credential's public label, for the outbound argument check alone: a vendor prefix of up to
+// three short segments (`sk_test_`, `github_pat_`, `xoxb-`) or a JWT's header segment. Documents
+// name these and every credential of a kind shares them. Reading a secret's opening as a label
+// only stops runs starting inside it from matching; the rest of the value still matches.
+const PUBLIC_LABEL = /^(?:[Ee]yJ[\w-]*\.|(?:[A-Za-z][A-Za-z0-9]{1,6}[-_]){1,3})/;
 // A private value shorter than this is matched only as a whole field value: a leaf, key, number,
 // boolean or decoded view equal to one of its forms. One to three units recur inside ordinary
 // words, counts and ids, so a substring match would rewrite them everywhere.
@@ -115,7 +120,7 @@ const TAGS = new Set(("type:text type:image type:audio type:resource type:resour
     "resultType:input_required mode:form mode:url method:elicitation/create jsonrpc:2.0 writeOutcome:unknown").split(" "));
 // Outcome flags: a boolean under these names is kept, since a boolean carries one bit whatever
 // produced it. A number or string under them is matched like any other.
-const FACTS = new Set(["isError", "ok", "retryable", "truncated", "hasMore"]);
+const FACTS = new Set(["isError", "ok", "retryable", "truncated", "hasMore", "toolAnswered"]);
 // An error's diagnostics. Its own accessors under these names, such as V8's stack, are read once
 // into its copy, as is whatever its chain answers for them; any other own accessor is never
 // invoked. Accessors its class chain defines are read once too.
@@ -1096,6 +1101,9 @@ function windows(layer, reach) {
     return ranges;
 }
 export class SentSecrets {
+    /** Rises whenever this set could match more. Text checked at one revision has not been
+     * checked against a later one. */
+    revision = 0;
     /** Normalized form to its strongest kind. */
     forms = new Map();
     /** A form's leading units that encode only public auth framing; absent is none. */
@@ -1132,6 +1140,7 @@ export class SentSecrets {
         this.widestForm = Math.max(this.widestForm, form.length);
         this.smallForms ||= kind < PRIVATE;
         this.unicodeForms ||= /[\u0080-\uffff]/.test(form);
+        this.revision++;
         this.views = {};
         this.memo = new Map();
         for (const recipient of this.recipients)
@@ -1141,6 +1150,7 @@ export class SentSecrets {
         if (length >= this.unmatched)
             return;
         this.unmatched = length;
+        this.revision++;
         this.views = {};
         this.memo = new Map();
         for (const recipient of this.recipients)
@@ -1278,6 +1288,17 @@ export class SentSecrets {
         else
             this.secret(framed[1]);
     }
+    /** A header maintained provider code declares a public identifier: matched whole only. A name
+     * alone never establishes this. Whitespace means an auth scheme or other framing, so that value
+     * is a credential whatever its header, and the answer is false. */
+    publicIdentifierHeader(value) {
+        if (/\s/.test(value)) {
+            this.header(value);
+            return false;
+        }
+        this.identifier(value);
+        return true;
+    }
     request(input, init) {
         const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
         for (const [name, value] of headers) {
@@ -1412,6 +1433,16 @@ export class SentSecrets {
     redactCredentials(value) {
         return this.credentials().redact(value, "envelope");
     }
+    /** A program's outbound arguments, with what the {@link outbound} check matched replaced,
+     * and whether it matched anything: a write that did is refused rather than sent altered.
+     * Output keeps the stricter matching; a program never holds what output withheld. */
+    filterCredentials(value) {
+        const outbound = this.outbound();
+        if (outbound.idle())
+            return { value, changed: false };
+        const filtered = outbound.project(value, outbound.scan(false));
+        return { value: filtered.value, changed: filtered.changed };
+    }
     idle() {
         return !this.forms.size && this.unmatched === Infinity;
     }
@@ -1453,6 +1484,23 @@ export class SentSecrets {
         }
         return this.views.credentials;
     }
+    /** Credentials as an outbound argument can hold them: a whole form, or eight units of what
+     * follows its public framing and label. Identifiers and submitted private values are not
+     * here. Telling a secret from a label by shape has a limit: fewer than eight units past a
+     * label pass, and a public value sharing eight units of the rest, such as a publishable key
+     * beside its secret key, still matches. */
+    outbound() {
+        if (!this.views.outbound) {
+            const view = new SentSecrets();
+            for (const [form, kind] of this.forms) {
+                const frame = this.frames.get(form) ?? 0;
+                if (kind === CREDENTIAL && frame !== Infinity)
+                    view.store(form, kind, frame + (PUBLIC_LABEL.exec(form.slice(frame))?.[0].length ?? 0));
+            }
+            this.views.outbound = view;
+        }
+        return this.views.outbound;
+    }
     /** Every form lowercased, for fields such as hosts that reach output lowercased. */
     folded() {
         if (!this.views.folded) {

package/dist/skill-origin.js

@@ -0,0 +1,16 @@
+/**
+ * The fixed sentence that marks downstream guidance as third-party. A prefix has
+ * no closing delimiter to forge, and connector IDs are deployment-authored.
+ */
+export function downstreamOrigin(connectorId) {
+    return `Third-party guidance from connector ${JSON.stringify(connectorId.slice(0, 128))}.`;
+}
+/** Downstream description text on one line, so it cannot begin a new listing entry. */
+export function labeledDownstreamDescription(connectorId, description) {
+    return `${downstreamOrigin(connectorId)} ${description.replace(/\s+/g, " ").trim()}`;
+}
+const SKILL_RESOURCE = /^skill:\/\/|\/SKILL\.md(?:[?#]|$)/i;
+/** Whether a downstream resource URI addresses skill instructions rather than ordinary data. */
+export function isSkillResource(uri) {
+    return SKILL_RESOURCE.test(uri);
+}

package/dist/skills.js

@@ -1,41 +1,108 @@
 import { META_ROUTES, routeNames } from "./agent-routes.js";
+import { READ_PROGRAM_SOURCE } from "./tool-safety.js";
 import { bytesToHex, utf8Length } from "./bytes.js";
 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 { downstreamOrigin, labeledDownstreamDescription } from "./skill-origin.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";
+/** Trusted diagnostics constructed from the caller-visible local registry. */
+export class SkillLookupError extends ConnectorCallError {
+}
 // The meta instructions and built-in guides use the meta names: built-in guides
 // are byte-identical across deployments, and the eval code arm replaces usage.
-const ROUTE = `Choose a route before discovery. One known-address read uses ${META_ROUTES.read}; one known-address write uses ${META_ROUTES.write}. Unknown-address read-only work starts with ${META_ROUTES.program} 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 = `When an auth error includes a handoff, give it to the user or operator. Use ${META_ROUTES.authorize} for a fresh link. Page resultId notices and format:"paged" handles with connecta.result(handleOrId, { page? }). Missing guidance/repair only: skills tool "usage" or connecta.skill("usage").`;
-/**
- * The always-loaded MCP `instructions` string. An endpoint is writable or
- * read-only: a writable one lets programs and call_destructive_tool write,
- * and the client owns approval; a read-only one omits write tools from search
- * and describe and refuses every write call. Guides may still name them.
- */
-export const CONNECTA_INSTRUCTIONS = `${ROUTE} On a writable endpoint, programs and ${META_ROUTES.write} may write. On a read-only endpoint, search omits write tools and every write call is refused; guides may still name them. The ${META_ROUTES.program} description says which this endpoint is. Never repeat a write to recover its output. ${RECOVERY}`;
+const WRITE_POLICY = "This endpoint permits writes, subject to connector restrictions; the host owns approval. Never resend a write to see its output.";
+const READ_ONLY_POLICY = "This endpoint can't perform writes; no write route exists here.";
+const RECOVERY = "On errors and truncated results, follow nextAction; give auth links to the user or operator.";
+/** A guide can name a write step, so its notice says what happens to one. */
+const READ_ONLY_GUIDE_NOTICE = "This endpoint can't perform writes; guide steps that change data will be refused. No write route exists on this endpoint.";
+const policy = (readOnly) => (readOnly ? READ_ONLY_POLICY : WRITE_POLICY);
+/** Connector ids in instructions; execute_code's inventory carries the rest. */
+const INSTRUCTION_CONNECTORS_MAX_BYTES = 120;
+/** Ids in roster order, then an exact count once they pass the byte cap. Ids are ASCII. */
+function connectorList(ids) {
+    if (ids.length === 0)
+        return "none";
+    const all = ids.join(", ");
+    if (all.length <= INSTRUCTION_CONNECTORS_MAX_BYTES)
+        return all;
+    for (let shown = ids.length - 1; shown > 0; shown--) {
+        const line = [...ids.slice(0, shown), `+${ids.length - shown} more`].join(", ");
+        if (line.length <= INSTRUCTION_CONNECTORS_MAX_BYTES)
+            return line;
+    }
+    return `+${ids.length} more`;
+}
 /**
- * The instructions one endpoint serves: {@link CONNECTA_INSTRUCTIONS}, then
- * the admitted pool's `description` after a fixed lead-in. Plain `/mcp` and a
- * pool without a description serve the constant unchanged. The description
- * comes from deployment config for the pool the request was admitted through;
- * nothing a request sends reaches it.
+ * The instructions one endpoint serves: pool scope, what the endpoint reaches,
+ * routing, write policy, recovery. The description comes from deployment config
+ * for the pool the request was admitted through. `connectorIds` is that
+ * request's admitted roster, the same one execute_code's inventory discloses:
+ * configured ids only, in registry order, with no catalog, call or auth state.
+ * A native pool omits them because its tool names already show them.
  */
-export function endpointInstructions(description, native) {
-    const instructions = native ? nativeInstructions(native.executeCode) : CONNECTA_INSTRUCTIONS;
-    return description === undefined ? instructions : `${instructions} This endpoint: ${description}`;
+export function endpointInstructions(description, native, readOnly, connectorIds, readRoute = false) {
+    const gateway = `Gateway to connected services: ${connectorList(connectorIds)}. One known read: ${META_ROUTES.read}. ${readOnly ? "" : `One known write: ${META_ROUTES.write}. `}`;
+    const instructions = native
+        ? nativeInstructions(native.executeCode, readOnly)
+        : readRoute
+            ? `${gateway}Other read work: one ${READ_PROGRAM_SOURCE} program that searches, calls and returns the answer, with no write approval. ${readOnly ? "" : `Programs that write: ${META_ROUTES.program}. ${META_ROUTES.search} finds a write's address. `}${policy(readOnly)} ${RECOVERY}`
+            : `${gateway}Everything else: one ${META_ROUTES.program} program that searches, calls and returns the answer. ${policy(readOnly)} ${RECOVERY}`;
+    return description === undefined ? instructions : `${description} ${instructions}`;
 }
 /** Instructions for pools whose host searches the listed native tools. */
-export function nativeInstructions(executeCode) {
+export function nativeInstructions(executeCode, readOnly = false) {
     const routes = routeNames(executeCode ? "native-code" : "native");
-    return `Each tool here is one operation; annotations classify reads/writes. Call known tools directly; ${executeCode ? `combine work in ${routes.program} 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. Tools missing? Call authorize_connector; after repair, reconnect to refresh your list. Follow nextAction to page with ${executeCode ? `connecta.result in ${routes.program}` : "read_result"}. ${routes.skills} lists guidance.`;
+    return `Call known tools directly; ${executeCode ? `combine several in ${routes.program} using each tool's Program address.` : "find others with your host's search."} ${policy(readOnly)} ${RECOVERY} Tools missing: ask the operator to repair, then reconnect.`;
+}
+/** The `capabilities.extensions` key carrying {@link endpointExtension}. */
+export const ENDPOINT_EXTENSION = "dev.connecta/endpoint";
+const inventoryWords = (text) => text
+    .toLowerCase()
+    .split(/[^\p{L}\p{N}]+/u)
+    .filter(Boolean);
+/** Text that only respells what its entry already shows ("Google Calendar" for google_calendar) adds nothing. */
+export function addsInformation(shown, text) {
+    const words = inventoryWords(text);
+    const shownWords = inventoryWords(shown);
+    return words.join("") !== shownWords.join("") && words.some((word) => !shownWords.includes(word));
+}
+/** Clips on a whole token, so text with no token that fits leaves nothing to show. */
+export const inventoryNote = (text, maxBytes) => {
+    const clipped = boundedEchoText(text, maxBytes);
+    return clipped === "…" ? undefined : clipped;
+};
+/** A connector's bounded title for inventories, or undefined when it adds nothing to the id or cannot fit. */
+export function connectorInventoryTitle(connector) {
+    const title = connector.title?.replace(/\s+/g, " ").trim();
+    return title && addsInformation(connector.id, title) ? inventoryNote(title, 45) : undefined;
+}
+/**
+ * Facts about the endpoint this request reached, for a client composing its own
+ * host-specific guidance. Built only from the admitted scope and configuration:
+ * `connectors` is the caller's registry view, the roster `execute_code` and
+ * `authorize_connector` already describe, and nothing here loads a catalog.
+ */
+export function endpointExtension(connectors, native, executeCode, readOnly) {
+    return {
+        surface: native ? "native" : "meta",
+        executeCode,
+        readOnly,
+        connectors: connectors.map((connector) => {
+            const title = connectorInventoryTitle(connector);
+            return {
+                id: connector.id,
+                ...(title ? { title } : {}),
+                ...(connectorGuideRequired(connector) ? { readFirst: connectorSkillName(connector.id) } : {}),
+            };
+        }),
+    };
 }
 /** True when at least one of `connectors` carries a usage guide. */
 export function hasConnectorGuides(connectors) {
@@ -97,14 +164,19 @@ const CONNECTOR_SKILL_PREFIX = "connector:";
 export function connectorSkillName(connectorId) {
     return `${CONNECTOR_SKILL_PREFIX}${connectorId}`;
 }
-/** The connector's guide, or undefined when it declares none (or a blank one). */
-export function connectorGuide(connector) {
+/** The guide as authored, or undefined when the connector declares none (or a blank one). */
+function authoredGuide(connector) {
     const guide = connector.usageGuide;
     const content = typeof guide === "string" ? guide : guide?.content;
-    if (!content || content.trim() === "")
+    return !content || content.trim() === "" ? undefined : content;
+}
+/** The connector's guide with its connection's read-only notice, or undefined when it has none. */
+export function connectorGuide(connector) {
+    const content = authoredGuide(connector);
+    if (content === undefined)
         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}`
+        ? `This connection can't perform writes; guide steps that change data will be refused. No write route exists for this connection.\n\n${content}`
         : content;
 }
 /** Discovery budget for one connector-guide summary, including an ellipsis. */
@@ -338,49 +410,116 @@ const PRIVATE = { resultType: "complete", ttlMs: 0, cacheScope: "private" };
 function localRecord(name, uri, description, content, aliases) {
     return { entry: { uri, frontmatter: { name, description }, resources: "dynamic" }, content, aliases };
 }
+/** A local record's text after the frontmatter block Connecta wrote ahead of it. */
+function localSkillBody(text) {
+    const close = text.indexOf("\n---\n", 3);
+    return close === -1 ? text : text.slice(close + "\n---\n".length).replace(/^\n/, "");
+}
 /** 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);
 }
-function localRecords(connectors) {
-    return runEdge(localRecordsNative(connectors));
+/** Resolve guide names once from the admitted connector roster, including collisions. */
+export function resolvedConnectorGuides(connectors) {
+    return runEdge(resolvedConnectorGuidesNative(connectors));
+}
+const resolvedConnectorGuidesNative = /* @__PURE__ */ registerAuth(resolvedConnectorGuides, function (connectors) {
+    return authFlow(function* () {
+        const allocated = new Set(connectors.map((connector) => connector.id));
+        return 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 digest = validSkillName(connector.id)
+                ? ""
+                : bytesToHex(new Uint8Array(yield* upwardStep(authInvoke(crypto.subtle, "digest", ["SHA-256", encoder.encode(connector.id)]))));
+            const legacy = `connector-${digest.slice(0, 48)}`;
+            const slug = connector.id
+                .toLowerCase()
+                .replace(/[^a-z0-9]+/g, "-")
+                .replace(/^-|-$/g, "")
+                .slice(0, 42)
+                .replace(/-$/g, "") || "connector";
+            let name = connector.id;
+            if (!validSkillName(name)) {
+                const base = `${slug}-${digest.slice(0, 12)}`;
+                name = base;
+                let suffix = 1;
+                while (allocated.has(name))
+                    name = `${base}-${suffix++}`;
+                allocated.add(name);
+            }
+            return {
+                connector,
+                name,
+                legacy,
+                reference: AVAILABLE_SKILLS.some((skill) => skill.name === name)
+                    ? `skill://connecta/connectors/${name}`
+                    : name,
+            };
+        }), { concurrency: 1 }));
+    });
+});
+function localRecords(connectors, readOnly = false) {
+    return runEdge(localRecordsNative(connectors, readOnly));
 }
-const localRecordsNative = /* @__PURE__ */ registerAuth(localRecords, function (connectors) {
+const localRecordsNative = /* @__PURE__ */ registerAuth(localRecords, function (connectors, readOnly = false) {
     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-${bytesToHex(new Uint8Array(yield* upwardStep(authInvoke(crypto.subtle, "digest", ["SHA-256", encoder.encode(connector.id)])))).slice(0, 48)}`;
+        const identities = yield* upwardStep(authCall(resolvedConnectorGuides, [
+            connectors,
+        ]));
+        const guides = identities.map(({ connector, name, legacy }) => {
             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)}`;
+            // One read-only notice: the endpoint's already covers its connections.
+            const guide = readOnly
+                ? `${READ_ONLY_GUIDE_NOTICE}\n\n${authoredGuide(connector)}`
+                : connectorGuide(connector);
+            const content = `---\n${JSON.stringify({ name, description }, null, 2)}\n---\n\n${guide}`;
             return {
                 ...localRecord(name, `${root}/SKILL.md`, description, content, [
                     connectorSkillName(connector.id),
+                    ...(connector.id.includes(":") ? [] : [connector.id]),
+                    ...(name !== connector.id
+                        ? [legacy, `skill://connecta/connectors/${legacy}`, `skill://connecta/connectors/${legacy}/SKILL.md`]
+                        : []),
                     `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)];
     });
 });
-/** `granola` names connector granola's guide; built-in names and URIs never do. */
-function bareConnectorGuide(records, name) {
-    if (name.includes(":") || AVAILABLE_SKILLS.some((skill) => skill.name === name))
-        return undefined;
-    const alias = connectorSkillName(name);
-    return records.find((record) => record.connector !== undefined && record.aliases.includes(alias));
+/** Canonical identities win; an alias shared by different guides is ambiguous. */
+function localLookup(records, key) {
+    const canonical = new Map();
+    for (const record of records) {
+        canonical.set(record.entry.uri, record);
+        canonical.set(record.entry.uri.slice(0, -"/SKILL.md".length), record);
+        const name = record.entry.frontmatter.name;
+        if (!record.connector || !AVAILABLE_SKILLS.some((skill) => skill.name === name))
+            canonical.set(name, record);
+    }
+    const aliases = new Map();
+    for (const record of records) {
+        for (const alias of record.aliases) {
+            if (canonical.has(alias))
+                continue;
+            aliases.set(alias, aliases.has(alias) && aliases.get(alias) !== record ? null : record);
+        }
+    }
+    const result = canonical.get(key) ?? aliases.get(key);
+    if (result === null)
+        throw new ConnectorCallError("invalid_args", "Ambiguous skill alias; use its canonical URI.");
+    return result;
 }
 /** Keep the downstream path tree, so relative supporting-file references still resolve. */
 export function downstreamSkillUri(connectorId, uri) {
@@ -485,6 +624,7 @@ export class SkillsRegistry {
     baseUrl;
     options;
     scope;
+    cacheHints;
     local;
     snapshot;
     constructor(registry, baseUrl, options = {}) {
@@ -493,7 +633,11 @@ export class SkillsRegistry {
         this.options = options;
         void SkillsRegistry.nativePrograms;
         this.scope = options.requestScope ?? {};
-        this.local = authCall(localRecords, [registry.listConnectors()]);
+        this.cacheHints = {
+            ...PRIVATE,
+            ttlMs: registry.listConnectors().some((connector) => connector.downstreamSkills !== undefined) ? 0 : 300_000,
+        };
+        this.local = authCall(localRecords, [registry.listConnectors(), options.readOnly === true]);
     }
     operation(connector, read) {
         return runEdge(authOwnMethod(SkillsRegistry.prototype, this, "operation", [connector, read]));
@@ -547,7 +691,7 @@ export class SkillsRegistry {
             : name.startsWith(CONNECTOR_SKILL_PREFIX)
                 ? `Unknown connector "${boundedEchoText(id)}".`
                 : `Unknown skill "${boundedEchoText(name)}".`;
-        return new ConnectorCallError("not_found", `${message} Available skills: ${available}.`);
+        return new SkillLookupError("not_found", `${message} Available skills: ${available}.`);
     }
     list(cursor) {
         return runEdge(authOwnMethod(SkillsRegistry.prototype, this, "list", [cursor]));
@@ -574,7 +718,9 @@ export class SkillsRegistry {
                 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),
+                    description: record.files
+                        ? labeledDownstreamDescription(record.connector.id, String(record.entry.frontmatter.description))
+                        : String(record.entry.frontmatter.description),
                 }));
             })).pipe(Effect.provideService(RequestScope, requestOwner(this.scope)));
         }, SkillsRegistry.prototype.summaries);
@@ -583,10 +729,16 @@ export class SkillsRegistry {
             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];
+                // Connecta prepends frontmatter to local guides for native SKILL.md; a
+                // tool reader wants only the body. Downstream files keep their bytes.
+                if (!record.files && typeof content.text === "string")
+                    return localSkillBody(content.text);
+                const origin = record.files ? `${downstreamOrigin(record.connector.id)}\n\n` : "";
                 if (typeof content.text === "string")
-                    return content.text;
+                    return origin + content.text;
                 try {
-                    return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(Uint8Array.from(atob(content.blob), (char) => char.charCodeAt(0)));
+                    return (origin +
+                        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.");
@@ -596,7 +748,7 @@ export class SkillsRegistry {
         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));
+                const local = localLookup(yield* upwardStep(self.local), uri);
                 if (local) {
                     const record = yield* upwardStep(authCall(withManifest, [local]));
                     self.assertSafe([record]);
@@ -606,7 +758,7 @@ export class SkillsRegistry {
                     const text = record.connector
                         ? sentSecretsForRequest(self.scope).redact(record.content)
                         : record.content;
-                    return { ...PRIVATE, contents: [{ uri: record.entry.uri, mimeType: "text/markdown", text }] };
+                    return { ...self.cacheHints, contents: [{ uri: record.entry.uri, mimeType: "text/markdown", text }] };
                 }
                 if (!uri.startsWith("skill://downstream/"))
                     throw self.missing(uri);
@@ -642,7 +794,7 @@ export class SkillsRegistry {
                 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 }] };
+                return { ...self.cacheHints, contents: [{ ...clean, uri }] };
             })).pipe(Effect.provideService(RequestScope, requestOwner(this.scope)));
         }, SkillsRegistry.prototype.read);
         registerAuthMethod(SkillsRegistry.prototype, "resources", function (cursor) {
@@ -650,7 +802,7 @@ export class SkillsRegistry {
             return duringViewEffect({ requestScope: this.scope, signal: this.options.requestSignal }, () => authFlow(function* () {
                 const page = yield* upwardStep(authInvoke(self, "list", [cursor]));
                 return {
-                    ...PRIVATE,
+                    ...self.cacheHints,
                     resources: page.skills.flatMap((skill) => (skill.resources === "dynamic" ? [{ uri: skill.uri }] : skill.resources).map((file) => ({
                         uri: file.uri,
                         name: file.uri === skill.uri
@@ -668,7 +820,10 @@ export class SkillsRegistry {
         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 };
+                return {
+                    ...self.cacheHints,
+                    skill: (yield* upwardStep(authInvoke(self, "lookup", [uri]))).entry,
+                };
             })).pipe(Effect.provideService(RequestScope, requestOwner(this.scope)));
         }, SkillsRegistry.prototype.get);
         registerAuthMethod(SkillsRegistry.prototype, "list", function (cursor) {
@@ -679,7 +834,7 @@ export class SkillsRegistry {
                 if (!Number.isSafeInteger(offset) || offset % SKILL_PAGE_SIZE !== 0 || offset >= records.length)
                     throw new ConnectorCallError("invalid_args", "Invalid skills cursor.");
                 return {
-                    ...PRIVATE,
+                    ...self.cacheHints,
                     skills: records.slice(offset, offset + SKILL_PAGE_SIZE).map((record) => record.entry),
                     ...(offset + SKILL_PAGE_SIZE < records.length
                         ? { nextCursor: `skills:${offset + SKILL_PAGE_SIZE}` }
@@ -691,8 +846,7 @@ export class SkillsRegistry {
             const self = this;
             return duringViewEffect({ requestScope: this.scope, signal: this.options.requestSignal }, () => authFlow(function* () {
                 const records = yield* upwardStep(self.local);
-                const local = records.find((record) => record.entry.uri === uri || record.aliases.includes(uri)) ??
-                    bareConnectorGuide(records, uri);
+                const local = localLookup(records, uri);
                 if (local) {
                     const record = yield* upwardStep(authCall(withManifest, [local]));
                     self.assertSafe([record]);
@@ -791,9 +945,11 @@ export class SkillsRegistry {
                     ...(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.")));
+                return yield* authCall(read, [ctx]).pipe(Effect.mapError((error) => error instanceof ConnectorCallError && error.code === "unsupported_capability"
+                    ? new ConnectorCallError("unsupported_capability", "Downstream Skills capability is not supported.", { retryable: false })
+                    : 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 } : {}),