Delete Trace

Instructions

Implementation Reference

• src/tools/delete-trace.ts:57-67 (handler)

  The handler function (inline in registerTool) that calls storage.deleteTrace(LOCAL_TENANT, args.trace_id) and returns { deleted, trace_id }. This is the core execution logic of the delete_trace tool.

  async (args) => {
    const deleted = await storage.deleteTrace(LOCAL_TENANT, args.trace_id);
    return {
      content: [
        {
          type: 'text' as const,
          text: JSON.stringify({ deleted, trace_id: args.trace_id }),
        },
      ],
    };
  },

• src/tools/delete-trace.ts:17-22 (schema)

  Input schema for delete_trace: trace_id is a Zod string matching 32-hex lowercase regex, described as obtained from log_trace or get_traces.

  const inputSchema = {
    trace_id: z
      .string()
      .regex(/^[a-f0-9]{32}$/)
      .describe('Trace id to delete (32-hex lowercase; obtained from log_trace response or get_traces)'),
  };

• src/tools/delete-trace.ts:24-69 (registration)

  The registerDeleteTraceTool function that registers the 'delete_trace' tool on the MCP server with title, description, inputSchema, annotations (destructiveHint: true, readOnlyHint: false), and the handler.

  export function registerDeleteTraceTool(
    server: McpServer,
    storage: IStorageAdapter,
  ): void {
    server.registerTool(
      'delete_trace',
      {
        title: 'Delete Trace',
        description: [
          'Remove a single trace by id. Cascades to spans; eval_results keep the score history with trace_id NULLed.',
          '',
          'Sibling tools — log_trace creates traces, get_traces queries them, evaluate_output / evaluate_with_llm_judge / verify_citations score them. delete_rule handles custom-rule deletion (separate concern); list_rules / deploy_rule manage the custom-rule lifecycle. delete_trace is the DESTRUCTIVE single-row remove for traces; it does NOT touch eval_results (preserved for audit + drift analytics), spans cascade automatically.',
          '',
          'Behavior. DESTRUCTIVE — SQL DELETE scoped to the caller\'s tenant_id. Cascades: spans belonging to this trace are deleted (FK ON DELETE CASCADE); eval_results that referenced this trace have their trace_id set to NULL (FK ON DELETE SET NULL) so aggregate dashboards + historical scores remain valid even after the trace is gone. Not idempotent: deleting an already-deleted trace returns `deleted: false`. Does not emit an audit log entry in v0.4 — traces are user-scope data, not policy changes. Rate-limited to 20 req/min on HTTP MCP.',
          '',
          'Output shape. Returns JSON: `{ "deleted": boolean, "trace_id": string }`. `deleted=true` if a row was removed; `deleted=false` if no trace with that id existed (or it belonged to a different tenant — cross-tenant deletes silently fail).',
          '',
          "Use when a trace was captured in error, contains sensitive data that must be removed for compliance (e.g., a customer exercises GDPR right-to-erasure), or when cleaning up test data. Combine with get_traces to find candidates: query with filters → review → delete_trace(id) per target. For bulk time-window deletion, use `deleteTracesOlderThan` via the CLI / retention config — delete_trace is the single-row surgical path.",
          '',
          "Don't use to clean up OLD data in bulk (use retention config with --retention-days). Don't use to PAUSE a trace — traces are immutable once stored; there's nothing to pause. Don't use to delete eval_results — eval_results survive their trace's deletion intentionally (for audit + drift analysis); they're pruned only by retention.",
          '',
          'Parameters. trace_id is the only parameter; must match 32-char lowercase hex (Zod regex). The trace_id you pass is exactly what log_trace returned in its response, or what get_traces returned per row. Format mismatch fails Zod with 400 BEFORE the storage layer is touched. Cross-tenant trace_ids return `deleted: false` silently — they\'re invisible to the caller\'s tenant (prevents enumeration attacks; matches delete_rule\'s tenant-isolation contract).',
          '',
          "Error modes. Throws 400 on malformed trace_id (wrong format: not 32-char lowercase hex). Returns `{deleted: false}` when the id doesn't exist in the caller's tenant (not an error — the trace may simply have been deleted already). Returns 429 on HTTP rate limit. Storage failures propagate as 500.",
        ].join('\n'),
        inputSchema,
        annotations: {
          readOnlyHint: false,
          destructiveHint: true,
          idempotentHint: false,
          openWorldHint: false,
        },
      },
      async (args) => {
        const deleted = await storage.deleteTrace(LOCAL_TENANT, args.trace_id);
        return {
          content: [
            {
              type: 'text' as const,
              text: JSON.stringify({ deleted, trace_id: args.trace_id }),
            },
          ],
        };
      },
    );
  }

• src/storage/sqlite-adapter.ts:553-562 (handler)

  The SQLite storage implementation of deleteTrace(). Executes 'DELETE FROM traces WHERE tenant_id = ? AND trace_id = ?' and returns true if a row was deleted.

  async deleteTrace(tenantId: TenantId, traceId: string): Promise<boolean> {
    assertTenant(tenantId);
    // Tenant-scoped: a trace id owned by a different tenant is
    // untouchable from this call. Cross-tenant deletions are not just
    // denied — they're invisible (no indication the id even exists).
    const result = this.db
      .prepare('DELETE FROM traces WHERE tenant_id = ? AND trace_id = ?')
      .run(tenantId, traceId);
    return result.changes > 0;
  }

• src/types/query.ts:127-127 (schema)

  Interface definition for deleteTrace in IStorageAdapter: deleteTrace(tenantId: TenantId, traceId: string): Promise<boolean>.

  deleteTrace(tenantId: TenantId, traceId: string): Promise<boolean>;