feat(see): link cards to bounded run traces (TASK-499)

backend/__tests__/service/runTraceToolCalls.test.js

@@ -0,0 +1,24 @@
+/** Read joins must execute against real PostgreSQL, not only pg-mem. */
+const ToolCall = require('../../models/ToolCall');
+const { pool } = require('../../config/db-pg');
+const run = process.env.INTEGRATION_TEST === 'true' ? describe : describe.skip;
+const grantId = `lark-trace-${Date.now()}`;
+const podId = `${grantId}-pod`;
+run('run trace attribution on real PostgreSQL', () => {
+  afterAll(async () => { await pool.query('DELETE FROM tool_calls WHERE grant_id = $1', [grantId]); });
+  it('reads only referenced calls in the authorized pod, with current approval outcome', async () => {
+    const record = (id, over = {}) => ({ callId: `${grantId}-${id}`, grantId, podId,
+      agentUserId: 'agent', credentialOwnerId: 'credential-owner', tool: 'vendor.read',
+      argsDigest: 'a'.repeat(64), outcome: 'ok', ...over });
+    await ToolCall.create(record('ok'));
+    await ToolCall.create(record('pending', { outcome: 'pending_approval', approvalId: 'approval' }));
+    await ToolCall.create(record('resolved', { outcome: 'failed', approvalId: 'approval' }));
+    await ToolCall.create(record('foreign', { podId: 'another-pod' }));
+    const ids = ['ok', 'pending', 'foreign'].map((id) => `${grantId}-${id}`);
+    const rows = await ToolCall.listRunReferences(podId, ids);
+    expect(rows).toHaveLength(2);
+    expect(rows.find((r) => r.callId.endsWith('-ok'))).toMatchObject({ grantId, credentialOwnerId: 'credential-owner', outcome: 'ok' });
+    expect(rows.find((r) => r.callId.endsWith('-pending')).outcome).toBe('superseded');
+    expect(await ToolCall.listRunReferences(podId, [])).toEqual([]);
+  });
+});

backend/__tests__/unit/models/ApprovalAction.runTrace.test.js

@@ -0,0 +1,26 @@
+const mongoose = require('mongoose');
+const { setupMongoDb, closeMongoDb } = require('../../utils/testUtils');
+const ApprovalAction = require('../../../models/ApprovalAction');
+
+beforeAll(setupMongoDb);
+afterAll(closeMongoDb);
+
+test('the originating run persists across an approval save, reload and transition', async () => {
+  const runId = new mongoose.Types.ObjectId();
+  const runPodId = new mongoose.Types.ObjectId();
+  const action = await ApprovalAction.create({
+    podId: new mongoose.Types.ObjectId(), ownerUserId: new mongoose.Types.ObjectId(),
+    agentName: 'trace-seat', actionType: 'create_pod', params: { name: 'Research' },
+    summary: 'Create a research pod', runId, runPodId,
+  });
+  const loaded = await ApprovalAction.findById(action._id);
+  expect(String(loaded.runId)).toBe(String(runId));
+  expect(String(loaded.runPodId)).toBe(String(runPodId));
+  loaded.status = 'resolved';
+  loaded.decision = 'declined';
+  await loaded.save();
+  const resolved = await ApprovalAction.findById(action._id).lean();
+  expect(String(resolved.runId)).toBe(String(runId));
+  expect(String(resolved.runPodId)).toBe(String(runPodId));
+  expect(resolved.status).toBe('resolved');
+});

backend/__tests__/unit/routes/runTraces.test.js

@@ -0,0 +1,139 @@
+jest.mock('../../../config/db-pg', () => {
+  const { newDb } = require('pg-mem');
+  const { Pool } = newDb().adapters.createPg();
+  return { pool: new Pool() };
+});
+const express = require('express');
+const request = require('supertest');
+const mongoose = require('mongoose');
+const { MongoMemoryServer } = require('mongodb-memory-server');
+
+jest.mock('../../../middleware/auth', () => (req, res, next) => {
+  if (!req.get('x-user')) return res.sendStatus(401);
+  req.user = { id: req.get('x-user') };
+  return next();
+});
+const AgentRun = require('../../../models/AgentRun');
+const Pod = require('../../../models/Pod');
+const User = require('../../../models/User');
+const ToolCall = require('../../../models/ToolCall');
+const { pool } = require('../../../config/db-pg');
+const { boundRunValue, RUN_TRACE_BYTES } = require('../../../services/agentRunLimits');
+const { BSON } = require('mongodb');
+const MEMBER = new mongoose.Types.ObjectId();
+const POD = new mongoose.Types.ObjectId();
+const OTHER = new mongoose.Types.ObjectId();
+let mongo;
+let app;
+let run;
+beforeAll(async () => {
+  mongo = await MongoMemoryServer.create();
+  await mongoose.connect(mongo.getUri());
+  app = express();
+  app.use('/api/pods', require('../../../routes/runTraces'));
+});
+afterAll(async () => { await mongoose.disconnect(); await mongo.stop(); });
+beforeEach(async () => {
+  await AgentRun.deleteMany({});
+  await Pod.deleteMany({});
+  await User.deleteMany({});
+  await Pod.create({ _id: POD, name: 'Trace pod', type: 'team', members: [MEMBER], createdBy: MEMBER });
+  run = await AgentRun.create({
+    podId: POD, agentName: 'trace-seat', instanceId: 'default', trigger: 'mention', status: 'succeeded',
+    startedAt: new Date('2020-01-01'),
+    turns: [{ turnIndex: 0, model: 'model', elapsedMs: 1, llmResponseText: 'private prompt',
+      toolCalls: [{ name: 'vendor.read', args: { secret: 'PRIVATE_ARGS' }, result: 'PRIVATE_RESULT', callId: 'trace-call', outcome: 'ok' }] }],
+  });
+  await ToolCall.create({ callId: `unused-${run.id}`, grantId: 'grant', podId: String(POD), agentUserId: 'seat', tool: 'vendor.read', argsDigest: 'a'.repeat(64), outcome: 'ok' });
+  await pool.query('DELETE FROM tool_calls WHERE call_id IN ($1, $2)', ['trace-call', 'foreign-call']);
+  await ToolCall.create({ callId: 'trace-call', grantId: 'grant', podId: String(POD), credentialOwnerId: 'owner', agentUserId: 'seat', tool: 'vendor.read', argsDigest: 'a'.repeat(64), outcome: 'ok' });
+  await ToolCall.create({ callId: 'foreign-call', grantId: 'foreign-grant', podId: String(OTHER), credentialOwnerId: 'foreign-owner', agentUserId: 'seat', tool: 'vendor.read', argsDigest: 'a'.repeat(64), outcome: 'failed' });
+});
+const get = (pod = POD, id = run.id, user = MEMBER) => request(app).get(`/api/pods/${pod}/runs/${id}`).set('x-user', String(user));
+
+test('requires authentication and current pod access, not knowledge of a run ID', async () => {
+  expect((await request(app).get(`/api/pods/${POD}/runs/${run.id}`)).status).toBe(401);
+  expect((await get(POD, run.id, OTHER)).status).toBe(404);
+  expect((await get(OTHER)).status).toBe(404);
+  expect((await get(POD, 'bad-id')).status).toBe(404);
+});
+test('returns durable turn + PG attribution after card retention without content', async () => {
+  const res = await get();
+  expect(res.status).toBe(200);
+  expect(res.headers['cache-control']).toBe('no-store');
+  expect(res.body.run.turns[0].toolCalls[0].trail).toMatchObject({ callId: 'trace-call', grantId: 'grant', credentialOwnerId: 'owner', outcome: 'ok' });
+  expect(JSON.stringify(res.body)).not.toMatch(/PRIVATE_|private prompt|argsDigest/);
+  expect(res.body.retention).toEqual({ cardDefaultDays: 30, traceExpiresAt: null });
+});
+test.each(['global admin', 'agent-dm observer'])(
+  'returns trace metadata without authorization identities to a non-member %s', async (viewerType) => {
+    if (viewerType === 'global admin') {
+      await User.create({ _id: OTHER, username: 'trace-admin', email: 'trace-admin@example.test',
+        role: 'admin', authProviders: [{ provider: 'github', providerId: 'trace-admin' }] });
+    } else {
+      await Pod.updateOne({ _id: POD }, { $set: { type: 'agent-dm' } });
+      await Pod.create({ name: 'Shared team', type: 'team', members: [MEMBER, OTHER], createdBy: MEMBER });
+    }
+    const res = await get(POD, run.id, OTHER);
+    expect(res.status).toBe(200);
+    expect(res.headers['cache-control']).toBe('no-store');
+    const call = res.body.run.turns[0].toolCalls[0];
+    expect(call.outcome).toBe('ok');
+    expect(call.trail).toEqual({ callId: 'trace-call', tool: 'vendor.read', outcome: 'ok',
+      at: expect.any(String), durationMs: null });
+    expect(JSON.stringify(res.body)).not.toMatch(/grantId|credentialOwnerId|PRIVATE_|private prompt|argsDigest/);
+  },
+);
+test('cross-pod references never join a foreign trail', async () => {
+  run.turns[0].toolCalls[0].callId = 'foreign-call';
+  await run.save();
+  const res = await get();
+  expect(res.status).toBe(200);
+  expect(res.body.run.turns[0].toolCalls[0]).toMatchObject({ outcome: 'unavailable', trail: null });
+  expect(JSON.stringify(res.body)).not.toMatch(/foreign-owner|foreign-grant/);
+});
+test('PG failure is explicit instead of an empty audit', async () => {
+  jest.spyOn(ToolCall, 'listRunReferences').mockRejectedValueOnce(new Error('db offline'));
+  expect((await get()).status).toBe(503);
+});
+test('save caps UTF-8 args/results, response text and aggregate BSON size', async () => {
+  const huge = '界'.repeat(10000);
+  run.turns = Array.from({ length: 140 }, (_, turnIndex) => ({
+    turnIndex, model: 'm', elapsedMs: 1, llmResponseText: huge,
+    toolCalls: Array.from({ length: turnIndex === 0 ? 70 : 0 }, () => ({ name: 'read', elapsedMs: 1, args: huge, result: huge })),
+  }));
+  await run.save();
+  const stored = await AgentRun.findById(run.id).lean();
+  expect(stored.traceTruncated).toBe(true);
+  expect(stored.turns[0].toolCalls[0].args).toEqual({ truncated: true, originalBytes: Buffer.byteLength(JSON.stringify(huge)) });
+  expect(stored.omittedTurns).toBeGreaterThan(0);
+  expect(stored.omittedToolCalls).toBeGreaterThan(0);
+  expect(Buffer.byteLength(JSON.stringify(stored.turns))).toBeLessThan(RUN_TRACE_BYTES);
+  expect(BSON.calculateObjectSize(JSON.parse(JSON.stringify(stored)))).toBeLessThan(8 * 1024 * 1024);
+  expect(boundRunValue({ small: 'kept' })).toEqual({ small: 'kept' });
+  expect(boundRunValue([...[...Array(300)].map(() => 0)])).toMatchObject({ truncated: true });
+  await run.save();
+  expect(run.omittedTurns).toBe(stored.omittedTurns);
+});
+
+
+test('aggregate budget caps many individually valid values before Mongo insert', async () => {
+  run.turns = Array.from({ length: 80 }, (_, turnIndex) => ({
+    turnIndex, model: 'm', elapsedMs: 1,
+    toolCalls: Array.from({ length: 10 }, () => ({ name: 'read', elapsedMs: 1,
+      args: 'x'.repeat(4000), result: 'y'.repeat(4000) })),
+  }));
+  await run.save();
+  const stored = await AgentRun.findById(run.id).lean();
+  expect(stored.omittedToolCalls).toBeGreaterThan(0);
+  expect(BSON.calculateObjectSize(JSON.parse(JSON.stringify(stored.turns)))).toBeLessThan(RUN_TRACE_BYTES);
+});
+
+
+test('limits repeated trace reads before authentication and database work', async () => {
+  let status;
+  for (let attempt = 0; attempt < 125 && status !== 429; attempt += 1) {
+    status = (await request(app).get(`/api/pods/${POD}/runs/bad-id`)).status;
+  }
+  expect(status).toBe(429);
+});

backend/__tests__/unit/services/agentMessageService.threadWrites.test.js

@@ -430,3 +430,26 @@ describe('agent in-thread posts (threadRootId, no reply edge)', () => {
     expect(mockFirstTask).not.toHaveBeenCalled();
   });
 });
+
+
+test('server run identity survives PG storage and live message broadcast with existing card fields', async () => {
+  const runId = 'aaaaaaaaaaaaaaaaaaaaa111';
+  await AgentMessageService.postMessage({
+    agentName: 'sprint-review', instanceId: 'default', podId: POD,
+    content: 'Run complete.', messageType: 'card',
+    payload: { kind: 'starts', starts: [{ id: 'test', label: 'Test' }], runId: 'forged', runPodId: 'forged-pod' }, runId, runPodId: POD,
+  });
+  expect(PGMessage.create.mock.calls[0][5]).toEqual({
+    kind: 'starts', starts: [{ id: 'test', label: 'Test' }], runId, runPodId: POD,
+  });
+  expect(emitted.find((entry) => entry.event === 'newMessage').payload.payload.runId).toBe(runId);
+});
+
+
+test('an agent-authored payload cannot claim another run', async () => {
+  await AgentMessageService.postMessage({
+    agentName: 'sprint-review', instanceId: 'default', podId: POD,
+    content: 'A card.', payload: { kind: 'ui', runId: 'aaaaaaaaaaaaaaaaaaaaa111', runPodId: POD },
+  });
+  expect(PGMessage.create.mock.calls[0][5]).toEqual({ kind: 'ui' });
+});

backend/__tests__/unit/services/approvalActionService.test.js

@@ -490,3 +490,36 @@ describe('approved connect_local_agent execution — the seat, never the token',
     expect(mockInstallUpsert).not.toHaveBeenCalled();
   });
 });
+
+
+test('approval card rebuilds keep their originating run after a transition', () => {
+  const { buildCardPayload } = require('../../../services/approvalActionService');
+  const row = flaggedRow({ runId: 'aaaaaaaaaaaaaaaaaaaaa111' });
+  expect(buildCardPayload(row).runId).toBe('aaaaaaaaaaaaaaaaaaaaa111');
+  expect(buildCardPayload({ ...row, status: 'resolved', decision: 'declined' }).runId).toBe('aaaaaaaaaaaaaaaaaaaaa111');
+});
+
+
+test('a proposal carries its originating run into the saved action and posted card', async () => {
+  const { proposeAction } = require('../../../services/approvalActionService');
+  const runId = 'aaaaaaaaaaaaaaaaaaaaa111';
+  const runPodId = 'bbbbbbbbbbbbbbbbbbbbb111';
+  const row = flaggedRow({ runId, runPodId });
+  mockPodFindById.mockReturnValue({ select: () => ({ lean: async () => ({ createdBy: OWNER }) }) });
+  mockInstallFindOne.mockResolvedValue({ installedBy: OWNER });
+  mockApprovalCreate.mockResolvedValue(row);
+  mockPostMessage.mockResolvedValue({ success: true, message: { id: 42 } });
+
+  const result = await proposeAction({
+    podId: 'pod-1', agentName: 'guide', instanceId: 'udefault', runId, runPodId,
+    actionType: 'create_pod', params: { name: 'Research', type: 'chat' }, summary: 'Create a research pod',
+  });
+
+  expect(result.ok).toBe(true);
+  expect(mockApprovalCreate).toHaveBeenCalledWith(expect.objectContaining({ runId, runPodId }));
+  expect(mockPostMessage).toHaveBeenCalledWith(expect.objectContaining({
+    runId, runPodId, payload: expect.objectContaining({ runId, runPodId, kind: 'approval-card' }),
+  }));
+  expect(row.messageId).toBe('42');
+  expect(row.save).toHaveBeenCalled();
+});

backend/__tests__/unit/services/grantBrokerProjectionService.test.js

@@ -203,6 +203,8 @@ describe('dispatchHostedBrokerTool', () => {
       agentName: 'kai',
       instanceId: 'default',
       noOutboundRelay: true,
+      runId: 'aaaaaaaaaaaaaaaaaaaaa111',
+      runPodId: POD_A,
     });
 
     expect(mockCallTool).toHaveBeenCalledWith({
@@ -214,6 +216,8 @@ describe('dispatchHostedBrokerTool', () => {
       // so the seat-confinement refusal does not apply to it (Wren, TASK-175).
       hostedTurn: true,
       noOutboundRelay: true,
+      runId: 'aaaaaaaaaaaaaaaaaaaaa111',
+      runPodId: POD_A,
       tool: 'github.list_issues',
       args: { grantId: 'grant-someone-else', agentUserId: OTHER_SEAT, state: 'open' },
     });

backend/__tests__/unit/services/nativeRuntimeService.byoHandoff.test.js

@@ -109,6 +109,7 @@ describe('commonly_offer_local_agent', () => {
     const posted = AgentMessageService.postMessage.mock.calls[0][0];
     expect(posted.messageType).toBe('card');
     expect(posted.payload.kind).toBe('byo-handoff');
+    expect(posted.runId).toBe('run-1');
     expect(posted.payload.agentName).toBe('sam-xu-opencode');
     expect(posted.payload.commands.mac).toContain('commonly agent attach opencode');
     expect(posted.payload.commands.mac).toContain('--memory-from scout --memory-instance default');

backend/__tests__/unit/services/nativeRuntimeService.hostedBroker.test.js

@@ -229,6 +229,8 @@ describe('a hosted run in a granted pod', () => {
       // seat-confinement refusal is out of scope for it (Wren, TASK-175).
       hostedTurn: true,
       noOutboundRelay: false,
+      runId: 'run-1',
+      runPodId: POD,
       tool: 'github.list_issues',
       args: { state: 'open' },
     });

backend/__tests__/unit/services/nativeRuntimeService.hostedOffer.test.js

@@ -90,6 +90,7 @@ describe('commonly_offer_hosted_agent', () => {
     const posted = AgentMessageService.postMessage.mock.calls[0][0];
     expect(posted.content).toBe(REPLY);
     expect(posted.podId).toBe(POD);
+    expect(posted.runId).toBe('run-1');
     expect(posted.payload).toEqual({
       kind: 'starts',
       starts: [{ id: 'run-hosted', label: 'Run it here', href: `/v2/agents/byo?pod=${POD}&mode=hosted` }],

backend/__tests__/unit/services/nativeRuntimeService.webSearch.test.js

@@ -124,6 +124,21 @@ describe('native turn with commonly_web_search', () => {
     mockProposeAction.mockResolvedValue({ ok: true, approvalId: 'approval-1' });
   });
 
+  test.each([
+    [{ success: false, refused: true, reason: 'consecutive_agent_cap' }, 'failed', false],
+    [{ success: true, message: { id: 'posted-1' } }, 'ok', true],
+  ])('records the actual post result %j as %s', async (postResult, outcome, posted) => {
+    AgentMessageService.postMessage.mockResolvedValueOnce(postResult);
+    axios.post.mockResolvedValueOnce(toolCalls(call('p1', 'commonly_post_message', { content: 'Here is the update.' })))
+      .mockResolvedValueOnce(finalReply);
+    await runAgent(install, mention);
+    const recorded = savedRun.turns[0].toolCalls[0];
+    expect(recorded.name).toBe('commonly_post_message');
+    expect(recorded.outcome).toBe(outcome);
+    expect(recorded.error).toBe(posted ? undefined : 'message_post_refused');
+    expect(JSON.parse(toolMessages(1)[0].content)).toEqual(expect.objectContaining({ posted, ok: posted }));
+  });
+
   test('results reach the model marked untrusted; the run keeps the count and the addresses only', async () => {
     axios.post
       .mockResolvedValueOnce(toolCalls(call('c1', 'commonly_web_search', { query: 'node 26 release' })))
@@ -210,7 +225,7 @@ describe('native turn with commonly_web_search', () => {
 
       expect(offeredIn(1)).toContain('linear_list_issues');
       expect(AgentMessageService.postMessage).toHaveBeenCalledWith(expect.objectContaining({
-        content: 'issue result', noOutboundRelay: true,
+        content: 'issue result', noOutboundRelay: true, runId: 'run-1', runPodId: install.podId,
       }));
     });
 
@@ -286,7 +301,7 @@ describe('native turn with commonly_web_search', () => {
 
       expect(offeredIn(1)).toContain('linear_list_issues');
       expect(AgentMessageService.postMessage).toHaveBeenCalledWith(expect.objectContaining({
-        content: 'Here is what shipped.', noOutboundRelay: true,
+        content: 'Here is what shipped.', noOutboundRelay: true, runId: 'run-1', runPodId: install.podId,
       }));
     });
 
@@ -329,7 +344,7 @@ describe('native turn with commonly_web_search', () => {
 
       await runAgent(proposalInstall, mention);
 
-      expect(mockProposeAction).toHaveBeenCalledWith(expect.objectContaining({ noOutboundRelay: true }));
+      expect(mockProposeAction).toHaveBeenCalledWith(expect.objectContaining({ noOutboundRelay: true, runId: 'run-1', runPodId: install.podId }));
     });
 
     test('a failed hosted turn after a broker call keeps its fixed line inside the pod', async () => {
@@ -346,7 +361,7 @@ describe('native turn with commonly_web_search', () => {
       expect(result.status).toBe('failed');
       expect(AgentMessageService.postMessage).toHaveBeenCalledWith(expect.objectContaining({
         metadata: expect.objectContaining({ runFailed: true }),
-        noOutboundRelay: true,
+        noOutboundRelay: true, runId: 'run-1', runPodId: install.podId,
       }));
     });
 

backend/__tests__/unit/services/toolBrokerService.test.js

@@ -469,13 +469,17 @@ describe('tool broker guard rails', () => {
       tools: ['github.close_issue'], writeMode: 'write-with-confirm', budget: { calls: 1 },
     }));
     await expect(callTool({
-      grantId: 'grant-1', agentUserId: 'agent-a', tool: 'github.close_issue', args: { issueNumber: 7 },
+      grantId: 'grant-1', agentUserId: 'agent-a', tool: 'github.close_issue',
+      runId: 'aaaaaaaaaaaaaaaaaaaaa111', runPodId: 'bbbbbbbbbbbbbbbbbbbbb111', args: { issueNumber: 7 },
     })).rejects.toMatchObject({ code: 'approval_required' });
     expect(mockReserveBudgetLineage).not.toHaveBeenCalled();
     expect(mockToolCall.create).toHaveBeenCalledWith(expect.objectContaining({
       outcome: 'pending_approval', reason: 'approval_required',
     }));
     expect(mockGithub.closeIssue).not.toHaveBeenCalled();
+    expect(require('../../../services/approvalActionService').proposeAction).toHaveBeenCalledWith(expect.objectContaining({
+      runId: 'aaaaaaaaaaaaaaaaaaaaa111', runPodId: 'bbbbbbbbbbbbbbbbbbbbb111',
+    }));
   });
 });