@ouro.bot/friends 0.1.0-alpha.4

package/dist/mcp/dispatch.js

@@ -0,0 +1,432 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.coerceBool = coerceBool;
+exports.coerceInt = coerceInt;
+exports.coerceString = coerceString;
+exports.coerceOptionalString = coerceOptionalString;
+exports.dispatchTool = dispatchTool;
+// Tool dispatch for the friends MCP server.
+//
+// MCP sends string-ish args; the coercion helpers normalize them before calling
+// the library fns. `dispatchTool` is a flat tool → library-fn map (D9/D10) with
+// NO domain logic of its own — every behavior lives in the friends library.
+const observability_1 = require("../observability");
+const types_1 = require("../types");
+const resolver_1 = require("../resolver");
+const trust_explanation_1 = require("../trust-explanation");
+const standing_1 = require("../standing");
+const channel_1 = require("../channel");
+const group_context_1 = require("../group-context");
+const tokens_1 = require("../tokens");
+const notes_1 = require("../notes");
+const trust_mutation_1 = require("../trust-mutation");
+const link_identity_1 = require("../link-identity");
+const agent_peer_1 = require("../agent-peer");
+const outcomes_1 = require("../outcomes");
+const whoami_1 = require("../whoami");
+const room_1 = require("../room");
+const share_1 = require("../share");
+const grants_1 = require("../grants");
+const missions_1 = require("../missions");
+const mission_share_1 = require("../mission-share");
+const coordination_1 = require("../coordination");
+const types_2 = require("../types");
+function coerceBool(v) {
+    return v === true || v === "true";
+}
+function coerceInt(v) {
+    if (v === undefined || v === null)
+        return undefined;
+    const n = typeof v === "number" ? v : parseInt(String(v), 10);
+    return Number.isNaN(n) ? undefined : n;
+}
+function coerceString(v) {
+    return typeof v === "string" ? v : "";
+}
+function coerceOptionalString(v) {
+    return typeof v === "string" ? v : undefined;
+}
+/** Parse a value that may be a JSON-string-encoded object/array. Returns
+ * undefined when the value is absent or the string fails to parse (guarded). */
+function parseMaybeJson(v) {
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v === "string") {
+        try {
+            return JSON.parse(v);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return v;
+}
+/** A grant-backed tool was called without a GrantStore wired (a store-only
+ * embedding). The consent surface needs grant persistence, so report it cleanly
+ * rather than guessing. */
+const NO_GRANT_STORE = { ok: false, status: "unsupported", message: "no grant store configured (consent/share tools require one)" };
+/** A mission-backed tool was called without a MissionStore wired (a store-only
+ * embedding). The mission ledger needs mission persistence, so report it cleanly
+ * rather than guessing. */
+const NO_MISSION_STORE = { ok: false, status: "unsupported", message: "no mission store configured (mission tools require one)" };
+async function dispatchTool(store, name, args, grants, missions) {
+    (0, observability_1.emitNervesEvent)({
+        component: "clients",
+        event: "clients.mcp_dispatch",
+        message: "dispatching friends mcp tool",
+        meta: { tool: name },
+    });
+    switch (name) {
+        case "resolve_party": {
+            const provider = coerceString(args.provider);
+            const externalId = coerceString(args.externalId);
+            const tenantId = coerceOptionalString(args.tenantId);
+            const displayName = coerceString(args.displayName) || "Unknown";
+            const channel = coerceString(args.channel);
+            const existing = await store.findByExternalId(provider, externalId, tenantId);
+            const created = existing === null;
+            const resolved = await new resolver_1.FriendResolver(store, { provider, externalId, tenantId, displayName, channel }).resolve();
+            return { result: { friend: resolved.friend, channel: resolved.channel, created }, isError: false };
+        }
+        case "describe_trust": {
+            const friend = await store.get(coerceString(args.friendId));
+            if (!friend) {
+                return { result: { ok: false, status: "not_found", message: "friend record not found" }, isError: true };
+            }
+            const explanation = (0, trust_explanation_1.describeTrustContext)({
+                friend,
+                channel: coerceString(args.channel),
+                isGroupChat: coerceBool(args.isGroupChat),
+            });
+            return { result: explanation, isError: false };
+        }
+        case "assess_standing": {
+            // Pure read mirroring describe_trust: resolve the record, run the store-free
+            // assessment, return the value. No rule injected at the boundary — the tool
+            // uses DEFAULT_STANDING_RULE via the fn's `rule ?? DEFAULT` fallback. Never
+            // writes trust; never produces a wire artifact.
+            const friend = await store.get(coerceString(args.friendId));
+            if (!friend) {
+                return { result: { ok: false, status: "not_found", message: "friend record not found" }, isError: true };
+            }
+            return { result: (0, standing_1.assessStanding)(friend), isError: false };
+        }
+        case "explain_standing": {
+            const friend = await store.get(coerceString(args.friendId));
+            if (!friend) {
+                return { result: { ok: false, status: "not_found", message: "friend record not found" }, isError: true };
+            }
+            return { result: (0, standing_1.explainStanding)(friend), isError: false };
+        }
+        case "get_friend": {
+            const friend = await store.get(coerceString(args.friendId));
+            if (!friend) {
+                return { result: { ok: false, status: "not_found", message: "friend record not found" }, isError: true };
+            }
+            return { result: friend, isError: false };
+        }
+        case "list_friends": {
+            const all = typeof store.listAll === "function" ? await store.listAll() : [];
+            const trust = coerceOptionalString(args.trust);
+            const kind = coerceOptionalString(args.kind);
+            const limit = coerceInt(args.limit);
+            let filtered = all;
+            if (trust !== undefined)
+                filtered = filtered.filter((f) => f.trustLevel === trust);
+            if (kind !== undefined)
+                filtered = filtered.filter((f) => f.kind === kind);
+            if (limit !== undefined)
+                filtered = filtered.slice(0, limit);
+            return { result: filtered, isError: false };
+        }
+        case "save_note": {
+            const type = coerceString(args.type);
+            // The library helper takes a typed `type` union; the MCP boundary validates
+            // the raw string here so an unknown type is a clean `invalid` result
+            // rather than garbage written under an undefined key.
+            if (type !== "name" && type !== "tool_preference" && type !== "note") {
+                return {
+                    result: { ok: false, status: "invalid", message: `unrecognized note type '${type}' — use name, tool_preference, or note` },
+                    isError: true,
+                };
+            }
+            const result = await (0, notes_1.applyFriendNote)(store, coerceString(args.friendId), {
+                type,
+                key: coerceOptionalString(args.key),
+                content: coerceString(args.content),
+                override: coerceBool(args.override),
+                provenance: parseMaybeJson(args.provenance),
+            });
+            return { result, isError: result.ok === false };
+        }
+        case "record_interaction": {
+            const friendId = coerceString(args.friendId);
+            const usage = parseMaybeJson(args.usage);
+            const outcome = parseMaybeJson(args.outcome);
+            const familiarityDelta = coerceInt(args.familiarityDelta);
+            const provenance = parseMaybeJson(args.provenance);
+            if (usage === undefined && outcome === undefined) {
+                return { result: { ok: true, status: "noop", message: "no usage or outcome provided" }, isError: false };
+            }
+            const combined = {};
+            if (usage !== undefined) {
+                await (0, tokens_1.accumulateFriendTokens)(store, friendId, usage);
+                combined.tokensAccumulated = true;
+            }
+            if (outcome !== undefined) {
+                combined.outcome = await (0, outcomes_1.recordRelationshipOutcome)(store, friendId, { missionId: outcome.missionId, result: outcome.result, note: outcome.note, provenance: outcome.provenance ?? provenance }, familiarityDelta);
+            }
+            return { result: combined, isError: false };
+        }
+        case "upsert_group": {
+            const participants = parseMaybeJson(args.participants) ?? [];
+            const results = await (0, group_context_1.upsertGroupContextParticipants)({
+                store,
+                participants,
+                groupExternalId: coerceString(args.groupExternalId),
+            });
+            return { result: results, isError: false };
+        }
+        case "set_trust": {
+            const result = await (0, trust_mutation_1.setFriendTrust)(store, coerceString(args.friendId), coerceString(args.trustLevel));
+            return { result, isError: result.ok === false };
+        }
+        case "link_identity": {
+            const result = await (0, link_identity_1.linkExternalId)(store, coerceString(args.friendId), {
+                provider: coerceString(args.provider),
+                externalId: coerceString(args.externalId),
+                tenantId: coerceOptionalString(args.tenantId),
+            });
+            return { result, isError: result.ok === false };
+        }
+        case "unlink_identity": {
+            const result = await (0, link_identity_1.unlinkExternalId)(store, coerceString(args.friendId), {
+                provider: coerceString(args.provider),
+                externalId: coerceString(args.externalId),
+            });
+            return { result, isError: result.ok === false };
+        }
+        case "onboard_agent": {
+            const record = await (0, agent_peer_1.upsertAgentPeer)(store, {
+                name: coerceString(args.name),
+                agentId: coerceString(args.agentId),
+                trustLevel: coerceOptionalString(args.trustLevel),
+                a2a: parseMaybeJson(args.a2a),
+                mailbox: parseMaybeJson(args.mailbox),
+                bundleName: coerceOptionalString(args.bundleName),
+            });
+            return { result: record, isError: false };
+        }
+        case "whoami": {
+            return { result: await (0, whoami_1.whoami)(store), isError: false };
+        }
+        case "channel_caps": {
+            return { result: (0, channel_1.getChannelCapabilities)(coerceString(args.channel)), isError: false };
+        }
+        case "resolve_room": {
+            const view = await (0, room_1.resolveRoom)(store, coerceString(args.groupExternalId), (coerceOptionalString(args.channel) ?? "mcp"));
+            return { result: view, isError: false };
+        }
+        case "share_profile": {
+            // De-stubbed producer. Self identity comes from whoami (the dispatch is
+            // store-only); the subject is named by join key inside the library.
+            if (!grants)
+                return { result: NO_GRANT_STORE, isError: true };
+            const scope = coerceString(args.scope);
+            if (!(0, types_1.isShareScope)(scope)) {
+                return {
+                    result: { ok: false, status: "invalid", message: `unrecognized scope '${scope}' — use name, identity, notes:safe, notes:all, or outcomes` },
+                    isError: true,
+                };
+            }
+            const self = await (0, whoami_1.whoami)(store);
+            // whoami sets selfFriendId + selfAgentName together or neither; the local
+            // self id (selfFriendId) is the asserter tag. "" when there is no self yet.
+            const selfAgentId = self.selfFriendId ?? "";
+            const result = await (0, share_1.prepareProfileShare)(store, grants, {
+                friendId: coerceString(args.friendId),
+                toAgentId: coerceString(args.toAgentId),
+                scope: scope,
+                selfAgentId,
+                proof: coerceOptionalString(args.proof),
+            });
+            return { result, isError: result.ok === false };
+        }
+        case "import_profile": {
+            const envelope = parseMaybeJson(args.envelope);
+            if (!envelope || typeof envelope !== "object") {
+                return { result: { ok: false, status: "invalid", message: "an envelope object is required" }, isError: true };
+            }
+            const result = await (0, share_1.importProfileShare)(store, {
+                envelope,
+                fromAgentId: coerceString(args.fromAgentId),
+                trustOfSource: coerceString(args.trustOfSource),
+            });
+            return { result, isError: result.ok === false };
+        }
+        case "grant_share": {
+            if (!grants)
+                return { result: NO_GRANT_STORE, isError: true };
+            const scope = coerceString(args.scope);
+            if (!(0, types_1.isShareScope)(scope)) {
+                return {
+                    result: { ok: false, status: "invalid", message: `unrecognized scope '${scope}' — use name, identity, notes:safe, notes:all, or outcomes` },
+                    isError: true,
+                };
+            }
+            // Fork D compat seam (b): accept the new `subjectKey` arg, falling back to
+            // the legacy `subjectFriendId` so old-arg callers (incl. the unmodified
+            // examples) keep working. coerceString gives "" when an arg is absent, so
+            // `||` selects subjectKey when present, else subjectFriendId.
+            const grant = await (0, grants_1.grantShare)(grants, {
+                subjectKey: coerceString(args.subjectKey) || coerceString(args.subjectFriendId),
+                recipientAgentId: coerceString(args.recipientAgentId),
+                scope: scope,
+                expiresAt: coerceOptionalString(args.expiresAt),
+            });
+            return { result: grant, isError: false };
+        }
+        case "revoke_share": {
+            if (!grants)
+                return { result: NO_GRANT_STORE, isError: true };
+            const result = await (0, grants_1.revokeShare)(grants, coerceString(args.grantId));
+            return { result, isError: result.ok === false };
+        }
+        case "list_shares": {
+            if (!grants)
+                return { result: NO_GRANT_STORE, isError: true };
+            // Fork D compat seam (b): accept `subjectKey`, falling back to the legacy
+            // `subjectFriendId` filter arg.
+            const result = await (0, grants_1.listShares)(grants, {
+                subjectKey: coerceOptionalString(args.subjectKey) ?? coerceOptionalString(args.subjectFriendId),
+                recipientAgentId: coerceOptionalString(args.recipientAgentId),
+                effectiveOnly: coerceBool(args.effectiveOnly),
+            });
+            return { result, isError: false };
+        }
+        case "record_mission": {
+            if (!missions)
+                return { result: NO_MISSION_STORE, isError: true };
+            const input = {
+                missionKey: coerceString(args.missionKey),
+                title: coerceOptionalString(args.title),
+                status: coerceOptionalString(args.status),
+                participants: parseMaybeJson(args.participants),
+                learnings: parseMaybeJson(args.learnings),
+                outcomes: parseMaybeJson(args.outcomes),
+            };
+            const record = await (0, missions_1.recordMission)(missions, input);
+            return { result: record, isError: false };
+        }
+        case "get_mission": {
+            if (!missions)
+                return { result: NO_MISSION_STORE, isError: true };
+            const record = await missions.get(coerceString(args.missionId));
+            if (!record) {
+                return { result: { ok: false, status: "not_found", message: "mission record not found" }, isError: true };
+            }
+            return { result: record, isError: false };
+        }
+        case "list_missions": {
+            if (!missions)
+                return { result: NO_MISSION_STORE, isError: true };
+            const all = await missions.listAll();
+            const limit = coerceInt(args.limit);
+            const result = limit !== undefined ? all.slice(0, limit) : all;
+            return { result, isError: false };
+        }
+        case "share_mission": {
+            // Producer. Self identity comes from whoami (the dispatch is store-only);
+            // the mission is named by its missionKey inside the library. Gated on BOTH a
+            // GrantStore (consent) and a MissionStore.
+            if (!missions || !grants)
+                return { result: NO_MISSION_STORE, isError: true };
+            const scope = coerceString(args.scope);
+            if (scope !== "mission" && scope !== "outcomes") {
+                return {
+                    result: { ok: false, status: "invalid", message: `unrecognized mission scope '${scope}' — use mission or outcomes` },
+                    isError: true,
+                };
+            }
+            const self = await (0, whoami_1.whoami)(store);
+            const selfAgentId = self.selfFriendId ?? "";
+            const result = await (0, mission_share_1.prepareMissionShare)(missions, store, grants, {
+                missionId: coerceString(args.missionId),
+                toAgentId: coerceString(args.toAgentId),
+                scope,
+                selfAgentId,
+                proof: coerceOptionalString(args.proof),
+            });
+            return { result, isError: result.ok === false };
+        }
+        case "import_mission": {
+            if (!missions)
+                return { result: NO_MISSION_STORE, isError: true };
+            const envelope = parseMaybeJson(args.envelope);
+            if (!envelope || typeof envelope !== "object") {
+                return { result: { ok: false, status: "invalid", message: "an envelope object is required" }, isError: true };
+            }
+            const result = await (0, mission_share_1.importMissionShare)(missions, {
+                envelope,
+                fromAgentId: coerceString(args.fromAgentId),
+                trustOfSource: coerceString(args.trustOfSource),
+            });
+            return { result, isError: result.ok === false };
+        }
+        case "coordinate": {
+            // Producer (brick 5). Self identity comes from whoami (the dispatch is
+            // store-only); the mission is named by its missionKey inside the library.
+            // Gated on BOTH a GrantStore (consent via the "coordinate" scope) and a
+            // MissionStore — like share_mission.
+            if (!missions || !grants)
+                return { result: NO_MISSION_STORE, isError: true };
+            const intent = coerceString(args.intent);
+            if (!(0, types_2.isCoordinationIntent)(intent)) {
+                return {
+                    result: { ok: false, status: "invalid", message: `unrecognized coordination intent '${intent}' — use request, offer, accept, decline, or handoff` },
+                    isError: true,
+                };
+            }
+            const self = await (0, whoami_1.whoami)(store);
+            const selfAgentId = self.selfFriendId ?? "";
+            const result = await (0, coordination_1.prepareCoordination)(missions, store, grants, {
+                missionId: coerceString(args.missionId),
+                toAgentId: coerceString(args.toAgentId),
+                intent,
+                note: coerceOptionalString(args.note),
+                proposedAssignee: parseMaybeJson(args.proposedAssignee),
+                selfAgentId,
+                proof: coerceOptionalString(args.proof),
+            });
+            return { result, isError: result.ok === false };
+        }
+        case "import_coordination": {
+            if (!missions)
+                return { result: NO_MISSION_STORE, isError: true };
+            const envelope = parseMaybeJson(args.envelope);
+            if (!envelope || typeof envelope !== "object") {
+                return { result: { ok: false, status: "invalid", message: "an envelope object is required" }, isError: true };
+            }
+            const result = await (0, coordination_1.importCoordination)(missions, {
+                envelope,
+                fromAgentId: coerceString(args.fromAgentId),
+                trustOfSource: coerceString(args.trustOfSource),
+            });
+            return { result, isError: result.ok === false };
+        }
+        case "get_coordination": {
+            // Read lens (brick 5), like get_mission: return the mission's coordination
+            // sub-object (assignee + log), or the empty default when unset.
+            if (!missions)
+                return { result: NO_MISSION_STORE, isError: true };
+            const record = await missions.get(coerceString(args.missionId));
+            if (!record) {
+                return { result: { ok: false, status: "not_found", message: "mission record not found" }, isError: true };
+            }
+            return { result: record.coordination ?? { assignee: undefined, log: [] }, isError: false };
+        }
+        default: {
+            return { result: { error: `Unknown tool: ${name}` }, isError: true };
+        }
+    }
+}

package/dist/mcp/index.d.ts

@@ -0,0 +1,6 @@
+export { createFriendsMcpServer } from "./server";
+export type { FriendsMcpServer, FriendsMcpServerOptions } from "./server";
+export { getToolSchemas } from "./schemas";
+export type { McpToolSchema } from "./schemas";
+export { runMain } from "./run-main";
+export type { RunMainIo } from "./run-main";

package/dist/mcp/index.js

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runMain = exports.getToolSchemas = exports.createFriendsMcpServer = void 0;
+// @ouro.bot/friends/mcp — the MCP server surface.
+//
+// A thin, harness-agnostic MCP tool surface over the friends library: dual
+// stdio framing, a flat tool → library-fn dispatch, and NO agent turn. Consumed
+// via the `friends-mcp` bin or embedded directly through `createFriendsMcpServer`.
+var server_1 = require("./server");
+Object.defineProperty(exports, "createFriendsMcpServer", { enumerable: true, get: function () { return server_1.createFriendsMcpServer; } });
+var schemas_1 = require("./schemas");
+Object.defineProperty(exports, "getToolSchemas", { enumerable: true, get: function () { return schemas_1.getToolSchemas; } });
+var run_main_1 = require("./run-main");
+Object.defineProperty(exports, "runMain", { enumerable: true, get: function () { return run_main_1.runMain; } });

package/dist/mcp/run-main.d.ts

@@ -0,0 +1,7 @@
+import type { FriendsMcpServer } from "./server";
+export interface RunMainIo {
+    stdin: NodeJS.ReadableStream;
+    stdout: NodeJS.WritableStream;
+    onError: (message: string) => void;
+}
+export declare function runMain(argv: string[], env: NodeJS.ProcessEnv, io: RunMainIo): FriendsMcpServer | null;

package/dist/mcp/run-main.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runMain = runMain;
+// runMain — the covered core of the `friends-mcp` bin.
+//
+// Resolves the friends directory from `--dir <path>` (flag wins) or the
+// `FRIENDS_DIR` environment variable, constructs a FileFriendStore over it, and
+// starts an MCP server on the given streams. If neither source supplies a
+// directory, it reports via `onError` and constructs nothing (returns null).
+const observability_1 = require("../observability");
+const file_bundle_1 = require("../file-bundle");
+const server_1 = require("./server");
+/** Parse `--dir <value>` from argv. Returns the value, or undefined if the flag
+ * is absent or has no following value. */
+function parseDirFlag(argv) {
+    const idx = argv.indexOf("--dir");
+    if (idx === -1)
+        return undefined;
+    const value = argv[idx + 1];
+    if (value === undefined)
+        return undefined;
+    return value;
+}
+function runMain(argv, env, io) {
+    const flagDir = parseDirFlag(argv);
+    const dir = flagDir ?? env.FRIENDS_DIR;
+    const source = flagDir !== undefined ? "flag" : "env";
+    if (!dir) {
+        io.onError("friends-mcp requires --dir <path> or FRIENDS_DIR");
+        return null;
+    }
+    (0, observability_1.emitNervesEvent)({
+        component: "clients",
+        event: "clients.mcp_run_main",
+        message: "friends mcp run-main",
+        meta: { source },
+    });
+    // The consent-grant + mission collections are sibling `_grants/` + `_missions/`
+    // dirs under the friends dir, so the single `--dir` wires the whole substrate
+    // (friends + consent + missions). `openFileBundle` encapsulates that convention.
+    const { store, grants, missions } = (0, file_bundle_1.openFileBundle)(dir);
+    const server = (0, server_1.createFriendsMcpServer)({ store, grants, missions, stdin: io.stdin, stdout: io.stdout });
+    server.start();
+    return server;
+}

package/dist/mcp/schemas.d.ts

@@ -0,0 +1,10 @@
+export interface McpToolSchema {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+export declare function getToolSchemas(): McpToolSchema[];