Skip to content

feat(mcp): add opt-in stop, resume, and cancel tracking tools - #508

Merged
alosec merged 7 commits into
mainfrom
alex/dev-14372-tracking-lifecycle
Nov 6, 2026
Merged

alosec merged 7 commits into
mainfrom
alex/dev-14372-tracking-lifecycle

Conversation

@alosec

@alosec alosec commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Add stop_shipment_tracking, resume_shipment_tracking, and cancel_tracking_request behind the opt-in tracking_lifecycle toolset. Stop/cancel preview first and support both user elicitation and confirmation-token flows; resume is additive. Default discovery stays at 30 tools.

Third part of #451 / DEV-14372, based on #507. Original author: Akshay Dodeja. Includes behavior, contracts, protocol, stdio-secret, gateway auth, and telemetry-redaction coverage.

Validation: full npm run agent-verify plus all 88 gateway tests through the explicit MCP test config. The integration snapshot is generated from the actual tool registry.

Known limit preserved from #451: approval consumption is per process. After stop then resume restores the same public shipment state, a different gateway instance can accept the old stop approval within its five-minute expiry. This is why lifecycle tools remain opt-in. No production toolset change is included.


Prove it works
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.

Review order: #506 → #507 → #508 → #509. Each diff is against its predecessor; #509 is the combined QA target.

Follow-up review: Resuming tracking explicitly warns about tracking quota and possible pay-as-you-go charges and requests client interaction. It remains additive/non-destructive and does not gain a server confirmation token. Client UI owns approval.

RetriggerView in GreptileConfidence Score: 4/5

The PR appears safe to merge, with non-blocking feedback on batch audit outcomes.

Fix All in CodexFindings

  1. P2 Failed batches look successful ▶
Fix with agent prompt
### Issue 1
packages/mcp/src/tools/write-kit.ts:505-511
`auditOutcome` returns `done` for every normal batch result because `RecordWriteResult` has neither `status` nor `error`. A batch where every save fails therefore gets the same audit outcome as a fully successful batch. This makes failed and partial writes harder to spot in logs and analytics.

Add a batch-specific outcome based on `updated`, `failed`, and `not_attempted`.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Adds opt-in tracking lifecycle tools and shared approval flows for destructive writes.

  • Shipment tracking can be stopped, resumed, or cancelled through opt-in tools.
  • Party-role and custom-field changes preview before removing existing data.
  • Confirmation tokens are removed from write logs and telemetry.
  • SDK rate-limit errors include how long callers should wait.

Acknowledged limits: alosec explicitly preserves per-process approval consumption, including cross-instance stop/resume replay within five minutes. The supplied follow-up also intentionally leaves resume approval to the client.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart TD
  Call[Write tool call] --> Read[Read current records]
  Read --> Kind{Change needs approval?}
  Kind -->|No| Write[Apply change]
  Kind -->|Yes| Approval{Matching approval supplied?}
  Approval -->|No| Preview[Return preview or ask client]
  Preview --> Call
  Approval -->|Yes| Spend[Reserve approval]
  Spend --> Write
  Write --> Audit[Record audit outcome]
  Audit --> Result[Return result]
Loading

Reviews (1) · Last reviewed commit: "test(mcp): expect client interaction for..." · Reviewed by Greptile

@vercel

vercel Bot commented Nov 6, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
api Ready Ready Preview Nov 6, 2026 8:31pm UTC

Request Review

@linear-code

linear-code Bot commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

DEV-14372

@github-actions github-actions Bot added the risk-shadow:high Shadow-only risk signal: high label Nov 6, 2026
@github-actions

github-actions Bot commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

Shadow risk calibration

Signal Result Authority
Path classifier risk:high Deterministic advisory policy
heuristic fallback risk-shadow:high Shadow only

Calibration result: agreement.

Shadow risk never blocks or enables merge. Keep it in observation mode until roughly 50 pull requests have human-reviewed labels, then calibrate before considering any policy use.

@alosec
alosec changed the base branch from alex/dev-14372-confirmed-batch-writes to main November 6, 2026 20:52
@mintlify

mintlify Bot commented Nov 6, 2026 •

Copy link
Copy Markdown
Contributor

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated
terminal49 🟢 Ready View Preview Nov 6, 2026, 8:53 PM

💡 Tip: Enable Automations to automatically generate PRs for you.

@alosec
alosec marked this pull request as ready for review November 6, 2026 20:52
@github-actions github-actions Bot added the risk:high Advisory path risk; current-head human review needed label Nov 6, 2026
@alosec
alosec merged commit 7a81377 into main Nov 6, 2026
33 checks passed
@alosec
alosec deleted the alex/dev-14372-tracking-lifecycle branch November 6, 2026 20:55
Comment on lines +505 to +511
export function auditOutcome(result: unknown): string {
const parsed = z
.object({ status: z.string() })
.or(z.object({ error: z.string() }))
.safeParse(result);
if (!parsed.success) return 'done';
return 'status' in parsed.data ? parsed.data.status : parsed.data.error;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Failed batches look successful

auditOutcome returns done for every normal batch result because RecordWriteResult has neither status nor error. A batch where every save fails therefore gets the same audit outcome as a fully successful batch. This makes failed and partial writes harder to spot in logs and analytics.

Add a batch-specific outcome based on updated, failed, and not_attempted.

Knowledge Base Used: MCP observability and quality assurance

Prompt To Fix With AI
This is a comment left during a code review.
Path: packages/mcp/src/tools/write-kit.ts
Line: 505-511

Comment:
**Failed batches look successful**

`auditOutcome` returns `done` for every normal batch result because `RecordWriteResult` has neither `status` nor `error`. A batch where every save fails therefore gets the same audit outcome as a fully successful batch. This makes failed and partial writes harder to spot in logs and analytics.

Add a batch-specific outcome based on `updated`, `failed`, and `not_attempted`.

**Knowledge Base Used:** [MCP observability and quality assurance](https://app.greptile.com/-/switch-tenant?tenant=terminal49&next=%2Fcustom-context%2Fknowledge-base%2Fterminal49%2Fapi%2F-%2Fdocs%2Fmcp-observability-and-quality.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Fix in Codex Fix in Claude Code

@github-actions github-actions Bot added risk:unknown Advisory evidence unavailable or changed; no merge permission and removed risk:high Advisory path risk; current-head human review needed labels Nov 6, 2026

This branch was successfully deployed

2 active deployments
staging - docs — 02b2563e Deployed Nov 6, 2026 by mintlify[bot]
Preview — 02b2563e Deployed Nov 6, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

risk:unknown Advisory evidence unavailable or changed; no merge permission risk-shadow:high Shadow-only risk signal: high

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant