@bolloon/bolloon-agent 0.4.29 → 0.4.30

package/dist/agents/contacts/store.js

@@ -0,0 +1,326 @@
+/**
+ * contacts/store.ts — 联系方式事实的唯一落盘层 (2026-09-19, Phase 1/4)
+ *
+ * 目录: ~/.bolloon/contacts/
+ *   social-identity.json   SocialIdentity (DID 主身份 + 已验证 contactId 列表)
+ *   contacts.json          VerifiedContact[]  (含 normalizedValue, 只在本层读写)
+ *   secrets.json           Secret Store, **0600**; 记录里只引用 secretRef
+ *   sent.json              SendRecord[]       (requestId 去重 + 回信关联)
+ *   ledger.jsonl           只追加的通信台账 (脱敏, 可回放)
+ *   outbox/                本地投递通道 (provider=local-sink) 的真落盘目录
+ *
+ * 纪律:
+ *   - 所有写都是 tmp + rename (原子); secrets.json 额外 chmod 0600。
+ *   - 读失败**不吞成空**: 解析损坏时抛/标记, 由调用方决定, 不许静默当成"没有联系方式"。
+ *   - 任何对外返回值都先过 `maskContact()` —— 明文只在本层内部流转。
+ */
+import * as fs from 'fs';
+import * as fsp from 'fs/promises';
+import * as os from 'os';
+import * as path from 'path';
+import { displayFor, newIdentityId, } from './types.js';
+const home = () => process.env.HOME || os.homedir() || '/tmp';
+export function contactsDir(homeDir) {
+    return path.join(homeDir || home(), '.bolloon', 'contacts');
+}
+const f = (dir, name) => path.join(dir, name);
+// ── 原子写 + 权限 ───────────────────────────────────────────────────────────
+async function writeJsonAtomic(file, data, mode) {
+    // 目录可能还没建 (例如首个动作就是写 secret) → 先建, 否则 rename 必 ENOENT
+    await fsp.mkdir(path.dirname(file), { recursive: true });
+    const tmp = `${file}.tmp-${process.pid}-${Date.now().toString(36)}`;
+    await fsp.writeFile(tmp, JSON.stringify(data, null, 2), 'utf8');
+    if (mode) {
+        try {
+            await fsp.chmod(tmp, mode);
+        }
+        catch { /* 平台不支持就算了, 但要如实记 */ }
+    }
+    await fsp.rename(tmp, file);
+    if (mode) {
+        try {
+            await fsp.chmod(file, mode);
+        }
+        catch { /* 同上 */ }
+    }
+}
+async function readJson(file) {
+    try {
+        return JSON.parse(await fsp.readFile(file, 'utf8'));
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return null;
+        // 损坏的文件绝不静默当空: 抛出去, 让上层报 degraded
+        throw new Error(`联系方式存储损坏 (${file}): ${err?.message || err}`);
+    }
+}
+/** 任何离开 store 的联系方式都要走这里 (明文 → 脱敏) */
+export function maskContact(c) {
+    const { normalizedValue: _drop, consentScope: _scope, secretRef: _ref, ...rest } = c;
+    return { ...rest, displayValue: c.displayValue || displayFor(c.kind, c.normalizedValue) };
+}
+export class SecretStore {
+    dir;
+    constructor(dir) { this.dir = dir; }
+    file() { return f(this.dir, 'secrets.json'); }
+    async list() {
+        const all = (await readJson(this.file())) || [];
+        return all.map(({ value: _v, ...rest }) => rest);
+    }
+    /** 真值只在这里出现; 调用方只能是 provider 适配器 */
+    async get(ref) {
+        if (!ref)
+            return null;
+        const all = (await readJson(this.file())) || [];
+        return all.find((s) => s.ref === ref) || null;
+    }
+    async put(ref, provider, value) {
+        const all = (await readJson(this.file())) || [];
+        const i = all.findIndex((s) => s.ref === ref);
+        const entry = { ref, provider, value, createdAt: all[i]?.createdAt || new Date().toISOString(), lastVerifiedAt: all[i]?.lastVerifiedAt };
+        if (i >= 0)
+            all[i] = entry;
+        else
+            all.push(entry);
+        await writeJsonAtomic(this.file(), all, 0o600);
+    }
+    async remove(ref) {
+        const all = (await readJson(this.file())) || [];
+        await writeJsonAtomic(this.file(), all.filter((s) => s.ref !== ref), 0o600);
+    }
+    async has(ref) { return !!(await this.get(ref)); }
+}
+// ── 主 store ────────────────────────────────────────────────────────────────
+export class ContactsStore {
+    dir;
+    secrets;
+    constructor(homeDir) {
+        this.dir = contactsDir(homeDir);
+        this.secrets = new SecretStore(this.dir);
+    }
+    async ensureDirs() {
+        await fsp.mkdir(this.dir, { recursive: true });
+        await fsp.mkdir(f(this.dir, 'outbox'), { recursive: true });
+    }
+    // ── 身份 ──────────────────────────────────────────────────────────────────
+    async getIdentity(ownerDid) {
+        const ids = (await readJson(f(this.dir, 'social-identity.json'))) || [];
+        return ids.find((i) => i.ownerDid === ownerDid) || null;
+    }
+    async ensureIdentity(ownerDid, displayName = '') {
+        await this.ensureDirs();
+        const file = f(this.dir, 'social-identity.json');
+        const ids = (await readJson(file)) || [];
+        let id = ids.find((i) => i.ownerDid === ownerDid);
+        if (!id) {
+            id = {
+                identityId: newIdentityId(),
+                ownerDid,
+                displayName,
+                verifiedContacts: [],
+                privacyPolicy: {
+                    plaintextVisibleToAgent: false,
+                    batchAllowed: false,
+                    note: '明文联系方式不进 prompt/Run/Git; 外部只看到 已验证/可联系/不可联系/需要重新授权',
+                },
+                createdAt: new Date().toISOString(),
+                updatedAt: new Date().toISOString(),
+            };
+            ids.push(id);
+        }
+        await writeJsonAtomic(file, ids);
+        return id;
+    }
+    // ── 联系方式 ──────────────────────────────────────────────────────────────
+    async listContacts(opts = {}) {
+        const all = (await readJson(f(this.dir, 'contacts.json'))) || [];
+        return opts.identityId ? all.filter((c) => c.identityId === opts.identityId) : all;
+    }
+    async getContact(contactId) {
+        return (await this.listContacts()).find((c) => c.contactId === contactId) || null;
+    }
+    /** 内部用 —— 拿明文值 (只有 provider / 回信校验该调) */
+    async getNormalized(contactId) {
+        const c = await this.getContact(contactId);
+        return c ? c.normalizedValue : null;
+    }
+    async putContact(c) {
+        await this.ensureDirs();
+        const file = f(this.dir, 'contacts.json');
+        const all = (await readJson(file)) || [];
+        const i = all.findIndex((x) => x.contactId === c.contactId);
+        c.updatedAt = new Date().toISOString();
+        if (i >= 0)
+            all[i] = c;
+        else
+            all.push(c);
+        // 2026-09-19: contacts.json 里存 normalizedValue (真发信要用它), 所以按 0600 落盘 ——
+        //   明文联系方式不该有"随便能被别人读"的副本; Run/Goal/ledger 里永远只有脱敏值。
+        await writeJsonAtomic(file, all, 0o600);
+        // 身份里的 verifiedContacts 跟着走
+        const sf = f(this.dir, 'social-identity.json');
+        const ids = (await readJson(sf)) || [];
+        const idIdx = ids.findIndex((x) => x.identityId === c.identityId);
+        if (idIdx >= 0) {
+            const list = new Set(ids[idIdx].verifiedContacts);
+            if (c.verificationStatus === 'verified' && !c.revokedAt)
+                list.add(c.contactId);
+            else
+                list.delete(c.contactId);
+            ids[idIdx].verifiedContacts = [...list];
+            ids[idIdx].updatedAt = new Date().toISOString();
+            await writeJsonAtomic(sf, ids);
+        }
+        return c;
+    }
+    /** 按 contactId → DID → 明确名称/别名 匹配 (禁止模糊姓名自动发送) */
+    async resolve(opts) {
+        const all = (await this.listContacts({ identityId: opts.identityId })).filter((c) => !c.revokedAt);
+        if (opts.contactId) {
+            const hit = all.find((c) => c.contactId === opts.contactId);
+            return { contact: hit || null, by: hit ? 'contactId' : 'none' };
+        }
+        if (opts.did) {
+            const hits = all.filter((c) => c.peerDid && c.peerDid === opts.did);
+            if (hits.length === 1)
+                return { contact: hits[0], by: 'did' };
+            if (hits.length > 1)
+                return { contact: null, by: 'none', ambiguous: true };
+        }
+        if (opts.name) {
+            const n = opts.name.trim().toLowerCase();
+            const hits = all.filter((c) => (c.aliases || []).some((a) => a.trim().toLowerCase() === n));
+            if (hits.length === 1)
+                return { contact: hits[0], by: 'name' };
+            if (hits.length > 1)
+                return { contact: null, by: 'none', ambiguous: true };
+        }
+        return { contact: null, by: 'none' };
+    }
+    // ── 发送台账 (去重 + 回信关联) ─────────────────────────────────────────────
+    async listSends() {
+        return (await readJson(f(this.dir, 'sent.json'))) || [];
+    }
+    /** 同一 requestId 已发过 → 返回旧记录 (调用方必须拒绝重复发送) */
+    async findSend(requestId) {
+        return (await this.listSends()).find((s) => s.requestId === requestId) || null;
+    }
+    async findSendByThread(threadToken) {
+        return (await this.listSends()).find((s) => s.threadToken === threadToken) || null;
+    }
+    async recordSend(rec) {
+        await this.ensureDirs();
+        const file = f(this.dir, 'sent.json');
+        const all = await this.listSends();
+        all.push(rec);
+        await writeJsonAtomic(file, all.slice(-500));
+    }
+    async patchSend(requestId, patch) {
+        const file = f(this.dir, 'sent.json');
+        const all = await this.listSends();
+        const i = all.findIndex((s) => s.requestId === requestId);
+        if (i < 0)
+            return;
+        all[i] = { ...all[i], ...patch };
+        await writeJsonAtomic(file, all.slice(-500));
+    }
+    /** 当天该 contact 的发送条数 (速率限制真值) */
+    async countSentToday(contactId, now = Date.now()) {
+        const day = new Date(now).toISOString().slice(0, 10);
+        return (await this.listSends()).filter((s) => s.contactId === contactId && s.sentAt.slice(0, 10) === day && s.status === 'sent').length;
+    }
+    async countSentForGoal(goalId) {
+        return (await this.listSends()).filter((s) => s.goalId === goalId && s.status === 'sent').length;
+    }
+    async markUsed(contactId) {
+        const c = await this.getContact(contactId);
+        if (!c)
+            return;
+        c.lastUsedAt = new Date().toISOString();
+        await this.putContact(c);
+    }
+    // ── 待批准正文 (用户内容, 0600, 发完即删) ───────────────────────────────────
+    /** 待批准时把真实正文暂存起来 —— consents.json 里只放脱敏预览 */
+    async putPendingBody(requestId, body, subject, exec) {
+        const file = path.join(this.dir, 'pending', `${requestId}.json`);
+        // 2026-09-19: 执行参数 (是否等回复 / 等多久) 必须和正文一起留下来 ——
+        //   否则"批准后执行"会退回默认 48h, 把用户/任务指定的等待窗口丢掉 (真跑抓到过)。
+        await writeJsonAtomic(file, {
+            requestId, body, subject, replyExpected: exec?.replyExpected, replyWindowMs: exec?.replyWindowMs,
+            createdAt: new Date().toISOString(),
+        }, 0o600);
+    }
+    async getPendingBody(requestId) {
+        try {
+            const raw = JSON.parse(await fsp.readFile(path.join(this.dir, 'pending', `${requestId}.json`), 'utf8'));
+            return { body: String(raw?.body || ''), subject: raw?.subject, replyExpected: raw?.replyExpected, replyWindowMs: raw?.replyWindowMs };
+        }
+        catch {
+            return null;
+        }
+    }
+    async clearPendingBody(requestId) {
+        try {
+            await fsp.unlink(path.join(this.dir, 'pending', `${requestId}.json`));
+        }
+        catch { /* 没有就算了 */ }
+    }
+    // ── 台账 (只追加) ─────────────────────────────────────────────────────────
+    evidenceRefFor(contactId, activity, ts) {
+        return `contact:${contactId}@${ts}#${activity}`;
+    }
+    async appendLedger(entry) {
+        await this.ensureDirs();
+        const full = {
+            ...entry,
+            detail: String(entry.detail || '').slice(0, 300),
+            evidenceRef: entry.evidenceRef || this.evidenceRefFor(entry.contactId || '-', entry.activity, entry.ts),
+        };
+        await fsp.appendFile(f(this.dir, 'ledger.jsonl'), JSON.stringify(full) + '\n', 'utf8');
+        return full;
+    }
+    async readLedger(opts = {}) {
+        try {
+            const raw = await fsp.readFile(f(this.dir, 'ledger.jsonl'), 'utf8');
+            let rows = raw.split('\n').filter(Boolean).map((l) => { try {
+                return JSON.parse(l);
+            }
+            catch {
+                return null;
+            } }).filter(Boolean);
+            if (opts.contactId)
+                rows = rows.filter((r) => r.contactId === opts.contactId);
+            if (opts.goalId)
+                rows = rows.filter((r) => r.goalId === opts.goalId);
+            return opts.limit ? rows.slice(-opts.limit) : rows;
+        }
+        catch (err) {
+            if (err?.code === 'ENOENT')
+                return [];
+            throw err;
+        }
+    }
+}
+/** 单例 (默认 HOME); 测试要隔离时直接 new ContactsStore(tmpHome) */
+let _default = null;
+export function contactsStore(homeDir) {
+    if (homeDir)
+        return new ContactsStore(homeDir);
+    if (!_default)
+        _default = new ContactsStore();
+    return _default;
+}
+export function resetContactsStore() { _default = null; }
+/** 文件权限自检 (doctor 用): secrets.json 必须 0600 */
+export async function secretsFileMode(homeDir) {
+    const p = f(contactsDir(homeDir), 'secrets.json');
+    try {
+        const st = fs.statSync(p);
+        const mode = (st.mode & 0o777).toString(8);
+        return { path: p, mode, ok: mode === '600' };
+    }
+    catch {
+        return { path: p, mode: null, ok: true }; // 还没有 secret = 不算问题
+    }
+}

package/dist/agents/contacts/tools.js

@@ -0,0 +1,154 @@
+/**
+ * contacts/tools.ts — 暴露给 Agent 的联系工具 (2026-09-19, Phase 8)
+ *
+ * 设计铁律:
+ *   - Agent **拿不到**手机号/邮箱原文, 只能拿 `contactId` + 脱敏 displayValue。
+ *   - Agent **不能**指定任意收件人地址 —— 只能指定已授权 contactId (或已在别名表里的名字)。
+ *   - 每个工具都经 policy 判定, 返回里带 blockKind / requiresApproval, 不吞掉拒绝原因。
+ *
+ * 六个工具: contact.list_authorized / preview / request_consent / send / await_reply / revoke
+ */
+export const CONTACT_TOOL_NAMES = [
+    'contact.list_authorized',
+    'contact.preview',
+    'contact.request_consent',
+    'contact.send',
+    'contact.await_reply',
+    'contact.revoke',
+];
+function text(v) { return String(v ?? '').trim(); }
+export function registerContactTools(ctx, chain) {
+    const registered = [];
+    ctx.tools.set('contact.list_authorized', {
+        name: 'contact.list_authorized',
+        description: '列出已授权可联系的联系方式 (只返回脱敏值: 联系人不给完整手机号/邮箱)。需要联系某人先调这个; 拿到的 contactId 才能用于发送。',
+        parameters: {},
+        execute: async () => {
+            const list = await chain.listAuthorized();
+            return {
+                success: true,
+                contacts: list,
+                channels: chain.channels(),
+                note: list.length ? '只能对这里列出的 contactId 发送; 未验证/已撤销的一律发不出去' : '还没有任何已绑定的联系方式 —— 需要用户在 CLI/桌面/手机上先绑定并验证',
+            };
+        },
+    });
+    ctx.tools.set('contact.preview', {
+        name: 'contact.preview',
+        description: '生成一份可审计的发送预览 (联系人/通道/收件人脱敏/任务/权限/是否需要人工批准), 不发送任何东西。',
+        parameters: {
+            contactId: '联系人 id (必填, 来自 contact.list_authorized)',
+            body: '正文 (必填)',
+            subject: '主题 (可选, 邮箱用)',
+            goalId: '关联的长期任务 id (可选但强烈建议; 未绑定的任务联系人会被拒绝)',
+        },
+        execute: async (args) => {
+            const contactId = text(args.contactId);
+            if (!contactId)
+                return { success: false, error: 'contactId 必填 (不允许按姓名直接发送)' };
+            const { decision, text: rendered } = await chain.preview({
+                contactId, body: text(args.body), subject: text(args.subject) || undefined, goalId: text(args.goalId) || undefined,
+            });
+            return {
+                success: true,
+                preview: rendered,
+                allowed: decision.allowed,
+                blockKind: decision.blockKind,
+                reason: decision.reason,
+                requiresApproval: decision.requiresApproval,
+                reallySent: decision.reallySent,
+            };
+        },
+    });
+    const sendLike = (name, description) => async (args) => {
+        const contactId = text(args.contactId);
+        if (!contactId)
+            return { success: false, error: 'contactId 必填 (不允许按姓名直接发送; 用 contact.list_authorized 拿 id)' };
+        const res = await chain.send({
+            contactId,
+            goalId: text(args.goalId) || undefined,
+            runId: text(args.runId) || undefined,
+            taskKind: text(args.taskKind) || undefined,
+            subject: text(args.subject) || undefined,
+            body: text(args.body),
+            requestId: text(args.requestId) || undefined,
+            replyExpected: args.replyExpected !== false,
+        });
+        const ok = res.status === 'sent' || res.status === 'awaiting_reply';
+        return {
+            success: ok,
+            status: res.status,
+            reason: res.reason,
+            blockKind: res.blockKind,
+            requestId: res.requestId,
+            consentId: res.consentId,
+            preview: res.preview,
+            evidenceRef: res.evidenceRef,
+            goalStatus: res.goalStatus,
+            // 让 Agent 说人话: 被拒/等批准时必须如实转述, 不许假装已发送
+            note: res.status === 'awaiting_approval'
+                ? '已生成待批准请求: 需要用户在 CLI/桌面/手机点批准后才会真正发送 (首次联系/敏感内容/策略要求时必然如此)'
+                : res.status === 'denied' ? `被策略拒绝 (${res.blockKind}): ${res.reason}` : undefined,
+        };
+    };
+    const sendParams = {
+        contactId: '联系人 id (必填)',
+        body: '正文 (必填)',
+        subject: '主题 (可选)',
+        goalId: '长期任务 id (任务绑定联系人必须给)',
+        runId: '当前 Run id (可选; 通信证据会写进这个 Run)',
+        requestId: '幂等 id (可选; 同一个 requestId 绝不会重复发送)',
+        replyExpected: '是否等待回复 (默认 true; goalId 存在时会绑定外部等待)',
+    };
+    ctx.tools.set('contact.send', {
+        name: 'contact.send',
+        description: '联系一个人 (手机号/邮箱): 经策略判定 —— 首次联系/敏感内容需要用户批准, 批量永远禁止, 未验证/已撤销一律拒绝。发送成功后若等待回复, 任务会进入 awaiting_external。',
+        parameters: sendParams,
+        execute: sendLike('contact.send', ''),
+    });
+    ctx.tools.set('contact.request_consent', {
+        name: 'contact.request_consent',
+        description: '就某次联系向用户请求授权 (不发送): 生成待批准请求 + 可审计预览, 用户批准后才发送。',
+        parameters: sendParams,
+        execute: sendLike('contact.request_consent', ''),
+    });
+    ctx.tools.set('contact.await_reply', {
+        name: 'contact.await_reply',
+        description: '查看某次联系是否在等待回复 / 是否已收到回复 / 是否超时 (只读)。',
+        parameters: { requestId: '发送时拿到的 requestId (必填)' },
+        execute: async (args) => {
+            const requestId = text(args.requestId);
+            if (!requestId)
+                return { success: false, error: 'requestId 必填' };
+            const rec = await chain.store.findSend(requestId);
+            if (!rec)
+                return { success: false, error: `没有 requestId=${requestId} 的发送记录` };
+            const ledger = await chain.store.readLedger({ limit: 200 });
+            const mine = ledger.filter((l) => l.detail.includes(requestId) || (l.contactId === rec.contactId && l.goalId === rec.goalId));
+            return {
+                success: true,
+                status: rec.status,
+                goalId: rec.goalId,
+                sentAt: rec.sentAt,
+                replied: mine.some((l) => l.activity === 'contact.reply_received'),
+                timedOut: mine.some((l) => l.activity === 'contact.wait_expired'),
+                provider: rec.provider,
+                evidence: mine.slice(-5).map((l) => ({ activity: l.activity, ts: l.ts, detail: l.detail, evidenceRef: l.evidenceRef })),
+            };
+        },
+    });
+    ctx.tools.set('contact.revoke', {
+        name: 'contact.revoke',
+        description: '撤销某个联系方式的授权 (用户级动作; 撤销后历史证据保留但后续调用一律拒绝)。',
+        parameters: { contactId: '联系人 id (必填)', reason: '撤销原因 (可选)' },
+        execute: async (args) => {
+            const contactId = text(args.contactId);
+            if (!contactId)
+                return { success: false, error: 'contactId 必填' };
+            const r = await chain.revoke({ contactId, by: 'agent_request', reason: text(args.reason) || undefined });
+            return { success: r.ok, error: r.error, affectedGoals: r.affectedGoals, evidenceRef: r.evidenceRef };
+        },
+    });
+    registered.push(...CONTACT_TOOL_NAMES);
+    return registered;
+}

package/dist/agents/contacts/types.js

@@ -0,0 +1,148 @@
+/**
+ * contacts/types.ts — 社交身份模型 (2026-09-19, Phase 0/1)
+ *
+ * 核心定义 (leo 冻结):
+ *   Bolloon 的社交身份 = **DID 主身份 + 已验证联系方式 + 联系能力 Skill + 调用权限 + 可恢复任务证据**,
+ *   不是"公开手机号/邮箱"。外部只看到四类状态: 已验证 / 可联系 / 不可联系 / 需要重新授权。
+ *
+ * 硬规则 (贯穿本目录所有文件):
+ *   1. 明文手机号/邮箱**不进**普通 Run step、不进 prompt、不进 Git; 只有 displayValue(脱敏) 可以。
+ *   2. 密钥 (API key / OAuth refresh / SMTP 密码) 只存 Secret Store, 记录里只留 secretRef。
+ *   3. Goal/Run 只保存 contactId / provider / 动作 / 状态 / 证据引用。
+ *   4. 未验证的联系方式**任何情况下**不能被用于真实发送。
+ *   5. 撤销后历史证据保留, 但后续调用一律拒绝。
+ */
+export const DEFAULT_LIMITS = { dailyMax: 5, perTaskMax: 3, requireApprovalEachTime: false };
+// ── 规范化 ──────────────────────────────────────────────────────────────────
+const CC = {
+    CN: '86', US: '1', CA: '1', JP: '81', GB: '44', DE: '49', FR: '33', IN: '91', AU: '61', SG: '65', KR: '82', RU: '7',
+};
+export function normalizePhone(input, defaultRegion = '') {
+    const raw = String(input || '').trim();
+    if (!raw)
+        return { ok: false, error: 'empty' };
+    const plus = raw.startsWith('+');
+    const digits = raw.replace(/[^\d]/g, '');
+    if (digits.length < 4)
+        return { ok: false, error: 'too_short' };
+    let e164;
+    if (plus) {
+        e164 = `+${digits}`;
+    }
+    else {
+        const cc = CC[(defaultRegion || '').toUpperCase()];
+        if (!cc)
+            return { ok: false, error: 'region_required' };
+        const local = digits.replace(/^0+/, '');
+        e164 = `+${cc}${local}`;
+    }
+    const numDigits = e164.length - 1;
+    if (numDigits < 8 || numDigits > 15)
+        return { ok: false, error: 'invalid_length' };
+    return { ok: true, value: e164 };
+}
+export function normalizeEmail(input) {
+    const raw = String(input || '').trim().toLowerCase();
+    if (!raw)
+        return { ok: false, error: 'empty' };
+    if (/\s/.test(raw))
+        return { ok: false, error: 'contains_space' };
+    const m = raw.match(/^([^@]+)@([^@]+\.[^@.]+)$/);
+    if (!m)
+        return { ok: false, error: 'invalid_format' };
+    if (m[1].length > 64)
+        return { ok: false, error: 'local_part_too_long' };
+    return { ok: true, value: `${m[1]}@${m[2]}` };
+}
+/** 脱敏展示值 —— 唯一允许出现在 prompt / evidence / Web UI 的形态 */
+export function maskPhone(e164) {
+    const digits = e164.replace(/[^\d]/g, '');
+    if (digits.length <= 6)
+        return `+${'*'.repeat(Math.max(0, digits.length - 2))}${digits.slice(-2)}`;
+    return `+${digits.slice(0, 2)}******${digits.slice(-4)}`;
+}
+export function maskEmail(email) {
+    const [local, domain] = String(email).split('@');
+    if (!domain)
+        return '***';
+    const head = local.slice(0, 1);
+    return `${head}${'*'.repeat(Math.max(1, Math.min(6, local.length - 1)))}@${domain}`;
+}
+export function displayFor(kind, normalized) {
+    return kind === 'phone' ? maskPhone(normalized) : maskEmail(normalized);
+}
+/** 内部状态 → 外部四类状态 (Phase 0: 外部只看到这四个) */
+export function externalStatusOf(c) {
+    if (c.revokedAt || c.verificationStatus === 'revoked')
+        return 'reauth_required';
+    if (c.verificationStatus === 'blocked' || c.verificationStatus === 'expired')
+        return 'not_contactable';
+    if (c.verificationStatus === 'verified') {
+        return c.capabilities.includes('send') && c.policy !== 'draft_only' ? 'contactable' : 'verified';
+    }
+    return 'not_contactable';
+}
+export function scanSensitive(text) {
+    const out = [];
+    const s = String(text || '');
+    const push = (kind, hint) => {
+        if (!out.some((f) => f.kind === kind && f.hint === hint))
+            out.push({ kind, hint });
+    };
+    // 卡号: 13-19 位连续数字 (允许空格/横线分隔)
+    for (const m of s.matchAll(/\b(?:\d[ -]?){13,19}\b/g)) {
+        const digits = m[0].replace(/[^\d]/g, '');
+        if (digits.length >= 13 && digits.length <= 19)
+            push('card_number', `${digits.slice(0, 4)}…${digits.slice(-4)}`);
+    }
+    // 中国大陆身份证: 17 位 + 数字/X
+    for (const m of s.matchAll(/\b\d{17}[\dXx]\b/g))
+        push('id_number_cn', `${m[0].slice(0, 4)}…${m[0].slice(-2)}`);
+    // API key / token
+    for (const m of s.matchAll(/\b(sk-[A-Za-z0-9]{12,}|AKIA[0-9A-Z]{12,}|ghp_[A-Za-z0-9]{20,}|npm_[A-Za-z0-9]{20,})\b/g)) {
+        push('api_key', `${m[0].slice(0, 6)}…`);
+    }
+    if (/(密码|password|passwd|pwd)\s*[:：=]\s*\S+/i.test(s))
+        push('password', '疑似密码明文');
+    // 一次性验证码: 只在出现"验证码/otp/code"上下文时才算
+    if (/(验证码|动态码|one[-\s]?time|otp)\D{0,8}\d{4,8}/i.test(s))
+        push('otp_code', '疑似一次性验证码');
+    // 银行账号: 10-17 位且上下文含"账号/account"
+    if (/(账号|账户|account|iban)\D{0,6}\d{10,17}/i.test(s))
+        push('bank_account', '疑似银行账号');
+    return out;
+}
+/**
+ * 永不由联系方式授权放行的内容类别 (2026-09-19, Phase 6):
+ *   凭证 / 资金指令 / 合同承诺 —— 即使 full_contact_access 也拒绝, 它们属于另一类高风险能力。
+ */
+export function scanForbidden(text) {
+    const s = String(text || '');
+    const out = new Set();
+    if (/\b(sk-[A-Za-z0-9]{12,}|AKIA[0-9A-Z]{12,}|ghp_[A-Za-z0-9]{20,}|npm_[A-Za-z0-9]{20,})\b/.test(s))
+        out.add('api_key');
+    if (/(密码|password|passwd|pwd)\s*[:：=]\s*\S+/i.test(s))
+        out.add('password');
+    if (/(账号|账户|account|iban)\D{0,6}\d{10,17}/i.test(s))
+        out.add('bank_account');
+    if (/(转账|打款|汇款|付款指令|支付授权|remit|wire transfer|pay\s+to|send\s+funds)/i.test(s))
+        out.add('payment_instruction');
+    if (/(签署合同|签订合同|签合同|同意采购|承诺下单|sign\s+(the\s+)?(contract|agreement)|binding\s+commitment)/i.test(s))
+        out.add('contract_commitment');
+    return [...out];
+}
+/** 发送前把正文里明显的口令类内容打码 (预览与证据都走这个) */
+export function redactForEvidence(text) {
+    let s = String(text || '');
+    s = s.replace(/\b\d[ -]?(?:\d[ -]?){12,18}\d\b/g, (m) => `${m.replace(/[^\d]/g, '').slice(0, 4)}…<卡号已打码>`);
+    s = s.replace(/\b(sk-|AKIA|ghp_|npm_)[A-Za-z0-9_-]{8,}\b/g, '<密钥已打码>');
+    s = s.replace(/\b\d{17}[\dXx]\b/g, '<身份证已打码>');
+    return s;
+}
+// ── id 生成 ─────────────────────────────────────────────────────────────────
+const rid = (n = 8) => Math.random().toString(36).slice(2, 2 + n);
+export const newContactId = (kind) => `ct-${kind}-${Date.now().toString(36)}-${rid(4)}`;
+export const newIdentityId = () => `sid-${Date.now().toString(36)}-${rid(4)}`;
+export const newRequestId = () => `creq-${Date.now().toString(36)}-${rid(6)}`;
+export const newThreadToken = () => `thr-${rid(20)}`;
+export const newEventId = () => `cev-${Date.now().toString(36)}-${rid(6)}`;

package/dist/agents/pi-sdk.js

@@ -45,6 +45,8 @@ export { TOOL_DEFINITIONS, } from './pi-sdk-types.js';
 export { PiSessionManager } from './pi-sdk-session-manager.js';
 import { PiSessionManager } from './pi-sdk-session-manager.js';
 import { registerBuiltinTools, registerWalletTools, setupInboxListener, IdempotencyCache, } from './pi-sdk-tools.js';
+import { registerContactTools } from './contacts/tools.js';
+import { ContactChain } from './contacts/chain.js';
 export { createAgentSession, getAgentSession, resetAgentSession, runSelfImproveLoop, } from './pi-sdk-session-factory.js';
 // Judgment 注入门 (P0): 在主对话 LLM 调起前自动拼入 Top 3 判断力
 // 失败静默, 不阻塞主对话
@@ -575,6 +577,14 @@ export class PiAgentSession {
             },
         };
         registerBuiltinTools(toolCtx);
+        // 2026-09-19: 联系方式工具 (手机/邮箱) —— Agent 拿不到明文, 只能给 contactId;
+        //   所有调用都要过 contacts/policy (首次联系/敏感内容需人工批准, 批量永远禁止)。
+        try {
+            registerContactTools(toolCtx, new ContactChain({ ownerDid: this.identity?.did || 'did:bolln:local' }));
+        }
+        catch (err) {
+            console.warn('[contacts] 注册联系工具失败 (非致命, 该能力不可用):', err?.message || err);
+        }
         registerWalletTools(toolCtx);
         setupInboxListener(toolCtx);
         // 镜像到 ToolRegistry (alias resolve 用)