feat: shared curator AI-model access (opt-in, membership-gated)

[Zigoljube]

Shared curator AI-model access (MVP)

Let a context-graph (CG) curator optionally share access to the AI model they
already run — in the same flow as inviting an agent to the CG's shared working
memory. Members send prompts to the curator's model over the DKG P2P substrate
and get completions back. The curator's API key never leaves the curator's
node.

Additive and default-off: nothing is shared unless a curator explicitly turns
it on per CG. No genesis/ontology change — the grant predicates are written to the
CG _meta graph locally, so the network/genesis hash is untouched.

Design

• Membership = the invite you already sent. Authorization reuses the
  delegatee-peer binding written to _meta at invite/join time
  (allowedDelegateePeer / delegationDelegateePeer). No new identity system,
  no separate recipient-acceptance step — approved members inherit access.
• Key isolation. Members only ever send prompts and receive completions; the
  API key stays on the curator's node.
• Grant lives in _meta as two triples (sharedModelEnabled,
  sharedModelId) and syncs to members the same way the rest of _meta does.
• Reuses the model the curator already configures (config.llm);
  config.sharedModel can scope/override it. A built-in mock provider supports
  offline testing.

What's included

Commit	What
feat(agent)	SharedModelMethods mixin: per-CG grant in _meta, provider client (mock + openai-compatible), per-member daily quota, membership gate, P2P verb /dkg/10.0.2/shared-model-invoke
feat(cli)	daemon routes (model/share, model/grant, model/invoke, invite-with-model) + sharedModel config wiring
feat(node-ui)	"AI Model Access" toggle in the Share Project modal (curator opt-in)
feat(cli,agent)	OpenAI-compatible endpoint …/model/v1/chat/completions so any OpenAI client points at the curator's model
docs(agent)	feature README incl. member-usage roadmap + the cross-device findings below

Member-usage spectrum

This PR ships #1 raw invoke and #2 OpenAI-compatible endpoint. #3 a
node-UI model picker is the next follow-up; #4 tool/skill use is covered by
#2 (any OpenAI-speaking agent uses it as its backend); #5 metering/payment is
intentionally deferred (needs a real settlement mechanism — x402 / PCA — and is
its own RFC + PR). Full table in packages/agent/src/shared-model/README.md.

API surface

Method & path	Purpose
POST …/invite-with-model	invite a member and (optionally) share the model in one call
POST …/model/share	curator toggles sharing for a CG
GET …/model/grant	read the grant { enabled, modelId }
POST …/model/invoke	member invokes (native shape)
POST …/model/v1/chat/completions	OpenAI-compatible member usage

Testing & findings

Validated:

• Unit — shared-model suite (mock provider, authorize gate, daily quota,
  wire round-trip, OpenAI request/response mapping): 10/10.
• Build — pnpm --filter @origintrail-official/dkg-agent build green;
  build:runtime ships a dist-ui carrying the curator toggle.
• Live single-node — curator-local invoke returns a completion.
• Live two-node (separate nodes, stable link) — a member node (own peer id +
  agent) joins a private CG, the curator approves, the authenticated
  post-approval _meta sync lands the grant on the first poll, and
  …/model/invoke returns
  {"ok":true,"content":"[shared-model:mock-model] …","model":"mock-model"} —
  exercising the full P2P path (resolve curator peer →
  /dkg/10.0.2/shared-model-invoke → membership gate → model → completion).

In progress: a different-country (NAT'd, relayed) member run. The feature
itself works whenever _meta is present; the remaining work is purely the
cross-NAT _meta bootstrap, which is upstream sync behavior (below).

Upstream _meta-sync issues this surfaced (not introduced by this PR)

The grant is two triples in the curated CG's _meta and can only reach a member
through the existing curated-CG sync. Cross-NAT first-sync exposed:

1. Bootstrap auth deadlock. An authenticated private meta-sync request needs
   the curator peer id as targetPeerId, resolved from the member's local
   _meta — the thing it's fetching. Only the join-approved-triggered
   runImmediatePostApprovalSync breaks it (it's handed the curator peer id);
   background/subscribe catchup sends an unauthenticated request that a private
   CG rejects (phase=meta, request-authorize.ts).
2. synced-flag poison. POST …/subscribe marks the CG synced:true even
   when _meta was denied; buildSyncRequest (dkg-agent-cg-resolve.ts) then
   derives needsAuth from synced, not metaSynced, so every later
   meta-sync — including the authenticated post-approval one — is sent
   unauthenticated and permanently denied (recoverable only by restart, since
   subscribedContextGraphs is in-memory).
   Suggested fix: gate needsAuth on metaSynced for private CGs, and/or
   don't set synced until _meta lands.
3. A re-fired already-member join-approved is dropped by the requester's
   trusted-sender guard after a restart (no local curator triple, no in-memory
   pending record), so re-joining an existing membership doesn't re-trigger the
   sync — a fresh, genuine pending join does.

These are independent of this feature (they affect any curated-CG member), but
the grant rides on that sync, so they're documented here and worth a separate
upstream fix.

Known limitations (MVP)

• Quotas/grant are node-local and in-memory (reset on restart) — no on-chain
  accounting or payment; monetization is a follow-up.
• No streaming; single completion per request; no tool-calls forwarded.
• Cross-NAT first-sync of the grant depends on the upstream _meta sync above;
  reliable procedure documented in the feature README.

🤖 Generated with Claude Code

[github-actions]

🔴 Bug: This membership check authorizes any peer that appears in any allowedDelegateePeer or delegationDelegateePeer triple in the graph. Pending join requests already persist delegationDelegateePeer, so a requester can invoke the shared model before approval, and on multi-agent nodes any other agent behind an approved peer inherits access. Bind the invoke request to a specific agent address and validate only that agent's approved delegation/allowlist rows, like the sync auth path does.

[github-actions]

🔴 Bug: The local fast-path is keyed only on whether this node curates the context graph, then hard-codes isMember: true. On a multi-agent node that lets any local agent token bypass membership checks, and it also misses CGs curated by a non-default local agent because isContextGraphCuratorSelf() only recognizes the default agent + peer ID. This branch needs caller-specific ownership/member resolution instead of a node-wide shortcut.

[github-actions]

🔴 Bug: quota.allow() mutates the daily counter before authorization succeeds. Requests denied for other reasons (sharing disabled, non-member, oversized prompt, provider misconfigured, etc.) still burn quota, so a member can be rate-limited without ever receiving a completion. Compute the other gates first and increment the bucket only once the request is actually allowed.

[github-actions]

🟡 Issue: This trusts body.messages as SharedModelMessage[] after only checking that it's a non-empty array. Payloads like [{"role":"user"}] or [{"content":1}] will fall through and then throw inside invokeContextGraphModel() when it reads m.content.length, turning a client error into a 500. Validate each message shape here (or reuse the wire/OpenAI validators) and return 400 for malformed bodies.

[github-actions]

🟡 Issue: invite-with-model applies the invite before attempting to enable model sharing. If setContextGraphModelSharing() fails, the handler returns 400 even though membership was already granted, so callers retry against partially-applied state. Either make the operation transactional/compensating, or return an explicit partial-success response instead of treating it as a full failure.

[TomazOT]

Really like the shape of this. Reusing the invite/_meta delegatee-peer binding for auth instead of inventing a new identity layer, keeping the API key node-local, and making it owner-gated and default-off are all the right calls, and the pure decideSharedModelAuthorization + mock provider make it easy to reason about and test.

A few small things worth tightening while it's still MVP, in rough priority:

1. contextGraphId reaches SPARQL before the membership gate. In handleSharedModelInvoke, req.contextGraphId comes straight off the wire (decodeInvokeRequest validates message shape but not the id), then flows through contextGraphMetaGraphUri / contextGraphDataGraphUri into the interpolated queries in getContextGraphModelGrant and isPeerContextGraphMember, both of which run on the caller-supplied id before membership is confirmed. If those builders don't already assertSafeIri the id, a peer could inject SPARQL against the curator's store pre-auth. Could you confirm they sanitize, or add an id-charset check in decodeInvokeRequest? Cheap belt-and-suspenders either way.
2. No timeout on the provider call. openAiCompatibleComplete uses a bare fetch with no AbortController, so a slow upstream can pin the curator's handler (and the member's sendReliable) open. A timeout bounds the failure mode.
3. Clamp maxTokens. Full token metering is clearly a follow-up (the usage: {0,0,0} note), but a simple clamp to a configured ceiling is a cheap interim guard against a single oversized request driving cost/latency.
4. Minor: quota.allow(fromPeerId) is evaluated before decideSharedModelAuthorization, so a request denied for another reason still spends a quota slot. Moving the consume to after the other checks pass keeps the counter honest.

Post-MVP (tracking, not blockers for this PR)

• Token metering. Bound spend by tokens rather than request count, make the counter durable across restarts (it's in-memory today, so the bound resets on restart), and fill in the usage block so OpenAI clients get real accounting. This is the proper version of the maxTokens clamp above.
• Per-invocation audit trail. For a curator lending their key, a record of who invoked, when, and at what token cost is what makes abuse detectable and usage accountable.
• Separate scoped key by default. sharedModel reusing llm.apiKey means enabling sharing points the curator's personal key at the group. Defaulting to a dedicated key (fail closed if unset) shrinks the blast radius.
• Abuse/liability posture. The curator runs members' prompts on their own provider account, so a jailbreak or ToS-tripping prompt lands under the curator's account. Worth a per-member disable and a docs note making the trust assumption explicit.
• Revocation coverage. A quick regression test confirming that removing a member from the CG actually cuts model access (the delegatee-peer binding is removed and propagates), since access is only as revocable as that binding.

[github-actions]

🔴 Bug: inviteAgentToContextGraph() only writes the bare allowlist entry here; it does not create the allowedDelegateePeer delegation that handleSharedModelInvoke() uses to authorize remote callers. That means invite-with-model can return modelShared: true, but the invited member will still be denied when invoking from another node. This flow needs to require a signed join delegation (or otherwise persist the delegatee peer binding), or it should not advertise that model access was granted.

[github-actions]

🔴 Bug: the remote quota bucket is keyed by fromPeerId, but the public contract/config is explicitly per agent (dailyRequestQuotaPerAgent) and the local fast-path keys by caller agent address. On a multi-agent member node, one approved agent can exhaust the quota for every other agent sharing that peer. Key the quota off the normalized req.agentAddress after authorization succeeds, or rename the API/config/docs if per-peer throttling is actually intended.

[github-actions]

🟡 Issue: malformed JSON on POST /model/share will currently escape as an unhandled exception because the JSON.parse(await readBody(...)) happens outside the try. The other new shared-model routes already normalize this to a 400; this one should catch parse/read errors too so a bad body does not surface as a 500.

[github-actions]

🔴 Bug: invite-with-model currently calls inviteAgentToContextGraph() without a signed delegation, but handleSharedModelInvoke() authorizes remote members only through getContextGraphAllowedDelegateePeers(). The result is a false-success path: this endpoint can return modelShared:true even though an invited member on another node can never invoke the shared model. Either require/promote a join delegation here, or broaden the runtime gate so the invite path actually grants usable access.

[github-actions]

🔴 Bug: callerAgentAddress is optional here, but both auth paths reject an omitted caller (isCallerLocalCgMember() returns false, and the remote path sends no agentAddress, which handleSharedModelInvoke() denies). That breaks the new exported SDK surface and the README example invokeContextGraphModel(cg, messages): callers have to discover and pass a hidden fourth argument or every invoke is denied. Either derive the default/current agent address here before authorizing, or make the parameter required and update the public API/docs.

[github-actions]

🔴 Bug: the quota bucket is keyed by fromPeerId, not by the authorized agentAddress, even though the feature and config are explicitly per-agent (dailyRequestQuotaPerAgent) and membership is now checked per claimed agent. On a multi-agent node, two approved agents sharing one peer will burn each other's quota on the remote path. Use the validated agent address (or an (agent,peer) tuple if you need both) as the quota key.

[github-actions]

🔴 Bug: this JSON.parse(await readBody(...)) happens outside the try, so a malformed POST /model/share body escapes as a 500 instead of the 400 that the other new shared-model routes return. Wrap the body read/parse in the same validation branch used below before destructuring enabled/modelId.