@inetafrica/open-claudia 2.0.5 → 2.1.0

package/core/people.js

@@ -0,0 +1,247 @@
+// People store: the roster of human team members the bot knows about.
+// A person aggregates one or more "handles" (adapter + channelId pairs),
+// optional notes, and a primary channel for outbound messages. Auth
+// (can-this-chat-talk-to-me) stays in core/access.js; this layer adds
+// identity, notes, and cross-channel grouping on top.
+//
+// Owner is just a person with isOwner=true. The owner is auto-seeded
+// on first read from the existing auth.json (the bootstrap owner) and
+// any KAZEE_OWNER_USER_ID in env.
+
+const fs = require("fs");
+const { PEOPLE_FILE, AUTH_FILE, config } = require("./config");
+const { channelKey, setIdentityMapping, canonicalForChannel } = require("./identity");
+
+function nowIso() { return new Date().toISOString(); }
+
+function nextId() {
+  return `person_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function load() {
+  try {
+    const raw = JSON.parse(fs.readFileSync(PEOPLE_FILE, "utf-8"));
+    if (!Array.isArray(raw)) return [];
+    return raw;
+  } catch (e) { return []; }
+}
+
+function save(list) {
+  const tmp = `${PEOPLE_FILE}.tmp`;
+  fs.writeFileSync(tmp, JSON.stringify(list, null, 2));
+  fs.renameSync(tmp, PEOPLE_FILE);
+}
+
+function findById(id) {
+  return load().find((p) => p.id === id) || null;
+}
+
+function findByName(name) {
+  const needle = String(name || "").trim().toLowerCase();
+  if (!needle) return null;
+  return load().find((p) => (p.name || "").toLowerCase() === needle) || null;
+}
+
+function findByCanonicalUserId(canonicalUserId) {
+  const id = String(canonicalUserId || "").toLowerCase();
+  if (!id) return null;
+  return load().find((p) => (p.handles || []).some((h) => h.canonicalUserId === id)) || null;
+}
+
+function findByHandle(adapter, channelId) {
+  const a = String(adapter || "").toLowerCase();
+  const c = String(channelId || "");
+  return load().find((p) => (p.handles || []).some((h) => h.adapter === a && String(h.channelId) === c)) || null;
+}
+
+function list() { return load(); }
+
+function add({ name, isOwner = false, bio = null }) {
+  const all = load();
+  const p = {
+    id: nextId(),
+    name: String(name || "").trim(),
+    isOwner: !!isOwner,
+    bio: bio ? String(bio) : null,
+    handles: [],
+    notes: [],
+    primaryChannel: null,
+    createdAt: nowIso(),
+    updatedAt: nowIso(),
+  };
+  if (!p.name) throw new Error("person name is required");
+  all.push(p);
+  save(all);
+  return p;
+}
+
+function update(id, patch) {
+  const all = load();
+  const idx = all.findIndex((p) => p.id === id);
+  if (idx < 0) return null;
+  all[idx] = { ...all[idx], ...patch, updatedAt: nowIso() };
+  save(all);
+  return all[idx];
+}
+
+function remove(id) {
+  const all = load();
+  const idx = all.findIndex((p) => p.id === id);
+  if (idx < 0) return null;
+  const [removed] = all.splice(idx, 1);
+  save(all);
+  return removed;
+}
+
+// Attach a channel handle to a person. Also writes the channel→canonical
+// link in identities.json so the rest of the bot resolves the chat to
+// the same canonical user id as any other handle on this person.
+function linkHandle(personId, { adapter, channelId, displayName = null, approvedBy = null }) {
+  const all = load();
+  const p = all.find((x) => x.id === personId);
+  if (!p) throw new Error(`person not found: ${personId}`);
+  const a = String(adapter || "").toLowerCase();
+  const c = String(channelId || "");
+  if (!a || !c) throw new Error("adapter and channelId are required");
+
+  if (!Array.isArray(p.handles)) p.handles = [];
+  const conflict = all.find((other) =>
+    other.id !== p.id &&
+    (other.handles || []).some((h) => h.adapter === a && String(h.channelId) === c));
+  if (conflict) throw new Error(`handle ${a}:${c} already linked to ${conflict.name} (${conflict.id})`);
+
+  const canonical = canonicalForChannel(a, c);
+  const existing = p.handles.find((h) => h.adapter === a && String(h.channelId) === c);
+  if (!existing) {
+    p.handles.push({
+      adapter: a,
+      channelId: c,
+      canonicalUserId: canonical,
+      displayName,
+      approvedBy,
+      addedAt: nowIso(),
+    });
+  } else {
+    existing.canonicalUserId = canonical;
+    existing.displayName = displayName || existing.displayName;
+  }
+
+  if (!p.primaryChannel) p.primaryChannel = { adapter: a, channelId: c };
+  p.updatedAt = nowIso();
+  save(all);
+
+  // Mirror into identities.json so canonicalForChannel resolves cross-handle.
+  if (p.handles.length > 1) {
+    const primary = p.handles[0];
+    const primaryCanonical = primary.canonicalUserId || canonicalForChannel(primary.adapter, primary.channelId);
+    try { setIdentityMapping(a, c, primaryCanonical); } catch (e) {}
+  }
+
+  return p;
+}
+
+function unlinkHandle(personId, { adapter, channelId }) {
+  const all = load();
+  const p = all.find((x) => x.id === personId);
+  if (!p) return null;
+  const a = String(adapter || "").toLowerCase();
+  const c = String(channelId || "");
+  const before = (p.handles || []).length;
+  p.handles = (p.handles || []).filter((h) => !(h.adapter === a && String(h.channelId) === c));
+  if (p.primaryChannel && p.primaryChannel.adapter === a && String(p.primaryChannel.channelId) === c) {
+    p.primaryChannel = p.handles[0] ? { adapter: p.handles[0].adapter, channelId: p.handles[0].channelId } : null;
+  }
+  if (p.handles.length === before) return null;
+  p.updatedAt = nowIso();
+  save(all);
+  return p;
+}
+
+function setPrimary(personId, { adapter, channelId }) {
+  const all = load();
+  const p = all.find((x) => x.id === personId);
+  if (!p) return null;
+  const a = String(adapter || "").toLowerCase();
+  const c = String(channelId || "");
+  const has = (p.handles || []).some((h) => h.adapter === a && String(h.channelId) === c);
+  if (!has) throw new Error(`person ${p.id} has no handle ${a}:${c}`);
+  p.primaryChannel = { adapter: a, channelId: c };
+  p.updatedAt = nowIso();
+  save(all);
+  return p;
+}
+
+function note(personId, text, { by = null } = {}) {
+  const all = load();
+  const p = all.find((x) => x.id === personId);
+  if (!p) return null;
+  if (!Array.isArray(p.notes)) p.notes = [];
+  const entry = { at: nowIso(), by, text: String(text || "").trim() };
+  if (!entry.text) throw new Error("note text is required");
+  p.notes.push(entry);
+  p.updatedAt = nowIso();
+  save(all);
+  return entry;
+}
+
+function removeNote(personId, index) {
+  const all = load();
+  const p = all.find((x) => x.id === personId);
+  if (!p || !Array.isArray(p.notes)) return null;
+  if (index < 0 || index >= p.notes.length) return null;
+  const [removed] = p.notes.splice(index, 1);
+  p.updatedAt = nowIso();
+  save(all);
+  return removed;
+}
+
+function owners() { return load().filter((p) => p.isOwner); }
+
+function hasOwnerRecord() { return owners().length > 0; }
+
+// First-boot seeding: if people.json is empty but auth.json has an
+// owner entry (the legacy bootstrap), promote that owner into a person
+// record so the new system has a baseline before any intros happen.
+function seedOwnerFromLegacy() {
+  if (hasOwnerRecord()) return null;
+  let legacyOwner = null;
+  try {
+    const auth = JSON.parse(fs.readFileSync(AUTH_FILE, "utf-8"));
+    legacyOwner = (auth.authorized || []).find((a) => a.isOwner === true) || null;
+  } catch (e) {}
+  if (!legacyOwner) return null;
+
+  const adapter = "telegram";
+  const channelId = String(legacyOwner.chatId);
+  const name = legacyOwner.name || legacyOwner.username || "Owner";
+
+  const person = add({ name, isOwner: true, bio: "Seeded from legacy auth.json" });
+  try { linkHandle(person.id, { adapter, channelId, displayName: legacyOwner.username || null, approvedBy: "bootstrap" }); } catch (e) {}
+
+  const kazeeOwnerUserId = (config && config.KAZEE_OWNER_USER_ID) || "";
+  if (kazeeOwnerUserId) {
+    try { linkHandle(person.id, { adapter: "kazee", channelId: kazeeOwnerUserId, approvedBy: "bootstrap" }); } catch (e) {}
+  }
+  return person;
+}
+
+function roster() {
+  return load().map((p) => ({
+    id: p.id,
+    name: p.name,
+    isOwner: !!p.isOwner,
+    bio: p.bio || null,
+    handles: (p.handles || []).map((h) => ({ adapter: h.adapter, channelId: h.channelId })),
+    primaryChannel: p.primaryChannel || null,
+    notes: (p.notes || []).slice(-5),
+  }));
+}
+
+module.exports = {
+  load, save, list, roster,
+  add, update, remove,
+  findById, findByName, findByCanonicalUserId, findByHandle,
+  linkHandle, unlinkHandle, setPrimary,
+  note, removeNote,
+  owners, hasOwnerRecord, seedOwnerFromLegacy,
+};

package/core/relay.js

@@ -0,0 +1,61 @@
+// Cross-channel relay: lets the agent (or any authorized caller) send
+// a message to another person on any of their handles, without being
+// inside that chat's async-local context. Resolves person → handle →
+// adapter → send. Every send is audited.
+
+const people = require("./people");
+const registry = require("./adapter-registry");
+const audit = require("./audit");
+
+function resolveTarget({ personId, personName, canonicalUserId, adapter, channelId }) {
+  if (adapter && channelId) {
+    return { adapter: String(adapter).toLowerCase(), channelId: String(channelId), person: people.findByHandle(adapter, channelId) };
+  }
+  let person = null;
+  if (personId) person = people.findById(personId);
+  if (!person && personName) person = people.findByName(personName);
+  if (!person && canonicalUserId) person = people.findByCanonicalUserId(canonicalUserId);
+  if (!person) throw new Error("target person not found");
+  const handles = person.handles || [];
+  if (handles.length === 0) throw new Error(`person ${person.name} has no handles`);
+  const primary = person.primaryChannel
+    ? handles.find((h) => h.adapter === person.primaryChannel.adapter && String(h.channelId) === String(person.primaryChannel.channelId))
+    : null;
+  const handle = primary || handles[0];
+  return { adapter: handle.adapter, channelId: handle.channelId, person };
+}
+
+async function send({ text, target, from = null, kind = "relay" }) {
+  if (!text || !String(text).trim()) throw new Error("text is required");
+  const resolved = resolveTarget(target);
+  const adapter = registry.findAdapter(resolved.adapter) || registry.getAdapters().find((a) => a.type === resolved.adapter);
+  if (!adapter) throw new Error(`no live adapter for ${resolved.adapter}`);
+
+  let ok = false;
+  let messageId = null;
+  let errorMsg = null;
+  try {
+    const result = await adapter.send(resolved.channelId, String(text));
+    if (typeof result === "object" && result && "messageId" in result) { messageId = result.messageId; ok = !!messageId; }
+    else { messageId = result; ok = !!result; }
+  } catch (e) { errorMsg = e.message; }
+
+  audit.log(kind, {
+    from,
+    to: {
+      personId: resolved.person?.id || null,
+      personName: resolved.person?.name || null,
+      adapter: resolved.adapter,
+      channelId: resolved.channelId,
+    },
+    ok,
+    messageId,
+    textPreview: String(text).slice(0, 200),
+    error: errorMsg,
+  });
+
+  if (!ok) throw new Error(errorMsg || "send failed");
+  return { ok, messageId, to: { adapter: resolved.adapter, channelId: resolved.channelId, person: resolved.person } };
+}
+
+module.exports = { send, resolveTarget };

package/core/router.js

@@ -8,6 +8,7 @@ const { runInChat } = require("./context");
 const { dispatch } = require("./commands");
 const { handleAction } = require("./actions");
 const { isChatAuthorized } = require("./access");
+const introFlow = require("./intro-flow");
 const { send, deleteMessage } = require("./io");
 const { currentState } = require("./state");
 const { runClaude } = require("./runner");
@@ -78,7 +79,13 @@ async function onMessage(envelope) {
         return;
       }
 
-      if (!isChatAuthorized(envelope.channelId)) return;
+      if (!isChatAuthorized(envelope.channelId)) {
+        if (envelope.type === "text") {
+          if (isDuplicate(envelope)) return;
+          await introFlow.handleInbound(envelope, (text) => send(text));
+        }
+        return;
+      }
 
       if (envelope.type === "voice") return handleVoice(envelope);
       if (envelope.type === "audio") return handleAudio(envelope);

package/core/system-prompt.js

@@ -10,6 +10,7 @@ const { currentAdapter, currentChannelId } = require("./context");
 const { vault } = require("./vault-store");
 const { transcriptPointerNote } = require("./transcripts");
 const tasksStore = require("./tasks");
+const people = require("./people");
 
 function loadSoul() {
   try { return fs.readFileSync(SOUL_FILE, "utf-8"); }
@@ -37,6 +38,31 @@ function buildSystemPrompt() {
     } catch (e) {}
   }
 
+  let teamBlock = "";
+  let currentSpeakerBlock = "";
+  try {
+    const roster = people.roster();
+    if (roster.length > 0) {
+      const lines = roster.map((p) => {
+        const handleSummary = (p.handles || []).map((h) => `${h.adapter}:${h.channelId}`).join(", ") || "(no handles)";
+        const primary = p.primaryChannel ? ` primary=${p.primaryChannel.adapter}:${p.primaryChannel.channelId}` : "";
+        const noteSummary = (p.notes || []).length > 0
+          ? "\n    Notes: " + p.notes.slice(-3).map((n) => `[${n.at?.slice(0, 10) || ""}] ${n.text}`).join(" | ")
+          : "";
+        return `- ${p.name}${p.isOwner ? " (owner)" : ""} — ${handleSummary}${primary}${p.bio ? "\n    Bio: " + p.bio : ""}${noteSummary}`;
+      });
+      teamBlock = `\n## Team\nThe humans you know about. You can reach any of them via the relay tool below. Use names from this list when the user refers to teammates.\n\n${lines.join("\n")}\n`;
+    }
+
+    if (adapter && channelId) {
+      const speaker = people.findByHandle(adapter.type, channelId);
+      if (speaker) {
+        const recentNotes = (speaker.notes || []).slice(-3).map((n) => `- [${n.at?.slice(0, 10) || ""}] ${n.text}`).join("\n");
+        currentSpeakerBlock = `\n## Speaker\nYou are talking to ${speaker.name}${speaker.isOwner ? " (the owner)" : ""} on ${adapter.type}.${speaker.bio ? "\nBio: " + speaker.bio : ""}${recentNotes ? "\nRecent notes:\n" + recentNotes : ""}\n`;
+      }
+    }
+  } catch (e) {}
+
   return `
 ${soul}
 
@@ -56,7 +82,7 @@ ${soul}
 - Received user files directory: ${FILES_DIR}
 
 ${transcriptPointerNote(state)}
-${pendingTasksBlock}
+${currentSpeakerBlock}${teamBlock}${pendingTasksBlock}
 ## Delivery
 Reply normally in your final answer. To send a file, image, or voice clip back to the current chat, run the bot CLI from inside this task — channel context is already in the env:
 - \`open-claudia send-file <path> [caption]\` — any document/binary
@@ -75,7 +101,9 @@ Wake-ups and crons (real schedulers, not hallucinations — use them instead of
 
 Persistent todo list with plans + subtasks (per channel; survives compaction and restart).
 
-For any work with 3+ distinct steps you MUST create a plan before starting. The plan is a parent task whose children are the steps. As you work, mark each subtask in_progress when you begin and completed when done — this is how a resumed turn (after compaction, restart, or wakeup) sees where you left off. If pending tasks already exist when you start a turn they will be shown under "## Pending tasks" above; check them first.
+Use a plan when work is likely to outlive a single turn — i.e. it may hit a compaction, a restart, or a scheduled wakeup before completing, or its progress is something the user will want to see between turns. The plan is a parent task whose children are the steps. As you work, mark each subtask in_progress when you begin and completed when done — this is how a resumed turn sees where you left off. If pending tasks already exist when you start a turn they will be shown under "## Pending tasks" above; check them first.
+
+Skip the plan for work that visibly completes within the current turn (e.g. running a few CLI commands in sequence and replying). A plan there is overhead the user has to read past.
 
 - \`open-claudia task plan "<plan title>" "<step 1>" "<step 2>" "<step 3>" [--description "<why / success criteria>"]\` — atomic create
 - \`open-claudia task add "<content>" [--parent <plan-id>] [--description "..."]\` — add a single task or subtask
@@ -85,6 +113,21 @@ For any work with 3+ distinct steps you MUST create a plan before starting. The
 
 For one-off work under 3 steps, skip the plan and just track it in your own response.
 
+Cross-channel relay (talk to other team members on their primary channel — see Team block above for names):
+- \`open-claudia send-to --person "<name>" "<message>"\` — sends to that person's primary channel.
+- \`open-claudia send-to --adapter <type> --channel <id> "<message>"\` — explicit channel target.
+- Be honest about provenance. If you are forwarding on someone's behalf, prefix the message: "From <speaker name>: ...". If you are reaching out autonomously (cron, wakeup, your own judgement), prefix with "Open Claudia: ...".
+- Use sparingly — every relay is logged to the audit trail. Don't message people unprompted unless the user asked you to or the context obviously calls for it.
+
+Recent activity lookup (read other chats' transcripts on demand — don't try to carry everything in context):
+- \`open-claudia recent --person "<name>" [--limit 20]\`
+- \`open-claudia recent --adapter <type> --channel <id> [--limit 20]\`
+
+People management (owner-only commands; safe to call to inspect):
+- \`open-claudia people list\` / \`people show <id-or-name>\` — read-only, anyone can call.
+- \`open-claudia people note <id-or-name> "<note>"\` — record something the team should remember.
+- \`open-claudia intros list\` / \`intros approve <id>\` / \`intros reject <id>\` — owner-gated.
+
 Sub-agents (spawn a fresh throwaway Claude for focused research — output comes back on stdout):
 - \`open-claudia agent "<prompt>" [--role "<role>"]\`
 - Use when a side question would pollute this conversation, or to fan out independent lookups.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inetafrica/open-claudia",
-  "version": "2.0.5",
+  "version": "2.1.0",
   "description": "Your always-on AI coding assistant — Claude Code, Cursor Agent, and OpenAI Codex via Telegram or Kazee Chat",
   "main": "bot.js",
   "bin": {