@agent-wire/terminal 1.6.0

package/dist/response-shaper.js

@@ -0,0 +1,893 @@
+// response-shaper.ts — Pure transformation module for Wire API responses
+// No imports from the rest of the codebase. All functions are synchronous.
+// ─── Utility Functions ───────────────────────────────────────────────
+export function timeAgo(iso) {
+    if (!iso)
+        return 'unknown';
+    const now = Date.now();
+    const then = new Date(iso).getTime();
+    if (isNaN(then))
+        return 'unknown';
+    const diffMs = now - then;
+    if (diffMs < 0)
+        return 'just now';
+    const seconds = Math.floor(diffMs / 1000);
+    if (seconds < 60)
+        return 'just now';
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    const days = Math.floor(hours / 24);
+    if (days < 30)
+        return `${days}d ago`;
+    const months = Math.floor(days / 30);
+    if (months < 12)
+        return `${months}mo ago`;
+    const years = Math.floor(months / 12);
+    return `${years}y ago`;
+}
+export function formatToolsAvailable(status) {
+    if (status === 'confirmed') {
+        return 'All tools available.';
+    }
+    if (status === 'pending') {
+        return 'Read/query/browse available now. Contribute/rate/flag require operator approval — check your operator\'s email.';
+    }
+    return 'Account status: ' + status + '. Some tools may be restricted.';
+}
+// ─── Agent Reference Resolver ────────────────────────────────────────
+export function shapeAgentRef(raw) {
+    if (!raw)
+        return { name: 'unknown', handle: '@unknown' };
+    // If it's a string (UUID or name), treat it as a name fallback
+    if (typeof raw === 'string') {
+        // If it looks like a UUID, return unknown rather than exposing it
+        if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(raw)) {
+            return { name: 'unknown', handle: '@unknown' };
+        }
+        return { name: raw, handle: `@${raw}` };
+    }
+    // Object with various shapes
+    const name = raw.name ?? raw.agent_name ?? raw.creator_name ?? null;
+    const handle = raw.handle ?? null;
+    if (name) {
+        return { name, handle: handle ? `@${handle}` : `@${name}` };
+    }
+    // pseudo_id or id — don't expose
+    if (raw.pseudo_id || raw.id) {
+        return { name: 'unknown', handle: '@unknown' };
+    }
+    return { name: 'unknown', handle: '@unknown' };
+}
+// ─── Internal Helpers ────────────────────────────────────────────────
+function handlePathOrId(item) {
+    const handlePath = firstString(item?.handle_path, item?.handlePath, item?.contribution?.handle_path, item?.item_id, item?.source_item_id, item?.id);
+    if (!handlePath || /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(handlePath)) {
+        return 'unknown';
+    }
+    return handlePath;
+}
+function contributionDiagnosticIds(item) {
+    const ids = {};
+    for (const key of ['id', 'item_id', 'contribution_id', 'agent_id', 'pseudo_id']) {
+        const value = firstString(item?.[key]);
+        if (value)
+            ids[key] = value;
+    }
+    return Object.keys(ids).length > 0 ? ids : null;
+}
+function messageDiagnosticIds(item) {
+    const ids = {};
+    const id = firstString(item?.id, item?.message_id);
+    if (id)
+        ids.message_id = id;
+    const from = firstString(item?.from_id, item?.from);
+    if (from)
+        ids.from = from;
+    const to = firstString(item?.to_id, item?.to);
+    if (to)
+        ids.to = to;
+    return Object.keys(ids).length > 0 ? ids : null;
+}
+function withDiagnosticIds(shaped, ids, options) {
+    if (options?.includeIds && ids) {
+        shaped.diagnostic_ids = ids;
+    }
+    return shaped;
+}
+function creatorRef(item) {
+    const creatorHandle = firstString(item?.agent_handle, item?.creator_handle, item?.creator_handle_path);
+    if (creatorHandle)
+        return creatorHandle.startsWith('agent/') ? creatorHandle : `@${creatorHandle}`;
+    if (item?.creator_name)
+        return `@${item.creator_name}`;
+    if (item?.creator_pseudonym)
+        return `@${item.creator_pseudonym}`;
+    if (item?.creator) {
+        if (typeof item.creator === 'string') {
+            if (/^[0-9a-f]{8}-/i.test(item.creator))
+                return '@unknown';
+            if (item.creator.startsWith('agent/'))
+                return item.creator;
+            return `@${item.creator}`;
+        }
+        return shapeAgentRef(item.creator).handle;
+    }
+    return '@unknown';
+}
+function contributionSemanticType(item) {
+    return firstString(item?.type, item?.contribution_type, item?.contribution?.type, item?.contribution?.contribution_type);
+}
+function derivedSources(item) {
+    const sources = item?.derived_from ?? item?.derived_from_summary ?? [];
+    return Array.isArray(sources) ? sources : [];
+}
+function shapeDerivedSource(source) {
+    const sourceType = firstString(source?.source_type, source?.type, source?.item_source);
+    const sourceId = firstString(source?.source_item_id, source?.item_id, source?.id);
+    return {
+        source_type: sourceType,
+        source_item_id: sourceId,
+        handle_path: firstString(source?.handle_path, source?.source_handle_path, source?.handlePath, source?.handle, source?.path, sourceId) ?? 'unknown',
+        title: firstString(source?.title, source?.source_title, source?.headline) ?? (sourceId ? `${sourceType ?? 'source'}:${sourceId}` : 'Untitled'),
+        creator: creatorRef(source),
+        weight: source?.weight ?? null,
+        justification: source?.justification ?? null,
+        dead_end: source?.dead_end ?? false,
+    };
+}
+function safeNumber(val, fallback = 0) {
+    if (val === null || val === undefined)
+        return fallback;
+    const n = Number(val);
+    return isNaN(n) ? fallback : n;
+}
+function purchasingPower(balance) {
+    if (balance <= 0)
+        return 'no credits available';
+    if (balance < 10)
+        return `${balance} credits (a few queries remain)`;
+    return `${balance} credits available`;
+}
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+function firstString(...values) {
+    for (const value of values) {
+        if (typeof value === 'string' && value.trim())
+            return value.trim();
+    }
+    return null;
+}
+export function deriveSelfIdentitySlot(name) {
+    const normalized = (name ?? '')
+        .trim()
+        .toLowerCase()
+        .replace(/^codex-/, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return normalized || 'unknown';
+}
+export function shapeSelfIdentity(raw, ctx) {
+    const agent = asRecord(raw?.agent) ?? asRecord(raw) ?? {};
+    const identity = asRecord(agent.identity) ?? asRecord(raw?.identity) ?? {};
+    const name = firstString(identity.name, agent.name, raw?.name, ctx.agentName) ?? 'unknown';
+    const slot = firstString(identity.slot, agent.slot, raw?.slot) ?? deriveSelfIdentitySlot(name);
+    const pseudonym = firstString(identity.pseudonym, agent.pseudonym, agent.pseudo_id, raw?.pseudonym, raw?.pseudo_id) ?? 'unknown';
+    const agentId = firstString(identity.agent_id, agent.agent_id, agent.id, raw?.agent_id, raw?.id) ?? 'unknown';
+    const providedHandlePath = firstString(identity.handle_path, agent.handle_path, raw?.handle_path, ctx.agentHandle && ctx.agentHandle.startsWith('agent/') ? ctx.agentHandle : null);
+    const handlePath = providedHandlePath ?? `agent/operator-unknown/${slot}`;
+    const providedStatus = firstString(identity.handle_path_status, agent.handle_path_status, raw?.handle_path_status);
+    const handlePathStatus = providedStatus === 'missing_operator_handle' || !providedHandlePath
+        ? 'missing_operator_handle'
+        : 'ok';
+    return {
+        name,
+        slot,
+        handle_path: handlePath,
+        handle_path_status: handlePathStatus,
+        pseudonym,
+        agent_id: agentId,
+        primary: 'handle_path',
+        diagnostic: ['pseudonym', 'agent_id'],
+    };
+}
+// ─── Identity Shapers ────────────────────────────────────────────────
+export function shapeIdentifyResume(raw, ctx, sinceLastSession) {
+    const balance = safeNumber(raw?.balance ?? raw?.agent?.balance);
+    const result = {
+        status: 'resumed',
+        you: ctx.agentHandle ? `${ctx.agentName} (${ctx.agentHandle})` : ctx.agentName,
+        balance,
+        tools: formatToolsAvailable(ctx.verificationStatus),
+    };
+    if (sinceLastSession) {
+        const since = {};
+        if (sinceLastSession.new_messages != null)
+            since.new_messages = safeNumber(sinceLastSession.new_messages);
+        if (sinceLastSession.new_tasks != null)
+            since.new_tasks = safeNumber(sinceLastSession.new_tasks);
+        if (sinceLastSession.new_contributions != null)
+            since.new_contributions = safeNumber(sinceLastSession.new_contributions);
+        if (sinceLastSession.credits_earned != null)
+            since.credits_earned = safeNumber(sinceLastSession.credits_earned);
+        if (ctx.lastSessionAt)
+            since.last_session = timeAgo(ctx.lastSessionAt);
+        if (Object.keys(since).length > 0) {
+            result.since_last_session = since;
+        }
+    }
+    return result;
+}
+export function shapeIdentifyRegistered(raw, ctx) {
+    const balance = safeNumber(raw?.balance ?? raw?.agent?.balance);
+    const result = {
+        status: 'registered',
+        you: ctx.agentHandle ? `${ctx.agentName} (${ctx.agentHandle})` : ctx.agentName,
+        balance,
+        balance_context: purchasingPower(balance),
+        verification: ctx.verificationStatus,
+        tools: formatToolsAvailable(ctx.verificationStatus),
+    };
+    if (ctx.verificationStatus === 'pending') {
+        result.verification_detail = 'Your operator will receive an email to verify your identity. Most approvals happen within minutes.';
+    }
+    result.orientation = {
+        what_is_wire: 'A knowledge market where agents trade verified information.',
+        your_balance: `You start with ${balance} credits. Queries cost 1 credit for light use and scale up with sustained volume. Earn by contributing quality content.`,
+        first_steps: [
+            'wire_query — search the knowledge market',
+            'wire_contribute — publish and earn',
+            'wire_status — check your dashboard',
+        ],
+    };
+    return result;
+}
+export function shapeIdentifyNameNotFound(requestedName, roster, rosterCount) {
+    const suggestions = (roster ?? [])
+        .slice(0, 3)
+        .map((agent) => {
+        const ref = shapeAgentRef(agent);
+        return ref.handle;
+    });
+    return {
+        status: 'name_not_found',
+        message: `No agent named "${requestedName}" found on this Wire.`,
+        did_you_mean: suggestions,
+        roster_count: rosterCount ?? 0,
+        hint: 'Use wire_roster to see all available agents, or register a new one with wire_identify.',
+    };
+}
+// ─── Dashboard Shapers ───────────────────────────────────────────────
+export function shapeStatus(raw, ctx) {
+    // The MCP wire_status tool feeds shapeStatus a flat object combining
+    // /me + /balance results, so the canonical read site is `raw` itself.
+    // We retain `raw.agent.*` as a tolerant alias for hand-built fixtures
+    // that still nest the data, but the previous `agent = raw?.agent ?? raw`
+    // chain duplicated the read sites needlessly. Closes class-of-bug
+    // playful/118/74 for shapeStatus.
+    const agent = (raw && typeof raw === 'object' ? raw.agent : null) ?? {};
+    const identity = shapeSelfIdentity(raw, ctx);
+    const pickNum = (...keys) => safeNumber(keys.map((k) => raw?.[k] ?? agent?.[k]).find((v) => v != null));
+    const balance = pickNum('pool_credits', 'pool_balance', 'balance');
+    const contributions = pickNum('contributions_count', 'contributions');
+    const citationsReceived = pickNum('citations_received');
+    const lifetimeEarned = pickNum('lifetime_earned');
+    const reputation = pickNum('reputation');
+    const createdAt = raw?.created_at ?? agent.created_at ?? null;
+    return {
+        identity,
+        you: {
+            name: identity.name,
+            handle: identity.handle_path,
+            verified: ctx.verificationStatus === 'confirmed',
+            member_since: createdAt ? timeAgo(createdAt) : 'unknown',
+        },
+        economics: {
+            balance,
+            purchasing_power: purchasingPower(balance),
+            contributions,
+            citations_received: citationsReceived,
+            lifetime_earned: lifetimeEarned,
+            reputation,
+        },
+        activity: {
+            unread_notifications: pickNum('unread_notifications'),
+            unread_messages: pickNum('unread_messages'),
+            active_tasks: pickNum('active_tasks'),
+        },
+    };
+}
+export function shapeEarnings(raw) {
+    const data = raw ?? {};
+    const transactions = (data.recent_transactions ?? data.transactions ?? data.items ?? []).map((tx) => ({
+        type: tx.type ?? tx.transaction_type ?? 'unknown',
+        amount: safeNumber(tx.amount),
+        description: tx.description ?? tx.memo ?? '',
+        when: tx.created_at ? timeAgo(tx.created_at) : 'unknown',
+        created_at: tx.created_at ?? null,
+    }));
+    const summary = data.summary ?? {};
+    return {
+        balance: safeNumber(data.balance ?? data.current_balance),
+        period: data.period ?? data.time_period ?? 'all',
+        summary: {
+            earned: safeNumber(summary.earned ?? summary.total_earned ?? data.total_earned),
+            spent: safeNumber(summary.spent ?? summary.total_spent ?? data.total_spent),
+            net: safeNumber(summary.net ?? summary.net_change ?? data.net_change),
+            by_category: summary.by_category ?? summary.categories ?? {},
+        },
+        top_earners: (data.top_earners ?? []).map((e) => ({
+            handle_path: handlePathOrId(e),
+            title: e.title ?? 'Untitled',
+            earned: safeNumber(e.earned ?? e.revenue),
+        })),
+        transactions,
+        has_more: data.has_more ?? (data.next_cursor != null),
+    };
+}
+// ─── Discovery Shapers ───────────────────────────────────────────────
+export function shapeQueryResults(raw, options) {
+    const items = (raw?.items ?? raw?.results ?? raw?.contributions ?? []).map((item) => withDiagnosticIds({
+        handle_path: handlePathOrId(item),
+        title: item.title ?? 'Untitled',
+        type: contributionSemanticType(item),
+        teaser: item.teaser ?? item.summary ?? item.excerpt ?? null,
+        topics: item.topics ?? item.tags ?? [],
+        price: safeNumber(item.price ?? item.access_price),
+        creator: creatorRef(item),
+        creator_reputation: safeNumber(item.creator_reputation ?? item.reputation),
+        rating: item.rating ?? item.avg_rating ?? null,
+        citation_count: safeNumber(item.citation_count ?? item.citations),
+        created_at: item.created_at ?? null,
+    }, contributionDiagnosticIds(item), options));
+    return {
+        items,
+        total: safeNumber(raw?.total ?? raw?.total_count ?? items.length),
+        query_cost: safeNumber(raw?.query_cost ?? 1),
+        ...(raw?.governor ? { governor: raw.governor } : {}),
+        tip: 'Use wire_inspect for full entities and citation chains before buying.',
+    };
+}
+// Pick the contribution-shaped item out of a server response. Object-mode
+// counterpart to the array-mode key resolution used by shapeRoster /
+// shapeCorpora list. Closes class-of-bug playful/118/74 for shapeInspect /
+// shapeRead by emitting an explicit diagnostic when no recognizable item is
+// present, instead of silently returning {handle_path: 'unknown', title: 'Untitled'}.
+function pickContributionItem(raw) {
+    if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+        if (raw.contribution && typeof raw.contribution === 'object')
+            return { item: raw.contribution, note: null };
+        if (raw.item && typeof raw.item === 'object')
+            return { item: raw.item, note: null };
+        // Treat raw as the item if it carries any of the canonical contribution
+        // identity fields. Otherwise surface a diagnostic note.
+        if ('handle_path' in raw || 'item_id' in raw || 'id' in raw ||
+            'title' in raw || 'body' in raw || 'type' in raw) {
+            return { item: raw, note: null };
+        }
+        return { item: {}, note: 'shaper could not locate contribution item — server contract may have changed' };
+    }
+    return { item: {}, note: 'shaper received non-object response — server contract may have changed' };
+}
+export function shapeInspect(raw, alreadyOwned, options) {
+    const { item, note } = pickContributionItem(raw);
+    const result = {
+        handle_path: handlePathOrId(item),
+        title: item.title ?? 'Untitled',
+        teaser: item.teaser ?? item.summary ?? null,
+        type: contributionSemanticType(item),
+        price: safeNumber(item.price ?? item.access_price),
+        price_schedule: item.price_schedule ?? null,
+        creator: creatorRef(item),
+        creator_reputation: safeNumber(item.creator_reputation ?? item.reputation),
+        rating: item.rating ?? item.avg_rating ?? null,
+        cited_by_count: safeNumber(item.cited_by_count ?? item.citations_received ?? item.citation_count),
+        created_at: item.created_at ?? null,
+        when: item.created_at ? timeAgo(item.created_at) : null,
+        note,
+    };
+    withDiagnosticIds(result, contributionDiagnosticIds(item), options);
+    if (alreadyOwned) {
+        result.entities = item.entities ?? [];
+        result.derived_from = derivedSources(item).map(shapeDerivedSource);
+        result.affordances = ['cite', 'rate', 'flag'];
+    }
+    else {
+        result.affordances = ['buy', 'cite'];
+    }
+    if ('definition_access' in item) {
+        result.definition = item.definition ?? null;
+        result.definition_access = item.definition_access;
+    }
+    return result;
+}
+export function shapeRead(raw, options) {
+    const { item, note } = pickContributionItem(raw);
+    return withDiagnosticIds({
+        handle_path: handlePathOrId(item),
+        title: item.title ?? 'Untitled',
+        body: item.body ?? item.content ?? item.text ?? null,
+        type: contributionSemanticType(item),
+        creator: creatorRef(item),
+        entities: item.entities ?? [],
+        structured_data: item.structured_data ?? null,
+        derived_from: derivedSources(item).map(shapeDerivedSource),
+        claims: item.claims ?? [],
+        purchase: {
+            price_paid: safeNumber(item.price_paid ?? item.price),
+            already_owned: item.already_owned ?? item.owned ?? false,
+        },
+        affordances: ['cite', 'rate', 'flag', 'supersede'],
+        note,
+    }, contributionDiagnosticIds(item), options);
+}
+export function shapeGraph(raw, view) {
+    const data = raw ?? {};
+    switch (view) {
+        case 'topics':
+            return {
+                topics: (data.topics ?? data.items ?? []).map((t) => ({
+                    topic: t.topic ?? t.name ?? t.label ?? 'unknown',
+                    count: safeNumber(t.count ?? t.document_count),
+                    trend: t.trend ?? null,
+                })),
+            };
+        case 'entities':
+            return {
+                entities: (data.entities ?? data.items ?? []).map((e) => ({
+                    entity: e.entity ?? e.name ?? e.label ?? 'unknown',
+                    type: e.type ?? e.entity_type ?? null,
+                    mentions: safeNumber(e.mentions ?? e.count),
+                    contributions: safeNumber(e.contributions ?? e.document_count),
+                })),
+            };
+        case 'arcs':
+            return {
+                arcs: (data.arcs ?? data.items ?? []).map((a) => ({
+                    arc: a.arc ?? a.name ?? a.label ?? 'unknown',
+                    contributions: safeNumber(a.contributions ?? a.document_count),
+                    timeline: a.timeline ?? null,
+                })),
+            };
+        default:
+            return { view, data: data.items ?? data };
+    }
+}
+export function shapeCorpora(raw, slug) {
+    if (slug) {
+        // Detail mode
+        const corpus = raw?.corpus ?? raw ?? {};
+        return {
+            corpus: corpus.slug ?? corpus.title ?? slug,
+            documents: (corpus.documents ?? corpus.items ?? []).map((doc) => ({
+                handle_path: handlePathOrId(doc),
+                title: doc.title ?? 'Untitled',
+                type: doc.type ?? null,
+                scouted: doc.scouted ?? doc.processed ?? false,
+                created_at: doc.created_at ?? null,
+            })),
+            unscouted: safeNumber(corpus.unscouted ?? corpus.unprocessed),
+        };
+    }
+    // List mode — server returns { items, total, limit, offset }. `corpora`
+    // is retained as a tolerant alias for legacy / hand-built fixtures. If
+    // neither key resolves to an array, emit a diagnostic note instead of
+    // silently returning empty (closes class-of-bug playful/118/74 for
+    // shapeCorpora list).
+    let listItems;
+    let listNote = null;
+    if (Array.isArray(raw?.items)) {
+        listItems = raw.items;
+    }
+    else if (Array.isArray(raw?.corpora)) {
+        listItems = raw.corpora;
+    }
+    else {
+        listItems = [];
+        if (raw && typeof raw === 'object') {
+            listNote = 'corpora response did not include an items[] array — server contract may have changed';
+        }
+    }
+    return {
+        corpora: listItems.map((c) => ({
+            slug: c.slug ?? c.id ?? 'unknown',
+            title: c.title ?? c.name ?? 'Untitled',
+            themes: c.themes ?? c.topics ?? [],
+            documents: safeNumber(c.document_count ?? c.documents),
+            unscouted: safeNumber(c.unscouted ?? c.unprocessed),
+        })),
+        total: safeNumber(raw?.total ?? raw?.count ?? listItems.length),
+        note: listNote,
+    };
+}
+export function shapeContributeResult(raw, submitted, options) {
+    const response = asRecord(raw?.response) ?? asRecord(raw) ?? {};
+    const contribution = asRecord(raw?.contribution) ?? asRecord(response.contribution) ?? asRecord(raw) ?? {};
+    const economics = asRecord(raw?.economics) ?? asRecord(raw?.transaction) ?? response;
+    const citations = raw?.citations ?? {};
+    const publishEconomics = asRecord(economics.publish_economics) ?? {};
+    const storageFee = asRecord(publishEconomics.storage_fee) ?? {};
+    const bid = asRecord(publishEconomics.bid) ?? {};
+    const handlePath = firstString(contribution.handle_path, response.handle_path, raw?.handle_path) ?? handlePathOrId(contribution);
+    const id = firstString(contribution.id, response.id, raw?.id, raw?.contribution_id);
+    const semanticType = firstString(contribution.type, response.type, submitted?.type, contribution.contribution_type, response.contribution_type);
+    const contributionShape = withDiagnosticIds({
+        handle_path: handlePath,
+        title: firstString(contribution.title, response.title, submitted?.title) ?? 'Untitled',
+        type: semanticType ?? null,
+        creator: creatorRef(contribution),
+    }, id ? { id } : contributionDiagnosticIds(contribution), options);
+    return {
+        status: 'published',
+        contribution: contributionShape,
+        economics: {
+            deposit_charged: safeNumber(economics.deposit_charged ?? economics.deposit ?? economics.cost),
+            deposit_refund_at: economics.deposit_refund_at ?? economics.refund_at ?? null,
+            storage_fee_charged: safeNumber(economics.storage_fee_charged ?? storageFee.amount),
+            bid_locked: safeNumber(economics.bid_locked ?? bid.amount ?? submitted?.bid?.amount),
+            total_charged: safeNumber(economics.total_charged ?? publishEconomics.total_charged),
+            line_items: Array.isArray(publishEconomics.line_items) ? publishEconomics.line_items : null,
+            price_set: safeNumber(economics.price_set ?? economics.price ?? contribution.price ?? submitted?.price),
+            market_context: economics.market_context ?? null,
+        },
+        citations: {
+            sources_cited: safeNumber(citations.sources_cited ?? citations.count ?? (contribution.derived_from ?? submitted?.derived_from ?? []).length),
+            unrated_sources: safeNumber(citations.unrated_sources ?? citations.unrated),
+            rating_prompt: citations.unrated_sources > 0 || citations.unrated > 0
+                ? 'You cited sources you haven\'t rated yet. Use wire_rate to rate them — it improves your reputation.'
+                : null,
+        },
+        next_actions: [
+            'wire_my_contributions — track performance',
+            'wire_earnings — monitor revenue',
+            'wire_query — find related content to cite',
+        ],
+    };
+}
+export function shapeMyContributions(raw, ctx, options) {
+    const data = raw ?? {};
+    // Server returns { contributions, total_count, has_more }. `items` is
+    // retained as a tolerant alias for hand-built fixtures. Surface a
+    // diagnostic note when neither key resolves so contract drift is
+    // visible (closes class-of-bug playful/118/74 for shapeMyContributions).
+    let items;
+    let listNote = null;
+    if (Array.isArray(data.contributions)) {
+        items = data.contributions;
+    }
+    else if (Array.isArray(data.items)) {
+        items = data.items;
+    }
+    else {
+        items = [];
+        if (data && typeof data === 'object' && Object.keys(data).length > 0) {
+            listNote = 'my-contributions response did not include a contributions[] array — server contract may have changed';
+        }
+    }
+    void ctx; // ctx reserved for future per-agent insights — keep parameter stable
+    const totalCitations = items.reduce((sum, c) => sum + safeNumber(c.citations_received ?? c.citation_count), 0);
+    const totalRevenue = items.reduce((sum, c) => sum + safeNumber(c.revenue ?? c.earned ?? c.price ?? 0), 0);
+    const accuracies = items
+        .map((c) => c.accuracy ?? c.avg_accuracy)
+        .filter((a) => a != null)
+        .map((a) => safeNumber(a));
+    const avgAccuracy = accuracies.length > 0
+        ? Math.round(accuracies.reduce((a, b) => a + b, 0) / accuracies.length * 100) / 100
+        : null;
+    const contributions = items.map((c) => withDiagnosticIds({
+        handle_path: handlePathOrId(c),
+        title: c.title ?? 'Untitled',
+        type: contributionSemanticType(c),
+        creator: creatorRef(c),
+        citations_received: safeNumber(c.citations_received ?? c.citation_count),
+        revenue: safeNumber(c.revenue ?? c.earned ?? c.price ?? 0),
+        rating: c.rating ?? c.avg_rating ?? null,
+        accuracy: c.accuracy ?? c.avg_accuracy ?? null,
+        created_at: c.created_at ?? null,
+        when: c.created_at ? timeAgo(c.created_at) : null,
+    }, contributionDiagnosticIds(c), options));
+    // Generate insights
+    const insights = [];
+    if (contributions.length > 0) {
+        const topCited = [...contributions].sort((a, b) => b.citations_received - a.citations_received)[0];
+        if (topCited && topCited.citations_received > 0) {
+            insights.push(`Your most-cited work is "${topCited.title}" with ${topCited.citations_received} citations.`);
+        }
+        const topEarner = [...contributions].sort((a, b) => b.revenue - a.revenue)[0];
+        if (topEarner && topEarner.revenue > 0) {
+            insights.push(`Top earner: "${topEarner.title}" with ${topEarner.revenue} credits.`);
+        }
+    }
+    return {
+        summary: {
+            total: contributions.length,
+            citations_received: totalCitations,
+            revenue_earned: totalRevenue,
+            avg_accuracy: avgAccuracy,
+            network_avg_accuracy: safeNumber(data.network_avg_accuracy ?? data.network_accuracy, null),
+            trend: data.trend ?? null,
+        },
+        contributions,
+        insights,
+        note: listNote,
+    };
+}
+// ─── Social Shapers ─────────────────────────────────────────────────
+export function shapePulse(raw) {
+    const data = raw ?? {};
+    const messagesData = data.messages ?? {};
+    const messageItems = Array.isArray(messagesData.preview)
+        ? messagesData.preview
+        : Array.isArray(messagesData.recent)
+            ? messagesData.recent
+            : Array.isArray(messagesData.messages)
+                ? messagesData.messages
+                : Array.isArray(data.message_preview)
+                    ? data.message_preview
+                    : [];
+    const notificationsData = data.notifications?.data ?? data.notifications ?? {};
+    const notificationItems = Array.isArray(data.unread_notifications)
+        ? data.unread_notifications
+        : Array.isArray(notificationsData.notifications)
+            ? notificationsData.notifications
+            : [];
+    const tasksData = data.tasks ?? {};
+    const taskItems = Array.isArray(data.active_tasks)
+        ? data.active_tasks
+        : Array.isArray(tasksData.tasks)
+            ? tasksData.tasks
+            : [];
+    const messagePreview = messageItems.map((m) => ({
+        from: m.from_handle ?? m.from ?? creatorRef(m),
+        snippet: m.snippet ?? m.body?.slice(0, 80) ?? '',
+        when: (m.created_at ?? m.sent_at) ? timeAgo(m.created_at ?? m.sent_at) : 'unknown',
+    }));
+    return {
+        since: data.since ?? data.last_check ?? null,
+        messages: {
+            unread: safeNumber(messagesData.unread
+                ?? messagesData.unread_count
+                ?? data.unread_messages
+                ?? (Array.isArray(messagesData.messages) ? messagesData.messages.length : undefined)),
+            preview: messagePreview,
+        },
+        tasks: safeNumber(tasksData.active ?? tasksData.total ?? data.active_tasks_count ?? taskItems.length),
+        notifications: safeNumber(notificationsData.unread
+            ?? notificationsData.unread_count
+            ?? data.unread_notifications_count
+            ?? notificationItems.length),
+        fleet: data.fleet ?? data.fleet_online ?? null,
+        circles: data.circles ?? data.circle_activity ?? null,
+    };
+}
+export function shapeMessages(raw, options) {
+    const data = raw ?? {};
+    const shapeMessage = (message) => {
+        const handle = firstString(message?.message_handle, message?.handle) ?? 'unknown';
+        return withDiagnosticIds({
+            message_handle: handle,
+            from_handle: firstString(message?.from_handle) ?? null,
+            to_handle: firstString(message?.to_handle) ?? null,
+            circle: message?.circle ?? null,
+            body: message?.body ?? null,
+            sent_at: message?.sent_at ?? message?.created_at ?? null,
+            direction: message?.direction ?? null,
+            read: message?.read ?? message?.read_by_me ?? null,
+        }, messageDiagnosticIds(message), options);
+    };
+    if (Array.isArray(data.messages)) {
+        return {
+            messages: data.messages.map(shapeMessage),
+            cost: safeNumber(data.cost),
+        };
+    }
+    if (data.message && typeof data.message === 'object') {
+        return {
+            message: shapeMessage(data.message),
+            cost: safeNumber(data.cost),
+        };
+    }
+    if (data.sent === true) {
+        return {
+            sent: true,
+            message_handle: firstString(data.handle, data.message_handle) ?? 'unknown',
+            from_handle: firstString(data.from_handle) ?? null,
+            to_handle: firstString(data.to_handle) ?? null,
+            circle: data.circle ?? null,
+            cost: safeNumber(data.cost),
+            ...(options?.includeIds ? { diagnostic_ids: messageDiagnosticIds(data) ?? undefined } : {}),
+        };
+    }
+    return data;
+}
+export function shapeOpportunities(raw) {
+    const data = raw ?? {};
+    return {
+        opportunities: (data.opportunities ?? data.items ?? []).map((opp) => ({
+            type: opp.type ?? 'unknown',
+            topic: opp.topic ?? opp.title ?? null,
+            demand: safeNumber(opp.demand ?? opp.query_count),
+            avg_price: safeNumber(opp.avg_price ?? opp.price),
+            description: opp.description ?? null,
+        })),
+        your_strengths: data.your_strengths ?? data.strengths ?? [],
+    };
+}
+export function shapeRate(raw) {
+    const data = raw ?? {};
+    return {
+        status: data?.status ?? 'recorded',
+        item_id: data?.item_id ?? null,
+        rating_id: data?.rating_id ?? null,
+    };
+}
+export function shapePatrolScan(raw) {
+    const data = raw ?? {};
+    return {
+        patrol_opportunities: (data.opportunities ?? data.items ?? data.flagged ?? []).map((item) => ({
+            handle_path: handlePathOrId(item),
+            title: item.title ?? 'Untitled',
+            flag_type: item.flag_type ?? item.type ?? 'unknown',
+            flag_count: safeNumber(item.flag_count ?? item.flags),
+            needs: item.needs ?? item.action_needed ?? 'review',
+        })),
+        your_patrol_stats: {
+            patrols_completed: safeNumber(data.patrols_completed ?? data.your_patrols),
+            accuracy: data.patrol_accuracy ?? data.your_accuracy ?? null,
+            reputation_earned: safeNumber(data.reputation_earned),
+        },
+    };
+}
+// ─── Utility Shapers ─────────────────────────────────────────────────
+export function shapeNotifications(raw) {
+    const data = raw ?? {};
+    const items = data.notifications ?? data.items ?? [];
+    return {
+        notifications: items.map((n) => ({
+            notification_id: n.notification_id ?? n.id ?? null,
+            type: n.type ?? n.event_type ?? 'unknown',
+            event_type: n.event_type ?? n.type ?? null,
+            summary: n.summary ?? n.message ?? n.title ?? 'Notification',
+            read: n.read ?? n.is_read ?? false,
+            when: n.created_at ? timeAgo(n.created_at) : 'unknown',
+            created_at: n.created_at ?? null,
+            source_agent: n.source_agent ?? n.source_agent_pseudonym ?? n.agent_handle ?? n.agent_id ?? null,
+            related: n.related ?? n.related_handle_path ?? n.source_contribution_handle_path ?? n.related_id ?? n.source_contribution_id ?? null,
+            related_id: n.related_id ?? n.source_contribution_id ?? null,
+            diagnostic: n.diagnostic ?? null,
+        })),
+        unread_count: safeNumber(data.unread_count ?? data.unread ?? items.filter((n) => !(n.read ?? n.is_read)).length),
+        buckets: data.buckets ?? null,
+        mark_read_hint: 'Use wire_notifications action=mark_read with notification_ids, or all=true after inspection.',
+    };
+}
+export function shapeTasks(raw) {
+    const data = raw ?? {};
+    const items = data.tasks ?? data.items ?? [];
+    const taskStatus = (t) => String(t.status ?? t.column ?? t.column_name ?? '').toLowerCase();
+    const backlog = items.filter((t) => taskStatus(t) === 'backlog' || taskStatus(t) === 'open').length;
+    const claimed = items.filter((t) => taskStatus(t) === 'claimed' || taskStatus(t) === 'in_progress').length;
+    const done = items.filter((t) => taskStatus(t) === 'done' || taskStatus(t) === 'completed').length;
+    return {
+        board_summary: {
+            backlog: data.backlog_count ?? backlog,
+            claimed: data.claimed_count ?? claimed,
+            done: data.done_count ?? done,
+        },
+        tasks: items.map((t) => ({
+            id: t.id ?? null,
+            handle: t.handle ?? null,
+            title: t.title ?? 'Untitled',
+            status: t.status ?? t.column ?? t.column_name ?? 'unknown',
+            assignee: t.assignee ? shapeAgentRef(t.assignee).handle : null,
+            creator: t.creator ? shapeAgentRef(t.creator).handle : null,
+            priority: t.priority ?? null,
+            when: t.created_at ? timeAgo(t.created_at) : null,
+        })),
+        archive_hint: done > 0 ? `${done} completed tasks can be archived.` : null,
+    };
+}
+export function shapeRoster(raw, ctx) {
+    // Server response shape (src/lib/server/wire-roster.ts getRoster) is:
+    //   { status, operator, operator_verified, existing_agents[], suggested[], can_create_new }
+    // The previous shaper read raw.agents / raw.roster / raw.items / raw —
+    // none of those keys exist on the real response, so it silently fell
+    // through to the response object itself, Array.isArray returned false,
+    // and every caller saw {agents: [], total: 0} regardless of the actual
+    // fleet. Closes friction obs playful/118/57.
+    const existing = Array.isArray(raw?.existing_agents)
+        ? raw.existing_agents
+        // Defensive: also accept the legacy `agents` key in case any caller
+        // upstream restructures the response. Pure tolerance, not the primary path.
+        : Array.isArray(raw?.agents) ? raw.agents : [];
+    const suggested = Array.isArray(raw?.suggested) ? raw.suggested : [];
+    // Index suggestions by name so callers can sort by ranking inline.
+    const suggestionByName = new Map();
+    for (const s of suggested) {
+        if (s && typeof s.name === 'string')
+            suggestionByName.set(s.name, s);
+    }
+    const agents = existing.map((agent) => {
+        const ref = shapeAgentRef(agent);
+        const isMe = ref.name === ctx.agentName || ref.handle === ctx.agentHandle;
+        const sug = suggestionByName.get(ref.name);
+        const handlePath = rosterAgentHandlePath(agent, ref.name, ctx);
+        return {
+            name: ref.name,
+            // Roster handles should be copy/paste identifiers for tools like
+            // wire_messages. Prefer agent/<operator>/<slot> over shapeAgentRef's
+            // display-only @name fallback, which the agent resolver does not accept.
+            handle: handlePath ?? ref.handle,
+            handle_path: handlePath,
+            // pseudo_id is the canonical DM-routing key. Surface it explicitly so
+            // callers can resolve recipients without an extra wire_messages list
+            // round-trip — the missing piece that motivated playful/118/57.
+            pseudo_id: agent.pseudo_id ?? null,
+            is_me: isMe,
+            role: agent.role ?? null,
+            description: agent.description ?? null,
+            contribution_count: typeof agent.contribution_count === 'number'
+                ? agent.contribution_count
+                : safeNumber(agent.contribution_count ?? 0),
+            online: agent.online ?? agent.is_online ?? null,
+            last_active: agent.last_active
+                ?? (agent.last_active_at ?? agent.last_seen_at
+                    ? timeAgo(agent.last_active_at ?? agent.last_seen_at)
+                    : null),
+            suggestion_score: sug?.confidence ?? null,
+            suggestion_reason: sug?.reason ?? null,
+            roster_status: agent.roster_status ?? null,
+        };
+    });
+    // Diagnostic hint when the result is empty — the prior shaper returned
+    // `{agents: [], total: 0}` with no signal as to why. If the caller hit a
+    // genuinely-empty operator account, the hint surfaces that; if the server
+    // returned a shape the shaper couldn't parse, surface that too so callers
+    // don't silently get the wrong answer.
+    let note = null;
+    if (agents.length === 0) {
+        if (raw && typeof raw === 'object' && !Array.isArray(raw.existing_agents) && !Array.isArray(raw.agents)) {
+            note = 'roster response did not include an existing_agents array — server contract may have changed';
+        }
+        else if (raw?.can_create_new === true) {
+            note = 'no agents on this operator account yet — wire_identify with create_new:true to register one';
+        }
+        else {
+            note = 'operator has no active agents in the roster';
+        }
+    }
+    return {
+        agents,
+        total: safeNumber(raw?.total ?? raw?.count ?? agents.length),
+        operator: raw?.operator ?? null,
+        operator_verified: raw?.operator_verified ?? null,
+        can_create_new: raw?.can_create_new ?? null,
+        note,
+    };
+}
+function rosterAgentHandlePath(agent, name, ctx) {
+    const direct = firstString(agent?.handle_path, agent?.handlePath);
+    if (direct)
+        return direct.replace(/^@/, '');
+    const handle = firstString(agent?.handle);
+    if (handle?.replace(/^@/, '').startsWith('agent/'))
+        return handle.replace(/^@/, '');
+    const operator = operatorSegmentFromAgentHandle(ctx.agentHandle);
+    if (!operator || !name || name === 'unknown')
+        return null;
+    return `agent/${operator}/${name}`;
+}
+function operatorSegmentFromAgentHandle(handle) {
+    const normalized = firstString(handle)?.replace(/^@/, '');
+    if (!normalized)
+        return null;
+    const parts = normalized.split('/');
+    if (parts.length >= 3 && parts[0] === 'agent' && parts[1])
+        return parts[1];
+    return null;
+}
+//# sourceMappingURL=response-shaper.js.map