Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

fix(gateway): align ChatGPT tool annotations with behavior (#3525)

rUv3dce4664dda0
diff --git a/plugins/ruflo-x-gateway/.claude-plugin/plugin.json b/plugins/ruflo-x-gateway/.claude-plugin/plugin.json
index 816cddd2c3..9767086590 100644
--- a/plugins/ruflo-x-gateway/.claude-plugin/plugin.json
+++ b/plugins/ruflo-x-gateway/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-x-gateway",
"description": "x.ruv.io gateway service \u2014 an MCP server (Streamable HTTP at /mcp) exposing ruflo swarm FEDERATION and CLAIMS tools over an open, membership-gated, signed Nostr relay (buzz-relay). Tools: federation_identity/join/publish/sync, claims_issue/release/status, channel_list/sync/publish (ADR-386 public + private channels; private content is NIP-44 ciphertext the gateway cannot decrypt). Resources: ruv://federation/registry, ruv://swarm/roster, ruv://claims/board, ruv://swarm/channels. Every coordination message is a signed Nostr event (verifiable authorship); the relay gates membership + NIP-42 auth for security. Deployed to Cloud Run behind x.ruv.io.",
- "version": "0.7.1",
+ "version": "0.7.3",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
diff --git a/plugins/ruflo-x-gateway/annotation-review.md b/plugins/ruflo-x-gateway/annotation-review.md
new file mode 100644
index 0000000000..a1bf90b39f
--- /dev/null
+++ b/plugins/ruflo-x-gateway/annotation-review.md
@@ -0,0 +1,30 @@
+# RuFlo Federation tool annotation review
+
+Endpoint: `https://x.ruv.io/chatgpt/mcp`
+
+All four MCP hints are explicit booleans for every exposed tool. The relay is
+classified as open-world because its channels, resources, publishers, and
+message content are controlled by independent federation members. Membership
+gating and signed events are security controls; they do not make those external
+entities part of one bounded private workspace.
+
+| Tool | Read-only | Destructive | Idempotent | Open-world | Justification |
+| --- | --- | --- | --- | --- | --- |
+| `federation_identity` | true | false | true | false | Returns fixed gateway configuration, changes nothing, is safe to repeat, and contacts no external entity. |
+| `federation_sync` | true | false | true | true | Reads independently published relay messages without modifying them; repeating the read adds no effect. |
+| `claims_status` | true | false | true | true | Reads the reduced claims ledger created by independent members; it neither issues nor releases claims. |
+| `federation_join` | false | true | false | true | Publishes a new signed `PeerHello` to external federation members. The append-only event cannot be retracted, and every retry creates another event. |
+| `federation_publish` | false | true | false | true | Publishes an append-only signed coordination message to external members. It cannot be edited or retracted, and every retry creates another event. |
+| `claims_issue` | false | false | false | true | Creates or extends a temporary claim in a shared external ledger. It is reversible by release or expiry, but a retry creates an event and may extend the TTL. |
+| `claims_release` | false | true | false | true | Removes ownership immediately in a shared external ledger. The prior grant is not restored automatically, and every retry creates another signed event. |
+| `channel_list` | true | false | true | true | Reads channels and publisher activity created by independent members; it does not create, rename, or remove a channel. |
+| `channel_sync` | true | false | true | true | Reads independently published channel messages without editing, decrypting, or removing them; repeating the read adds no effect. |
+| `channel_publish` | false | true | false | true | Publishes an append-only message to a public federation channel. It cannot be deleted or retracted, and every retry creates another event. |
+| `federation_onboarding` | true | false | true | false | Returns static setup guidance, changes nothing, is safe to repeat, and contacts no external entity. |
+| `seraphina_guidance` | false | false | false | true | Calls an external model and consumes metered budget. It does not delete or publish federation state, but every retry spends budget and may return a new answer. |
+
+The legacy `/mcp` endpoint additionally exposes operator-only membership tools.
+Those tools also declare all four hints explicitly: invite minting is
+`false/false/false/false`; direct admission is `false/true/false/true` because it
+grants an arbitrary external key access, has no matching revoke tool, and emits a
+new administrative event on every call.
diff --git a/plugins/ruflo-x-gateway/chatgpt-app-submission.json b/plugins/ruflo-x-gateway/chatgpt-app-submission.json
index 6695f577ea..3e8c5e1624 100644
--- a/plugins/ruflo-x-gateway/chatgpt-app-submission.json
+++ b/plugins/ruflo-x-gateway/chatgpt-app-submission.json
@@ -16,115 +16,115 @@
},
"justifications": {
"read_only_justification": "Only returns the gateway's public identity and relay metadata without changing any state.",
- "open_world_justification": "Reads identity information from the private federation service and does not affect public internet state.",
+ "open_world_justification": "Returns fixed gateway configuration and performs no request to any external entity.",
"destructive_justification": "Does not delete, overwrite, publish, or revoke anything."
}
},
"federation_sync": {
"annotations": {
"readOnlyHint": true,
- "openWorldHint": false,
+ "openWorldHint": true,
"destructiveHint": false
},
"justifications": {
"read_only_justification": "Only retrieves recent verified coordination messages from the federation relay.",
- "open_world_justification": "Reads from the membership-gated federation and does not change public or third-party systems.",
+ "open_world_justification": "Reads messages whose publishers, message types, and content are chosen by independent members of the multi-owner federation relay.",
"destructive_justification": "Does not modify or remove relay messages or federation state."
}
},
"claims_status": {
"annotations": {
"readOnlyHint": true,
- "openWorldHint": false,
+ "openWorldHint": true,
"destructiveHint": false
},
"justifications": {
"read_only_justification": "Only reads current work-claim ownership and expiration status from the relay ledger.",
- "open_world_justification": "Reads bounded claim data from the private federation and does not affect outside systems.",
+ "open_world_justification": "Reads resource identifiers and claim events created by independent members of the multi-owner federation relay.",
"destructive_justification": "Does not issue, extend, release, or otherwise change a work claim."
}
},
"federation_join": {
"annotations": {
"readOnlyHint": false,
- "openWorldHint": false,
+ "openWorldHint": true,
"destructiveHint": true
},
"justifications": {
"read_only_justification": "Publishes a new signed PeerHello event using the gateway identity.",
- "open_world_justification": "Writes only to the membership-gated federation relay rather than a public internet destination.",
+ "open_world_justification": "Publishes to a multi-owner federation relay where independent external members can receive and respond to the event.",
"destructive_justification": "The signed presence event is an irreversible append-only message that cannot be retracted."
}
},
"federation_publish": {
"annotations": {
"readOnlyHint": false,
- "openWorldHint": false,
+ "openWorldHint": true,
"destructiveHint": true
},
"justifications": {
"read_only_justification": "Publishes a new signed coordination event using the gateway identity.",
- "open_world_justification": "Publishes only within the membership-gated federation relay, not to the public internet.",
+ "open_world_justification": "Publishes to a multi-owner federation relay where independent external members can receive and act on the message.",
"destructive_justification": "The signed coordination message is append-only and cannot be edited or retracted after publication."
}
},
"claims_issue": {
"annotations": {
"readOnlyHint": false,
- "openWorldHint": false,
+ "openWorldHint": true,
"destructiveHint": false
},
"justifications": {
"read_only_justification": "Creates or extends a gateway-owned work claim on the federation ledger.",
- "open_world_justification": "Changes only bounded claim state inside the membership-gated federation.",
+ "open_world_justification": "Creates or extends a claim for a caller-selected resource identifier in a ledger shared with independent federation members.",
"destructive_justification": "Reserves a resource temporarily and the claim can be released or allowed to expire."
}
},
"claims_release": {
"annotations": {
"readOnlyHint": false,
- "openWorldHint": false,
+ "openWorldHint": true,
"destructiveHint": true
},
"justifications": {
"read_only_justification": "Removes a gateway-owned work claim from the federation ledger.",
- "open_world_justification": "Changes only bounded claim state inside the membership-gated federation.",
+ "open_world_justification": "Releases a claim in a ledger shared with independent federation members, allowing another member to claim the resource.",
"destructive_justification": "Releases ownership immediately so another agent can claim the resource, and the prior grant is not restored automatically."
}
},
"channel_list": {
"annotations": {
"readOnlyHint": true,
- "openWorldHint": false,
+ "openWorldHint": true,
"destructiveHint": false
},
"justifications": {
"read_only_justification": "Only lists discovered and configured federation channels without changing them.",
- "open_world_justification": "Reads a bounded directory from the federation service and does not affect public systems.",
+ "open_world_justification": "Discovers channels and publisher activity created by independent members of the multi-owner federation relay.",
"destructive_justification": "Does not create, rename, publish to, or remove channels."
}
},
"channel_sync": {
"annotations": {
"readOnlyHint": true,
- "openWorldHint": false,
+ "openWorldHint": true,
"destructiveHint": false
},
"justifications": {
"read_only_justification": "Only retrieves recent messages for a selected federation channel.",
- "open_world_justification": "Reads channel data from the bounded federation service and does not change outside systems.",
+ "open_world_justification": "Reads messages whose publishers and content are controlled by independent members of the selected federation channel.",
"destructive_justification": "Does not publish, edit, decrypt, or remove channel messages."
}
},
"channel_publish": {
"annotations": {
"readOnlyHint": false,
- "openWorldHint": false,
+ "openWorldHint": true,
"destructiveHint": true
},
"justifications": {
"read_only_justification": "Publishes a new signed message to a public federation channel using the gateway identity.",
- "open_world_justification": "Writes only to a federation-controlled public channel rather than a general public internet service.",
+ "open_world_justification": "Publishes to a public federation channel visible to independent external members of the multi-owner relay.",
"destructive_justification": "The channel message is append-only and cannot be deleted or retracted after publication."
}
},
diff --git a/plugins/ruflo-x-gateway/package.json b/plugins/ruflo-x-gateway/package.json
index e1fd1086c8..8d2ffed431 100644
--- a/plugins/ruflo-x-gateway/package.json
+++ b/plugins/ruflo-x-gateway/package.json
@@ -1,6 +1,6 @@
{
"name": "@ruflo/x-gateway",
- "version": "0.7.2",
+ "version": "0.7.3",
"private": true,
"type": "module",
"description": "x.ruv.io gateway β€” MCP server for ruflo swarm federation + claims over a signed, membership-gated Nostr relay. Exposes /mcp tools and ruv:// resources.",
diff --git a/plugins/ruflo-x-gateway/src/server.mjs b/plugins/ruflo-x-gateway/src/server.mjs
index e4ea86d14a..a08f9c806a 100644
--- a/plugins/ruflo-x-gateway/src/server.mjs
+++ b/plugins/ruflo-x-gateway/src/server.mjs
@@ -161,9 +161,12 @@ export function createGateway({ relay, keyFile, port } = {}) {
// These are HINTS and the spec says a client MUST NOT trust them for security.
// They change how a tool is PRESENTED, never what it is allowed to do: the
// `gated()` admin check below is the enforcement and is untouched.
- const READ = (title) => ({ title, readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false });
- // Every write here lands on our own membership-gated relay, so openWorld stays
- // false unless a tool genuinely reaches an open-ended external service.
+ const READ = (title, { openWorld = false } = {}) =>
+ ({ title, readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: openWorld });
+ // `openWorldHint` describes the entities a tool can interact with, not who
+ // operates the transport. The federation relay is multi-owner: other members
+ // choose channels, resource ids and message content. Relay reads and writes
+ // are therefore open-world even though membership and signing are enforced.
const WRITE = (title, { destructive = false, idempotent = false, openWorld = false } = {}) =>
({ title, readOnlyHint: false, destructiveHint: destructive, idempotentHint: idempotent, openWorldHint: openWorld });
@@ -183,10 +186,10 @@ export function createGateway({ relay, keyFile, port } = {}) {
mcp.tool('federation_identity', 'Gateway Nostr pubkey + relay. Open read.', {}, READ('Gateway identity'), async () => text({ pubkey, relay: RELAY, httpBase: HTTP_BASE }));
mcp.tool('federation_sync', 'Fetch recent verified swarm coordination messages (#t=ruflo-swarm). Open read; optional type filter.',
{ sinceSeconds: z.number().optional(), limit: z.number().optional(), type: z.string().optional() },
- READ('Read swarm messages'),
+ READ('Read swarm messages', { openWorld: true }),
async (a) => { const msgs = await fetchRecent(RELAY, sk, a); return relayText({ count: msgs.length, messages: msgs }); });
mcp.tool('claims_status', 'Current owner-per-resource claims ledger from recent verified claim events. Open read.', {},
- READ('Read claims ledger'),
+ READ('Read claims ledger', { openWorld: true }),
// The claims ledger is derived from relay events, and every resourceId in it
// is a string a third party chose. Same surface, same envelope.
async () => { const ev = await fetchRecent(RELAY, sk, { sinceSeconds: 86400, limit: 500 }); return relayText(reduceClaims(ev.filter((e) => String(e.type).startsWith('Claim')))); });
@@ -196,26 +199,26 @@ export function createGateway({ relay, keyFile, port } = {}) {
// Appends a PeerHello event that cannot be retracted. Under Apps SDK
// review semantics, an irreversible send is destructive even though it
// adds rather than deletes state. Each call is also a NEW event.
- WRITE('Announce gateway peer', { destructive: true }),
+ WRITE('Announce gateway peer', { destructive: true, openWorld: true }),
gate(async ({ name, platform, note }) => text({ ok: true, eventId: await publish(RELAY, sk, 'PeerHello', { from: name, platform, note }) })));
mcp.tool('federation_publish', 'Publish a signed coordination message AS THE GATEWAY (Status/Task/Result…). Authorised by OAuth swarm:publish or the service-side admin token.',
{ msgType: z.string(), payload: z.record(z.any()), ...adminSchema },
// A signed relay message is an irreversible external send: it cannot be
// edited or retracted after publication.
- WRITE('Publish coordination message', { destructive: true }),
+ WRITE('Publish coordination message', { destructive: true, openWorld: true }),
gate(async ({ msgType, payload }) => text({ ok: true, eventId: await publish(RELAY, sk, msgType, payload) })));
mcp.tool('claims_issue', 'Issue a work claim AS THE GATEWAY. Authorised by OAuth swarm:publish or the service-side admin token. One owner per resourceId.',
{ resourceId: z.string(), ttlSeconds: z.number().optional(), ...adminSchema },
// Not idempotent: re-issuing the same claim extends its TTL, which is a real
// additional effect even though the owner does not change.
- WRITE('Issue work claim'),
+ WRITE('Issue work claim', { openWorld: true }),
gate(async ({ resourceId, ttlSeconds }) => text({ ok: true, eventId: await publish(RELAY, sk, 'ClaimIssued', { from: pubkey, resourceId, ttlSeconds }), resourceId })));
mcp.tool('claims_release', 'Release a gateway-held work claim. Authorised by OAuth swarm:publish or the service-side admin token.',
{ resourceId: z.string(), ...adminSchema },
- // The one genuinely destructive tool here: it REMOVES an ownership grant
- // rather than adding one, and another agent can take the resource the
- // moment it lands. Releasing twice changes nothing, so it is idempotent.
- WRITE('Release work claim', { destructive: true, idempotent: true }),
+ // This removes an ownership grant and appends an externally visible event.
+ // Retrying creates another signed event, so the operation is not
+ // idempotent even when the reduced claims board is already released.
+ WRITE('Release work claim', { destructive: true, openWorld: true }),
gate(async ({ resourceId }) => text({ ok: true, eventId: await publish(RELAY, sk, 'ClaimReleased', { from: pubkey, resourceId }), resourceId })));
// ---- relay MEMBERSHIP administration β€” legacy endpoint only ----
//
@@ -234,20 +237,20 @@ export function createGateway({ relay, keyFile, port } = {}) {
adminOnly(async ({ ttlSecs, maxUses }) => text(await mintInvite(HTTP_BASE, sk, { ttlSecs, maxUses }))));
mcp.tool('federation_admit', 'Admit a pubkey as a relay member directly (NIP-43 kind 9030). Requires the admin token; OAuth swarm:publish is not sufficient.',
{ pubkey: z.string(), role: z.enum(['member', 'admin']).optional(), ...adminSchema },
- // Additive grant, and admitting the same pubkey at the same role twice
- // leaves the roster identical β€” idempotent.
- WRITE('Admit relay member', { idempotent: true }),
+ // This grants an arbitrary external key relay access and there is no
+ // matching revoke tool. Each call also publishes a new admin event.
+ WRITE('Admit relay member', { destructive: true, openWorld: true }),
adminOnly(async ({ pubkey: pk, role }) => text(await admitMember(RELAY, sk, pk, role))));
}
// ---- ADR-386 channels ----
mcp.tool('channel_list', 'List swarm channels seen recently, with visibility, message count and publisher count. Open read. Public channel ids carry their name (pub:<name>); private ids are opaque (prv:<hex>) and reveal nothing about the topic. Well-known channels (pub:announce, pub:help, pub:claims, pub:showcase) are always listed even when quiet, with messages:0 and a purpose β€” a channel nobody posted in today is otherwise undiscoverable, which is how it stays empty. Use when you want to find where coordination is happening before reading a stream. Reading the flat firehose with federation_sync instead is wrong once channels are in use, because it mixes unrelated work and cannot show you private traffic exists at all.',
{ sinceSeconds: z.number().optional(), limit: z.number().optional() },
- READ('List swarm channels'),
+ READ('List swarm channels', { openWorld: true }),
// Public channel ids carry their name, and members choose those names.
async (a) => relayText({ channels: await listChannels(RELAY, sk, a) }));
mcp.tool('channel_sync', 'Read one channel. Open read. A public channel returns parsed JSON messages. A PRIVATE channel returns NIP-44 ciphertext verbatim with encrypted:true β€” the gateway holds no channel keys and cannot decrypt, by design (ADR-386); open it client-side with `ruflo federation channel read`. Use when you know the channel id. Asking the gateway to decrypt is wrong because a gateway that could would be a custodian of every private channel on the service.',
{ channel: z.string().describe('Channel id: pub:<name> or prv:<16 hex>'), sinceSeconds: z.number().optional(), limit: z.number().optional() },
- READ('Read a channel'),
+ READ('Read a channel', { openWorld: true }),
async ({ channel, sinceSeconds, limit }) => {
if (!CHANNEL_ID_RE.test(String(channel))) throw new Error('channel must be pub:<name> or prv:<16 hex>');
const messages = await fetchChannel(RELAY, sk, { channelId: channel, sinceSeconds, limit });
@@ -262,7 +265,7 @@ export function createGateway({ relay, keyFile, port } = {}) {
{ channel: z.string(), msgType: z.string(), payload: z.record(z.any()), ...adminSchema },
// Public-channel events are append-only and cannot be deleted or
// retracted, so publication is destructive for review purposes.
- WRITE('Publish to public channel', { destructive: true }),
+ WRITE('Publish to public channel', { destructive: true, openWorld: true }),
gate(async ({ channel, msgType, payload }) => {
// Refuse private BEFORE normalising, so a prv: id gets the real reason rather
// than a name-validation error from the public-id helper.
@@ -292,8 +295,7 @@ export function createGateway({ relay, keyFile, port } = {}) {
// an IP-hourly allowance, and spends real meta-llm money. readOnlyHint:true
// tells a client the call is free to repeat, which for this tool is false.
// openWorld is true because the answer comes from an external model whose
- // output is not drawn from any closed set this gateway owns β€” unlike every
- // other tool here, which only ever reads or writes our own relay.
+ // output is not drawn from a closed set this gateway owns.
WRITE('Ask Seraphina for guidance', { openWorld: true }),
(async ({ goal, tier, sinceSeconds, limit, adminToken }) => {
// Review profile: the credential arrives as a header, never an argument.
diff --git a/plugins/ruflo-x-gateway/test-cases.md b/plugins/ruflo-x-gateway/test-cases.md
index 4b7609a775..6767ff931b 100644
--- a/plugins/ruflo-x-gateway/test-cases.md
+++ b/plugins/ruflo-x-gateway/test-cases.md
@@ -52,9 +52,12 @@ curl -s -X POST https://x.ruv.io/chatgpt/mcp \
**Pass:** exactly **12** tools. Every one carries an `annotations` object with
`readOnlyHint`, `destructiveHint`, `idempotentHint` and `openWorldHint` all
-present as explicit booleans. Six are read-only. Exactly one β€” `claims_release` β€”
-is marked `destructiveHint: true`. Exactly one β€” `seraphina_guidance` β€” is marked
-`openWorldHint: true`.
+present as explicit booleans. Six are read-only. Four β€” `federation_join`,
+`federation_publish`, `claims_release`, and `channel_publish` β€” are destructive
+because their append-only external effects cannot be retracted (and claim release
+removes ownership). Ten are open-world: every tool that reads or writes the
+multi-owner federation relay, plus `seraphina_guidance`. Only
+`federation_identity` and `federation_onboarding` are closed-world.
**Also verify:** the string `adminToken` appears nowhere in the response, and no
tool declares any input property whose name suggests a secret.
diff --git a/plugins/ruflo-x-gateway/test/gateway.test.mjs b/plugins/ruflo-x-gateway/test/gateway.test.mjs
index ac9bb06d5d..a1fd475101 100644
--- a/plugins/ruflo-x-gateway/test/gateway.test.mjs
+++ b/plugins/ruflo-x-gateway/test/gateway.test.mjs
@@ -451,23 +451,25 @@ test('onboarding: exposed as an open tool and an open resource', async () => {
/** Expected hints per tool. Grouped by class, stated exhaustively. */
const EXPECTED_ANNOTATIONS = {
- // Reads: closed world, no mutation, safe to repeat.
+ // Local/static reads are closed world; relay reads are open world because
+ // other federation members choose the entities and content returned.
federation_identity: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
- federation_sync: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
- claims_status: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
- channel_list: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
- channel_sync: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+ federation_sync: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+ claims_status: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+ channel_list: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+ channel_sync: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
federation_onboarding: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
- // Irreversible sends: these append signed events that cannot be retracted.
- federation_join: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
- federation_publish: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
- channel_publish: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
- claims_issue: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+ // Relay writes affect a multi-owner external federation. Append-only sends
+ // that cannot be retracted are also destructive.
+ federation_join: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+ federation_publish: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+ channel_publish: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+ claims_issue: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
federation_invite_mint: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
- // Additive but idempotent: same pubkey + role leaves the roster identical.
- federation_admit: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
- // Destructive: removes an ownership grant. Releasing twice is a no-op.
- claims_release: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+ // Grants an arbitrary external key access, with no matching revoke tool.
+ federation_admit: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+ // Removes a grant; every retry appends a distinct signed event.
+ claims_release: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
// Open world: answers come from an external model, and each call spends budget.
seraphina_guidance: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
};
@@ -547,11 +549,22 @@ test('annotations: destructiveHint marks removals and irreversible external send
// Blanket-setting destructive is exactly as misleading as omitting it.
assert.deepEqual(
tools.filter((t) => t.annotations.destructiveHint).map((t) => t.name),
- ['federation_join', 'federation_publish', 'claims_release', 'channel_publish'],
+ ['federation_join', 'federation_publish', 'claims_release', 'federation_admit', 'channel_publish'],
'destructive tools must include claim removal and append-only sends that cannot be retracted',
);
});
+test('annotations: openWorldHint marks the multi-owner relay and external model', async () => {
+ const tools = await listToolsOverHttp();
+ assert.deepEqual(
+ tools.filter((t) => t.annotations.openWorldHint).map((t) => t.name),
+ ['federation_sync', 'claims_status', 'federation_join', 'federation_publish',
+ 'claims_issue', 'claims_release', 'federation_admit', 'channel_list',
+ 'channel_sync', 'channel_publish', 'seraphina_guidance'],
+ 'only fixed local metadata, static guidance, and local invite minting are closed world',
+ );
+});
+
// ─── /chatgpt/mcp β€” the isolated public-review profile ───
//
// An OpenAI app review forbids a tool that accepts a secret as an argument, and
@@ -655,7 +668,7 @@ test('review endpoint: no tool accepts a secret in any input field', async () =>
gw.close();
});
-test('review endpoint: every tool declares the three required hints', async () => {
+test('review endpoint: every tool declares all four hints', async () => {
process.env.RUFLO_ADMIN_TOKEN = 'test-admin-token';
const gw = await startGateway();
for (const t of await toolsAt(gw.base, '/chatgpt/mcp')) {
@@ -667,6 +680,25 @@ test('review endpoint: every tool declares the three required hints', async () =
gw.close();
});
+test('review endpoint: submission annotations and justifications match the live surface', async () => {
+ process.env.RUFLO_ADMIN_TOKEN = 'test-admin-token';
+ const gw = await startGateway();
+ const review = await toolsAt(gw.base, '/chatgpt/mcp');
+ const submission = JSON.parse(readFileSync(new URL('../chatgpt-app-submission.json', import.meta.url), 'utf8'));
+ assert.deepEqual(Object.keys(submission.tools).sort(), review.map((t) => t.name).sort());
+ for (const tool of review) {
+ const declared = submission.tools[tool.name];
+ for (const hint of ['readOnlyHint', 'destructiveHint', 'openWorldHint']) {
+ assert.equal(typeof declared.annotations[hint], 'boolean', `${tool.name}.${hint} is not explicit in the submission`);
+ assert.equal(declared.annotations[hint], tool.annotations[hint], `${tool.name}.${hint} differs between submission and server`);
+ }
+ for (const key of ['read_only_justification', 'destructive_justification', 'open_world_justification']) {
+ assert.ok(declared.justifications[key]?.trim(), `${tool.name}.${key} is missing`);
+ }
+ }
+ gw.close();
+});
+
test('review endpoint: dropping the argument did NOT drop the gate', async () => {
// The whole change is "move the credential to a header". If that had turned a
// gated write into an open one, this is where it shows up. Removing a field