@rine-network/eve 0.3.0 → 0.5.0

package/dist/tools/groups-admin.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The 5 admission + membership-exit group tool factories:
+ * `rine_group_requests`, `rine_group_vote`, `rine_group_leave`,
+ * `rine_group_sync`, `rine_group_reclaim`.
+ *
+ * Split from `tools/groups.ts` (which holds the six create/invite/inspect/join
+ * factories) so both files stay inside the ~200-LOC budget. Same idiom: one
+ * exported factory per tool, the SDK does the work, the tool renders.
+ *
+ * `rine_group_leave` is a distinct verb rather than a mode of
+ * `rine_group_remove`, which keeps its own "name your own agent to leave"
+ * behaviour: a leave destroys THIS host's key material, a removal acts on a
+ * third party, and one wrong argument should not turn one into the other.
+ */
+import { type RineToolOpts } from "../tool.js";
+/** `rine_group_requests` — list a group's outstanding admissions. */
+export declare function rineGroupRequestsTool(opts?: RineToolOpts): import("eve/tools").ToolDefinition<any, any>;
+/** `rine_group_vote` — approve or deny one pending join request. */
+export declare function rineGroupVoteTool(opts?: RineToolOpts): import("eve/tools").ToolDefinition<any, any>;
+/** `rine_group_leave` — leave a group this agent is a member of. */
+export declare function rineGroupLeaveTool(opts?: RineToolOpts): import("eve/tools").ToolDefinition<any, any>;
+/** `rine_group_sync` — catch this host's MLS state up with the group. */
+export declare function rineGroupSyncTool(opts?: RineToolOpts): import("eve/tools").ToolDefinition<any, any>;
+/** `rine_group_reclaim` — seat the unseated, then retire the orphaned leaves. */
+export declare function rineGroupReclaimTool(opts?: RineToolOpts): import("eve/tools").ToolDefinition<any, any>;

package/dist/tools/groups-admission.d.ts

@@ -0,0 +1,56 @@
+/**
+ * What an admission did, rendered for a model.
+ *
+ * A roster on `rine_group_create`, a batch on `rine_group_invite` and a single
+ * `agentToInvite` are the same operation at three entry points, so they answer
+ * in the same vocabulary. The two plural ones report one outcome per requested
+ * agent, in the order they were named: a batch never fails whole — naming 32
+ * agents and having one of them revoked costs that one agent its seat, not the
+ * other 31 theirs — which is only useful if the caller is told which one.
+ *
+ * Two reports, deliberately not merged. The server's says whether an
+ * **invitation** was minted; the MLS one says whether a ratchet-tree **leaf**
+ * was. An agent can be `invited` in the first and `no_key_package` in the
+ * second: it may join, and it will not be able to read a word until a leaf
+ * exists for it. Collapsing them into one number is how that goes unreported.
+ *
+ * On a `majority` or `unanimity` group the server's answer is `nominated`
+ * rather than `invited`: the invite files a join request the electorate
+ * decides, and no leaf is minted for it. So a nomination has no MLS report at
+ * all — the vote seats the member, and seating is what grants the key.
+ *
+ * The shapes and the reason→sentence maps are `@rine-network/core`'s, so this
+ * module is the rendering and nothing else. A skip used to print the raw wire
+ * token, which read as a refusal on exactly the groups it is not one for: an
+ * open group mints no invitation because it needs none, and `not_applicable`
+ * said nothing about that to a model deciding what to do next.
+ */
+import { type GroupAdmissionReport, type MlsAdmissionResult } from "@rine-network/core";
+/** The refusal when a caller names both invite targets, or neither. */
+export declare const INVITE_TARGET_REQUIRED = "Name exactly one of agentToInvite (one invitation) or agentsToInvite (a batch).";
+/**
+ * What one `agentToInvite` produced, told from the row's own status.
+ *
+ * The singular route answers one row rather than a per-agent report, so the
+ * status word is all a caller has to go on — and `Invited X (status pending)`
+ * both claims something that did not happen and hands a model a word no other
+ * outcome of this tool uses. `invited` and `pending` are therefore named, and
+ * any other status still prints itself rather than being read as one of them.
+ *
+ * `invited` covers two shapes and the sentence names both. A closed group mints
+ * a real invitation row that occupies a ratchet-tree seat until it is accepted
+ * or expires; an open group answers `invited` having minted nothing at all,
+ * because nobody needs an invitation to join one — and it runs sender keys, so
+ * there is no ratchet tree for a seat to sit in.
+ */
+export declare function renderSingularInvite(agentRef: string, groupRef: string, status: string): string;
+/** Per-agent invitation outcomes, one line each, in the order they were named. */
+export declare function renderAdmission(report: GroupAdmissionReport): string;
+/**
+ * What the MLS admission seated, and who is still without a leaf.
+ *
+ * `already_in_group` is filtered out of the unseated list: an agent that
+ * already holds a leaf is what a resumed admission looks like when it has
+ * nothing left to do, not a failure to report.
+ */
+export declare function renderMlsAdmission(mls: MlsAdmissionResult): string;

package/dist/tools/groups-list.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The group domain's three READ verbs: `rine_groups` (the groups this agent's
+ * ORG belongs to), `rine_discover_groups` (the public directory) and
+ * `rine_group_roster` (who is in one group).
+ *
+ * A third group module beside `groups.ts` (the six founding/admission verbs)
+ * and `groups-admin.ts` (the five admission and exit verbs), so all three hold
+ * the ~200-LOC budget.
+ *
+ * Nothing here mutates anything, so none of them carries an approval gate.
+ * `rine_discover_groups` reads the public directory and needs no membership at
+ * all — it answers for `public`-visibility groups across every org, and returns
+ * no roster for any of them.
+ */
+import { type RineToolOpts } from "../tool.js";
+/** `rine_groups` — the groups this agent's ORG belongs to. */
+export declare function rineGroupsTool(opts?: RineToolOpts): import("eve/tools").ToolDefinition<any, any>;
+/** `rine_discover_groups` — search the public group directory. */
+export declare function rineDiscoverGroupsTool(opts?: RineToolOpts): import("eve/tools").ToolDefinition<any, any>;
+/** `rine_group_roster` — who is in one group, and since when. */
+export declare function rineGroupRosterTool(opts?: RineToolOpts): import("eve/tools").ToolDefinition<any, any>;

package/dist/tools/groups-resolve.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Handle → UUID resolution for the group tools.
+ *
+ * What is left here is the AGENT half. The group half moved out entirely: the
+ * SDK's `groups.resolveRef` is now the one ladder for a group reference, and
+ * it answers with the group's whole record — id, handle, the caller's own
+ * spelling, and the row the resolve already read — so a verb that reads the
+ * group before it writes spends no `GET /groups/{id}` of its own. This package
+ * used to search `groups.list()` and match locally, which is a second copy of a
+ * ladder the SDK, the CLI and the MCP server all reach through one function; a
+ * refusal that differed per surface is what that copy was.
+ *
+ * Agents still resolve here, and differently on purpose: `resolveToUuid` is a
+ * WebFinger lookup, so an agent that this org has never messaged resolves too.
+ *
+ * `join` is the exception and does NOT resolve through `resolveRef`: it is the
+ * one group verb whose target is by definition a group this org is not in, so
+ * the org's seats are the one set it cannot be found in. It delegates to the
+ * SDK's join ladder (`resolveRefForJoin`), which walks the org's seats, this
+ * agent's invitations and the public directory. A bare UUID always passes
+ * through unchanged.
+ *
+ * Split out of `tools/groups.ts` so that file holds its six tool factories and
+ * nothing else; `tools/registry.ts` — which is what the shipped-surface gate
+ * reads for tool names — is untouched by the move.
+ */
+import type { AsyncRineClient } from "@rine-network/sdk";
+/**
+ * A tool's answer, led by the item-18 completion notice when there is one.
+ *
+ * 🔴 `resolveToUuid` completes a short handle before it reaches WebFinger —
+ * `kofi@acme` is looked up as `kofi@acme.rine.network` — and answers with the
+ * resolved UUID, never the handle it resolved. The model named one agent and
+ * the call may have invited, removed or seated another, with nothing in the
+ * answer saying so.
+ *
+ * 🔴 A LINE, not a key, and that is this surface's shape rather than a choice:
+ * every tool here declares `STRING_OUTPUT`, so there is no object to hang a
+ * field on. `@rine-network/mcp` returns objects and rides the same sentence as
+ * a `handle_completion` key; the CLI writes it to stderr. The BYTES are
+ * {@link handleCompletionNotes}' in `@rine-network/core` and are retyped by
+ * none of the three.
+ *
+ * It leads rather than trails because a model reads the head of a tool result
+ * and acts on it — a caveat about which agent was actually touched is worth
+ * nothing underneath the report of touching them.
+ */
+export declare function withHandleCompletionLine(answer: string, spellings: readonly string[]): string;
+/** Resolve an agent handle/UUID to its `AgentUuid` (UUIDs pass through). */
+export declare function resolveAgentUuid(apiUrl: string, target: string): Promise<import("@rine-network/sdk").AgentUuid>;
+/**
+ * Resolve a batch of agent handles/UUIDs, **in the order they were named**.
+ *
+ * Order is load-bearing: the server answers one admission entry per requested
+ * id in request order, so a report read against a re-ordered list names the
+ * wrong agents. Duplicates are dropped case-insensitively rather than sent
+ * twice, because the second copy of an id comes back `already_invited` and
+ * reads as a failure the caller did not cause.
+ */
+export declare function resolveAgentUuids(apiUrl: string, targets: string[]): Promise<import("@rine-network/sdk").AgentUuid[]>;
+/**
+ * Resolve a group handle/UUID to its `GroupUuid` for `rine_group_join`.
+ *
+ * 🔴 The SDK's own join ladder, not a copy of one. This package used to search
+ * `groups.listInvites()` alone, which answered for a group that had invited
+ * this agent and for nothing else — so the commonest join there is, a handle
+ * read straight off `rine_discover_groups`, was refused here with the server
+ * never having been asked. `resolveRefForJoin` walks the org's seats, then this
+ * agent's invitations, then the public directory, matching the handle exactly at
+ * every rung. What this package could always do it still does: a BARE name
+ * resolves against this agent's own pending invitations — and against nothing
+ * else, because that list is the only set bounded to groups that have already
+ * asked for this agent, and a join cannot be taken back.
+ *
+ * The refusals it throws lead with `Group not found`, which is the phrase
+ * `formatError` (`../errors.ts`) keys on to append this surface's own discover
+ * verbs — the old `No pending invite` wording matched none of its three
+ * spellings, so a refused join carried no remedy at all.
+ */
+export declare function resolveJoinGroupUuid(client: AsyncRineClient, target: string): Promise<import("@rine-network/sdk").GroupUuid>;

package/dist/tools/groups.d.ts

@@ -1,24 +1,28 @@
 /**
- * The 6 group tool factories: `rine_group_create`, `rine_group_invite`,
- * `rine_group_remove`, `rine_group_inspect`, `rine_group_join`,
- * `rine_group_invites`. Groups are MLS-by-default.
+ * 6 of the group domain's 13 tool factories: `rine_group_create`,
+ * `rine_group_invite`, `rine_group_remove`, `rine_group_inspect`,
+ * `rine_group_join`, `rine_group_invites`. The four admission and exit verbs —
+ * `rine_group_requests`, `rine_group_vote`, `rine_group_leave`,
+ * `rine_group_sync` — live in `groups-admin.ts`, so both files hold the
+ * ~200-LOC budget. Groups are MLS-by-default.
  *
- * The TS SDK's `groups.invite`/`removeMember` take BRANDED UUIDs positionally, so
- * invite/remove/inspect PRE-RESOLVE handle→UUID here:
- *   - a group → `groups.list()` + local match (`findGroup`),
- *   - an agent → `resolveToUuid` (WebFinger) → its UUID (or pass a UUID through),
- *     so unlisted agents resolve too.
- * `join` resolves a handle the same way but against the caller's PENDING
- * INVITES (`groups.listInvites()`) — an invitee isn't a member yet, so it can't
- * appear in `groups.list()`. A bare UUID always passes through unchanged (the
- * path for a publicly discovered open-enrollment group with no invite record).
+ * `visibility` has no default here or anywhere else — see `schemas-groups.ts`.
+ *
+ * Admission is plural on both write verbs. `members` on create and
+ * `agentsToInvite` on invite each take a batch and report one outcome per
+ * agent, because a batch drops what it cannot admit rather than refusing
+ * everyone, and on an MLS group it mints every new leaf in one commit instead
+ * of one commit each.
+ *
+ * Handle→UUID resolution lives in `groups-resolve.ts` and the admission
+ * rendering in `groups-admission.ts`, so this file is those six factories.
  */
 import { type RineToolOpts } from "../tool.js";
 /** `rine_group_create` — create an MLS-by-default coordination group. */
 export declare function rineGroupCreateTool(opts?: RineToolOpts): import("eve/tools").ToolDefinition<any, any>;
-/** `rine_group_invite` — invite an agent into a group (handle→UUID pre-resolved). */
+/** `rine_group_invite` — invite one agent or a batch (handle→UUID pre-resolved). */
 export declare function rineGroupInviteTool(opts?: RineToolOpts): import("eve/tools").ToolDefinition<any, any>;
-/** `rine_group_remove` — remove a member; group keys rotate (handle→UUID pre-resolved). */
+/** `rine_group_remove` — evict a member, or leave (handle→UUID pre-resolved). */
 export declare function rineGroupRemoveTool(opts?: RineToolOpts): import("eve/tools").ToolDefinition<any, any>;
 /** `rine_group_inspect` — report a group's E2EE mode + policy. */
 export declare function rineGroupInspectTool(opts?: RineToolOpts): import("eve/tools").ToolDefinition<any, any>;

package/dist/tools/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * The 16 rine tool factories, re-exported for `@rine-network/eve/tools`.
+ * The 25 rine tool factories, re-exported for `@rine-network/eve/tools`.
  *
  * Eve discovers tools by file: each lives as a default-export in
  * `agent/tools/<name>.ts`, and the filename slug IS the tool name. The `init`
@@ -9,8 +9,10 @@
  */
 import type { RineToolOpts } from "../tool.js";
 import { type RineToolMeta } from "./registry.js";
-export { rineCheckInboxTool, rineReadTool, rineReplyTool, rineSendAndWaitTool, rineSendTool, rineThreadTool, } from "./messaging.js";
-export { rineDiscoverTool, rineInspectTool } from "./discovery.js";
+export { rineInboxTool, rineReadTool, rineReplyTool, rineSendAndWaitTool, rineSendTool, rineThreadTool, } from "./messaging.js";
+export { rineDiscoverTool, rineInspectTool, rineWhoamiTool, } from "./discovery.js";
+export { rineGroupLeaveTool, rineGroupReclaimTool, rineGroupRequestsTool, rineGroupSyncTool, rineGroupVoteTool, } from "./groups-admin.js";
+export { rineDiscoverGroupsTool, rineGroupRosterTool, rineGroupsTool, } from "./groups-list.js";
 export { rineGroupCreateTool, rineGroupInspectTool, rineGroupInviteTool, rineGroupInvitesTool, rineGroupJoinTool, rineGroupRemoveTool, } from "./groups.js";
 export { rineFulfillTool, rinePayTool } from "./payments.js";
 export { RINE_TOOL_META, type RineToolMeta, type RineToolDomain, } from "./registry.js";

package/dist/tools/index.js

@@ -1,3 +1,3 @@
-import { _ as rineInspectTool, a as rineReadTool, c as rineSendTool, d as rineGroupInspectTool, f as rineGroupInviteTool, g as rineDiscoverTool, h as rineGroupRemoveTool, i as rineCheckInboxTool, l as rineThreadTool, m as rineGroupJoinTool, n as rineFulfillTool, o as rineReplyTool, p as rineGroupInvitesTool, r as rinePayTool, s as rineSendAndWaitTool, t as RINE_TOOLS, u as rineGroupCreateTool } from "../tools-BhkhV3Mv.js";
-import { t as RINE_TOOL_META } from "../registry-Bn4EqPcp.js";
-export { RINE_TOOLS, RINE_TOOL_META, rineCheckInboxTool, rineDiscoverTool, rineFulfillTool, rineGroupCreateTool, rineGroupInspectTool, rineGroupInviteTool, rineGroupInvitesTool, rineGroupJoinTool, rineGroupRemoveTool, rineInspectTool, rinePayTool, rineReadTool, rineReplyTool, rineSendAndWaitTool, rineSendTool, rineThreadTool };
+import { C as rineGroupVoteTool, E as rineWhoamiTool, S as rineGroupSyncTool, T as rineInspectTool, _ as rineGroupRosterTool, a as rineReadTool, b as rineGroupReclaimTool, c as rineSendTool, d as rineGroupInspectTool, f as rineGroupInviteTool, g as rineDiscoverGroupsTool, h as rineGroupRemoveTool, i as rineInboxTool, l as rineThreadTool, m as rineGroupJoinTool, n as rineFulfillTool, o as rineReplyTool, p as rineGroupInvitesTool, r as rinePayTool, s as rineSendAndWaitTool, t as RINE_TOOLS, u as rineGroupCreateTool, v as rineGroupsTool, w as rineDiscoverTool, x as rineGroupRequestsTool, y as rineGroupLeaveTool } from "../tools-CQDZG-qN.js";
+import { t as RINE_TOOL_META } from "../registry-DsU13KY3.js";
+export { RINE_TOOLS, RINE_TOOL_META, rineDiscoverGroupsTool, rineDiscoverTool, rineFulfillTool, rineGroupCreateTool, rineGroupInspectTool, rineGroupInviteTool, rineGroupInvitesTool, rineGroupJoinTool, rineGroupLeaveTool, rineGroupReclaimTool, rineGroupRemoveTool, rineGroupRequestsTool, rineGroupRosterTool, rineGroupSyncTool, rineGroupVoteTool, rineGroupsTool, rineInboxTool, rineInspectTool, rinePayTool, rineReadTool, rineReplyTool, rineSendAndWaitTool, rineSendTool, rineThreadTool, rineWhoamiTool };

package/dist/tools/messaging.d.ts

@@ -1,25 +1,27 @@
 /**
- * The 5 messaging tool factories: `rine_send`, `rine_send_and_wait`,
- * `rine_check_inbox`, `rine_read`, `rine_reply`. Each returns an Eve `defineTool`
- * descriptor — one `AsyncRineClient` call rendered to a string, wrapped by
- * `makeExecute` (lazy env client + formatError). The runtime tool NAME comes from
- * the filename slug of the scaffolded `agent/tools/<name>.ts`, not from here.
+ * The 6 messaging tool factories: `rine_send`, `rine_send_and_wait`,
+ * `rine_inbox`, `rine_read`, `rine_thread`, `rine_reply`. Each returns an Eve
+ * `defineTool` descriptor — one `AsyncRineClient` call rendered to a string,
+ * wrapped by `makeExecute` (lazy env client + formatError). The runtime tool
+ * NAME comes from the filename slug of the scaffolded `agent/tools/<name>.ts`,
+ * not from here.
  *
  * Renderers read only plaintext/decrypt_error/verification,
- * never the ciphertext envelope. `read`/`check_inbox` add a `toModelOutput`
+ * never the ciphertext envelope. `read`/`inbox`/`thread` add a `toModelOutput`
  * redactor as defence-in-depth.
  */
 import { type RineToolOpts } from "../tool.js";
-/** `rine_send` — send a 1:1 or `#`-group message (the SDK auto-routes groups). */
+/** `rine_send` — send a 1:1 or group message (the SDK auto-routes groups). */
 export declare function rineSendTool(opts?: RineToolOpts): import("eve/tools").ToolDefinition<any, any>;
 /** `rine_send_and_wait` — 1:1 send that blocks for a reply (ms timeout). */
 export declare function rineSendAndWaitTool(opts?: RineToolOpts): import("eve/tools").ToolDefinition<any, any>;
 /**
- * `rine_check_inbox` — poll the newest new messages, decrypt them, then
- * best-effort `markDelivered` the decryptable ids so a later check returns only
- * newer mail. On ack failure: warn but still return the reads.
+ * `rine_inbox` — poll the inbox under one status filter, decrypt what it
+ * returns, and on the `new` path best-effort `markDelivered` the decryptable
+ * ids so a later check returns only newer mail. On ack failure: warn but still
+ * return the reads.
  */
-export declare function rineCheckInboxTool(opts?: RineToolOpts): import("eve/tools").ToolDefinition<any, any>;
+export declare function rineInboxTool(opts?: RineToolOpts): import("eve/tools").ToolDefinition<any, any>;
 /** `rine_read` — fetch + decrypt one message by id. */
 export declare function rineReadTool(opts?: RineToolOpts): import("eve/tools").ToolDefinition<any, any>;
 /** `rine_thread` — fetch the both-sided, decrypted transcript of a conversation. */