@bevel-software/platform-mcp-core 0.33.0 → 0.34.0

package/dist/connection-scope-wire.d.ts

@@ -0,0 +1,53 @@
+/**
+ * What a connection's scope says about itself on the wire, and the words
+ * both MCP servers — the hosted proxy and the local `hexis-mcp` — build from
+ * it: the handshake line, the refusal of a tool the connection does not
+ * load, and the sentence a connection that loads nothing carries. ONE
+ * module, so the two servers cannot word the same connection differently.
+ *
+ * The deployment puts the wire on `GET /api/agent/all-tools` and
+ * `GET /api/agent/catalog-revision` as their `connection` field; absent for
+ * a connection made as Everything, which is told nothing new.
+ */
+/** The `code` beside a refusal of what the caller's connection does not load. */
+export declare const NOT_AVAILABLE_TO_CONNECTION = "not_available_to_connection";
+/**
+ * Where the sentence saying why a connection loads nothing rides a
+ * `tools/list` answer: the listing has no description of its own, and an
+ * empty `tools` array alone would read as an outage.
+ */
+export declare const CONNECTION_META_KEY = "software.bevel.hexis/connection";
+/** The agent a connection was made as, by the file that defines it. */
+export interface ScopeAgent {
+    /** Repo-relative path of the agent configuration, as the distribution records it. */
+    path: string;
+    /** Its name — the frontmatter `name`, else the file's base name; the path when the file cannot be read. */
+    name: string;
+}
+/** The `connection` field of the two deployment answers above. */
+export interface ConnectionScopeWire {
+    agent: ScopeAgent;
+    /** Set when the connection loads nothing because its file cannot be used: the one sentence saying why. */
+    unavailable?: string;
+}
+/**
+ * The wire an answer carries, validated at the boundary: HTTP loses the
+ * type. A malformed one is dropped — undefined, the Everything reading —
+ * which serves what the answer listed, itself already narrowed by the
+ * deployment's agent surfaces.
+ */
+export declare function connectionWireOf(body: unknown): ConnectionScopeWire | undefined;
+/**
+ * The answer to a call of `toolName` that the connection described by
+ * `wire` does not load: names the tool and the agent, so the caller knows
+ * the tool was refused by the connection's choice and not missing from the
+ * deployment; for a file that cannot be used, the sentence that says why.
+ * The ONE wording — the tool route and both MCP servers answer with it.
+ */
+export declare function connectionRefusal(toolName: string, wire: ConnectionScopeWire | undefined): string;
+/**
+ * The one line an agent is told about its connection (the MCP handshake, the
+ * agent guide); null for Everything, which is told nothing new.
+ */
+export declare function describeConnection(wire: ConnectionScopeWire | undefined): string | null;
+//# sourceMappingURL=connection-scope-wire.d.ts.map

package/dist/connection-scope-wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-scope-wire.d.ts","sourceRoot":"","sources":["../src/connection-scope-wire.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,iFAAiF;AACjF,eAAO,MAAM,2BAA2B,gCAAgC,CAAC;AAEzE;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,oCAAoC,CAAC;AAErE,uEAAuE;AACvE,MAAM,WAAW,UAAU;IACzB,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAC;IACb,2GAA2G;IAC3G,IAAI,EAAE,MAAM,CAAC;CACd;AAED,kEAAkE;AAClE,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,UAAU,CAAC;IAClB,0GAA0G;IAC1G,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,mBAAmB,GAAG,SAAS,CAQ/E;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,mBAAmB,GAAG,SAAS,GAAG,MAAM,CAOjG;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,mBAAmB,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAOvF"}

package/dist/connection-scope-wire.js

@@ -0,0 +1,63 @@
+/**
+ * What a connection's scope says about itself on the wire, and the words
+ * both MCP servers — the hosted proxy and the local `hexis-mcp` — build from
+ * it: the handshake line, the refusal of a tool the connection does not
+ * load, and the sentence a connection that loads nothing carries. ONE
+ * module, so the two servers cannot word the same connection differently.
+ *
+ * The deployment puts the wire on `GET /api/agent/all-tools` and
+ * `GET /api/agent/catalog-revision` as their `connection` field; absent for
+ * a connection made as Everything, which is told nothing new.
+ */
+/** The `code` beside a refusal of what the caller's connection does not load. */
+export const NOT_AVAILABLE_TO_CONNECTION = 'not_available_to_connection';
+/**
+ * Where the sentence saying why a connection loads nothing rides a
+ * `tools/list` answer: the listing has no description of its own, and an
+ * empty `tools` array alone would read as an outage.
+ */
+export const CONNECTION_META_KEY = 'software.bevel.hexis/connection';
+/**
+ * The wire an answer carries, validated at the boundary: HTTP loses the
+ * type. A malformed one is dropped — undefined, the Everything reading —
+ * which serves what the answer listed, itself already narrowed by the
+ * deployment's agent surfaces.
+ */
+export function connectionWireOf(body) {
+    const raw = body
+        ?.connection;
+    if (!raw || typeof raw.agent?.path !== 'string' || typeof raw.agent.name !== 'string')
+        return undefined;
+    return {
+        agent: { path: raw.agent.path, name: raw.agent.name },
+        ...(typeof raw.unavailable === 'string' && raw.unavailable ? { unavailable: raw.unavailable } : {}),
+    };
+}
+/**
+ * The answer to a call of `toolName` that the connection described by
+ * `wire` does not load: names the tool and the agent, so the caller knows
+ * the tool was refused by the connection's choice and not missing from the
+ * deployment; for a file that cannot be used, the sentence that says why.
+ * The ONE wording — the tool route and both MCP servers answer with it.
+ */
+export function connectionRefusal(toolName, wire) {
+    if (!wire)
+        return `The tool "${toolName}" is not available to this connection.`;
+    if (wire.unavailable)
+        return wire.unavailable;
+    return (`The tool "${toolName}" is not available to this connection: it is connected as the agent ` +
+        `"${wire.agent.name}" (\`${wire.agent.path}\`), which does not load it.`);
+}
+/**
+ * The one line an agent is told about its connection (the MCP handshake, the
+ * agent guide); null for Everything, which is told nothing new.
+ */
+export function describeConnection(wire) {
+    if (!wire)
+        return null;
+    if (wire.unavailable)
+        return wire.unavailable;
+    return (`This connection is connected as the agent "${wire.agent.name}" (\`${wire.agent.path}\`): it loads only the ` +
+        'platform tools, connectors, skills and plugins that file lists, and of those only what you may read.');
+}
+//# sourceMappingURL=connection-scope-wire.js.map

package/dist/connection-scope-wire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-scope-wire.js","sourceRoot":"","sources":["../src/connection-scope-wire.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,iFAAiF;AACjF,MAAM,CAAC,MAAM,2BAA2B,GAAG,6BAA6B,CAAC;AAEzE;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,iCAAiC,CAAC;AAiBrE;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAa;IAC5C,MAAM,GAAG,GAAI,IAAsG;QACjH,EAAE,UAAU,CAAC;IACf,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,CAAC,KAAK,EAAE,IAAI,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,KAAK,CAAC,IAAI,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACxG,OAAO;QACL,KAAK,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE;QACrD,GAAG,CAAC,OAAO,GAAG,CAAC,WAAW,KAAK,QAAQ,IAAI,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACpG,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,IAAqC;IACvF,IAAI,CAAC,IAAI;QAAE,OAAO,aAAa,QAAQ,wCAAwC,CAAC;IAChF,IAAI,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC,WAAW,CAAC;IAC9C,OAAO,CACL,aAAa,QAAQ,sEAAsE;QAC3F,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,QAAQ,IAAI,CAAC,KAAK,CAAC,IAAI,8BAA8B,CACzE,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAqC;IACtE,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,IAAI,IAAI,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC,WAAW,CAAC;IAC9C,OAAO,CACL,8CAA8C,IAAI,CAAC,KAAK,CAAC,IAAI,QAAQ,IAAI,CAAC,KAAK,CAAC,IAAI,yBAAyB;QAC7G,sGAAsG,CACvG,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -42,5 +42,6 @@ export { type SkillSummary, type LoadedSkill, skillPromptText, } from './skills.
 export { utcpNamespacePrefix, utcpNamespacedKey, seedBevelHostedManualVars, isPlatformHostedUrl, } from './utcp-namespace.js';
 export { sanitizeIdentifier, utcpNameToTsInterfaceName, findToolByName, findToolsByNames, AmbiguousToolNameError, } from './code-mode-names.js';
 export { printable } from './printable.js';
+export { CONNECTION_META_KEY, NOT_AVAILABLE_TO_CONNECTION, connectionRefusal, connectionWireOf, describeConnection, type ConnectionScopeWire, type ScopeAgent, } from './connection-scope-wire.js';
 export { GOOGLE_SERVICE_ACCOUNT_AUTH_TYPE, GOOGLE_TOKEN_URL, GoogleAuthHttpProtocol, GoogleServiceAccountTokenSource, ServiceAccountAuthError, findUnservedGoogleServiceAccountAuth, holdsLiteralGoogleServiceAccountKey, installGoogleServiceAccountAuth, isGoogleServiceAccountAuth, type GoogleServiceAccountAuth, type IServiceAccountTokenSource, } from './google-service-account/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -42,6 +42,10 @@ export { skillPromptText, } from './skills.js';
 export { utcpNamespacePrefix, utcpNamespacedKey, seedBevelHostedManualVars, isPlatformHostedUrl, } from './utcp-namespace.js';
 export { sanitizeIdentifier, utcpNameToTsInterfaceName, findToolByName, findToolsByNames, AmbiguousToolNameError, } from './code-mode-names.js';
 export { printable } from './printable.js';
+// A connection made as an `.agent` file, as the deployment says it on the
+// wire and as both MCP servers word it: one module, so the hosted proxy and
+// the local server cannot describe or refuse the same connection differently.
+export { CONNECTION_META_KEY, NOT_AVAILABLE_TO_CONNECTION, connectionRefusal, connectionWireOf, describeConnection, } from './connection-scope-wire.js';
 // Loading this package teaches UTCP `auth_type: google_service_account`, on
 // both surfaces alike: the auth type validates and the `http` protocol mints
 // the token. A side effect of the import, like the `@utcp/http` registration

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAEL,aAAa,EACb,oBAAoB,EACpB,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAEL,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAKlB,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,SAAS,EACT,wBAAwB,EACxB,qBAAqB,EAErB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,mBAAmB,EACnB,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,EAGxB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,EACpB,oBAAoB,EAGpB,eAAe,EACf,uBAAuB,EACvB,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAGL,YAAY,GACb,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjE,OAAO,EACL,gBAAgB,EAChB,2BAA2B,EAC3B,sBAAsB,EACtB,oBAAoB,EACpB,WAAW,EACX,gBAAgB,EAChB,QAAQ,EACR,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,0BAA0B,EAC1B,YAAY,EACZ,QAAQ,GAET,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAEhG,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE5F,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,sBAAsB,GAEvB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAGL,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,yBAAyB,EACzB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,cAAc,EACd,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,4EAA4E;AAC5E,6EAA6E;AAC7E,6EAA6E;AAC7E,yDAAyD;AACzD,OAAO,EACL,gCAAgC,EAChC,gBAAgB,EAChB,sBAAsB,EACtB,+BAA+B,EAC/B,uBAAuB,EACvB,oCAAoC,EACpC,mCAAmC,EACnC,+BAA+B,EAC/B,0BAA0B,GAG3B,MAAM,mCAAmC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAEL,aAAa,EACb,oBAAoB,EACpB,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAEL,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAKlB,UAAU,EACV,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,mBAAmB,EACnB,mBAAmB,EACnB,gBAAgB,EAChB,cAAc,EACd,SAAS,EACT,wBAAwB,EACxB,qBAAqB,EAErB,cAAc,EACd,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,iBAAiB,GAClB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,eAAe,EACf,mBAAmB,EACnB,0BAA0B,EAC1B,oBAAoB,EACpB,mBAAmB,EACnB,wBAAwB,EAGxB,gBAAgB,GACjB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,qBAAqB,EACrB,wBAAwB,EACxB,oBAAoB,EACpB,oBAAoB,EAGpB,eAAe,EACf,uBAAuB,EACvB,mBAAmB,EACnB,oBAAoB,EACpB,YAAY,EACZ,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAGL,YAAY,GACb,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAEjE,OAAO,EACL,gBAAgB,EAChB,2BAA2B,EAC3B,sBAAsB,EACtB,oBAAoB,EACpB,WAAW,EACX,gBAAgB,EAChB,QAAQ,EACR,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,0BAA0B,EAC1B,YAAY,EACZ,QAAQ,GAET,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,kBAAkB,CAAC;AAEhG,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE5F,OAAO,EACL,qBAAqB,EACrB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,aAAa,EACb,sBAAsB,EACtB,sBAAsB,GAEvB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAGL,eAAe,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,yBAAyB,EACzB,mBAAmB,GACpB,MAAM,qBAAqB,CAAC;AAE7B,OAAO,EACL,kBAAkB,EAClB,yBAAyB,EACzB,cAAc,EACd,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,0EAA0E;AAC1E,4EAA4E;AAC5E,8EAA8E;AAC9E,OAAO,EACL,mBAAmB,EACnB,2BAA2B,EAC3B,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,GAGnB,MAAM,4BAA4B,CAAC;AAEpC,4EAA4E;AAC5E,6EAA6E;AAC7E,6EAA6E;AAC7E,yDAAyD;AACzD,OAAO,EACL,gCAAgC,EAChC,gBAAgB,EAChB,sBAAsB,EACtB,+BAA+B,EAC/B,uBAAuB,EACvB,oCAAoC,EACpC,mCAAmC,EACnC,+BAA+B,EAC/B,0BAA0B,GAG3B,MAAM,mCAAmC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-mcp-core",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "description": "The transport-agnostic half of Bevel's MCP surface: UTCP manual registration, tool discovery, MCP listing/dispatch and the code-mode meta-tools. Shared by the hosted proxy and the local stdio server.",
   "type": "module",
   "main": "./dist/index.js",

package/src/connection-scope-wire.ts

@@ -0,0 +1,81 @@
+/**
+ * What a connection's scope says about itself on the wire, and the words
+ * both MCP servers — the hosted proxy and the local `hexis-mcp` — build from
+ * it: the handshake line, the refusal of a tool the connection does not
+ * load, and the sentence a connection that loads nothing carries. ONE
+ * module, so the two servers cannot word the same connection differently.
+ *
+ * The deployment puts the wire on `GET /api/agent/all-tools` and
+ * `GET /api/agent/catalog-revision` as their `connection` field; absent for
+ * a connection made as Everything, which is told nothing new.
+ */
+
+/** The `code` beside a refusal of what the caller's connection does not load. */
+export const NOT_AVAILABLE_TO_CONNECTION = 'not_available_to_connection';
+
+/**
+ * Where the sentence saying why a connection loads nothing rides a
+ * `tools/list` answer: the listing has no description of its own, and an
+ * empty `tools` array alone would read as an outage.
+ */
+export const CONNECTION_META_KEY = 'software.bevel.hexis/connection';
+
+/** The agent a connection was made as, by the file that defines it. */
+export interface ScopeAgent {
+  /** Repo-relative path of the agent configuration, as the distribution records it. */
+  path: string;
+  /** Its name — the frontmatter `name`, else the file's base name; the path when the file cannot be read. */
+  name: string;
+}
+
+/** The `connection` field of the two deployment answers above. */
+export interface ConnectionScopeWire {
+  agent: ScopeAgent;
+  /** Set when the connection loads nothing because its file cannot be used: the one sentence saying why. */
+  unavailable?: string;
+}
+
+/**
+ * The wire an answer carries, validated at the boundary: HTTP loses the
+ * type. A malformed one is dropped — undefined, the Everything reading —
+ * which serves what the answer listed, itself already narrowed by the
+ * deployment's agent surfaces.
+ */
+export function connectionWireOf(body: unknown): ConnectionScopeWire | undefined {
+  const raw = (body as { connection?: { agent?: { path?: unknown; name?: unknown }; unavailable?: unknown } } | null)
+    ?.connection;
+  if (!raw || typeof raw.agent?.path !== 'string' || typeof raw.agent.name !== 'string') return undefined;
+  return {
+    agent: { path: raw.agent.path, name: raw.agent.name },
+    ...(typeof raw.unavailable === 'string' && raw.unavailable ? { unavailable: raw.unavailable } : {}),
+  };
+}
+
+/**
+ * The answer to a call of `toolName` that the connection described by
+ * `wire` does not load: names the tool and the agent, so the caller knows
+ * the tool was refused by the connection's choice and not missing from the
+ * deployment; for a file that cannot be used, the sentence that says why.
+ * The ONE wording — the tool route and both MCP servers answer with it.
+ */
+export function connectionRefusal(toolName: string, wire: ConnectionScopeWire | undefined): string {
+  if (!wire) return `The tool "${toolName}" is not available to this connection.`;
+  if (wire.unavailable) return wire.unavailable;
+  return (
+    `The tool "${toolName}" is not available to this connection: it is connected as the agent ` +
+    `"${wire.agent.name}" (\`${wire.agent.path}\`), which does not load it.`
+  );
+}
+
+/**
+ * The one line an agent is told about its connection (the MCP handshake, the
+ * agent guide); null for Everything, which is told nothing new.
+ */
+export function describeConnection(wire: ConnectionScopeWire | undefined): string | null {
+  if (!wire) return null;
+  if (wire.unavailable) return wire.unavailable;
+  return (
+    `This connection is connected as the agent "${wire.agent.name}" (\`${wire.agent.path}\`): it loads only the ` +
+    'platform tools, connectors, skills and plugins that file lists, and of those only what you may read.'
+  );
+}

package/src/index.ts

@@ -169,6 +169,19 @@ export {
 
 export { printable } from './printable.js';
 
+// A connection made as an `.agent` file, as the deployment says it on the
+// wire and as both MCP servers word it: one module, so the hosted proxy and
+// the local server cannot describe or refuse the same connection differently.
+export {
+  CONNECTION_META_KEY,
+  NOT_AVAILABLE_TO_CONNECTION,
+  connectionRefusal,
+  connectionWireOf,
+  describeConnection,
+  type ConnectionScopeWire,
+  type ScopeAgent,
+} from './connection-scope-wire.js';
+
 // Loading this package teaches UTCP `auth_type: google_service_account`, on
 // both surfaces alike: the auth type validates and the `http` protocol mints
 // the token. A side effect of the import, like the `@utcp/http` registration