From 75d5305643da131dd3ef5bc0fbc37c753689f2f9 Mon Sep 17 00:00:00 2001 From: Tiberiu Socaci Date: Wed, 21 Oct 2026 19:28:19 +0300 Subject: [PATCH 1/2] docs: document agent discovery controls and specialist routing Signed-off-by: Tiberiu Socaci --- documentation/src/content/docs/controls.mdx | 2 +- .../docs/controls/conversation-settings.md | 22 +++++++++++++ .../controls/knowledge-and-instructions.md | 32 ++++++++++++++++++- .../src/content/docs/features/skills.md | 12 +++++++ 4 files changed, 66 insertions(+), 2 deletions(-) diff --git a/documentation/src/content/docs/controls.mdx b/documentation/src/content/docs/controls.mdx index a402895c..5c44f2ce 100644 --- a/documentation/src/content/docs/controls.mdx +++ b/documentation/src/content/docs/controls.mdx @@ -9,7 +9,7 @@ import { controlPages } from '../../data/control-reference.mjs'; Ask the agent for an outcome in ordinary language. It can use the controls below when its current permissions, platform, and connections allow them. These reference pages explain the exact tool names, inputs, results, and restrictions for people building integrations or checking how an action works. -The gateway defines **108 controls**. The separate [skills-library service](/docs/controls/skills-library) defines **10 more**. A run receives an authorized subset; a tool appearing here does not mean it is enabled in every conversation. The library endpoint uses its own access tokens. +The gateway defines **110 controls**. The separate [skills-library service](/docs/controls/skills-library) defines **10 more**. A run receives an authorized subset; a tool appearing here does not mean it is enabled in every conversation. The library endpoint uses its own access tokens. For practical workflows, browse the [feature directory](/docs/features). For deployment and conversation defaults, open [configuration](/docs/configuration). The [functionality map](/docs/functionality) connects the broader product areas to their guides. diff --git a/documentation/src/content/docs/controls/conversation-settings.md b/documentation/src/content/docs/controls/conversation-settings.md index 1939a382..8082519b 100644 --- a/documentation/src/content/docs/controls/conversation-settings.md +++ b/documentation/src/content/docs/controls/conversation-settings.md @@ -7,6 +7,28 @@ These controls are capability-bound to the current conversation, except the expl Persistent control changes require the current authorized human decision through the gateway approval path. Auto approval of engine tools does not approve these control-plane changes. The managed updater has an explicit Auto/Admin exception; restart has an Admin exception, described below. Read-only tools do not require that extra sign-off. +## set_channel_agent_profile + +Describe or hide the current channel's specialist agent without changing its skills or access. + +| Argument | Required | Meaning and default | +| --- | --- | --- | +| `description` | No | Purpose, up to 600 characters. Empty clears the curated purpose. | +| `examples` | No | Up to six example tasks, each up to 160 characters. Empty array clears them. | +| `hidden` | No | Hide/unhide this agent in discovery. | + +**Authority:** Authenticated current-channel manager or admin with current gateway access. +Channel-scoped and reversible; no second approval card. API/untrusted principals are refused. +At least one field is required semantically; omitted fields remain unchanged. + +**Result:** Saved profile, immediately available to subsequent directory lookups. Without a +curated purpose, platform purpose/topic supplies it. Announce the saved change in the reply. +The audit records actor, channel and changed keys without descriptive content. + +**Restrictions:** Always this conversation; model arguments cannot target another channel. +Publishing a purpose never widens private channel visibility. See +[search_agents](/docs/controls/knowledge-and-instructions/#search_agents). + ## set_channel_admin_mode **Required:** `enabled` (boolean). **Optional:** none. **Authority:** gateway admin, with control approval. diff --git a/documentation/src/content/docs/controls/knowledge-and-instructions.md b/documentation/src/content/docs/controls/knowledge-and-instructions.md index e8105003..d816792e 100644 --- a/documentation/src/content/docs/controls/knowledge-and-instructions.md +++ b/documentation/src/content/docs/controls/knowledge-and-instructions.md @@ -3,7 +3,37 @@ title: Memory and instruction controls description: Search, read, and update channel knowledge and request standing rules. --- -Memory stores declarative facts for later retrieval. Instructions govern behavior. These four controls use the current conversation only; the run capability does not expose another channel’s knowledge. +Memory stores declarative facts for later retrieval. Instructions govern behavior. Memory and +instruction controls use the current conversation only. Agent discovery returns a separately +authorized directory projection; it never reads another conversation's memory or history. + +## search_agents + +Find an existing specialist channel agent by purpose, example tasks or active shared skills. + +| Argument | Required | Meaning and default | +| --- | --- | --- | +| `query` | No | Up to 500 characters; empty lists eligible agents. | +| `limit` | No | Integer 1–50; default 20. | +| `offset` | No | Integer 0–10000; default 0. Use the previous page's `nextOffset`. | + +**Authority and scope:** Authenticated conversation member with current gateway access. Live +platform checks protect the requester and reply audience; API/untrusted principals are refused. +Slack currently supplies the metadata/membership provider. Unsupported or offline providers fail +closed. DMs/group DMs never appear as agents; personal skills never contribute. Private targets +cannot appear in public/shared sources. Other results require the complete current source roster +to belong to the target; a real one-to-one bot DM uses the requester's membership. + +**Result:** `agents`, `returned`, `hasMore` and `nextOffset`. Entries include the channel link, +purpose, examples, current shared skill summaries and platform verification time. Summaries +prioritize query matches; `skillsTotal` and `skillsTruncated` identify shortened skill lists. +Pages are bounded to 64 KiB. Continue with the same query and returned offset. + +**Restrictions:** No messages, invitations, delegated runs or file transfers. Cached metadata +narrows search but never authorizes a result. Channel metadata reconciles on startup and nightly +at 03:00 host-local time without an engine turn; platform-purpose keyword updates may wait for +that refresh. Curated profiles and shared skill changes participate immediately. See +[set_channel_agent_profile](/docs/controls/conversation-settings/#set_channel_agent_profile). ## search_channel_memory diff --git a/documentation/src/content/docs/features/skills.md b/documentation/src/content/docs/features/skills.md index a5406ac1..2fd84741 100644 --- a/documentation/src/content/docs/features/skills.md +++ b/documentation/src/content/docs/features/skills.md @@ -35,6 +35,18 @@ Catalog revisions preserve the exact package files and support history and rollb Lean removes optional skill grants. Related: [skill sources](/docs/configuration/skill-sources), [plugins](/docs/features/plugins), and the [complete skills reference](/docs/skills). +## Find an existing specialist agent + +Ask “Which agent can help me create a presentation?” or “List the agents and their skills.” The +gateway guide checks `search_agents` and recommends a relevant channel with its purpose, link and +active shared skills. It continues helping here if preferred; discovery does not send your request +elsewhere. Managers can describe or hide their own channel with `set_channel_agent_profile`. + +The directory protects everyone reading the reply as well as the requester. Private specialists +are not advertised to public/shared channels, and personal skills stay private. Metadata refreshes +nightly at 03:00 host-local time; skill grants resolve at lookup. See the +[directory control reference](/docs/controls/knowledge-and-instructions/#search_agents). + ## Explore the skills handbook - [Discovery and inspection](/docs/features/skill-discovery) From 8dc45f2f6a1242db822181c1fcc6d94c1b1844bc Mon Sep 17 00:00:00 2001 From: Tiberiu Socaci Date: Wed, 21 Oct 2026 19:29:20 +0300 Subject: [PATCH 2/2] test: align packaged skill version with agent discovery update Signed-off-by: Tiberiu Socaci --- test/channelgate-skill.test.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/test/channelgate-skill.test.js b/test/channelgate-skill.test.js index 7f9a01e5..3f595ed2 100644 --- a/test/channelgate-skill.test.js +++ b/test/channelgate-skill.test.js @@ -25,7 +25,7 @@ test("the ChannelGate skill is a valid, fully routed package", async () => { const { data, body } = parseFrontmatter(manifest); assert.equal(data.name, "channelgate"); - assert.equal(data.metadata.version, "3.2.0"); + assert.equal(data.metadata.version, "3.3.0"); assert.match(data.description, /device-login links/); assert.match(data.description, /Do not\s+use for ordinary work/); assert.match(data.description, /server sizing and hosting-provider choice/);