@indexnetwork/protocol 6.12.1-rc.404.1 → 6.13.22-rc.405.1

package/dist/negotiation/application/negotiation.tools.js

@@ -0,0 +1,782 @@
+import { z } from 'zod';
+import { success, error } from '../../shared/agent/tool.helpers.js';
+import { IndexNegotiator } from './negotiation.agent.js';
+import { allowedActionsFor, isTerminalAction, readProtocolVersion, rejectActionFor, resolveSeat, seatViolationMessage } from '../domain/negotiation.protocol.js';
+import { NEGOTIATION_ACTIONS } from '../../shared/schemas/negotiation-state.schema.js';
+import { protocolLogger } from '../../shared/observability/protocol.logger.js';
+import { focusedIntentId, focusedNetworkId } from '../../shared/agent/tool.scope.js';
+import { readAuthorizedNegotiationDetail } from './negotiation.detail-reader.js';
+import { buildLifecycleNarration } from '../domain/negotiation.lifecycle-narration.js';
+export { buildLifecycleNarration } from '../domain/negotiation.lifecycle-narration.js';
+const logger = protocolLogger('ChatTools:Negotiation');
+/**
+ * Default park-window budget for ambient (background) negotiations. When a personal
+ * agent is fresh, the dispatcher parks the turn and this is how long we wait before
+ * the system agent takes over as a fallback.
+ *
+ * Short enough that ambient opportunities materialize in minutes (not hours),
+ * long enough to cover two full polling cycles (30s * 2 = 60s) plus an agent
+ * subagent turn. 5 minutes gives generous headroom.
+ */
+export const AMBIENT_PARK_WINDOW_MS = 5 * 60 * 1000;
+/**
+ * Pulls the negotiation's network from task metadata. Tasks created after the
+ * scope hardening carry `metadata.networkId` directly; older tasks only have
+ * the network embedded in the parked `turnContext.indexContext.networkId`.
+ * Returns `null` for legacy tasks where neither field is present — callers
+ * scoped by the request scope envelope must reject these defensively rather than
+ * fall through to a global view.
+ */
+function readTaskNetworkId(meta) {
+    if (!meta)
+        return null;
+    if (typeof meta.networkId === 'string' && meta.networkId.trim())
+        return meta.networkId;
+    const fromTurnContext = meta.turnContext?.indexContext?.networkId;
+    if (typeof fromTurnContext === 'string' && fromTurnContext.trim())
+        return fromTurnContext;
+    return null;
+}
+const SCOPE_DENIAL = 'Access denied: this negotiation is not in your bound network scope.';
+/** Reads lifecycle evidence without making older host adapters mandatory. */
+async function readOpportunityLifecycles(database, opportunityIds, ownerUserId) {
+    if (opportunityIds.length === 0 || !database.getOpportunityLifecyclesForNegotiations)
+        return {};
+    try {
+        return await database.getOpportunityLifecyclesForNegotiations(opportunityIds, ownerUserId);
+    }
+    catch (err) {
+        logger.warn('Failed to load opportunity lifecycle for negotiation narration', { err });
+        return {};
+    }
+}
+/** Extracts the ordered NegotiationTurn list from A2A message data parts. */
+function turnsFromMessages(messages) {
+    return messages
+        .map((m) => {
+        const dp = m.parts?.find((p) => p.kind === 'data');
+        return dp?.data;
+    })
+        .filter(Boolean);
+}
+/**
+ * Creates negotiation MCP tools for external agent access.
+ * Exposes negotiation state for listing, reading, and responding to bilateral negotiations.
+ */
+export function createNegotiationTools(defineTool, deps) {
+    const { negotiationDatabase } = deps;
+    const list_negotiations = defineTool({
+        name: 'list_negotiations',
+        description: 'List bilateral negotiations the authenticated user is involved in, either as the source (initiator) or candidate (responder). ' +
+            'Negotiations are turn-based exchanges where two AI agents negotiate on behalf of their users to determine if there is a ' +
+            'mutual opportunity for collaboration.\n\n' +
+            '**Statuses:**\n' +
+            '- `active` — Negotiation is in progress, agents are exchanging turns.\n' +
+            '- `waiting_for_agent` — The graph has yielded and is waiting for an agent response (e.g. from the user via respond_to_negotiation) or a timeout.\n' +
+            '- `completed` — The agent negotiation has concluded (agent-side accept/reject, or turn cap). This is not a completed connection or an owner decision.\n\n' +
+            '**Lifecycle narration:** Every result includes additive `lifecycle` fields that distinguish the agent-negotiation state, ' +
+            'current opportunity status, and persisted owner acceptance. Agent-side `accept` means only that agents found a potential match; ' +
+            '`pending` still awaits owner review. `directConversationEvidence` is `not_provided`, so this tool never establishes that an H2H message thread exists.\n\n' +
+            '**When to use:** To see ongoing and past negotiations, check which negotiations need attention, ' +
+            'or find a negotiation ID for get_negotiation or respond_to_negotiation.',
+        querySchema: z.object({
+            status: z.enum(['active', 'waiting_for_agent', 'completed', 'all']).optional()
+                .describe('Filter by negotiation status. Omit or use "all" to return all negotiations.'),
+            scope: z.enum(['signal', 'all']).optional()
+                .describe('Scope to the pinned signal (requires an intent-pinned session), or pass "all" for the full negotiation history.'),
+            since: z.string().datetime().optional()
+                .describe('ISO 8601 date-time. Only return negotiations created at or after this timestamp.'),
+            limit: z.number().int().min(1).max(100).optional()
+                .describe('Maximum negotiations to return per page (1-100). Omit to return all.'),
+            page: z.number().int().min(1).optional()
+                .describe('Page number (1-based). Only used when limit is provided. Defaults to 1.'),
+            detail: z.enum(['summary', 'narrative']).optional()
+                .describe('Response detail level. Omit or use "summary" for the default fields. ' +
+                'Use "narrative" to receive additional context per negotiation suitable for ' +
+                'composing a digest or field report: indexContext (the community/network prompt ' +
+                'that seeded the negotiation), recentTurns (last 3 turns with action + message), ' +
+                'and outcome (for completed negotiations). These fields are populated from data ' +
+                'already loaded for the listing, so the extra cost is minimal.'),
+        }),
+        handler: async ({ context, query }) => {
+            try {
+                // Map tool status filter to task state query
+                const stateFilter = query.status && query.status !== 'all' ? query.status : undefined;
+                // For 'active', query 'working' state tasks
+                const dbState = stateFilter === 'active' ? 'working'
+                    : stateFilter === 'waiting_for_agent' ? 'waiting_for_agent'
+                        : stateFilter === 'completed' ? 'completed'
+                            : undefined;
+                const tasks = await negotiationDatabase.getTasksForUser(context.userId, dbState ? { state: dbState } : undefined);
+                const opportunityIds = [...new Set(tasks
+                        .map((task) => task.metadata?.opportunityId)
+                        .filter((opportunityId) => typeof opportunityId === 'string' && opportunityId.trim().length > 0)
+                        .map((opportunityId) => opportunityId.trim()))];
+                const opportunityLifecycles = await readOpportunityLifecycles(negotiationDatabase, opportunityIds, context.userId);
+                const scopedNetworkId = focusedNetworkId(context);
+                const pinnedIntentId = focusedIntentId(context);
+                const effectiveScope = query.scope ?? (pinnedIntentId ? 'signal' : 'all');
+                if (effectiveScope === 'signal' && !pinnedIntentId) {
+                    return error('Signal scope requires a pinned intent.');
+                }
+                const signalIntentIdsByOpportunity = effectiveScope === 'signal'
+                    ? await negotiationDatabase.getIntentIdsForOpportunities(opportunityIds, context.userId)
+                    : null;
+                const scopeMetadata = effectiveScope === 'signal'
+                    ? { scope: 'signal', intentId: pinnedIntentId }
+                    : { scope: 'all' };
+                const negotiations = await Promise.all(tasks.map(async (task) => {
+                    const meta = task.metadata;
+                    if (meta?.type !== 'negotiation')
+                        return null;
+                    // Network-scope filter: when caller's API key carries a network-bound
+                    // agent, drop tasks whose network differs (or whose network we cannot
+                    // determine — defense in depth for legacy tasks).
+                    if (scopedNetworkId) {
+                        const taskNetworkId = readTaskNetworkId(meta);
+                        if (taskNetworkId !== scopedNetworkId)
+                            return null;
+                    }
+                    // Intent-scope filter: a pinned negotiator workspace only shows
+                    // opportunity-bound tasks whose actor intent belongs to this user and
+                    // matches the pinned signal. Tasks without resolvable provenance are
+                    // dropped rather than widened into the user's full history.
+                    const opportunityId = typeof meta.opportunityId === 'string' ? meta.opportunityId.trim() : '';
+                    if (effectiveScope === 'signal'
+                        && (!opportunityId || signalIntentIdsByOpportunity?.[opportunityId] !== pinnedIntentId)) {
+                        return null;
+                    }
+                    const isSource = meta.sourceUserId === context.userId;
+                    const counterpartyId = isSource ? meta.candidateUserId : meta.sourceUserId;
+                    // Get messages for preview (and turns when narrative detail requested)
+                    const messages = await negotiationDatabase.getMessagesForConversation(task.conversationId);
+                    const lastMessage = messages[messages.length - 1];
+                    const lastTurnData = lastMessage
+                        ? lastMessage.parts?.find(p => p.kind === 'data')?.data
+                        : undefined;
+                    // Determine whose turn it is from the last message's sender — not
+                    // parity, which misattributes across continuation sessions. Rows
+                    // without senderId (legacy) fall back to parity.
+                    const turnCount = messages.length;
+                    const lastSenderId = turnCount > 0 ? messages[turnCount - 1].senderId : null;
+                    const currentSpeaker = lastSenderId
+                        ? (lastSenderId === `agent:${meta.sourceUserId}` ? 'candidate' : 'source')
+                        : (turnCount % 2 === 0 ? 'source' : 'candidate');
+                    // Map task state to tool status
+                    const status = task.state === 'working' ? 'active'
+                        : task.state === 'waiting_for_agent' ? 'waiting_for_agent'
+                            : task.state === 'completed' ? 'completed'
+                                : task.state;
+                    const isUsersTurn = status !== 'completed' &&
+                        ((isSource && currentSpeaker === 'source') || (!isSource && currentSpeaker === 'candidate'));
+                    const base = {
+                        id: task.id,
+                        counterpartyId: counterpartyId ?? 'unknown',
+                        role: isSource ? 'source' : 'candidate',
+                        turnCount,
+                        status,
+                        isUsersTurn,
+                        isContinuation: meta.isContinuation ?? false,
+                        priorTurnCount: meta.priorTurnCount ?? 0,
+                        latestAction: lastTurnData?.action ?? null,
+                        latestActionActor: 'agent',
+                        latestMessagePreview: lastTurnData?.message ?? null,
+                        lifecycle: buildLifecycleNarration(status, opportunityLifecycles[opportunityId]),
+                        createdAt: task.createdAt,
+                        updatedAt: task.updatedAt,
+                    };
+                    if (query.detail !== 'narrative')
+                        return base;
+                    // ── Narrative extras (messages already loaded — no extra DB cost) ──
+                    const RECENT_TURNS_LIMIT = 3;
+                    const recentMessages = messages.slice(-RECENT_TURNS_LIMIT);
+                    const recentTurns = recentMessages.map((m, sliceIdx) => {
+                        const absoluteIdx = messages.length - recentMessages.length + sliceIdx;
+                        const speaker = m.senderId
+                            ? (m.senderId === `agent:${meta.sourceUserId}` ? 'source' : 'candidate')
+                            : (absoluteIdx % 2 === 0 ? 'source' : 'candidate');
+                        const td = m.parts?.find(p => p.kind === 'data')?.data;
+                        return {
+                            turnNumber: absoluteIdx + 1,
+                            speaker,
+                            role: speaker === (isSource ? 'source' : 'candidate') ? 'own' : 'other',
+                            action: td?.action ?? 'unknown',
+                            actionActor: 'agent',
+                            message: td?.message ?? null,
+                        };
+                    });
+                    const indexContext = meta.turnContext?.indexContext ?? null;
+                    // Outcome artifact — only meaningful for completed negotiations
+                    let outcome = null;
+                    if (status === 'completed') {
+                        const artifacts = await negotiationDatabase.getArtifactsForTask(task.id);
+                        const outcomeArtifact = artifacts.find(a => a.name === 'negotiation-outcome');
+                        outcome = outcomeArtifact
+                            ? (outcomeArtifact.parts?.find(p => p.kind === 'data')?.data ?? null)
+                            : null;
+                    }
+                    return { ...base, indexContext, recentTurns, outcome };
+                }));
+                let filtered = negotiations.filter(Boolean);
+                if (query.since) {
+                    const sinceMs = new Date(query.since).getTime();
+                    filtered = filtered.filter(n => new Date(n.createdAt).getTime() >= sinceMs);
+                }
+                const shouldPaginate = query.limit !== undefined;
+                if (shouldPaginate) {
+                    const limit = query.limit;
+                    const page = query.page ?? 1;
+                    const offset = (page - 1) * limit;
+                    const paged = filtered.slice(offset, offset + limit);
+                    return success({
+                        ...scopeMetadata,
+                        count: paged.length,
+                        totalCount: filtered.length,
+                        limit,
+                        page,
+                        totalPages: Math.ceil(filtered.length / limit),
+                        negotiations: paged,
+                    });
+                }
+                return success({
+                    ...scopeMetadata,
+                    count: filtered.length,
+                    negotiations: filtered,
+                });
+            }
+            catch (err) {
+                logger.error('Failed to list negotiations', { err });
+                return error('Failed to list negotiations. Please try again.');
+            }
+        },
+    });
+    const get_negotiation = defineTool({
+        name: 'get_negotiation',
+        description: 'Get the full details of a specific negotiation, including all turns, messages, counterparty info, and current state. ' +
+            'Negotiations are bilateral exchanges where two AI agents negotiate on behalf of users. Each turn contains an action ' +
+            '(propose, accept, reject, counter, question), an assessment with reasoning and suggested roles, and an optional message.\n\n' +
+            '**Access control:** You must be a party to the negotiation (source or candidate) to view it.\n\n' +
+            '**Statuses:** `active` — in progress. `waiting_for_agent` — waiting for an agent response or timeout. `completed` — the agents concluded, not that the owner accepted or a connection/message thread exists.\n\n' +
+            '**Lifecycle narration:** The additive `lifecycle` object is authoritative for user-facing wording. A turn action of `accept` is agent-side; ' +
+            'only `lifecycle.ownerAction=accepted` records this owner as the human acceptor. `conversationType=agent_negotiation` identifies the returned ' +
+            'conversationId as the A2A negotiation transcript; this result does not provide H2H conversation evidence.\n\n' +
+            '**When to use:** To review the full negotiation history before responding, to understand why the agents ' +
+            'accepted or rejected a potential match, or to see the current state of an active negotiation.\n\n' +
+            '**Negotiation-turn-mode usage.** If you are running as a silent background subagent (dispatched by the ' +
+            "openclaw runtime's poller in response to a claimed negotiation turn), call this tool FIRST with the " +
+            'negotiationId from your task prompt. This returns the current state, both parties\' context, and the ' +
+            'history of turns so far. Ground your response in the caller\'s profile (read_user_contexts) and intents ' +
+            '(read_intents) before deciding on a turn action. Do not produce user-facing output in this mode.',
+        querySchema: z.object({
+            negotiationId: z.string().describe('The negotiation task ID (from list_negotiations results).'),
+        }),
+        handler: async ({ context, query }) => {
+            try {
+                const task = await negotiationDatabase.getTask(query.negotiationId);
+                if (!task) {
+                    return error('Negotiation not found.');
+                }
+                const meta = task.metadata;
+                if (meta?.type !== 'negotiation') {
+                    return error('Negotiation not found.');
+                }
+                // Network-scope check: a network-bound agent must not read negotiations
+                // outside its bound network. Run before the participant check so we
+                // don't leak existence-vs-membership signal across scopes.
+                const scopedNetworkId = focusedNetworkId(context);
+                if (scopedNetworkId) {
+                    const taskNetworkId = readTaskNetworkId(meta);
+                    if (taskNetworkId !== scopedNetworkId) {
+                        return error(SCOPE_DENIAL);
+                    }
+                }
+                // Access control: user must be source or candidate
+                const isSource = meta.sourceUserId === context.userId;
+                const isCandidate = meta.candidateUserId === context.userId;
+                if (!isSource && !isCandidate) {
+                    return error('Access denied: you are not a party to this negotiation.');
+                }
+                const detail = await readAuthorizedNegotiationDetail({
+                    task,
+                    metadata: meta,
+                    callerUserId: context.userId,
+                    callerRole: isSource ? 'source' : 'candidate',
+                    readMessages: (conversationId) => negotiationDatabase.getMessagesForConversation(conversationId),
+                    readArtifacts: (taskId) => negotiationDatabase.getArtifactsForTask(taskId),
+                    readLifecycleEvidence: (opportunityIds, ownerUserId) => readOpportunityLifecycles(negotiationDatabase, opportunityIds, ownerUserId),
+                });
+                return success(detail);
+            }
+            catch (err) {
+                logger.error('Failed to get negotiation', { err });
+                return error('Failed to get negotiation. Please try again.');
+            }
+        },
+    });
+    const respond_to_negotiation = defineTool({
+        name: 'respond_to_negotiation',
+        description: 'Respond to a negotiation that is waiting for agent input. This tool allows users to influence the negotiation ' +
+            'by accepting, rejecting, countering, or asking a clarifying question.\n\n' +
+            '**Turn-based model:** Negotiations alternate between source and candidate agents. When the graph yields with ' +
+            '`waiting_for_agent` status, the user whose turn it is can respond.\n\n' +
+            '**Valid actions depend on the negotiation protocol version and your seat** — call get_negotiation first: ' +
+            'its `seat`, `protocolVersion`, and `allowedActions` fields tell you exactly what you may submit.\n\n' +
+            '**v1 negotiations (legacy):** `propose | accept | reject | counter | question` — on the first turn the action MUST be `propose`.\n\n' +
+            '**v2 negotiations (client-advocate seat rules):**\n' +
+            '- Initiator seat (`outreach | counter | question | withdraw`): you reached out — you can NEVER accept. ' +
+            '`outreach` opens the negotiation; `withdraw` ends it without an opportunity.\n' +
+            '- Counterparty seat (`accept | decline | counter | question`): only your seat can `accept` (finalizes an opportunity); ' +
+            '`decline` ends the negotiation without one.\n\n' +
+            '- `counter` — Counter with a message (message is required). The negotiation continues.\n' +
+            '- `question` — Ask the other side a clarifying question (message is required). The negotiation continues.\n\n' +
+            '**What happens after:** Terminal actions (accept/reject/withdraw/decline) finalize the negotiation immediately. ' +
+            'Counter/question continues — if the counterparty has an agent, the negotiation yields again; otherwise the AI agent responds inline.\n\n' +
+            '**Silent-subagent response contract.** In negotiation-turn mode, submit exactly ONE call to this tool ' +
+            'per dispatch with an action from your seat\'s allowed set and the assessment (reasoning + suggestedRoles). ' +
+            'If the decision is ambiguous, pick the most conservative action — usually `counter` with specific objections. ' +
+            'Do not ask the user clarifying questions; you are authorized to act on their behalf within the scope granted to your agent.',
+        querySchema: z.object({
+            negotiationId: z.string().describe('The negotiation task ID to respond to.'),
+            action: z.enum(NEGOTIATION_ACTIONS).describe('The response action. Must be within your seat\'s allowedActions (see get_negotiation). v1 first turn MUST be "propose"; v2 initiator first turn MUST be "outreach".'),
+            reasoning: z.string().describe('Why you are taking this action — your assessment of the opportunity.'),
+            suggestedRoles: z.object({
+                ownUser: z.enum(['agent', 'patient', 'peer']).describe('Suggested role for your user in this opportunity.'),
+                otherUser: z.enum(['agent', 'patient', 'peer']).describe('Suggested role for the other user in this opportunity.'),
+            }).describe('Role suggestions for both parties.'),
+            message: z.string().optional().describe('Required for "counter" and "question" actions. Your message explaining what you want to change or clarify.'),
+        }),
+        handler: async ({ context, query }) => {
+            try {
+                const task = await negotiationDatabase.getTask(query.negotiationId);
+                if (!task) {
+                    return error('Negotiation not found.');
+                }
+                const meta = task.metadata;
+                if (meta?.type !== 'negotiation') {
+                    return error('Negotiation not found.');
+                }
+                // Network-scope check (mirrors get_negotiation): a network-bound agent
+                // must not act on negotiations outside its bound network.
+                const scopedNetworkId = focusedNetworkId(context);
+                if (scopedNetworkId) {
+                    const taskNetworkId = readTaskNetworkId(meta);
+                    if (taskNetworkId !== scopedNetworkId) {
+                        return error(SCOPE_DENIAL);
+                    }
+                }
+                // Validate negotiation is waiting for agent input (or claimed via polling)
+                if (task.state !== 'waiting_for_agent' && task.state !== 'claimed') {
+                    return error(`Negotiation is not waiting for a response. Current status: ${task.state}`);
+                }
+                // Access control: user must be a party
+                const isSource = meta.sourceUserId === context.userId;
+                const isCandidate = meta.candidateUserId === context.userId;
+                if (!isSource && !isCandidate) {
+                    return error('Access denied: you are not a party to this negotiation.');
+                }
+                // Seat + version validation (v2 client-advocate): the submitted action
+                // must be within the caller's seat vocabulary. v1 tasks accept the
+                // legacy vocabulary unchanged (grandfathered).
+                const protocolVersion = readProtocolVersion(meta) ?? 'v1';
+                const seat = resolveSeat(context.userId, meta);
+                if (!allowedActionsFor(protocolVersion, seat).includes(query.action)) {
+                    return error(seatViolationMessage(query.action, seat, protocolVersion));
+                }
+                // Determine whose turn it is from the last message's sender — not
+                // parity, which misattributes across continuation sessions. Rows
+                // without senderId (legacy) fall back to the parity heuristic.
+                const messages = await negotiationDatabase.getMessagesForConversation(task.conversationId);
+                const turnCount = messages.length;
+                const lastSenderId = turnCount > 0 ? messages[turnCount - 1].senderId : null;
+                const paritySpeaker = turnCount % 2 === 0 ? 'source' : 'candidate';
+                const isUsersTurn = lastSenderId
+                    ? lastSenderId !== `agent:${context.userId}`
+                    : ((isSource && paritySpeaker === 'source') || (!isSource && paritySpeaker === 'candidate'));
+                if (!isUsersTurn) {
+                    return error('It is not your turn to respond in this negotiation.');
+                }
+                // The caller is the current speaker (verified above).
+                const currentSpeaker = isSource ? 'source' : 'candidate';
+                // Validate counter/question has a message
+                if ((query.action === 'counter' || query.action === 'question') && !query.message?.trim()) {
+                    return error(`A message is required when using "${query.action}". Explain what you want to change or clarify.`);
+                }
+                // ── Cancel pending timeout ──
+                if (deps.negotiationTimeoutQueue) {
+                    await deps.negotiationTimeoutQueue.cancelTimeout(task.id);
+                }
+                // ── Build and persist the external agent's turn ──
+                const turnData = {
+                    action: query.action,
+                    assessment: {
+                        reasoning: query.reasoning,
+                        suggestedRoles: query.suggestedRoles,
+                    },
+                    ...(query.message ? { message: query.message } : {}),
+                };
+                const senderId = `agent:${context.userId}`;
+                const turnMessage = await negotiationDatabase.createMessage({
+                    conversationId: task.conversationId,
+                    senderId,
+                    role: 'agent',
+                    parts: [{ kind: 'data', data: turnData }],
+                    taskId: task.id,
+                });
+                const newTurnCount = turnCount + 1;
+                // ── Handle terminal actions (accept / reject / withdraw / decline): finalize immediately ──
+                if (isTerminalAction(query.action)) {
+                    const allMessages = [...messages, { id: turnMessage.id, senderId: turnMessage.senderId, role: turnMessage.role, parts: turnMessage.parts, createdAt: turnMessage.createdAt }];
+                    const history = turnsFromMessages(allMessages);
+                    const nextSpeaker = currentSpeaker === 'source' ? 'candidate' : 'source';
+                    const outcome = buildNegotiationOutcome(history, newTurnCount, query.action, meta.sourceUserId, meta.candidateUserId, nextSpeaker);
+                    await negotiationDatabase.updateTaskState(task.id, 'completed');
+                    await negotiationDatabase.createArtifact({
+                        taskId: task.id,
+                        name: 'negotiation-outcome',
+                        parts: [{ kind: 'data', data: outcome }],
+                        metadata: { hasOpportunity: outcome.hasOpportunity, turnCount: newTurnCount },
+                    });
+                    return success({
+                        message: query.action === 'accept'
+                            ? 'Negotiation accepted. An opportunity has been created.'
+                            : query.action === 'withdraw'
+                                ? 'Negotiation withdrawn.'
+                                : query.action === 'decline'
+                                    ? 'Negotiation declined.'
+                                    : 'Negotiation rejected.',
+                        negotiationId: task.id,
+                        action: query.action,
+                        turnNumber: newTurnCount,
+                        outcome,
+                    });
+                }
+                // ── Handle counter/question: check if under max turns ──
+                const maxTurns = meta.maxTurns ?? 6; // Read from task metadata; fallback to system default
+                if (newTurnCount >= maxTurns) {
+                    // Max turns reached — finalize with turn_cap
+                    const allMessages = [...messages, { id: turnMessage.id, senderId: turnMessage.senderId, role: turnMessage.role, parts: turnMessage.parts, createdAt: turnMessage.createdAt }];
+                    const history = turnsFromMessages(allMessages);
+                    const nextSpeakerForCap = currentSpeaker === 'source' ? 'candidate' : 'source';
+                    const outcome = buildNegotiationOutcome(history, newTurnCount, 'counter', meta.sourceUserId, meta.candidateUserId, nextSpeakerForCap);
+                    await negotiationDatabase.updateTaskState(task.id, 'completed');
+                    await negotiationDatabase.createArtifact({
+                        taskId: task.id,
+                        name: 'negotiation-outcome',
+                        parts: [{ kind: 'data', data: outcome }],
+                        metadata: { hasOpportunity: false, turnCount: newTurnCount },
+                    });
+                    return success({
+                        message: 'Maximum turns reached. Negotiation finalized without opportunity.',
+                        negotiationId: task.id,
+                        action: query.action,
+                        turnNumber: newTurnCount,
+                        outcome,
+                    });
+                }
+                // ── Counter/question under max turns: dispatch to counterparty's agent ──
+                const counterpartyUserId = isSource ? meta.candidateUserId : meta.sourceUserId;
+                const counterpartySpeaker = isSource ? 'candidate' : 'source';
+                const counterpartySeat = resolveSeat(counterpartyUserId, meta);
+                // Build the current turn history for dispatcher payload
+                const allMessagesWithTurn = [...messages, { id: turnMessage.id, senderId: turnMessage.senderId, role: turnMessage.role, parts: turnMessage.parts, createdAt: turnMessage.createdAt }];
+                const historyForDispatch = turnsFromMessages(allMessagesWithTurn);
+                const isFinalTurn = newTurnCount + 1 >= maxTurns;
+                const ownUserCtx = { id: counterpartyUserId, intents: [], profile: {} };
+                const otherUserCtx = { id: context.userId, intents: [], profile: {} };
+                const seedAssessment = { reasoning: 'Continued negotiation', valencyRole: 'peer' };
+                const dispatchPayload = {
+                    negotiationId: task.id,
+                    ownUser: ownUserCtx,
+                    otherUser: otherUserCtx,
+                    indexContext: { networkId: '' },
+                    seedAssessment,
+                    history: historyForDispatch,
+                    isFinalTurn,
+                    isDiscoverer: false,
+                    seat: counterpartySeat,
+                    protocolVersion,
+                    allowedActions: [...allowedActionsFor(protocolVersion, counterpartySeat, isFinalTurn)],
+                };
+                const scope = { action: 'negotiation.respond', scopeType: 'negotiation', scopeId: task.id };
+                const timeoutMs = AMBIENT_PARK_WINDOW_MS;
+                const dispatchResult = await deps.agentDispatcher?.dispatch(counterpartyUserId, scope, dispatchPayload, { timeoutMs });
+                if (dispatchResult?.handled === false && dispatchResult.reason === 'waiting') {
+                    // Counterparty's agent acknowledged — yield and wait
+                    await negotiationDatabase.updateTaskState(task.id, 'waiting_for_agent');
+                    if (deps.negotiationTimeoutQueue) {
+                        await deps.negotiationTimeoutQueue.enqueueTimeout(task.id, newTurnCount, timeoutMs);
+                    }
+                    return success({
+                        message: `${query.action === 'question' ? 'Question' : query.action === 'propose' ? 'Proposal' : query.action === 'outreach' ? 'Outreach' : 'Counter-proposal'} submitted. Waiting for counterparty response.`,
+                        negotiationId: task.id,
+                        action: query.action,
+                        turnNumber: newTurnCount,
+                        waitingForAgent: true,
+                    });
+                }
+                let aiTurn;
+                if (dispatchResult?.handled === true) {
+                    // Dispatcher returned an agent turn directly
+                    aiTurn = dispatchResult.turn;
+                }
+                else {
+                    // No agent or timeout — run the system AI agent inline.
+                    // The agent honors a per-turn LLM timeout (AbortSignal), so invoke
+                    // can reject. Mirror the graph turnNode's reject-shaped fallback so
+                    // a timed-out or failed call degrades gracefully instead of leaving
+                    // the task pinned in `working` while the outer catch returns a bare
+                    // error to the user.
+                    await negotiationDatabase.updateTaskState(task.id, 'working');
+                    const agent = new IndexNegotiator();
+                    try {
+                        aiTurn = await agent.invoke({
+                            ownUser: ownUserCtx,
+                            otherUser: otherUserCtx,
+                            indexContext: { networkId: '' },
+                            seedAssessment,
+                            history: historyForDispatch,
+                            isFinalTurn,
+                            seat: counterpartySeat,
+                            protocolVersion,
+                        });
+                    }
+                    catch (err) {
+                        const errMsg = err instanceof Error ? err.message : String(err);
+                        const errName = err?.name ?? '';
+                        const isTimeout = errName === 'TimeoutError' || /timeout|abort/i.test(errMsg);
+                        // Log the raw error for ops, but keep the persisted/returned
+                        // reasoning generic — this string round-trips back to the caller
+                        // via counterpartyResponse.reasoning and ends up in the negotiation
+                        // history visible through get_negotiation, so we don't want raw
+                        // provider messages (URLs, request IDs, internal stack hints) on
+                        // the wire.
+                        logger.warn('System negotiator inline invoke failed; treating as reject', {
+                            taskId: task.id,
+                            isTimeout,
+                            error: errMsg,
+                        });
+                        aiTurn = {
+                            action: rejectActionFor(protocolVersion, counterpartySeat),
+                            assessment: {
+                                reasoning: isTimeout
+                                    ? 'Negotiator response timed out.'
+                                    : 'Negotiator failed to produce a response.',
+                                suggestedRoles: { ownUser: 'peer', otherUser: 'peer' },
+                            },
+                        };
+                    }
+                }
+                // Persist the counterparty's turn (from dispatcher or inline AI)
+                const aiSenderId = `agent:${counterpartyUserId}`;
+                await negotiationDatabase.createMessage({
+                    conversationId: task.conversationId,
+                    senderId: aiSenderId,
+                    role: 'agent',
+                    parts: [{ kind: 'data', data: aiTurn }],
+                    taskId: task.id,
+                });
+                const finalTurnCount = newTurnCount + 1;
+                // Evaluate response
+                if (isTerminalAction(aiTurn.action)) {
+                    const fullHistory = [...historyForDispatch, aiTurn];
+                    const outcome = buildNegotiationOutcome(fullHistory, finalTurnCount, aiTurn.action, meta.sourceUserId, meta.candidateUserId, counterpartySpeaker === 'source' ? 'candidate' : 'source');
+                    await negotiationDatabase.updateTaskState(task.id, 'completed');
+                    await negotiationDatabase.createArtifact({
+                        taskId: task.id,
+                        name: 'negotiation-outcome',
+                        parts: [{ kind: 'data', data: outcome }],
+                        metadata: { hasOpportunity: outcome.hasOpportunity, turnCount: finalTurnCount },
+                    });
+                    return success({
+                        message: `${query.action === 'question' ? 'Question' : query.action === 'propose' ? 'Proposal' : 'Counter'} submitted. Counterparty responded with ${aiTurn.action}.`,
+                        negotiationId: task.id,
+                        action: query.action,
+                        turnNumber: newTurnCount,
+                        counterpartyResponse: { action: aiTurn.action, reasoning: aiTurn.assessment.reasoning, message: aiTurn.message ?? null },
+                        outcome,
+                    });
+                }
+                // Counterparty countered/questioned — check if max turns reached
+                if (finalTurnCount >= maxTurns) {
+                    const fullHistory = [...historyForDispatch, aiTurn];
+                    const outcome = buildNegotiationOutcome(fullHistory, finalTurnCount, 'counter', meta.sourceUserId, meta.candidateUserId, counterpartySpeaker === 'source' ? 'candidate' : 'source');
+                    await negotiationDatabase.updateTaskState(task.id, 'completed');
+                    await negotiationDatabase.createArtifact({
+                        taskId: task.id,
+                        name: 'negotiation-outcome',
+                        parts: [{ kind: 'data', data: outcome }],
+                        metadata: { hasOpportunity: false, turnCount: finalTurnCount },
+                    });
+                    return success({
+                        message: 'Counterparty responded but max turns reached. Negotiation finalized.',
+                        negotiationId: task.id,
+                        action: query.action,
+                        turnNumber: newTurnCount,
+                        counterpartyResponse: { action: aiTurn.action, reasoning: aiTurn.assessment.reasoning, message: aiTurn.message ?? null },
+                        outcome,
+                    });
+                }
+                // Counterparty countered/questioned, now user's turn again — dispatch to user's agent
+                const userDispatchPayload = {
+                    negotiationId: task.id,
+                    ownUser: { id: context.userId, intents: [], profile: {} },
+                    otherUser: { id: counterpartyUserId, intents: [], profile: {} },
+                    indexContext: { networkId: '' },
+                    seedAssessment,
+                    history: [...historyForDispatch, aiTurn],
+                    isFinalTurn: finalTurnCount + 1 >= maxTurns,
+                    isDiscoverer: true,
+                    seat,
+                    protocolVersion,
+                    allowedActions: [...allowedActionsFor(protocolVersion, seat, finalTurnCount + 1 >= maxTurns)],
+                };
+                const userDispatchResult = await deps.agentDispatcher?.dispatch(context.userId, scope, userDispatchPayload, { timeoutMs });
+                if (!userDispatchResult || (userDispatchResult.handled === false && userDispatchResult.reason === 'no_agent')) {
+                    // No agent for user — set back to waiting_for_agent so they can use respond_to_negotiation
+                    await negotiationDatabase.updateTaskState(task.id, 'waiting_for_agent');
+                    if (deps.negotiationTimeoutQueue) {
+                        await deps.negotiationTimeoutQueue.enqueueTimeout(task.id, finalTurnCount, timeoutMs);
+                    }
+                    return success({
+                        message: `${query.action === 'question' ? 'Question' : 'Counter'} submitted. Counterparty responded. Your turn to respond.`,
+                        negotiationId: task.id,
+                        action: query.action,
+                        turnNumber: newTurnCount,
+                        counterpartyResponse: { action: aiTurn.action, reasoning: aiTurn.assessment.reasoning, message: aiTurn.message ?? null },
+                        waitingForAgent: true,
+                    });
+                }
+                if (userDispatchResult.handled === false && userDispatchResult.reason === 'waiting') {
+                    // User's agent acknowledged — yield and wait
+                    await negotiationDatabase.updateTaskState(task.id, 'waiting_for_agent');
+                    if (deps.negotiationTimeoutQueue) {
+                        await deps.negotiationTimeoutQueue.enqueueTimeout(task.id, finalTurnCount, timeoutMs);
+                    }
+                    return success({
+                        message: `${query.action === 'question' ? 'Question' : 'Counter'} submitted. Counterparty countered back. Waiting for your agent's response.`,
+                        negotiationId: task.id,
+                        action: query.action,
+                        turnNumber: newTurnCount,
+                        counterpartyResponse: { action: aiTurn.action, reasoning: aiTurn.assessment.reasoning, message: aiTurn.message ?? null },
+                        waitingForAgent: true,
+                    });
+                }
+                if (userDispatchResult.handled === true) {
+                    // User's agent returned a turn directly — persist, evaluate, and continue
+                    const userAgentTurn = userDispatchResult.turn;
+                    const userAgentSenderId = `agent:${context.userId}`;
+                    await negotiationDatabase.createMessage({
+                        conversationId: task.conversationId,
+                        senderId: userAgentSenderId,
+                        role: 'agent',
+                        parts: [{ kind: 'data', data: userAgentTurn }],
+                        taskId: task.id,
+                    });
+                    const userTurnCount = finalTurnCount + 1;
+                    if (isTerminalAction(userAgentTurn.action)) {
+                        const fullHistory = [...historyForDispatch, aiTurn, userAgentTurn];
+                        const userSpeaker = isSource ? 'source' : 'candidate';
+                        const outcome = buildNegotiationOutcome(fullHistory, userTurnCount, userAgentTurn.action, meta.sourceUserId, meta.candidateUserId, userSpeaker === 'source' ? 'candidate' : 'source');
+                        await negotiationDatabase.updateTaskState(task.id, 'completed');
+                        await negotiationDatabase.createArtifact({
+                            taskId: task.id,
+                            name: 'negotiation-outcome',
+                            parts: [{ kind: 'data', data: outcome }],
+                            metadata: { hasOpportunity: outcome.hasOpportunity, turnCount: userTurnCount },
+                        });
+                        return success({
+                            message: `Your agent ${userAgentTurn.action}ed the counterparty's response.`,
+                            negotiationId: task.id,
+                            action: query.action,
+                            turnNumber: newTurnCount,
+                            counterpartyResponse: { action: aiTurn.action, reasoning: aiTurn.assessment.reasoning, message: aiTurn.message ?? null },
+                            outcome,
+                        });
+                    }
+                    if (userTurnCount >= maxTurns) {
+                        const fullHistory = [...historyForDispatch, aiTurn, userAgentTurn];
+                        const outcome = buildNegotiationOutcome(fullHistory, userTurnCount, 'counter', meta.sourceUserId, meta.candidateUserId, isSource ? 'candidate' : 'source');
+                        await negotiationDatabase.updateTaskState(task.id, 'completed');
+                        await negotiationDatabase.createArtifact({
+                            taskId: task.id,
+                            name: 'negotiation-outcome',
+                            parts: [{ kind: 'data', data: outcome }],
+                            metadata: { hasOpportunity: false, turnCount: userTurnCount },
+                        });
+                        return success({
+                            message: 'Your agent responded but max turns reached. Negotiation finalized.',
+                            negotiationId: task.id,
+                            action: query.action,
+                            turnNumber: newTurnCount,
+                            counterpartyResponse: { action: aiTurn.action, reasoning: aiTurn.assessment.reasoning, message: aiTurn.message ?? null },
+                            outcome,
+                        });
+                    }
+                    // User's agent countered/questioned — arm timeout for counterparty's next turn
+                    await negotiationDatabase.updateTaskState(task.id, 'waiting_for_agent');
+                    if (deps.negotiationTimeoutQueue) {
+                        await deps.negotiationTimeoutQueue.enqueueTimeout(task.id, userTurnCount, timeoutMs);
+                    }
+                    return success({
+                        message: `Your agent responded with ${userAgentTurn.action}. Waiting for counterparty.`,
+                        negotiationId: task.id,
+                        action: query.action,
+                        turnNumber: newTurnCount,
+                        counterpartyResponse: { action: aiTurn.action, reasoning: aiTurn.assessment.reasoning, message: aiTurn.message ?? null },
+                        waitingForAgent: true,
+                    });
+                }
+                // No agent / timeout — set back to working so graph can continue
+                await negotiationDatabase.updateTaskState(task.id, 'working');
+                return success({
+                    message: `${query.action === 'question' ? 'Question' : 'Counter'} submitted. Counterparty countered back. Negotiation continues.`,
+                    negotiationId: task.id,
+                    action: query.action,
+                    turnNumber: newTurnCount,
+                    counterpartyResponse: { action: aiTurn.action, reasoning: aiTurn.assessment.reasoning, message: aiTurn.message ?? null },
+                });
+            }
+            catch (err) {
+                logger.error('Failed to respond to negotiation', { err });
+                return error('Failed to respond to negotiation. Please try again.');
+            }
+        },
+    });
+    return [list_negotiations, get_negotiation, respond_to_negotiation];
+}
+/**
+ * Build a NegotiationOutcome from the full turn history.
+ * Mirrors the logic in the graph's finalizeNode for consistency.
+ *
+ * @param history - All negotiation turns
+ * @param turnCount - Total number of turns
+ * @param lastAction - The last turn's action (accept/reject/counter)
+ * @param sourceUserId - Source user ID
+ * @param candidateUserId - Candidate user ID
+ * @param currentSpeaker - Who would speak next (the person after the accepter/rejector)
+ */
+function buildNegotiationOutcome(history, turnCount, lastAction, sourceUserId, candidateUserId, currentSpeaker) {
+    const hasOpportunity = lastAction === 'accept';
+    // Non-terminal last action at finalization means the turn cap was hit.
+    const atCap = !isTerminalAction(lastAction);
+    let agreedRoles = [];
+    if (hasOpportunity && history.length >= 2) {
+        const acceptTurn = history[history.length - 1];
+        const precedingTurn = history[history.length - 2];
+        const accepterIsSource = currentSpeaker === 'candidate';
+        const [sourceRole, candidateRole] = accepterIsSource
+            ? [acceptTurn.assessment.suggestedRoles.ownUser, precedingTurn.assessment.suggestedRoles.ownUser]
+            : [precedingTurn.assessment.suggestedRoles.ownUser, acceptTurn.assessment.suggestedRoles.ownUser];
+        agreedRoles = [
+            { userId: sourceUserId, role: sourceRole },
+            { userId: candidateUserId, role: candidateRole },
+        ];
+    }
+    return {
+        hasOpportunity,
+        agreedRoles,
+        reasoning: history[history.length - 1]?.assessment.reasoning ?? '',
+        turnCount,
+        ...(atCap && { reason: 'turn_cap' }),
+    };
+}